Update the Sema4.ai application

Use Helm to upgrade an existing v3 installation on AWS EKS or Azure AKS. Omit --version to get the latest available version. Set it only when you need to upgrade to a specific release. These instructions cover updates within v3.

Before you start

Review the Release Notes for changes and any release-specific instructions.
Have the values file from your existing deployment ready, including any configuration changes you have made since installation. Keep the existing encryption keys in that file.
Use the same Kubernetes cluster, Helm release name, and namespace as the existing installation. If you need to look up the release name and namespace, run helm list --all-namespaces.

For the documented Kata Containers version, see Install the sandbox runtime. If your runtime also needs an update, follow Upgrading Kata or changing its configuration in a separate maintenance window.

Step 1: Review the update in the Enterprise Portal

Open the Enterprise Portal (opens in a new tab), go to Update, find your instance, and click Update available. Confirm the currently installed version and review the latest available release. Use the team for your v3 installation, whose license is assigned to the prod-selfhosted-v3 channel. If you also have a v2.5 installation, switch to the v3 team from the account menu.

Step 2: Log in to the registries

Copy and run the Export credentials and log in commands shown in the portal.

Skip preflight checks for this upgrade. Go straight from the credential and registry login commands to helm upgrade.

Step 3: Upgrade to the latest version

Run the upgrade with your existing release name, values file, and namespace:

helm upgrade <release-name> \
  oci://registry.sema4.ai/sema4ai/prod-selfhosted-v3/blockparty \
  --values my-values.yaml \
  --namespace <your-namespace>

Omitting --version selects the latest version available to your license on the v3 channel. If you copy the upgrade command from the portal, remove its --version option to use this default. The portal command omits the namespace, so add --namespace <your-namespace> yourself.

Use your deployment's current values file instead of a new or empty file. Include any additional values files or --set overrides your deployment uses.

Step 4: Verify

After the upgrade command completes, return to the portal and confirm that the instance is healthy and shows the new version.

Check the Helm release and the application Pods in your namespace:

helm status <release-name> --namespace <your-namespace>
helm list --namespace <your-namespace>
kubectl get pods --namespace <your-namespace>

Confirm the release is deployed and the chart and application versions match the update you intended to install. Wait for the application Pods to become ready, then open the application and verify that sign-in works. Run an agent or a workflow you use regularly to check that the application and its sandbox runtime work together.

Upgrade to a specific version

If you need a particular release, such as a version approved for your environment, add --version to the same command. Use the exact chart version shown in the Enterprise Portal for that release:

helm upgrade <release-name> \
  oci://registry.sema4.ai/sema4ai/prod-selfhosted-v3/blockparty \
  --version <chart-version> \
  --values my-values.yaml \
  --namespace <your-namespace>

Keep the same release name, values file, and namespace, then complete the verification steps above.

Troubleshooting

Release not found: Check the release name and namespace with helm list --all-namespaces, then use those values in the upgrade command.
Registry authentication fails: Run the credential export and registry login commands again before retrying the upgrade.
Configuration changed unexpectedly: Check that you supplied your deployment's current values file and any command-line overrides you normally use.
Agent runs fail after the upgrade: Check the sandbox runtime and data root.

Azure AKS Identity providers (OIDC)