Tutorial: Moving configuration resources between domains

This tutorial takes a set of configuration built in a development domain and carries it, step by step, into UAT and then production.

Along the way you register a source, build a target state definition from two domains in different cells, create a pipeline, promote the definition through it with a pause for testing, and read the logs of what each deployment did. By the end you will have seen every screen in the workflow and know where to look when something needs checking.

The scenario

Your firm has four LUSID domains:

Domain	Cell	Role in this tutorial
`acme-dev`	`emea-cell-1`	Where the team built a new set of property definitions and a valuation recipe
`acme-shared`	`emea-cell-2`	Holds a firm-wide custom data type the new properties depend on
`acme-uat`	`emea-cell-2`	Where the change is tested
`acme-prod`	`emea-prod-cell`	Production

The goal is a single definition, default/holdings-reporting, that holds the new configuration and can be promoted from UAT to production through a pipeline. The domain, cell and resource names here are examples. Substitute your own.

Prerequisites

Access to the Admin Portal with rights to create sources, write definitions and request deployments.
A colleague with the Trigger Deployments right for acme-uat and acme-prod. Every deployment request must be approved by someone other than the requester.
A GitLab, GitHub or Azure DevOps repository to store the definition, and permission to create a personal access token for it. A LUSID Drive folder works too and doesn’t require a token.
Access to the cells that own the four domains.

Step 1: Register a source

The definition needs somewhere to live before you can create it. More information.

Navigate to Configuration Management > Sources and select Add source.
Select Source control, give the source a Display name such as config-repo, and complete the repository details and access token for your provider.
Select Test connection, wait for Connection verified, then select Add source.

The source appears in the list as Connected. From now on, every .json file Admin Portal saves into it is a definition.

Step 2: Create the definition

Navigate to Configuration Management > Target State Definitions and select New definition.
Enter Scope default and Code holdings-reporting. This identifier becomes the deployment name in every domain you deploy to.
Select the config-repo source card. Admin Portal fills in a File path in this source of holdings-reporting.json. Leave it.
Select Create & add resources.

The empty definition opens in the builder. Nothing has been written to any domain. The builder is where the definition takes shape.

Step 3: Add the property definitions from the development domain

Select Add resources from a domain.
Choose the cell emea-cell-1, then the domain acme-dev, and select Continue. The dialog reminds you that reading a domain never changes it.
On the Select resources page, select Choose resource types, tick Property definition and Recipe, and confirm.
Use the search box to narrow the list to the new properties, for example by their scope. Tick the property definitions and the recipe you want. Leave the Behaviour column on Resource for each, because this definition should manage them. More information.
Select Add N to definition.

If the recipe depends on resources the definition does not hold, the Dependencies found dialog appears. Each dependency defaults to Reference, meaning the definition expects it to exist in the target domain already. For this tutorial, leave them as references and select Add selection + N dependencies.

You are back in the builder. Each row shows acme-dev in the Pulled from column.

Step 4: Add the shared data type from a domain in another cell

The new properties use a custom data type that lives in acme-shared, in a different cell. Because UAT and production may not have it yet, you want this definition to manage it too.

In the builder, select Add resources.
Choose the cell emea-cell-2, then the domain acme-shared, and select Continue.
Select Choose resource types, tick Data type, and confirm.
Tick the custom data type. Keep Behaviour as Resource.
Select Add 1 to definition.

The builder now holds resources from two domains, and the Pulled from column tells them apart. This is normal: a definition describes what a target should hold, wherever the pieces came from.

Step 5: Check the definition and save

Before saving, take a moment in the builder:

Use the Scope and Resource type facets on the left to check the mix of resources.
The Write behaviour column reads Default for every managed resource, which fails on any resource the target domain already holds. UAT or production may already have some of them, so select Write behaviour: ... in the toolbar, choose Adopt and select Apply. The deployment then adopts anything that already exists rather than failing.
Notice the Unsaved changes chip beside the save button.

Select Save changes. Admin Portal commits holdings-reporting.json to your repository with the message Update target state definition default/holdings-reporting via Admin Portal. The button now reads Saved.

Step 6: Create the pipeline

A pipeline sequences the domains the definition travels through. More information.

Navigate to Configuration Management > Pipelines and select New pipeline.
Enter Pipeline name Holdings reporting rollout.
In Definition source choose config-repo, then in Target State Definition choose default/holdings-reporting.
The editor opens with one stage named Development. Rename it to UAT, and under Add domain choose acme-uat.
Select Add stage, name it Production, and add acme-prod.
Select Create pipeline.

The pipeline board opens with two columns, UAT then Production, joined by an arrow. Both domains show Never deployed.

Step 7: Promote to UAT

Promoting raises a deployment request for each domain in the stage that is behind the latest revision. Nothing is applied until the request is approved and deployed. More information.

At the foot of the UAT column, select Promote the latest revision to acme-uat. Once the definition has a known revision, the button names it instead, for example Promote a1b2c3d to acme-uat.
The deploy flow opens on the Plan step. Admin Portal reads acme-uat and shows what a deploy would do. Because nothing has been deployed here before, the plan is a list of Create actions, one per resource. If UAT already had any of them, they appear as Update or Unchanged instead. Expand a row to see the fields that would change.
Select Continue. The Review step summarises the request: one card for acme-uat, the origin the definition is read from, and a note that a second person must approve. If the plan removed anything you would need to acknowledge it here. It does not, so select Submit request.
The Submitted screen confirms one request was raised and that nothing has been applied yet.

