Upgrading Anchore Enterprise

1 - Routine Upgrades (v6.x)

This section covers routine upgrades between releases within the same major version of Anchore Enterprise, for example from v6.1 to v6.2, or from v6.1.0 to v6.1.1. These upgrades are normally handled seamlessly by the Helm chart, an upsert of your Docker Compose configuration, or the Cloud Image Manager.

Prepare for the Upgrade

Prior to upgrading Anchore Enterprise, it is highly recommended to first review the Anchore Enterprise Release Notes for the target version, with particular attention on the Requirements and Recommended Component Versions sections.

• The Requirements section shares important notices and/or DB schema changes and any possible suggested downtime needed for schema and/or data changes.

• The Recommended Component Versions section details the supported versions of integration tooling like AnchoreCTL. This might require further upgrades of other software components across your environment to maintain compatibility with the core Anchore Enterprise service.

When you are ready to perform an upgrade, we recommend, as a best practice, that you first backup/snapshot your database. When backing up, you must first stop your Anchore Enterprise services/deployment so that all services have completed their writes. We also highly recommend you test upgrades in a QA/Test environment first.

Follow the Procedure for Your Deployment

• Upgrade using Docker Compose
• Upgrade on Kubernetes using Helm
• Upgrade the Cloud Image

1.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. The release notes call out breaking changes, new or changed configuration, and any version-specific upgrade instructions you need to plan for before starting.

Step 2: Stop Anchore Enterprise

docker compose down

Step 3: Back Up Your Data Volumes

As described in Prepare for the Upgrade, make a copy of any data volumes before proceeding.

Step 4: Back Up Your Original Compose File

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

Step 5: Update Your Compose File

Download the compose file that ships with the target release and check it against your current file to see if there any changes that may affect your deployment, such as new services, environment variables, or volume definitions:

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

name: "anchore-6001"
volumes:
  anchore-enterprise-6.0-db:
    external: false

Fold any relevant changes into your docker-compose.yaml. If the diff shows nothing beyond version bumps, confirm every service is still present in your file and update the image tags in place. All services using the enterprise image move to the new release tag, while the ui service uses the separately versioned enterprise-ui image:

 services:
   api:
-    image: docker.io/anchore/enterprise:v6.0.1
+    image: docker.io/anchore/enterprise:v6.1.1
   ui:
-    image: docker.io/anchore/enterprise-ui:v6.0.0
+    image: docker.io/anchore/enterprise-ui:v6.1.0

Step 6: Restart the Anchore Enterprise Containers

docker compose up -d

Step 7: Confirm the Services Start

Watch the output of the previous to confirm all the services start. Once they have all started, you can use the below command to list the running services and confirm that they are all healthy.

docker ps

Step 8: Verify the New Version Is Running

Once the containers are up, verify the new version is running:

anchorectl system status

1.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 project name or database volume name.

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.1
   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.1

Leave everything else in the file untouched — in particular, do not touch name: at the top of the file or the database volume name. 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 6: 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.

1.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
   

1.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.1
   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.1 / 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.1

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.

1.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.

2 - Major Upgrades (v5.x → v6.x)

Crossing a major version boundary of Anchore Enterprise is a migration rather than a routine upgrade. Major releases include breaking changes and data migrations, and moving between them requires planning, a maintenance window, and mechanism-specific steps that differ from the routine upgrade procedures.

Follow the migration guide for the boundary you are crossing:

• v5.x → v6.x Migration Guide — migrate a running Anchore Enterprise v5.x deployment to v6.x. Requires Anchore Enterprise v6.1.0 or later as the target version.

• v4.x → v5.x Migration Guide (EOL) — migrate an Anchore Enterprise v4.x deployment to v5.x. Anchore Enterprise v5.x is scheduled to reach end of life (EOL) in early 2027, so plan to continue to v6.x after completing this migration.

2.1 - v5.x → v6.x Migration Guide

This guide will help you understand, plan, and execute the migration of your Anchore Enterprise deployment from v5.x to v6.1.0 or later. The migration brings your database to PostgreSQL 17 (typically by dumping and restoring it into a new v6.1 deployment), and on first boot, Anchore Enterprise upgrades the database schema and migrates your v5.x SBOM data into the App / App Version / Asset data model automatically.

What Happens During the Migration

The first time v6.1 boots against your restored v5.x data, two things run automatically, and one v5.x feature does not migrate and needs your attention:

1. Schema upgrade — the standard Anchore Enterprise database upgrade chain brings the schema to the v6.1 level.

2. Legacy Imported SBOM migration — v5.x Imported SBOMs and SBOM Groups are migrated into the App / App Version / Asset / Artifact model:

   • Each v5.x SBOM Group becomes one App with a single version, with one Asset per SBOM in the group.
   • Each ungrouped v5.x SBOM becomes one App, App Version, and Asset.
   • Only the first 10 annotations per SBOM are carried over; any beyond that are dropped. If annotations matter to you, export them before migrating.
   • Identical SBOM content uploaded into multiple accounts becomes multiple Assets sharing a single Artifact, deduplicated on content hash.

   The Legacy Imported SBOM migration runs in the background after the schema upgrade completes. Your deployment is up and fully usable while it runs, though migrated SBOMs may not all appear as Apps, App Versions, and Assets until it finishes. Avoid interrupting services while the migration is in progress. Progress is recorded in the database, and each migration runbook includes steps to monitor and verify it.

3. Legacy Application Groups and source SBOMs are not migrated — there is no automatic migration for these. The data is retained in the database, but the Anchore Enterprise GUI no longer provides access to it; it remains reachable through the deprecated AnchoreCTL commands or the API directly. If your v5.x deployment uses Application Groups or source SBOMs, reach out to Anchore Customer Success via support.anchore.com for guidance on a plan to move this data to the App / App Version / Asset model before you migrate.

New Database Requirements in v6.x

Anchore Enterprise v6.x requires PostgreSQL 17 or greater with the pg_cron extension; these are new requirements in the v6.x line (see Requirements).

