Managing configuration resources

A LUSID domain is built from hundreds or thousands of configuration resources: data types, property types, recipes, workflows, transaction types and so on. Keeping multiple domains consistent by hand, or by re-running scripts, is slow and error-prone.

Admin Portal's configuration management lets you describe the configuration you want once, store it under version control, and roll it out to your domains in a controlled order, with a full plan and a second person's approval before anything changes.

Note: Configuration management in Admin Portal is an Early Access feature. Contact your FINBOURNE representative if you cannot see Configuration Management in the left-hand menu.

The idea in one sentence

You write down the configuration a domain should hold, and Admin Portal makes the target domain(s) match it. Work through a tutorial.

That "written down" configuration is a target state definition. Making a domain match it is a deployment. Everything else exists to make those two things safe, repeatable and visible:

The four building blocks

1. Sources

A source is a place where definitions live: a Git repository on GitLab, GitHub or Azure DevOps, or a folder in LUSID Drive. Registering a source tells Admin Portal where to look for definitions and where to save changes.

Storing definitions in Git gives you history, review and rollback built in. A Drive folder is quicker to set up and needs no repository access. You can register several sources and mix the two kinds.

See how to register a source.

2. Target state definitions

A target state definition is a named list of resources describing a desired end state. It is stored as a single JSON file in a source and identified by a scope and code, such as default/eod-holdings.

You build a definition by pulling resources in from a domain you already have, editing their values if you need to, and saving. You can pull from several domains, so a definition can combine the property definitions from one domain with a recipe from another, for example. You can also copy every resource a domain holds in one pass.

Two things are worth understanding early:

• The definition is the desired state, not an export. Editing a definition never changes a domain. It only changes the file.

• Each resource is either managed or a reference. A managed resource is created, updated and removed by deployments to match the definition. A reference must already exist in the target domain and is used but never changed. References are how you depend on shared configuration you do not own.

See how to create a target state definition.

3. Pipelines

A pipeline is an optional named route to production for one definition: stages you name yourself, in the order you want them, each with its own domains. A typical pipeline might be Development → UAT → Production, but the names and the number of stages are up to you.

You promote a definition along the pipeline one stage at a time. Each promotion raises a deployment request for every domain in that stage that is behind the latest revision, and each request must be approved before it can be deployed. Because you decide when to promote to the next stage, you can hold configuration in UAT for as long as testing takes.

Pipelines are optional. You can deploy a definition directly to any domain without one. A pipeline adds the sequencing and the single board that shows how far a definition has travelled.

See how to create a pipeline.

4. Deployments

A deployment applies a definition to a set of domains and keeps them reconciled to it. Each time you deploy to one domain constitutes a run: the unit that is planned, approved, executed and logged.

Every run follows the same sequence:

1. Plan. Admin Portal reads the definition and the domain and shows exactly what a deploy would create, update and remove. Nothing has changed yet.

2. Request. You review the plan, acknowledge any permanent removals, and submit a request.

3. Approve. A second person with deploy rights for that domain reviews the request and approves it. Approving does not deploy anything.

4. Deploy. Anyone with deploy rights selects Deploy now. The run executes and records every resource it touched.

See how to raise a deployment request.

Principles that shape the design

Nothing lands without a plan and an approval

Every deployment shows you the full plan first, and every request needs a second person to approve it. You cannot approve your own request.

Removals are explicit

If a domain holds a resource that a deployment manages but the definition no longer lists, the plan shows it as a removal, and you must acknowledge permanent removals before you can submit. On any removal you can instead choose Keep, which leaves the resource in the domain.

Three states, not two

For any domain a deployment targets, Admin Portal distinguishes the:

• definition: the desired state, as stored in the source;

• deployment record: the revision this deployment last applied to that domain;

• live domain: what the domain actually holds right now.

The live domain is only observed when a run executes or when you ask for a drift check. It can change underneath the record in between, for example if someone edits a resource by hand. Check for drift on a domain reads every resource the deployment manages and reports what has been modified or removed outside the deployment. Redeploying puts them back.

Write behaviour protects what you choose

Write behaviour decides what a deployment does when a resource already exists in the domain, and what happens to it when you remove it from the definition. Five presets cover the common cases, from Default (create, fail if it exists, keep updated, delete when removed) through Adopt (take over an existing resource) to One-shot (create once and never touch again). Resources you add from a domain start as Default, so choose Adopt before you deploy them to a domain that already holds them, including the domain you read them from.

Revisions, not versions

A deployment always reads the latest revision of the definition from its origin at the moment a run executes, not the version that existed when the request was raised. The run records both the revision the plan was computed against and the revision it actually applied, so a difference is visible rather than hidden.

The people involved

Configuration management requires at least two people:

• Someone who requests. They build definitions and raise deployment requests. This needs the right to write definitions and request deployments.

• Someone who approves and deploys. They review each request's plan, approve it, and choose when to select Deploy now. This needs the Trigger Deployments right for the domain in question.

A single person can hold both rights, but they still cannot approve their own request.

See how to approve someone else’s request.

Where to watch what is happening

• Configuration Management > Deployments has three tabs. Activity shows every run in flight, with what is awaiting approval, approved and ready, and running. Deployments by Definition lists each deployment with its domains. History keeps every finished run with its plan, its log and who approved it.

  Select Refresh at the top of the page to fetch the latest requests, runs and deployments. You stay on the same tab and keep your place on the page. If the list can't be refreshed, a warning says so, the page keeps showing what it last loaded, and nothing has changed in your domains.

• A pipeline's board shows, per stage and per domain, which revision is deployed and whether it is behind the latest.

• A domain's detail page under a deployment shows the three states, the drift check, a comparison of the definition against the deployment record, and the full run history with logs.

• Approvals lists deployment requests awaiting approval alongside other approvals in Admin Portal.

Glossary