Routine Upgrades (v6.x)

1 - Upgrade using Docker Compose

This procedure upgrades a Docker Compose deployment of Anchore Enterprise to a newer release within the same major version. Before you begin, review Prepare for the Upgrade.

Upgrade Procedure

Step 1: Review the Release Notes

View the Anchore Enterprise Release Notes for the target version.

Step 2: Match the Project Name and Volumes to Your Existing Deployment

Review the ’name’ and volume(s) used in your new compose file. Failure to match these to your existing deployment and older Compose file will result in a new/clean deployment rather than an upgrade.

name: "anchore-6010"
volumes:
  # Since this is for a quickstart, each minor version has its own db, to use a previous db and upgrade, change this
  # to the db volume name you want to upgrade from. e.g. "anchore-enterprise-6.0-db" if upgrading from a 6.0 quickstart deployment.
  # IMPORTANT: Do not change this volume name - it is used to persist data across minor version upgrades within this major version.
  anchore-enterprise-db:
    # Set this to 'true' to use an external volume. In which case, it must be created manually with "docker volume create anchore-db-volume"
    external: false

Step 3: Stop Anchore Enterprise

docker compose down

Step 4: Back Up Your Original Compose File

cp docker-compose.yaml docker-compose.yaml.backup

Step 5: Download the Latest Compose File

curl https://docs.anchore.com/current/docs/deployment/docker_compose/docker-compose.yaml > docker-compose.yaml

Step 6: Merge Your Customizations into the New File

Review the latest docker-compose.yaml and merge any edits/changes from your original docker-compose.yaml.backup to the latest docker-compose.yaml.

Step 7: Restart the Anchore Enterprise Containers

docker compose up -d

Step 8: Monitor the Upgrade

To monitor the progress of your upgrade, you can watch the docker logs from your catalog container, where you should see some initial output indicating whether or not an upgrade is needed or being performed, followed by the regular Anchore Enterprise log output.

docker compose logs -f catalog

Step 9: Verify the New Version Is Running

Once upgraded, you can review the new state of your Anchore Enterprise install to verify the new version is running using the regular system status command.

anchorectl system status

1.1 - Upgrade Air-Gapped using Docker Compose

A routine v6.x upgrade in an air-gapped Docker Compose deployment just needs the new image tags mirrored to your registry (or moved as a tarball) before you restart the stack. Unlike the major-version migration, there’s no new compose file, no new Dockerfile.anchore-db, and no rebuild required — you’re bumping versions on a running deployment, not standing up a new one. Your docker-compose.yaml stays as-is, provided you don’t touch the name or database volume name (see Step 2 of the main upgrade procedure).

Prepare the Images (low side)

1. Review the Release Notes for the target version to confirm which image tags actually changed. enterprise/enterprise-ui always move together; redis (and, less often, the PostgreSQL/pg_cron combination baked into anchore:db) can change independently, so don’t assume they’re unchanged from your last upgrade — diff the new reference docker-compose.yaml and Dockerfile.anchore-db against what you last mirrored if you’re unsure.

2. Pull the images that changed:

   docker pull docker.io/anchore/enterprise:v6.1.0
   docker pull docker.io/anchore/enterprise-ui:v6.1.0
   docker pull docker.io/redis:7.4.6
   

3. Only if Dockerfile.anchore-db changed for this release, rebuild the database image:

   docker build -f Dockerfile.anchore-db -t anchore:db .
   

   This is uncommon for a routine upgrade — most releases don’t touch the database image at all. If it didn’t change, skip this step; there’s nothing new to move for anchore-db.

Move the Images to the High Side

Choose one of the following, matching the equivalent step in the Air-Gapped Docker Compose deployment guide, for only the images that actually changed in step 2 (and step 3, if it applied):

• Private container registry (recommended) — re-tag, then push directly, or save/transfer/load/push, exactly as described in Option 1.
• Local image tarball — for hosts with no registry available, as described in Option 2.

Update Your Compose File

If this deployment was already deployed air-gapped, your docker-compose.yaml already points every image: line at your private registry or local image names — you only need to bump the tag on the lines that changed. The enterprise image is referenced by many services (api, catalog, component-catalog, queue, policy-engine, analyzer, reports, reports_worker, notifications, data-syncer, db-preflight), so update every occurrence:

  api:
    image: <registry>/anchore/enterprise:v6.1.0

Leave everything else in the file untouched — in particular, do not touch name: at the top of the file or the database volume name, per Step 2 of the main upgrade procedure. Changing either causes Compose to stand up a new, empty deployment instead of upgrading this one.

Restart the Stack

Continue with the main Upgrade using Docker Compose procedure starting at Step 7: Restart the Anchore Enterprise Containers — monitoring the catalog logs and verifying the new version with anchorectl system status need no changes for an air-gapped host.

2 - Upgrade on Kubernetes using Helm

This procedure upgrades a Helm deployment of Anchore Enterprise to a newer release within the same major version. Before you begin, review Prepare for the Upgrade.