We recommend a managed database service (such as Amazon RDS, Google Cloud SQL, or Azure Database for PostgreSQL) where available, or the CloudNativePG (CNPG) operator for running PostgreSQL in-cluster on Kubernetes. The runbooks listed in Run the Migration cover both moving your data into a new PostgreSQL 17 database and upgrading an existing external database in place.

Plan the Migration

Before you begin, make sure you have:

• A valid license entitlement.
• A review of the Anchore Enterprise Release Notes behind you, with particular attention on the Requirements and Recommended Component Versions sections. Read the v6.0.0 release notes as well, not only the notes for your target version: v6.0.0 carried most of the v6 deprecations and removals, and migrating from v5.x means crossing all of them.
• A database backup taken before you start. Together with your untouched v5.x data it is your rollback path.
• Enough disk space for the database dump if you are moving your data with a dump and restore (roughly the size of your v5.x database; the compressed custom format is smaller).
• A decision on at-rest encryption of sensitive database columns, such as stored registry credentials. It is off by default and can be enabled during the migration or at any time later; see Encrypting Database Secrets at Rest.
• A maintenance window. The v5.x deployment must be stopped for the dump, and the Legacy Imported SBOM migration runs on first boot of v6.1. As a reference point, roughly 35,000 SBOM records completed in about 2 hours on modest hardware. Scale expectations to your data.

Run the Migration

Follow the runbook for your deployment mechanism; each includes its own verification steps:

• Migrate using Docker Compose
• Migrate on Kubernetes using Helm
• Migrate the Cloud Image

2.1.1 - Migrate using Docker Compose

This runbook migrates a running Anchore Enterprise v5.x Docker Compose deployment to v6.1 or later. It assumes the commands are run on the host where the deployment lives. Before you begin, read the migration overview to understand what the migration does and what you need in place.

Rather than editing your existing v5.x docker-compose.yaml file in place, this guide has you start from a clean copy of the v6.x reference compose file and move your data into it.

The migration has two parts:

• Migrate the underlying database from PostgreSQL 13 to PostgreSQL 17, exporting your v5.x data and restoring it into the new database.
• Replace the v5.x application stack with a new deployment built from the v6.x reference compose file, running the v6.x images on the new migrated database.

Starting from the v6.x template takes care of both at once: the template already runs PostgreSQL 17, and once your data is restored into it, Anchore Enterprise upgrades its own database schema automatically on first boot.

Prerequisites

Before you begin, make sure you have:

• Confirm the deployment is currently running a supported Anchore Enterprise v5.x release. Check the Recommended Component Versions table in the Release Notes for the version you’re moving from.
• Docker and Docker Compose installed and up to date.
• A valid license.yaml.
• Ensure sufficient disk space exists for database backups, temporary migration files, and the additional PostgreSQL volume: a full second copy of your database’s data directory, plus the export file, at minimum.
• A maintenance window — you will need to stop the deployment and writes to the database before the final export in Step 8 so no data is missed.

Downtime Expectations

This migration requires application downtime during the database export and restore. Downtime duration depends on database size, disk performance, and system resources.

Migration Procedure

Step 1: Stop All Services

docker compose down --remove-orphans

This begins the downtime window.

Step 2: Back Up Your Existing Configuration

Before making any changes, back up the existing docker-compose.yaml and, optionally, the Docker volumes. Store the backup somewhere safe so it is not accidentally reused or deleted.

cp docker-compose.yaml docker-compose-v5.yaml.bak

Step 3: Set Up a New Deployment Directory

Create a separate directory for the v6.x deployment. Do not reuse your v5.x deployment directory. This method keeps the two deployments, and their compose projects, independent until you’re ready to retire v5.x.

mkdir anchore-enterprise-v6 && cd anchore-enterprise-v6

Step 4: Download the v6.x Deployment Files

Your new v6.x directory needs the v6.x docker-compose.yaml file, your license file copied over from the old v5.x directory, and the Dockerfile we provide for building the new PostgreSQL 17 database:

curl -sSfL https://docs.anchore.com/current/docs/deployment/docker_compose/docker-compose.yaml > docker-compose.yaml
curl -sSfL https://docs.anchore.com/current/docs/deployment/docker_compose/Dockerfile.anchore-db > Dockerfile.anchore-db
cp /path/to/your/v5-license.yaml ./license.yaml

Step 5: Configure Secrets

Follow Step 4: Configure Secrets in the standard deployment guide to set POSTGRES_PASSWORD, ANCHORE_ADMIN_PASSWORD, ANCHORE_AUTH_SECRET, and ANCHORE_DB_PASSWORD. These are fresh secrets for the new deployment; they do not need to match the values your v5.x deployment used.

Step 6: Start Only the New Database

docker compose up -d anchore-db

Wait for it to report healthy before continuing:

docker compose ps anchore-db

Step 7: Restart the v5.x Database

Step 1 stopped every v5.x service, including anchore-db, but the export in the next step needs it running. From your v5.x deployment directory, restart just the database:

cd /path/to/v5-directory
docker compose up -d anchore-db

The downtime window from Step 1 stays intact: the application services remain stopped, so nothing writes to the database, and anchore-db does not publish a host port, so it cannot conflict with the new v6.x database started in Step 6.

Step 8: Export the v5.x Database

From your v5.x deployment directory, export the database straight into the new v6.x deployment directory. You can decide where to archive the dump file once the migration is complete:

docker compose exec -T anchore-db pg_dump -U postgres -Fc -d postgres -f /tmp/anchore-v5-export.dump
docker compose cp anchore-db:/tmp/anchore-v5-export.dump /path/to/v6-directory/anchore-v5-export.dump

Step 9: Restore the Data into the New Database

From your new v6.x deployment directory, run the following to restore the export taken from the old database into the new one:

cd /path/to/v6-directory
docker compose exec -T anchore-db pg_restore -U postgres -d postgres --clean --if-exists --no-owner < ./anchore-v5-export.dump

