Major Upgrades (v5.x → v6.x)

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

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.1 reference compose file and move your data into it.

The migration has two parts: we safely migrate the underlying PostgreSQL database from PostgreSQL 13 to PostgreSQL 17, and we then move the actual Anchore Enterprise application images from v5.x to v6.1. Starting from the v6.1 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 5 so no data is missed.

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. Please file away the backup of the file somewhere safe so that you do not accidentally use/delete it.

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

Step 3: Set Up a New Deployment Directory

Create a separate directory for the v6.1 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 will need a new v6.1 formatted docker-compose.yaml file, your license file which we can copy from the old v5.x directory, and a Dockerfile that we also provide for download from our official documentation site for building the new Postgres 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: Export the v5.x Database

From your v5.x deployment directory, stop writes and export the database - we are going to export it to our new v6 deployment directory and then from there you can decide where you want to move it to after 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-deployment/anchore-v5-export.dump

Step 8: Restore the Data into the New Database

From your new v6.x deployment directory run the below command to restore data from the export that you previously took from the old database into the new database:

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

Step 9: Start the Full v6.x Deployment

Again, from inside the new v6.x deployment directory run the below to bring up the full v6 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.1 schema automatically — no separate migration command is needed.

Step 10: Validate the Upgrade

Retire the Old v5.x Deployment (Optional)

Once the upgrade is validated and you feel comfortable and confident you won’t need to roll back, you can take the real final (but completely optional!) step of removing the v5.x deployment’s volume backup. Our recommendation is to retain the database dump file, the original compose file, and the volume backup until the upgraded deployment has been fully validated in production.

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

Downtime Expectations

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

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.0
   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, and 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 10: Validate the Upgrade run exactly as written.
• Step 7: Export the v5.x Database and Step 8: 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.

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

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

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.

1.3 - Migrate the Cloud Image

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

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 v6.1.0

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 v6.1.0 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.
   • v6.1.0 only supports the new V2 API
   • v4.9.x supports both V1 and V2 APIs
2. PostgreSQL Database: required version 13+ for Enterprise v6.1.0
3. Enterprise Helm Chart:
   • v6.1.0 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 v6.1.0 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 v6.1.0.

Post Migration: Full v6.1.0 with V2 API Only

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

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 v6.1.0"]
    %% Upgrade to v6.1.0
        anchore5("Enterprise v6.1.0")
        enterpriseChart3["enterprise chart"]
        pg13_5[("PostgreSQL 13+")]
        anchore5 --> pg13_5
        anchorectl6("anchorectl v6.1.0") --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 v6.1.0 & 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 Current Version

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

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 v6.1.0]
    %% Upgrade to v6.1.0
        anchore5("Enterprise v6.1.0")
        enterpriseChart4["enterprise chart"]
        pg13_5[("PostgreSQL 13+")]
        anchore5 --> pg13_5
        anchorectl6("anchorectl v6.1.0") --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 v6.1.0 --> 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 v6.1.0 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 Current Version

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

Verify the Upgrade

Verify the version you’re using of AnchoreCTL

anchorectl version – All users should see v6.1.0 for the AnchoreCTL version

anchorectl system status – The system should return v6.1.0