Skip to content

Orion - Upgrade and Rollback

Overview

This guide covers upgrading and rolling back the version of your deployment of the Orion platform.

In general, there are 3 components you might want to upgrade: - Genesis - the management layer of your cluster - Environments / projects - Terra Plugins

Both Genesis and individual projects also consist of individual services.

Assumptions

This guide assumes that:

  • you already have basic familiarity with the product and its core concepts.
  • you are familiar with core ArgoCD concepts. If you are new to this tool, you can find a quick reference on it in our ArgoCD Introduction.
  • you can perform simple kubectl operations. If you are new to kubectl, you can find a good starting point here

Moreover, if you run an airgapped deployment it assumes that:

  • you have a proxied or forked version of all OCI images available
  • you have up-to-date deployment charts available

Versioning strategy - Genesis management layer and projects

For Genesis, Orion's management layer, you can safely assume upgrades of minor and patch versions will not break existing projects. The minimum supported version of the Genesis management layer is listed in the technical changelog.

When an upgrade is required, you would always upgrade first the Genesis management layer and only then the projects.

For the management layer, you can freely upgrade it through minor and patch versions without disrupting running projects. The aim here is to avoid downtime to heavily-used environments and projects, letting you upgrade at your own pace.

While projects can stay on a previous version until it is convenient to upgrade, we recommend keeping your management layer up-to-date to make use of the latest enhancements.

Changelogs

We maintain two release changelogs:

  • One contains new features where you can review the latest & greatest Orion has to offer.
  • The technical changelog provides guidance for technical teams operating Orion deployments. This is intentionally kept brief and only informs you of any deprecations, migration steps between major versions or addressed security vulnerabilities. If a release has nothing extra to consider, it is explicitly listed as such for you to have confirmation.

We recommend you link the technical changelog within your internal documentation and review it prior to each upgrade. Any major release requiring special upgrade steps also contains a detailed migration guide linked under the changelog.

Project upgrade workflow

Project upgrades can be carried out either via ArgoCD's UI or the kubectl commandline. For debugging, having both at hand is useful.

To debug a project's upgrade status, go to ArgoCD either via the dashboard in Genesis, your existing ingress or by port-forwarding it.

Projects - adjusting individual image versions

In day-to-day operations, it is recommended you stick to predefined image versions. When debugging or inquiring about early access/unstable releases, you might need to upgrade or roll back an individual component.

For projects, this is done by clicking "Manage" -> "Configure" and setting the Orion Version field: user-creation

Alternatively, you can do it via kubectl: 

kubectl patch app -n argocd <project name> --type='json' -p='[{"op": "replace", "path": "/spec/sources/0/targetRevision", "value": "v1.4.0"}]'

The release version number corresponds to a target branch of the environment/project deployment repo. Available releases can be seen both in the changelogs and as branches on the project deployment repo found here.

Genesis management layer upgrade workflow

To upgrade Orion's management layer, Genesis, you would edit the target branch.

The correct image versions will be automatically defaulted to, assuming you have no overrides in your Genesis settings accessible by clicking on your profile icon. If you do have overrides, make sure to remove them before the upgrade!

To edit the target branch, you would either edit the application spec directly in the ArgoCD web UI. The target branch is the release number. Available releases can be seen both in the changelogs and as branches on the deployment repo found here.

To perform the same with kubectl: 

kubectl patch app -n argocd <project name> --type='json' -p='[{"op": "replace", "path": "/spec/sources/0/targetRevision", "value": "v1.4.0"}]'

From there, you can observe the upgrade status in ArgoCD's UI.

Genesis management layer upgrade workflow - individual components

Similarly to projects, it's recommended to not adjust the management layer image versions unless requested so by the support team.

For the management layer, you can adjust:

  • Genesis (Orion's central management component)
  • Titan (user management)
  • Terra (plugin manager)

You can adjust those either directly in the web UI by clicking on your profile and going to "Settings" or by editing the argo app directly. It is recommended you adjust it via the .spec.parameters. This will remain compatible with the web UI adjustments - avoid using the values field, which interferes with it.

$ kubectl edit -n argocd genesis

      parameters:
        - name: image
          value: genesis:X.Y.Z
        - name: titan.image
          value: titan:X.Y.Z
        - name: terra.image
          value: terra:X.Y.Z

Versioning strategy - Terra plugins.

Detailed documentation on plugin releases is coming soon.