Step 10: Start the Full v6.x Deployment

Again, from inside the new v6.x deployment directory, run the following to bring up the full v6.x deployment:

docker compose up -d

Anchore Enterprise performs its own database schema migration in-process on first boot, upgrading your restored v5.x data to the v6.x schema automatically; no separate migration command is needed.

Step 11: Stop the v5.x Database

Step 7 restarted the v5.x anchore-db service, but now that the data has been imported into the new v6 database we can stop the v5 database from continuing to run from your old v5.x deployment directory:

cd /path/to/v5-directory
docker compose down anchore-db

Step 12: Validate the Upgrade

Retire the Old v5.x Deployment (Optional)

Once the upgrade is validated and you are confident you will not need to roll back, you can take the final (and completely optional) step of removing the old v5.x database volume. Our recommendation is to retain the database dump file, the original compose file, and the volume until the upgraded deployment has been fully validated in production.

docker volume rm <your-old-db-volume-name>

2.1.1.1 - Migrate Air-Gapped using Docker Compose

If the deployment host has no outbound internet access, complete this guide before Step 4: Download the v6.x Deployment Files in the main migration runbook. It mirrors the low-side/high-side process in Air-Gapped Docker Compose deployment: the v6.x reference compose file, database Dockerfile, and application images all need to reach the high side before you can start the new deployment, in addition to the database dump you already have to move as part of the migration itself.

Prepare the Files and Images (low side)

1. Download the v6.x compose file and database Dockerfile:

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

2. Pull the v6.x application images:

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

3. Build the database image from Dockerfile.anchore-db:

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

Move the Files and Images to the High Side

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

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

Also transfer docker-compose.yaml, Dockerfile.anchore-db, and your license.yaml to the high side along with the images. You’ll need docker-compose.yaml in Step 4 of the main runbook; the Dockerfile is kept for reference even though anchore:db is already built.

Point Your Compose File at the Registry (or Local Images)

Update the image: lines in your new docker-compose.yaml exactly as described in Deploy on the High Side on the deployment air-gapped page. Point every service referencing docker.io/anchore/enterprise and docker.io/anchore/enterprise-ui at your registry tag or locally loaded image name, replace anchore-db’s build: section with a direct image: <registry>/anchore:db (or image: anchore:db for a local tarball) reference, and update the redis image line the same way.

Run the Migration from the Local Files

Continue with the main migration runbook starting at Step 4, substituting the compose file you just edited for the one Step 4 would otherwise download, and skipping the curl commands there; you already have both files from the low side.

Every other step needs no changes for an air-gapped host:

• Step 5: Configure Secrets through Step 11: Validate the Upgrade run exactly as written.
• Step 8: Export the v5.x Database and Step 9: Restore the Data into the New Database are a direct pg_dump/pg_restore against your own database containers and require no internet access either way.

2.1.2 - Migrate on Kubernetes using Helm

This runbook migrates a running Anchore Enterprise v5.x Helm deployment to v6.1 or later. Before you begin, read the migration overview to understand what the migration does and what you need in place.

The v6.x Helm chart (the enterprise chart v4.1+ to migrate) requires a customer-provided PostgreSQL 17 database with the pg_cron extension. Unlike the v5.x chart, it does not deploy a PostgreSQL instance for you. How much work the migration involves depends on where your v5.x database runs today:

• If your v5.x deployment already uses an external PostgreSQL database, you upgrade that database to PostgreSQL 17, enable pg_cron, update your values file, and run helm upgrade. No data is moved. Follow Path A.
• If your v5.x deployment uses the chart’s bundled (Bitnami) PostgreSQL, that subchart is removed in v6.x. You must migrate your data into a new PostgreSQL 17 database before installing v6.1. Follow Path B.

Prerequisites

Complete these steps regardless of which path you follow.

• A running v5.x Helm deployment (v5.0.0 or later) with admin access to its PostgreSQL database.
• A provisioned or upgradeable PostgreSQL 17 database with the pg_cron extension, cron.use_background_workers enabled, and USAGE on the cron schema granted to the Anchore user. See Requirements.
• A CNCF-certified Kubernetes version within the chart’s supported kubeVersion range (1.23–1.36 at the time of writing), Helm v3.8+, and kubectl configured for the target cluster.
• A valid v6.x license. Optionally a database encryption key: at-rest column encryption is off by default and can be enabled now or later, so it is not a prerequisite for migrating. See the migration overview.
• A v6.1 values file built from the enterprise chart v4.1+. Do not reuse your v5-era values file unchanged — several keys were removed, renamed, or relocated in v6.x. See Values File Changes.

Set some environment variables used throughout this runbook:

export RELEASE=<your-helm-release-name>
export NAMESPACE=<your-namespace>

Confirm the license and pull-credential secrets already exist in your namespace (they carry over from v5.x):

kubectl get secret anchore-enterprise-license -n ${NAMESPACE}
kubectl get secret anchore-enterprise-pullcreds -n ${NAMESPACE}

Back Up the Database

This step is critical. Because the schema migration is one-way, this backup is your only way back to v5.x.

# Dump from the v5.x database in custom format (adjust host/user/db as needed).
# For the chart's bundled PostgreSQL, exec into the postgres pod:
kubectl exec -it ${RELEASE}-postgresql-0 -n ${NAMESPACE} -- \
  pg_dump -U anchore -d anchore -Fc -f /tmp/anchore_backup.dump

# Copy the dump off the pod to durable storage
kubectl cp ${NAMESPACE}/${RELEASE}-postgresql-0:/tmp/anchore_backup.dump ./anchore_backup.dump

Verify the backup is usable, then store it somewhere durable (not on ephemeral pod storage):

ls -lh anchore_backup.dump
pg_restore --list anchore_backup.dump | head -20

Path A: Upgrade with an Existing External PostgreSQL