Database column encryption is optional and off by default, so it is not a prerequisite for this upgrade. To enable it, supply a key — either anchoreConfig.database.encryption.currentKey in your values file, or ANCHORE_DB_ENCRYPTION_KEY_CURRENT in your own secret if you use useExistingSecrets: true. You can do this during this upgrade or at any later point. See Encrypting Database Secrets at Rest.

A Helm pre-upgrade hook initiates a Kubernetes job that scales down all active Anchore Enterprise pods and handles the Anchore Enterprise database upgrade.

The Helm upgrade is marked as successful only upon the job’s completion. This process causes the Helm client to pause until the job finishes and new Anchore Enterprise pods are initiated. To monitor the upgrade, you can follow the logs of the upgrade jobs:

kubectl get jobs -n ${NAMESPACE}
kubectl logs -f job/<JOB_NAME> -n ${NAMESPACE}

These jobs are automatically removed after a subsequent successful Helm upgrade.

An alternative post-upgrade hook is available to perform Anchore Enterprise upgrades without forcing all pods to terminate prior to running the upgrade. To enable the post-upgrade hook, set upgradeJob.usePostUpgradeHook=true in your values file.

1. View both the Helm Chart Release Notes for any necessary steps prior to upgrading and also review the Anchore Enterprise Release Notes

2. Update the Helm repository to get the latest chart version.

   helm repo update
   

3. Upgrade Anchore Enterprise using the Helm chart.

   export NAMESPACE=anchore
   export RELEASE=my-release
   
   helm upgrade ${RELEASE} -n ${NAMESPACE} anchore/enterprise -f anchore_values.yaml
   

4. Review the helm upgrade command output

5. Once upgraded, you can review the new state of your Anchore Enterprise install to verify the new version is running using the regular system status command.

   anchorectl system status
   

2.1 - Upgrade Air-Gapped using Helm

A routine v6.x upgrade in an air-gapped cluster needs the new chart version and any updated images mirrored to your registry before you run helm upgrade. This mirrors the same low-side/high-side process as Air-Gapped Helm deployment, but there’s less to move — you’re bumping versions on a running deployment, not standing up a new cluster.

Prepare the Chart and Images (low side)

1. Find the new chart version and download it:

   helm repo update
   helm search repo anchore/enterprise
   

   export CHART_VERSION="<new-chart-version-from-above>"
   
   helm pull anchore/enterprise --version ${CHART_VERSION}
   

2. Check what images that chart version actually references — redis and kubectlImage can change between chart releases independent of the Anchore Enterprise application version, so don’t assume they’re unchanged from your last upgrade:

   helm show values anchore/enterprise --version ${CHART_VERSION} | grep -E "^image:|repository:|tag:"
   

3. Pull the images:

   docker pull docker.io/anchore/enterprise:v6.1.0
   docker pull docker.io/anchore/enterprise-ui:v6.1.0
   docker pull docker.io/redis:<redis-tag-from-step-2>
   docker pull docker.io/bitnamilegacy/kubectl:<kubectl-tag-from-step-2>
   

   The v6.1.0 / v6.1.0 shortcodes always resolve to the version this documentation site currently covers. If you are upgrading to a different release, substitute that release’s actual tag instead.
   Unlike a fresh install, kubectlImage is always required for an upgrade, minor or major — the pre-upgrade hook (or the post-upgrade hook, if upgradeJob.usePostUpgradeHook: true) uses it to scale Anchore Enterprise pods during the upgrade.

Move the Chart and Images to the High Side

Choose one of the following, matching the equivalent step in the Air-Gapped Helm deployment guide:

• Private container registry (recommended) — re-tag, then save/transfer/load, then push from the high side, exactly as described in Option 1, but for the images pulled above.
• Local import onto cluster nodes — for small clusters with no registry available, as described in Option 2.
• Internal Helm repository or GitOps source — push the chart .tgz to your OCI registry or chart repository as described in Push the Chart to an Internal Helm Repository or GitOps Source.

Also transfer enterprise-${CHART_VERSION}.tgz to the high side along with the images.

Update Your Values File

If this cluster was deployed air-gapped, your existing anchore_values.yaml already points image, ui.image, and ui-redis.image at your private registry — you only need to bump the tags to the new version:

image: <registry>/anchore/enterprise:v6.1.0

ui:
  image: <registry>/anchore/enterprise-ui:v6.1.0

ui-redis:
  image:
    tag: <redis-tag-from-step-2>

kubectlImage: <registry>/bitnamilegacy/kubectl:<kubectl-tag-from-step-2>

If kubectlImage isn’t already set — for example, if this cluster’s values file hasn’t changed since a fresh install, which never uses it — add it now. See Deploy on the High Side on the deployment air-gapped page for the full registry-override block if you need the other image fields too.

Run the Upgrade from the Local Chart

Substitute the local chart archive — or your internal registry reference — for anchore/enterprise:

export NAMESPACE=anchore
export RELEASE=my-release

helm upgrade ${RELEASE} -n ${NAMESPACE} ./enterprise-${CHART_VERSION}.tgz -f anchore_values.yaml --timeout 3600s

