Skip to content

Upgrading

Sovereign Home Cloud has three components to upgrade, each on its own schedule:

Component How Effect on event broker services
Sovereign Home Cloud: the control plane, data stores, and default datacenter agent helm upgrade of the home-cloud-control-plane release None, event broker services keep serving messages.
An added datacenter's agent helm upgrade of that datacenter's solace-cloud-ca release None
An event broker service From the Cloud Console, one event broker service at a time A short interruption for that event broker service

What a Release Contains

A Sovereign Home Cloud release is one version of the home-cloud-control-plane chart. It sets:

  • the control plane image, which includes the Cloud Console, the Ops User Interface (UI) and their services
  • the images of the bundled data stores
  • the datacenter agent version for the default datacenter, and the agent chart for added datacenters
  • the event broker versions offered when you create or upgrade an event broker service. New event broker versions arrive by upgrading Sovereign Home Cloud, not separately.

Before upgrading, read the release notes for every version between yours and the target.

Before You Upgrade

  1. Back up the database and keep your copy of VAULT_LOCAL_KEY; see Backup and Restore. Downgrading is not supported: to go back, you must restore.
  2. Use the values files you installed with. Pass the same files, in the same order, to helm upgrade. Keep them under version control.

  3. Keep these values unchanged. Changing them on an installed release breaks it or is refused:

    Value Reason to Leave Unchanged
    maasPrefix Names stored data
    organization.operator.id, organization.default.id Identify the seeded organizations
    solace-cloud-ca.datacenter.id Identifies the default datacenter and its event broker services
    broker.enabled Switching the control plane's event broker is a reinstall
    Storage classes Volumes cannot move to another StorageClass

  4. Pin anything you rely on. If a release changes a default, helm upgrade applies the new default to every value your files do not set. The release notes list changed defaults; set the old value explicitly where you want to keep it.

  5. Air-gapped: mirror the target version's chart and images first, including the event broker versions you plan to upgrade to; see Mirror the Images.

Upgrade Sovereign Home Cloud

The commands below use the default release name and namespace, home-cloud-control-plane. If you installed under another name, such as self-managed-solace from the chart's earlier name, keep it: use your release name and namespace in these commands. The resources follow the release name, so the upgrade changes them in place.

  1. Check the upgrade against the cluster without changing anything:

    helm upgrade home-cloud-control-plane <chart for the target version> -n home-cloud-control-plane \
  -f <your values files> --dry-run=server

  2. Upgrade:

    helm upgrade home-cloud-control-plane <chart for the target version> -n home-cloud-control-plane \
  -f <your values files> --wait --timeout 30m

  3. Watch the control plane come back:

    kubectl get pods -n home-cloud-control-plane -w

Warning! The Cloud Console and the Ops UI are unavailable during the upgrade. In Early Access the control plane runs as one replica, and an upgrade stops it before the new version starts. The Cloud Console, the Ops UI, and the API are unavailable for several minutes, until the new control plane is ready. Event broker services are separate workloads and keep serving messages throughout. Plan your upgrades in a maintenance window.

After the control plane is ready, the upgrade re-runs the default datacenter's registration and updates its agent.

Verify

  1. Every pod is Running, and the datacenter agent is 1/1.
  2. Sign in to the Cloud Console and the Ops UI.
  3. Your existing event broker services show as running.

Upgrade an Added Datacenter's Agent

The default datacenter's agent is upgraded with Sovereign Home Cloud. For each datacenter you added, upgrade its release with the agent chart from the new home-cloud-control-plane chart, under charts/, and the values file you installed that datacenter with:

helm pull oci://registry.solace.com/solace/home-cloud-control-plane/charts/home-cloud-control-plane \
  --version <new chart version> --untar
helm upgrade <datacenter id> ./home-cloud-control-plane/charts/solace-cloud-ca -n <namespace> \
  -f <datacenter values file>

Set image.cloudAgent.tag in the datacenter's values to the agent version the new release uses. It is the same value as solace-cloud-ca.image.cloudAgent.tag in the new chart's values.yaml.

Upgrade an Event Broker Service

An organization's users upgrade their own event broker services from the Cloud Console. The Ops UI administrator can also upgrade any event broker service, from Upgrades in the Ops UI, either right away or scheduled into a maintenance window. To schedule an upgrade, you must first create a maintenance window.

From the Cloud Console:

  1. Open Cluster Manager and the event broker service.
  2. Choose to upgrade it, and pick the target version from the versions this release offers.
  3. Before upgrading, the agent runs pre-upgrade checks, including whether it can create resources in the namespace. After the upgrade it runs post-upgrade checks. You can view logs for the checks from the Service Details page in the Cloud Console.

The event broker service restarts on the new version with its message store and configuration kept. A single-node broker is unavailable for several minutes; applications reconnect when it is back.

Note: The target version's image must be in the registry the datacenter pulls from. If it is not, the upgrade fails its pre-upgrade checks or the broker stays in ImagePullBackOff. In an air-gapped installation, mirror the version's image first.

Next Steps