Use this path if your v5.x deployment already connects to an external PostgreSQL database (RDS, Cloud SQL, CNPG, or self-managed). This is the simplest path — your data stays where it is.

Step 1: Upgrade PostgreSQL to 17 and Enable pg_cron

If your database is not already on PostgreSQL 17+, upgrade it first. Take a snapshot before upgrading.

• Amazon RDS: Use the RDS major version upgrade process.
• Google Cloud SQL: Use the in-place major version upgrade.
• CloudNativePG: Update spec.imageName to a PostgreSQL 17 image that includes pg_cron; the operator performs a rolling restart.
• Self-managed: Upgrade using your normal process.

Then enable pg_cron using your platform’s method (see the provider-specific steps in the EKS, GKE, and AKS guides). In every case, finish by creating the extension and granting the Anchore user access to the cron schema:

CREATE EXTENSION IF NOT EXISTS pg_cron;
GRANT USAGE ON SCHEMA cron TO <ANCHORE_DB_USER>;

Step 2: Update Your Values File

Apply the changes in Values File Changes to your existing values file. At minimum, remove postgresql.chartEnabled and any other removed keys, and relocate any settings you previously passed via extraEnv.

Step 3: Run the Upgrade

helm upgrade ${RELEASE} -n ${NAMESPACE} anchore/enterprise -f anchore-values.yaml

The chart runs its database upgrade job (upgradeJob, executed as a pre-upgrade hook) automatically during helm upgrade. It verifies database connectivity, scales down the running v5.x pods, runs the database schema migration, and then starts all services on the v6.1 image. Do not interrupt this process. The Legacy Imported SBOM migration then runs in the background on first boot.

Continue to Verify the Migration.

Path B: Migrate Off the Bundled PostgreSQL

Use this path if your v5.x deployment uses the chart’s bundled Bitnami PostgreSQL (postgresql.chartEnabled: true). That subchart is removed in v6.x, and it runs PostgreSQL 13 by default (or another pre-17 version if you overrode the image tag) — so you must move your data to a new PostgreSQL 17 database before installing v6.1.

Step 1: Scale Down Anchore Enterprise

Stop all Anchore Enterprise services so no writes occur during the migration. Leave the bundled PostgreSQL pod running.

for deploy in $(kubectl get deploy -n ${NAMESPACE} -l app.kubernetes.io/name=${RELEASE}-enterprise -o name); do
  kubectl scale ${deploy} -n ${NAMESPACE} --replicas=0
done

# Verify all Anchore Enterprise pods are gone (the PostgreSQL pod should still be running)
kubectl get pods -n ${NAMESPACE}

Step 2: Provision the PostgreSQL 17 Database

Stand up a new PostgreSQL 17 database with pg_cron enabled, using the same database name as your v5.x database (for example, anchore), and grant the Anchore user USAGE on the cron schema. Use a managed service (see the EKS / GKE / AKS guides) or an in-cluster operator (see Run PostgreSQL In-Cluster with CloudNativePG).

Step 3: Move Your Data

Choose one migration method.

Method A: pg_dump / pg_restore (Any Target)

This works for any PostgreSQL 17 target. Dump from the bundled PostgreSQL pod (you may already have this from Back Up the Database):

kubectl exec -it ${RELEASE}-postgresql-0 -n ${NAMESPACE} -- \
  pg_dump -U anchore -d anchore -Fc -f /tmp/anchore_full.dump
kubectl cp ${NAMESPACE}/${RELEASE}-postgresql-0:/tmp/anchore_full.dump ./anchore_full.dump

Restore into the new PostgreSQL 17 database (reachable from where you run this):

pg_restore -h <TARGET_HOST> -U anchore -d anchore \
  --no-owner --no-privileges --clean --if-exists \
  anchore_full.dump

Verify the tables restored:

psql -h <TARGET_HOST> -U anchore -d anchore -c "\dt" | head -30

Method B: CloudNativePG Bootstrap Import

If your target is CloudNativePG, CNPG can import directly from the running bundled PostgreSQL using its bootstrap.initdb.import feature, so you do not run pg_dump/pg_restore by hand. Follow the CNPG operator and custom-image setup in the main deployment guide, then create a Cluster with an import bootstrap that points its externalClusters source at the ${RELEASE}-postgresql service. The bundled PostgreSQL pod must stay running during the import.

After the import completes, two follow-up tasks are required before the database is usable:

1. Create the pg_cron extension. A CNPG import bootstrap does not run the cluster’s postInitApplicationSQL, so the pg_cron extension is not created automatically, even though shared_preload_libraries includes pg_cron. Anchore Enterprise v6.x will not start without it. Create it on the imported database manually:

   kubectl exec -it anchore-pg-1 -n ${NAMESPACE} -- \
     psql -U postgres -d anchore -c \
     "CREATE EXTENSION IF NOT EXISTS pg_cron; GRANT USAGE ON SCHEMA cron TO anchore;"
   

2. Reset the Anchore role’s password. PostgreSQL 13 may store password hashes in the older md5 format, which PostgreSQL 17 does not accept, leaving every service failing to authenticate. Reset the password on the new database so it is rewritten using scram-sha-256:

   kubectl exec -it <new-pg-pod> -n ${NAMESPACE} -- \
     psql -U postgres -d anchore -c \
     "SET password_encryption = 'scram-sha-256'; ALTER ROLE anchore WITH PASSWORD '<PASSWORD>';"
   

Step 4: Update Your Values File

Create your v6.1 values file pointing at the new database, applying the changes in Values File Changes. A minimal example:

licenseSecretName: anchore-enterprise-license
imagePullSecretName: anchore-enterprise-pullcreds

postgresql:
  externalEndpoint: <NEW_DB_HOST>   # e.g. anchore-pg-rw.anchore.svc for CNPG
  auth:
    username: anchore
    password: <PASSWORD>
    database: anchore
  port: 5432

Step 5: Install v6.x

Choose one of two approaches based on your risk tolerance.

