Skip to main content
This guide assumes that you deployed Poolside using the instructions in the Install on Kubernetes guide.

​
Overview

This guide describes how to upgrade an existing Poolside deployment on a self-managed Kubernetes cluster to a new Helm bundle. The application chart (poolside-deployment) and the inference chart (inference-stack) are upgraded independently. The upgrade process includes the following phases:
  1. Prepare the new bundle: Extract the bundle and reuse the values file from the previous install. Add any new values required by the new chart.
  2. Back up the database: Backup PostgreSQL before making changes.
  3. Upload new container images: Push the new bundle’s images into your registry.
  4. Upgrade the application: Run helm upgrade against the poolside-deployment chart.
  5. Upgrade inference (optional): Run helm upgrade against the inference-stack chart.
  6. Verify: Confirm that the new revision is deployed and pods are healthy.

​
Deployment bundle

The new bundle follows the same structure as the initial install. For more information, see Install on Kubernetes.

​
Prerequisites

  • A working Poolside deployment completed with the Install on Kubernetes guide.
  • The new deployment bundle provided by Poolside.
  • The customized poolside_values.yaml and inference_values.yaml files used for the initial install.
  • Workstation tools, same versions as the initial install:
    • helm 3.12 or later
    • kubectl
    • skopeo

​
Downtime

The upgrade rolls pods one deployment at a time. Deployments that run multiple replicas (core-api, web-assistant, orchestrators, temporal-server, sandbox, public-docs) roll without downtime. Expect a short, transient gap of at most a few seconds per deployment as pods roll over. Plan a maintenance window if your environment runs single-replica deployments.

​
Back up the database

Before starting the upgrade, back up the Poolside PostgreSQL database either through your managed database’s snapshot mechanism or using the db-snapshot.sh helper bundled with the install. See Back up and restore the database.

​
Preparation

​
Step A: Extract the new bundle

Poolside provides the new bundle as a tarball. Extract it to a directory of your choice, then set shell variables for the old and new bundle roots: 
export OLD_BUNDLE=<path-to-previous-bundle>
export NEW_BUNDLE=<path-to-new-bundle>

​
Step B: Review and update the customized values.yaml files

The customized values.yaml files for the Helm charts from your previous install can be reused during the upgrade process. Poolside notes any required values changes in the release notes. The Poolside bundle contains values.yaml files for the poolside-deployment and inference-stack Helm charts at charts/poolside-deployment/values.yaml and charts/inference-stack/values.yaml. Use them as a reference while reviewing your existing files.

​
Upgrade

​
Step 1: Upload new container images

The new bundle ships updated images in ./containers/. Push them to the same registry that the cluster uses for global.containerRepositoryOverride. Log in to your target registry using docker login, podman login, or skopeo login before uploading. Run the upload script from the new bundle root: 
cd $NEW_BUNDLE
./scripts/upload_images.sh <registry-host>

​
Step 2: Dry-run the application upgrade (optional)

Run a Helm dry-run to preview the changes before applying them: 
helm upgrade <release-name> \
  $NEW_BUNDLE/charts/poolside-deployment \
  -f <path-to-values.yaml> \
  -n poolside --dry-run --debug | less
Replace <release-name> with the name reported by helm list (typically poolside-deployment).

​
Step 3: Apply the application upgrade

helm upgrade <release-name> \
  $NEW_BUNDLE/charts/poolside-deployment \
  -f <path-to-values.yaml> \
  -n poolside
Watch the state of pods during the upgrade process and verify that they are healthy at the end of the upgrade. The pods should be in a Running state at the end of the upgrade: 
kubectl get pods -n poolside -w

​
Step 4: Upgrade the inference stack (optional)

If you have a local inference deployment using the inference-stack chart, upgrade it separately. If your S3 backend uses a publicly trusted certificate, you can omit the --set-file flag from the helm upgrade command below. If your S3 backend uses a private CA (for example, SeaweedFS or MinIO with a self-signed certificate), prepare the CA bundle first and pass it with --set-file: 
helm upgrade inference-stack \
  $NEW_BUNDLE/charts/inference-stack \
  -f <path-to-inference-values.yaml> \
  --set-file global.inference.s3.caBundle=<path-to-s3-ca.crt> \
  -n poolside-models

​
Verification

Confirm the release is deployed: 
helm history <release-name> -n poolside
Verify that all pods are healthy: 
kubectl get pods -n poolside
kubectl get pods -n poolside-models
Confirm that the web endpoint still serves traffic: 
curl -sI https://<web-hostname>/ | head -1
Expect HTTP/1.1 200 OK. Alternatively open https://<web-hostname> in a web browser and verify that Poolside webpage is functional.

​
Troubleshooting

  • Pods stuck pulling images: Verify that the new tags are present in your registry, and confirm that global.imagePullSecrets still references a valid secret.