Upgrade or uninstall

Use the section that matches the install. A single VM upgrades with ./install.sh. A cloud install upgrades with Terraform.

Upgrade a single VM

Download the new superplane-single-host.tar.gz from the SuperPlane releases. From the existing install directory, replace the Compose file, install.sh, and uninstall.sh. Leave superplane.env, oidc/, fleet-manager.env, and Caddyfile in place.

mkdir -p /tmp/superplane-release
tar -C /tmp/superplane-release -xzf superplane-single-host.tar.gz
cp /tmp/superplane-release/superplane/docker-compose.yml .
cp /tmp/superplane-release/superplane/install.sh .
cp /tmp/superplane-release/superplane/uninstall.sh .
chmod +x install.sh uninstall.sh
./install.sh

./install.sh keeps the existing secrets, pulls the new images, and migrates the database when the app starts. It starts Fleet Manager with the other services. Confirm the health check:

docker compose ps
curl -fsS "https://superplane.example.com/health"

Uninstall a single VM

Stop new work and wait for current tasks to finish. From the installation directory, remove the services, managed runners, and project network:

./uninstall.sh --force

The script preserves data volumes, configuration, and OIDC keys. The --force flag permits interruption of running runners, including idle runners. Review the confirmation before you continue. Add --yes to skip confirmation for unattended removal.

When preserving data, the script uses the application API to retire runners before removing their containers. If retirement fails, run ./install.sh to resume before you retry removal.

Run ./install.sh from the same directory to restart with preserved data. Confirm service health and runner availability before you accept new work.

Purge deletes project data

Copy a backup off the VM first. The --purge option deletes this installation’s Docker data volumes. Configuration and OIDC keys remain.

To remove the installation and its data, use:

./uninstall.sh --force --purge

If you already removed the services while preserving volumes, run ./install.sh before purging so the script can verify resource ownership. Delete retained configuration and secrets only when you no longer need them.

The script does not delete the VM or its cloud disks. Remove those resources separately when you no longer need the installation.

Upgrade a cloud install

1. In your Terraform checkout, set superplane_chart_version to 1.0.0. Leave superplane_image_tag empty. The chart version has no v prefix. Move to a newer Terraform installer tag only when the release notes require it.
2. Set the new runner image IDs from the release notes. On Google Cloud, build a new image with Packer when the runner tools change, or keep the current image. runner_image_amd64 must not be empty while runners are enabled. Google Cloud now enables runners and GCS blob storage by default. To keep an older install without them, set enable_runners = false and enable_gcs_blob_storage = false.
3. Apply, then run the Fleet Manager Helm command from Fleet setup again. Set image.tag to v0.1.6. Set every runnerVersion to v0.2.1. Set Helm --version to 0.1.6. Do not install a newer Fleet Manager chart or Runner.

terraform plan -out tfplan
terraform apply tfplan

4. Confirm the installation:

kubectl get pods -n superplane
kubectl get certificate -n superplane

To change how many runner machines stay up, edit warmCapacity and maxCapacity in fleet-manager-values.yaml and run that same Helm command. Each AWS or Azure machine uses 2 vCPUs. The Google Cloud default machine type uses 4.

Uninstall a cloud install

Export anything you need first. This deletes the cluster, the database, and file storage.

Uninstall deletes the installation

Disable every fleet and wait until tasks finish and warm capacity is 0. Terminate runner machines that are still running. They are not in the Terraform state, and the cloud account keeps billing them.

AWS

export AWS_REGION=us-east-1
FLEET_MANAGER_ID=$(helm get values fleet-manager -n superplane --all --output json | jq -er '.manager.id')
RUNNER_INSTANCE_PROFILE_ARN=$(aws iam get-instance-profile \
  --instance-profile-name "$(terraform output -raw runner_instance_profile_name)" \
  --query 'InstanceProfile.Arn' --output text)
helm uninstall fleet-manager -n superplane

Set AWS_REGION from region in terraform.tfvars. Terminate any instances that are still running:

aws ec2 describe-instances --region "$AWS_REGION" \
  --filters "Name=tag:superplane_fleet_manager_id,Values=${FLEET_MANAGER_ID}" \
    "Name=iam-instance-profile.arn,Values=${RUNNER_INSTANCE_PROFILE_ARN}" \
    "Name=instance-state-name,Values=pending,running,stopping,stopped" \
  --query 'Reservations[].Instances[].InstanceId' --output text

Turn off RDS deletion protection, apply that change, and empty the S3 bucket from terraform output -raw blob_storage_bucket:

rds_deletion_protection = false

terraform plan -target=aws_db_instance.superplane -out tfplan
terraform apply tfplan

Azure

helm uninstall fleet-manager -n superplane
az vm list -g "$(terraform output -raw runner_resource_group)" -d -o table

Delete any sprunner- virtual machines that remain.

Google Cloud

helm uninstall fleet-manager -n superplane

Turn off deletion protection, then destroy. Terraform does not delete the static IP.

gke_deletion_protection   = false
sql_deletion_protection   = false
blob_bucket_force_destroy = true

terraform plan -out tfplan
terraform apply tfplan
terraform plan -destroy -out tfplan
terraform apply tfplan
gcloud compute addresses delete superplane-ip --global

On AWS and Azure, destroy after the steps in the tab:

terraform plan -destroy -out tfplan
terraform apply tfplan

terraform apply tfplan deletes resources because the plan is a destroy plan. If the AWS destroy stops on the load balancer, use the AWS installer README. Do not delete the Terraform state while a destroy is incomplete.

Remove an Azure install without the Terraform state

When the Terraform state is lost, delete the installation’s resource groups. Azure deletes the cluster’s node resource group, which starts with MC_, together with the cluster. Use the names from resource_group_name. The default is superplane.

az group delete --name your_install_name-runners --yes
az group delete --name your_install_name --yes

This also deletes any runner machines that are still in the runner group. Delete the DNS record for the installation separately.