• Approach 1 — helm upgrade in place (recommended). Keeps the same release name, service names, and any existing ingress/DNS configuration. Because the v5.x release is already scaled down and the data has moved, upgrade the existing release directly:

  helm upgrade ${RELEASE} -n ${NAMESPACE} anchore/enterprise -f anchore-values.yaml
  

  Helm cleans up the old bundled PostgreSQL resources during the upgrade. A PVC may be left behind; remove it once you have verified the new deployment:

  kubectl get pvc -n ${NAMESPACE} -l app.kubernetes.io/name=postgresql
  # kubectl delete pvc data-${RELEASE}-postgresql-0 -n ${NAMESPACE}
  

• Approach 2 — install as a new release (side-by-side). Keeps the scaled-down v5.x release as a safety net until you are confident. Install with a new release name:

  helm install anchore-v6 -n ${NAMESPACE} anchore/enterprise -f anchore-values.yaml
  

  A new release name changes every Kubernetes resource name (services, deployments) to the new prefix. After you verify v6.1 and uninstall the old release, you must update anything that referenced the old service names: ingress rules, DNS/load-balancer targets, CI/CD anchorectl or API URLs, and monitoring scrape targets.

Continue to Verify the Migration.

Values File Changes

Several chart values were removed, renamed, or relocated in v6.x. Review your existing values file against the tables below before running helm upgrade. The chart validates these on install/upgrade and fails fast with a descriptive error if a removed or relocated key is present, so it is safe to iterate.

Removed and Restructured Keys

Settings Moved Out of extraEnv

In v6.x, a number of settings that were commonly passed as environment variables via extraEnv must be set in their dedicated anchoreConfig value instead. The chart rejects these environment variables and will not install or upgrade until they are moved.

Verify the Migration

After the upgrade, watch the pods come up and confirm system status:

kubectl get pods -n ${NAMESPACE} -w

# Port-forward the API and check status (use the new release name for Path B, Approach 2)
kubectl port-forward svc/${RELEASE}-enterprise-api 8228:8228 -n ${NAMESPACE}
anchorectl system status
anchorectl system feeds list

Confirm that all services report up, that your existing images, policies, and scan results are present, that feed syncs are running, and that the UI is reachable.

The Legacy Imported SBOM migration runs in the background on first boot; your deployment is fully usable while it runs, though migrated SBOMs may not all appear as Apps, App Versions, and Assets until it finishes. Report its progress with anchore-enterprise-manager, which reads the database directly and so must be run from inside a running Anchore Enterprise pod:

kubectl exec -it deploy/${RELEASE}-enterprise-catalog -n ${NAMESPACE} -- bash -c \
  'anchore-enterprise-manager --json db --db-connect postgresql://"${ANCHORE_DB_USER}":"${ANCHORE_DB_PASSWORD}"@"${ANCHORE_DB_HOST}":"${ANCHORE_DB_PORT}"/"${ANCHORE_DB_NAME}" legacy-sbom-migration-status'

The database environment variables are already present in every Anchore Enterprise pod, so the connection string above needs no editing. It is quoted for the pod’s shell to expand, not yours.

{
  "message": "Legacy SBOM Migration is in progress. SBOM mappings migrated so far: 604, SBOM mappings remaining: 549, SBOM mappings failed to migrate: 0",
  "migrated": 604,
  "remaining": 549,
  "state": "in_progress",
  "total": 1153,
  "failed": 0
}

state reports one of:

The counts are SBOM mappings — one per SBOM per SBOM Group it belongs to, plus one per empty SBOM Group — not SBOM documents, so the total will exceed your imported SBOM count when SBOMs belong to more than one group. Drop --json to print the message line on its own.

If the migration ends as complete_with_failures, contact Anchore Customer Success via support.anchore.com before retiring your v5.x backup.

Roll Back

Rollback restores the pre-upgrade state from your backup, because the schema migration cannot be reversed.

1. Uninstall or scale down the v6.1 release.
2. Restore the database backup taken in Back Up the Database into a v5.x-compatible PostgreSQL instance.
3. Restart or reinstall the v5.x release pointing at the restored database.
4. Verify all services come back up with your pre-upgrade data intact.

Any work done in v6.1 after cutover is lost on rollback, so keep the v6.1 trial period write-light until you commit to it.

Troubleshooting

2.1.2.1 - Migrate Air-Gapped using Helm

If the cluster has no outbound internet access, complete this guide before Back Up the Database in the main migration runbook. It mirrors the low-side/high-side process in Air-Gapped Helm deployment, with one difference: this time kubectlImage must be mirrored too, because the pre-upgrade hook’s migration job actually runs it to scale down the v5.x pods — a fresh install never touches that image.

Prepare the Chart and Images (low side)

1. Add the chart repository and find the current chart version — use enterprise chart v4.1+, which ships Anchore Enterprise v6.1.0 or later:

   helm repo add anchore https://charts.anchore.io
   helm search repo anchore/enterprise
   

2. Download (pull) the chart archive:

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

3. Pull the images the migration needs:

   docker pull docker.io/anchore/enterprise:v6.1.1
   docker pull docker.io/anchore/enterprise-ui:v6.1.0
   docker pull docker.io/redis:7.4.6
   docker pull docker.io/bitnamilegacy/kubectl:1.30
   

   Unlike a fresh install, mirroring bitnamilegacy/kubectl:1.30 (the chart’s kubectlImage) is required here — the osaaMigrationJob and upgradeJob hooks use it to scale down the v5.x deployments before the schema migration runs.

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 push directly, or save/transfer/load/push, exactly as described in Option 1, but for all four 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 and the v6.x values file you build in Values File Changes to the high side along with the images.

Point Your Values File at the Registry

Add the registry overrides to your v6.x values file:

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

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

ui-redis:
  image:
    registry: <registry>
    repository: redis
    tag: 7.4.6
    pullSecrets:
      - anchore-enterprise-pullcreds

