Skip to content

How to make a configuration change and apply it

Selecting Units

To make a configuration change and then apply it in ConfigHub, first identify a set of units. It may be a vertical subset, like the units belonging to a single helm chart or cluster, or a horizontal subset, like all the variants of a unit across clusters.

Use a where expression or a saved Filter to select the units.

See the guide about managing sets of units for more details.

Change Sets

Create a ChangeSet with a Description. ChangeSets make it possible to group multiple related changes, in sequence and across units. ChangeSets can be used to refer to changes when restoring previous configurations and when merging configurations across units and "rebasing" prior changes on top of more recent changes. Each ChangeSet has a start tag and an end tag.

cub changeset create --space acme-home release-v452 --description "Release 452: Fix X. New feature Y. Upgrade Z."

Use bulk patch on the filtered set of units to add them to the change set, which "opens" it. A change set acts as a kind of lock, so if any units are in another change set, it will need to be removed (closed) first. If successful, this will create a new revision for each unit of the change set, whether the configuration data is changed or not, so set the LastChangeDescription on this update to refer to the ChangeSet.

cub unit update --patch --space acme-dev --filter acme-home/acme-app --changeset acme-home/release-v452 --change-desc "Starting Release 452 rollout"

Now you can make modifications to the filtered Units, such as upgrades, and the revisions will be part of the change set. If you invoke functions, the change set ID needs to be passed to the function invoke API, or the change will be rejected.

cub function do --space acme-dev --changeset acme-home/release-v452 --filter acme-home/acme-app --change-desc "Update image ref to v452" set-image-reference ":v452"

To close the changeset, the units need to be patched again with a null ChangeSetID. That will add the ChangeSet EndTagID to the Head Revision of each of the filtered Units.

cub unit update --patch --space acme-dev --filter acme-home/acme-app --changeset -

Review and Approval

Someone may need to review and approve the changes, if an is-approved Trigger has been installed in the spaces containing the units. Send the name and space of the ChangeSet to the desired approver(s).

The bulk approve API can pass "ChangeSet:" with the change set ID for the revision parameter. That will approve the revision marked with the ChangeSet's end tag for each of the filtered Units.

cub unit approve --space acme-dev --filter acme-home/acme-app --revision ChangeSet:acme-home/release-v452

Bulk apply works similarly.

cub unit apply --space acme-dev --filter acme-home/acme-app --revision ChangeSet:acme-home/release-v452

Undoing a Change Set

If you need to undo a ChangeSet, a bulk patch with a restore parameter of "Before:ChangeSet:" and the change set ID will restore the prior revisions. Then bulk approve and apply can be done with no revision parameter, to apply the new head revisions created by restore. You could tag those new restored head revisions using the bulk tag API by passing "HeadRevisionNum" for the Revision string in the request.

cub tag create --space acme-home rollback-v452 --description "Rollback release 452"
cub unit update --patch --space acme-dev --filter acme-home/acme-app --restore "Before:ChangeSet:acme-home/release-v452" --tag acme-home/rollback-v452

Merging and rebasing

In ConfigHub, revisions and clones are somewhat analogous to git commits and branches, but are somewhat different since each Unit is kind of like its own repo with its own commit history, and ConfigHub also enforces a linear revision history, which is generally more suitable and convenient for managing granular configuration units. But there are some cases where merging changes from other units or prior revisions is necessary or desirable.

Examples:

  1. Prior revisions were restored, as described above, but there were subsequent changes after the changeset that was undon. You can update the units with merge_source=Self and the change set or other revision range for the revisions to rebase on top of the restored revision.
  2. Changes have been made since the last Apply that shouldn't be applied yet, but an urgent change needs to be made. The last applied revision can be restored, then the urgent change made and applied, and the reverted changes patched back in when it's time to apply them, using the same approach as in (1).
  3. Changes have been made but not applied. A Refresh from the live resources creates a new head revision that reverts some of those changes. Again, they can be merged back into the new head revision.
  4. Clone a configuration unit and make changes for an upcoming release. When it's time to rollout the release, merge the changes with the upstream.
cub unit update --patch --space acme-dev --filter acme-home/acme-app --merge-source Self --merge-base Before:ChangeSet:acme-home/release-v452 --merge-end ChangeSet:acme-home/release-v452 --change-desc "Reapply release 452"

Tags

ChangeSets use "managed" Tags, but Tags can also be set independently, on any "named" revisions: HeadRevisionNum, LiveRevisionNum, PreviousLiveRevisionNum, or LastAppliedRevisionNum. It is a good idea to tag any revisions being approved and applied that aren't part of a ChangeSet, and then use the Tag in approve and apply (with "Tag:" and the tag ID) and restore (using "Before:Tag:" and the tag ID).

cub tag create --space acme-home upgrade-251023 --description "Upgrade from base"
cub unit update --patch --space acme-dev --filter acme-home/acme-app --upgrade # could also use --tag here
cub unit tag --space acme-dev --filter acme-home/acme-app acme-home/upgrade-251023

Listing ChangeSets and Tags

Use the organization-level Revision List API to list Revisions associated with ChangeSet or Tag. For ChangeSets, you can use the ChangeSet's StartTagID or EndTagID (if closed) via where Tags ? '<tag-id>', or filter by the ChangeSetID using where ChangeSetID = '<changeset-id>'.

cub revision list --space acme-dev --filter acme-home/acme-app --tag acme-home/rollback-v452

For a particular Unit, all Revisions in the ChangeSet can be listed using where ChangeSetID = '<changeset-id>' using the existing unit-level Revision List API.

cub revision list --space acme-dev frontend --where "ChangeSet.Slug = 'release-v452'"