Back on the pipeline board, acme-uat now shows Awaiting approval.

Step 8: Approve and deploy to UAT

Your colleague now takes over. They can work from the pipeline board or from Configuration Management > Deployments. More information.

Your colleague opens the pipeline board and selects Approve on the acme-uat node, or opens the Activity tab under Deployments and selects Review & approve on the request.
The Review & approve deployment dialog shows the definition, domain, origin, who requested it and the plan counts. They select Approve deployment.
Requests can also be approved, or denied, from the Approvals page.
The node now reads Approved · ready. Approving unlocks a Deploy now button but deploys nothing, so the team chooses when it lands.
Either of you with deploy rights selects Deploy now.

A Deploying to acme-uat window opens and streams the run's log as each resource is applied. You can close it; the deployment carries on and the log stays on the run's history. When it finishes the title changes to Deployed to acme-uat, and the pipeline board shows Succeeded for acme-uat with the counts of what was applied.

Step 9: Pause for testing

Nothing moves to production until you say so. The pipeline has no timer and no automatic advance. acme-prod sits at Never deployed while your team tests the configuration in acme-uat, for an hour or a fortnight.

During this pause, two views are useful:

The pipeline board shows at a glance that UAT is On latest and Production is behind.
The domain detail page for acme-uat, reached by selecting the domain's name on the board, shows the three states: the definition's latest revision, the revision the deployment record says was applied, and the live domain. If a tester changes a managed resource by hand in UAT, select Check for drift and Admin Portal lists exactly what was modified or removed outside the deployment.

If testing finds a problem, fix it in the definition in the builder, save, and promote to UAT again. The plan for the second run shows only what changed.

Step 10: Promote to production

When testing is complete:

On the pipeline board, select Promote a1b2c3d to acme-prod at the foot of the Production column.
Review the plan for acme-prod and select Continue, then Submit request. Because acme-prod lives in a production cell, the Review step notes This includes a production domain.
Your colleague approves the request and selects Deploy now, as in Step 8.

When the run completes, both columns show Succeeded on the same revision, and the pipeline's card in the list reads 2 of 2 on latest.

Step 11: Read the logs of what succeeded

Every run keeps a complete log, whether or not anyone was watching.

Navigate to Configuration Management > Deployments and open the History tab. Each finished run shows the definition, the domain, the status, when it finished, who deployed it and who approved it, and the counts of what it applied.
Select View log on the acme-prod run. Admin Portal opens the domain detail page with that run expanded under Deployment history on acme-prod.
Read the log. One line per event, each timestamped, including a line per resource such as Resource 'default/holdings-reporting/PortfolioManager' → created, and a closing Deployment summary line with the counts and duration.

You can also reach the same page from the pipeline board by selecting a domain's name or its Details link, then expanding any run in the history.

What you have built

A source that versions every definition you save.
A target state definition combining resources from two domains in two cells.
A pipeline that sequences UAT before production.
Two deployments, each planned, approved by a second person, deployed on your schedule, and logged.

From here, the same pipeline carries every future change. Edit the definition, save, and the board shows both domains as Behind latest. Promote to UAT, test, promote to production.

Variations

Deploy without a pipeline. Navigate to Configuration Management > Deployments, select New deployment, choose the definition, tick one or more domains, and follow the Plan and Review steps. Each domain still gets its own request and approval. More information.

Copy a whole domain instead of picking resources. On the Select resources page, Copy all resources reads every listable resource in the domain in one pass. More information.

The approver wants to reject a request. Denying is done from the Approvals page in Admin Portal, where the request appears under Configuration Deployment. There is no deny control on the pipeline board or under Deployments. The requester can instead withdraw their own request with Cancel request at any point before it is deployed.

A run fails. The board shows Failed and the run's error. Nothing is rolled back, and the domain may hold part of the definition, so select Check for drift on the domain to see what was applied. Fix the cause, then select Retry on the board, which raises a fresh request that is planned and approved again from scratch.

Someone else changed UAT by hand. Check for drift on the domain lists it. Promote to UAT again and the plan shows the resources being put back.

Troubleshooting

The Promote button is dimmed on Production before UAT is done. Promoting out of order is allowed but de-emphasised. The tooltip explains that the earlier stage is not on the latest revision. You can still promote, and the request is planned and approved on its own.

Approve and Deploy now are disabled for me. They need the Trigger Deployments right for that domain. The tooltip says so. Ask your administrator, or hand over to a colleague who has it.

I cannot approve my own request. Every request needs a second person to approve it, so hand it to a colleague with the Trigger Deployments right.

Redeploy is unavailable on a domain. A request is already pending for that domain. Resolve it first: approve and deploy it, or, if you raised it, select Cancel request.

The plan says some resources could not be compared. Admin Portal could not read those resources from the domain, so they are listed as Update (could not compare) rather than assumed unchanged. The deploy still proceeds for them.