kubectlImage: <registry>/bitnamilegacy/kubectl:1.30

Create (or update) the image pull secret to point at your private registry instead of Docker Hub, as described under Deploy on the High Side on the deployment air-gapped page.

Run the Migration from the Local Chart

Whichever path you follow in the migration runbook, complete Back Up the Database first. It needs no changes for an air-gapped cluster — pg_dump/pg_restore run directly against your database and require no internet access. Since you are already staging the chart and images for transfer, store the backup in that same durable storage.

Then substitute the local chart archive — or your internal registry reference — for anchore/enterprise in every helm upgrade/helm install command below.

Path A: Upgrade with an Existing External PostgreSQL

In Step 3: Run the Upgrade:

helm upgrade ${RELEASE} -n ${NAMESPACE} ./enterprise-${CHART_VERSION}.tgz -f anchore-values.yaml --timeout 30m

or, from an internal OCI registry:

helm upgrade ${RELEASE} -n ${NAMESPACE} oci://<registry>/charts/enterprise --version ${CHART_VERSION} -f anchore-values.yaml --timeout 30m

Path B: Migrate Off the Bundled PostgreSQL

Follow Path B through Step 1: Scale Down Anchore Enterprise and Step 2: Provision the PostgreSQL 17 Database as written — provisioning the new database doesn’t depend on the Anchore chart or images.

For Step 3: Move Your Data:

• Method A: pg_dump/pg_restore needs no changes — it’s a direct database-to-database copy and does not touch the Anchore chart or images.

• Method B: CloudNativePG Bootstrap Import additionally requires the CNPG operator chart, the CNPG operator image, and your custom pg_cron-enabled PostgreSQL image on the high side — none of which are part of the Anchore chart. Mirror all three exactly as described in step 4 of the deployment air-gapped guide (chart repo add/pull, operator image pull, custom image build), and include them in the same tarball you save and transfer in Move the Chart and Images to the High Side above. If you already mirrored these for a prior air-gapped deployment using the same registry, no extra mirroring is needed here.

  Also save a cnpg-cluster.yaml on the low side now, same as step 4e in that guide, but using Method B’s bootstrap-import configuration (the bootstrap.initdb.import block pointing externalClusters at ${RELEASE}-postgresql) instead of a plain new cluster — leave imageName as a placeholder until the high side.

  On the high side, install the operator from the local chart and point its image at your registry exactly as described in Install CloudNativePG and Provision the Database on the deployment air-gapped page. Then fill in imageName in your transferred cnpg-cluster.yaml and apply it — keeping the bundled v5.x PostgreSQL pod running during the import, per the warning in Method B.

At Step 5: Install v6.x, substitute the local chart archive (or internal registry reference) in whichever approach you choose:

# Approach 1 — helm upgrade in place
helm upgrade ${RELEASE} -n ${NAMESPACE} ./enterprise-${CHART_VERSION}.tgz -f anchore-values.yaml --timeout 30m

# Approach 2 — install as a new release
helm install anchore-v6 -n ${NAMESPACE} ./enterprise-${CHART_VERSION}.tgz -f anchore-values.yaml --timeout 30m

or, from an internal OCI registry, replace ./enterprise-${CHART_VERSION}.tgz with oci://<registry>/charts/enterprise --version ${CHART_VERSION} in either command.

2.1.3 - Migrate the Cloud Image

This page covers migrating an Anchore Enterprise Cloud Image (AECI) deployment from v5.x to v6.x.

2.2 - v4.x → v5.x Migration Guide (EOL)

This guide will help you understand, plan, and execute the migration of your Anchore Enterprise deployment from

Enterprise v4.x --> Enterprise v5.x

The Enterprise v5.x Major Release involved several breaking changes. The migration to a v5.x release can be more complex than the regular Anchore Enterprise feature release upgrade.

There are four significant component changes required to migrate to Enterprise v5.x that each have their own migration paths. This document will help you migrate all components in a safe and downtime-minimizing way.

The components are:

1. Anchore Enterprise: provides a new V2 API.
   • v5.x only supports the new V2 API
   • v4.9.x supports both V1 and V2 APIs
2. PostgreSQL Database: required version 13+ for Enterprise v5.x
3. Enterprise Helm Chart:
   • v5.x can be deployed only with the new enterprise Helm chart.
   • The older anchore-engine chart will be at end-of-life with the 4.x series.
4. Integrations & Clients: all Anchore-provided integrations have new released versions that are compatible with v5.x and support the new V2 API.

This guide will walk you through the process to go from this starting state.

Pre Migration: <= v4.8 with V1 API Only

graph
anchore("Enterprise <= v4.8 w/V1 API")
db[("PostgreSQL 9.6")]
chart["anchore-engine chart"]
ctl["anchorectl v1.x"]

anchore --uses--> db
chart --deploys--> anchore
ctl --v1 api calls-->anchore

To this ending state where you are in production running Enterprise v5.x.

Post Migration: Full v5.x with V2 API Only

graph
anchore("Enterprise v5.x w/V2 API")
db[("PostgreSQL 13+")]
chart["enterprise chart"]
ctl["anchorectl v5.x"]

anchore --uses--> db;
chart --deploys--> anchore
ctl --v2 api calls-->anchore

Plan Your Migration

Timing: Each phase has different duration expectations, and below we’ll review the expectations and process for each phase of the migration. You should expect and plan for downtime for each phase except the client API migrations, which are done while the system is running.

The migration may be a multi-day process since it involves things like client migrations that may take days or weeks depending on your org and how many other systems are integrated with your Anchore Enterprise deployment.

Combining Phases: Phases can be combined if you wish to use a smaller number of larger maintenance windows. Since combining phases increases the complexity of each phase and associated risk of misconfigurations or errors, the combination should be carefully considered for your specific needs and risk tolerance.

Migration Path 1: Chart-Managed Database

If you have PostgreSQL deployed in Kubernetes using the Anchore-Engine Helm Chart, then this is the migration path for you.

