---
title: "Tutorial: Moving configuration resources between domains"
slug: "moving-configuration-between-domains-with-admin-portal"
updated: 2026-10-16T13:27:29Z
published: 2026-10-16T13:27:29Z
canonical: "support.lusid.com/moving-configuration-between-domains-with-admin-portal"
---

> ## Documentation Index
> Fetch the complete documentation index at: https://support.lusid.com/llms.txt
> Use this file to discover all available pages before exploring further.

# 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](/v1/docs/how-do-i-set-up-a-source-in-admin-portal).

1. Navigate to **Configuration Management > Sources** and select **Add source**.
2. Select **Source control**, give the source a **Display name** such as `config-repo`, and complete the repository details and access token for your provider.
3. 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

1. Navigate to **Configuration Management > Target State Definitions** and select **New definition**.
2. Enter **Scope** `default` and **Code** `holdings-reporting`. This identifier becomes the deployment name in every domain you deploy to.
3. Select the `config-repo` source card. Admin Portal fills in a **File path in this source** of `holdings-reporting.json`. Leave it.
4. 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

1. Select **Add resources from a domain**.
2. 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.
3. On the **Select resources** page, select **Choose resource types**, tick **Property definition** and **Recipe**, and confirm.
4. 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](/v1/docs/how-do-i-create-a-target-state-definition-in-admin-portal).
5. 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.

1. In the builder, select **Add resources**.
2. Choose the cell `emea-cell-2`, then the domain `acme-shared`, and select **Continue**.
3. Select **Choose resource types**, tick **Data type**, and confirm.
4. Tick the custom data type. Keep **Behaviour** as **Resource**.
5. 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](/v1/docs/how-do-i-create-a-pipeline-in-admin-portal).

1. Navigate to **Configuration Management > Pipelines** and select **New pipeline**.
2. Enter **Pipeline name** `Holdings reporting rollout`.
3. In **Definition source** choose `config-repo`, then in **Target State Definition** choose `default/holdings-reporting`.
4. The editor opens with one stage named **Development**. Rename it to `UAT`, and under **Add domain** choose `acme-uat`.
5. Select **Add stage**, name it `Production`, and add `acme-prod`.
6. 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](/v1/docs/how-do-i-raise-a-deployment-request-in-admin-portal).

1. 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**.
2. 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.
3. 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**.
4. 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](/v1/docs/how-do-i-approve-a-deployment-request-in-admin-portal).

1. 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.
2. 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.
3. The node now reads **Approved · ready**. Approving unlocks a **Deploy now** button but deploys nothing, so the team chooses when it lands.
4. 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:

1. On the pipeline board, select **Promote a1b2c3d to acme-prod** at the foot of the **Production** column.
2. 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.**
3. 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.

1. 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.
2. 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**.
3. 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](/v1/docs/how-do-i-raise-a-deployment-request-in-admin-portal).

**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](/v1/docs/how-do-i-copy-all-configuration-from-one-domain-to-another-using-admin-portal).

**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.