or, from an internal OCI registry:

helm upgrade ${RELEASE} -n ${NAMESPACE} oci://<registry>/charts/enterprise --version ${CHART_VERSION} -f anchore_values.yaml --timeout 3600s

Continue with the rest of Upgrade on Kubernetes using Helm — monitoring the upgrade job logs and verifying with anchorectl system status — exactly as written.

3 - Upgrade the Cloud Image

Occasionally, Anchore will release updates to the Anchore Enterprise Cloud Image (AECI) and the subsequent version of Anchore Enterprise shipped with it. Upgrades are managed through the Cloud Image Manager, which will provide you with the upgrades that are available and allow you to determine when you want to upgrade.

If an upgrade is available, the Cloud Image Manager will walk you through the upgrade process. The upgrade involves a period of downtime and reboots, and the Cloud Image Manager tells you what to expect before proceeding. This will allow you to plan for the upgrade when it is convenient for you.

Prepare for the Upgrade

AECI runs the Anchore Enterprise GUI, API, and database together on a single virtual machine instance. That unified topology shapes how you prepare: the services share one failure domain, so an upgrade briefly affects all of them at once, and a snapshot of the instance’s volumes captures the whole system (application, configuration, and data) as one consistent restore point.

Before you begin:

• Review the release notes. Read the Anchore Enterprise Release Notes for the target version, with particular attention on the Requirements and Recommended Component Versions sections.

• Schedule a maintenance window and notify users. The GUI and API will be unavailable while services restart; a typical installation should expect approximately 20 minutes of downtime.

• Quiesce the system. Stop submitting new image scans and SBOM imports, and let in-flight analysis complete. Upgrading a quiet system keeps the database consistent and avoids cutting jobs off mid-run. To guarantee nothing new arrives during the window, consider temporarily blocking inbound traffic to the API and GUI in the instance’s network ingress rules (on platforms such as AWS, its security group) by removing the HTTPS (TCP 443) rule or restricting it to administrator addresses. Leave SSH (TCP 22) open, as it carries your Cloud Image Manager session, and restore the rule once you have verified the upgrade.

• Confirm the system is healthy. Use the Cloud Image Manager System Status screen to check that all services are running, and note the currently deployed versions so you know your starting point if you need to roll back. Do not upgrade a degraded deployment; resolve service issues first.

• Check disk space. The upgrade downloads new container images and may migrate data, so confirm there is free space on both the root and data volumes. If space is tight, expand the disks first; see Expand Disks.

• Snapshot your volumes. It is best practice to stop an instance before snapshotting its root volume (on platforms such as AWS, this is the documented recommendation). Once the system is quiesced, stop the instance, create snapshots of both the root and data volumes using your platform’s snapshot mechanism, and start the instance again before beginning the upgrade. Snapshotting while stopped guarantees the whole system, application, configuration, and data, is captured in a consistent state; the snapshots are your recovery point if the upgrade needs to be rolled back. Note that stopping and starting extends the maintenance window, and the instance’s public IP address may change unless you have assigned a static address (such as an Elastic IP on AWS). See Backups for broader backup and restore guidance.

• Change one thing at a time. Do not combine the upgrade with other changes to the instance, such as resizing it or expanding disks, in the same window. If those are needed, complete and verify them before you upgrade.

Upgrade using the Cloud Image Manager

Step 1: Connect to the Cloud Image Manager

Connect over SSH using your key pair and the instance address:

ssh -i ~/my-keypair.pem anchore@<instance-ip>

See Access the Cloud Image Manager for connection details and troubleshooting.

Step 2: Confirm Service Health

Review the System Status screen to confirm all services are healthy, and note the currently deployed versions.

Step 3: Open the Upgrade Screen

If upgrades are available for your deployment, the Updates available button in the Cloud Image Manager is highlighted yellow. Select it to open the upgrade screen.

Step 4: Run the Upgrade

The upgrade screen summarizes what to expect: the upgrade results in a period of downtime and reboots, with a typical installation expecting approximately 20 minutes of downtime. The Cloud Image Manager will prompt you to ensure you have taken your snapshots; it does not create them for you, so confirm the snapshots from your preparation are complete before you continue.

Select Start Upgrade and let the Cloud Image Manager run the upgrade to completion. Keep your SSH session open and do not interrupt the process while the upgrade is in progress.

Step 5: Verify the Result

When the upgrade finishes, the Cloud Image Manager shows Upgrade complete. Validate the system status in the Cloud Image Manager by opening the System Status screen and confirming that all services are running and the new versions are deployed.

Consider running a smoke test before handing the system back, for example logging in to the Anchore Enterprise GUI and scanning a known image. Then conduct any tasks needed to make the system available to users again, such as restoring the network ingress rules you changed during preparation and resuming paused CI/CD pipelines and integrations.

Roll Back if Needed

If the upgrade fails or the system does not come back healthy, the volume snapshots from your preparation are your recovery point into a new instance of the appliance. Contact Anchore Customer Success via support.anchore.com for assistance with restoring or troubleshooting.