graph
    subgraph Start
    %% Start at v4.8.x or earlier, using postgres 9.6 and the anchore-engine helm chart
        anchore4("Enterprise <= v4.8.x")
        pg9[("PostgreSQL 9.6")]
        engineChart["anchore-engine chart"]
        anchorectl("anchorectl v1.7.x") --V1 api calls--> anchore4
        anchore4 --uses--> pg9
        engineChart --deploys--> anchore4
    end
    
    subgraph step1[Latest Enterprise v4.9.x]
        %% Upgrade to v4.9.x for V2 API
        anchore49_1("Enterprise v4.9.x")
        pg9_2[("PostgreSQL 9.6")]
        engineChart1["anchore-engine chart"]
        anchore49_1 --uses--> pg9_2
        anchorectl3("anchorectl v1.8.x") --V1 api calls--> anchore49_1
        engineChart1 --deploys--> anchore49_1
    end

    subgraph step2[Chart and DB Migrated]
    %% Migrate to new Chart & DB Migration to PG13, no Anchore Enterprise version change
        anchore49("Enterprise = v4.9.x")
        pg13[("PostgreSQL 13+")]
        pg96[("PostgreSQL 9.6")]
        engineChart2["anchore-engine chart"]
        enterpriseChart["enterprise chart"]
        engineChart2 --uses--> pg96
        pg96 --migrates to--> pg13
        anchore49 --uses--> pg13
        anchorectl2("anchorectl v1.8.x") --V1 api calls--> anchore49
        enterpriseChart --deploys--> anchore49
    end

    subgraph step3[Integrations Migrated]
    %% Upgrade integrations/AnchoreCTL
        anchoreInter3("Enterprise v4.9.x")
        engineChart3["anchore-engine chart"]
        enterpriseChart2["enterprise chart"]
        pg13_4[("PostgreSQL 13+")]
        pg96_2[("PostgreSQL 9.6")]
        engineChart3 --> pg96_2
        anchoreInter3 --> pg13_4
        anchorectl5("anchorectl v4.9.x") --V2 api calls--> anchoreInter3
        enterpriseChart2 --deploys--> anchoreInter3
    end

    subgraph finish["Enterprise v5.x"]
    %% Upgrade to v5.x
        anchore5("Enterprise v5.x")
        enterpriseChart3["enterprise chart"]
        pg13_5[("PostgreSQL 13+")]
        anchore5 --> pg13_5
        anchorectl6("anchorectl v5.x") --V2 api calls--> anchore5
        enterpriseChart3 --deploys--> anchore5
    end

    Start --Upgrade Anchore Enterprise to latest v4.9.x release--> step1;
    step1 --Migrate to Enterprise Chart and PG13+ DB--> step2;
    step2 --Migrate integrations & anchorectl to use V2 API--> step3;
    step3 --Upgrade Anchore Enterprise to v5.x & delete 4.0.x deployment--> finish;

Step 1: Upgrade Anchore Enterprise to latest v4.9.x Release

Downtime: Required

Upgrade your Anchore Enterprise deployment to v4.9.x. This is an important step for several reasons:

1. It is supported by both the legacy anchore-engine helm chart and the new enterprise helm chart
2. It supports PostgreSQL 9.6+ and newer (13+), so it provides a stable base to execute the other upgrade steps
3. It supports both the V1 and V2 APIs, so you can have a stable Anchore Enterprise version for updating all your integrations

Upgrade mechanism: normal Anchore Enterprise upgrade process

Step 2: Migrate to Enterprise Chart, 4.9.x and PostgreSQL 13

Downtime: Required

Helm Migration Guide

Step 3: Migrate all integrations and clients to V2 API compatible versions

Downtime: None for Anchore Enterprise itself, but individual integrations may vary

Once your deployment is running v4.9.x you have a stable platform to migrate integrations and clients to using the V2 API of Enterprise. You should perform the upgrades/migrations for the new V2 API in this phase. This phase may last for a while and does not end until all your API calls are using the V2 endpoint instead of V1.

Upgrading AnchoreCTL Usage in CI

The installation script provided via Deploying AnchoreCTL will only automatically deploy new releases that are V1 API compatible, so you need to update use of that script to include specific versions.

For example, use:

curl -sSfL  https://anchorectl-releases.anchore.io/anchorectl/install.sh  | sh -s -- -b <DESTINATION_DIR> v4.9.0

Confirming V1 API is no longer in use

To verify that all clients have been updated, you can review the logs from the API containers in your v4.9.x deployment. We recommend that you monitor for multiple days to verify there are no periodic processes that still use the old endpoint.

Step 4: Upgrade from Enterprise 4.9.x to 5.9 using 2.10.0 of the chart

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

You will want to install the compatible version of AnchoreCTL 5.9.0 at this time as well.

curl -sSfL  https://anchorectl-releases.anchore.io/anchorectl/install.sh  | sh -s -- -b <DESTINATION_DIR> 5.9.0

Step 5: Upgrade from Enterprise 5.9 to Enterprise 5.27.3 (final v5.x release)

Helm Upgrade Guide

Upgrading AnchoreCTL

You will want to install the compatible version of AnchoreCTL (v5.27.3) at this time as well:

curl -sSfL https://anchorectl-releases.anchore.io/anchorectl/install.sh \
  | sh -s -- -b <DESTINATION_DIR> v5.27.3

Migration Path 2: External DB

If you deploy PostgreSQL using any mechanism other than the Anchore-provided chart (e.g. AWS RDS, your own DB chart, Google CloudSQL, etc.), then this is the migration plan for you.

graph
    subgraph Start[Enterprise v4.x]
        anchoreStart("Enterprise <= v4.8.X")
        pg9[("PostgreSQL 9.6")]
        engineChart["anchore-engine chart"]
        anchorectl("anchorectl v1.7.x") --V1 api calls--> anchoreStart
        anchoreStart --uses--> pg9
        engineChart --deploys--> anchoreStart
    end
    
    subgraph step1[Latest Enterprise v4.9.x]
        %% Upgrade to v4.9.x for V2
        anchoreInter1("Enterprise v4.9.x")
        pg9_2[("PostgreSQL 9.6")]
        engineChart2["anchore-engine chart"]
        anchoreInter1 --uses--> pg9_2
        anchorectl3("anchorectl v1.8.x") --V1 api calls--> anchoreInter1
        engineChart2 --deploys--> anchoreInter1
    end

    subgraph step2[Enterprise Helm Chart]
        %% Use new chart
        anchoreInter2("Enterprise v4.9.x")
        enterpriseChart["enterprise chart"]
        pg9_3[("PostgreSQL 9.6")]
        anchoreInter2 --> pg9_3
        anchorectl4("anchorectl v1.8.x") --V1 api calls--> anchoreInter2
        enterpriseChart --deploys--> anchoreInter2
    end
    
    subgraph step3[PostgreSQL 13+]
    %% Migrate to PG13+ , no Anchore Enterprise version change
        anchoreInter3("Enterprise = v4.9.x")
        pg13[("PostgreSQL 13+")]
        enterpriseChart2["enterprise chart"]
        anchoreInter3 --uses--> pg13
        anchorectl2("anchorectl v1.8.x") --V1 api calls--> anchoreInter3
        enterpriseChart2 --deploys--> anchoreInter3
    end
    
    subgraph step4[Integrations using V2 API]
    %% Upgrade integrations/AnchoreCTL
        anchoreInter4("Enterprise v4.9.x")
        enterpriseChart3["enterprise chart"]
        pg13_4[("PostgreSQL 13+")]
        anchoreInter4 --> pg13_4
        anchorectl5("anchorectl v4.9.x") --V2 api calls--> anchoreInter4
        enterpriseChart3 --deploys--> anchoreInter4
    end

    subgraph finish[Enterprise v5.x]
    %% Upgrade to v5.x
        anchore5("Enterprise v5.x")
        enterpriseChart4["enterprise chart"]
        pg13_5[("PostgreSQL 13+")]
        anchore5 --> pg13_5
        anchorectl6("anchorectl v5.x") --V2 api calls--> anchore5
        enterpriseChart4 --deploys--> anchore5
    end

    Start --Upgrade to latest v4.9.x Enterprise--> step1;
    step1 --Migrate to Enterprise Helm Chart--> step2;
    step2 --Upgrade External DB to PostgreSQL 13+--> step3;
    step3 --Migrate Integrations and AnchoreCTL to use V2 API--> step4;
    step4 --Upgrade Anchore Enterprise to v5.x --> finish;

Step 1: Upgrade to latest Anchore Enterprise v4.9.x

Downtime: Required

Upgrade your Anchore Enterprise deployment to v4.9.x. This is an important step for several reasons:

1. It is supported by both the legacy anchore-engine helm chart and the new enterprise helm chart
2. It supports PostgreSQL 9.6+ and newer (13+), so it provides a stable base to execute the other upgrade steps
3. It supports both the V1 and V2 APIs, so you can have a stable Anchore Enterprise version for updating all your integrations

Step 2: Upgrade PostgreSQL from 9.6.x to 13+

Downtime: Required

Enterprise v5.x requires PostgreSQL 13 or later to run. The DB upgrade process will be specific to your deployment mechanisms and way of running Postgres. Depending on what version of PostgreSQL you are running when you start, there may be multiple DB upgrade operations necessary in PostgreSQL to get to 13+.

However, this upgrade can be done with any Anchore Enterprise version. All 4.x versions of Anchore Enterprise already support PostgreSQL 13+, so the DB upgrade can be executed outside any changes to the Anchore Enterprise deployment itself.

If you are using AWS RDS or another cloud platform for hosting your PostgreSQL database, please refer to their upgrade documentation for the best practices to upgrade your instance(s) to version 13 or higher.

Step 3: Migrate to Enterprise Helm Chart

Downtime: Required

Helm Migration Guide

Step 4: Upgrade all your integrations/clients to use the V2 API

Downtime: None for Anchore Enterprise itself, but individual integrations may vary

Once your deployment is running v4.9.x you have a stable platform to migrate integrations and clients to using the V2 API of Enterprise. You should perform the upgrades/migrations for the new V2 API in this phase. This phase may last for a while and does not end until all your API calls are using the V2 endpoint instead of V1.

Upgrading AnchoreCTL Usage in CI

The installation script provided via Deploying AnchoreCTL will only automatically deploy new releases that are V1 API compatible, so you need to update use of that script to include specific versions.

For example, use:

curl -sSfL  https://anchorectl-releases.anchore.io/anchorectl/install.sh  | sh -s -- -b <DESTINATION_DIR> v4.9.0

Confirming V1 API is no longer in use

To verify that all clients have been updated, you can review the logs from the API containers in your v4.9.x deployment. We recommend that you monitor for multiple days to verify there are no periodic processes that still use the old endpoint.

Step 5: Upgrade from Enterprise 4.9.x to 5.9 using 2.10.0 of the chart

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

You will want to install the compatible version of AnchoreCTL 5.9.0 at this time as well.

curl -sSfL  https://anchorectl-releases.anchore.io/anchorectl/install.sh  | sh -s -- -b <DESTINATION_DIR> 5.9.0

Step 6: Upgrade from Enterprise 5.9 to Enterprise 5.27.3 (final v5.x release)

Helm Upgrade Guide

Upgrading AnchoreCTL

You will want to install the compatible version of AnchoreCTL (v5.27.3) at this time as well:

curl -sSfL https://anchorectl-releases.anchore.io/anchorectl/install.sh \
  | sh -s -- -b <DESTINATION_DIR> v5.27.3

Verify the Upgrade

Verify the version you’re using of AnchoreCTL

anchorectl version – All users should see v5.27.3 for the AnchoreCTL version

anchorectl system status – The system should return v5.27.3