v4.x --> v5.x Migration Guide

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

Enterprise v4.x --> Enterprise v5.3.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 feature release upgrade.

There are four significant component changes required to migrate to Enterprise v5.3.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.
    • v5.3.0 only supports the new V2 API
    • v4.9.x supports both V1 and V2 APIs
  2. PostgreSQL Database: required version 13+ for Enterprise v5.3.0
  3. Enterprise Helm Chart:
    • v5.3.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 v5.3.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 v5.3.0.

Post Migration: Full v5.3.0 with V2 API Only

graph anchore("Enterprise v5.3.0 w/V2 API") db[("PostgreSQL 13+")] chart["enterprise chart"] ctl["anchorectl v5.3.0"] anchore --uses--> db; chart --deploys--> anchore ctl --v2 api calls-->anchore

Note: The upgrade to v4.9.x is very strongly recommended for all deployments as a key part of the migration process to v5.3.0. If you use ANY integrations or API calls you should use v4.9.x and its dual-API support as the version of Anchore to run while you migrate all you integrations to use the V2 API.

Planning 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 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 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.3.0"] %% Upgrade to v5.3.0 anchore5("Enterprise v5.3.0") enterpriseChart3["enterprise chart"] pg13_5[("PostgreSQL 13+")] anchore5 --> pg13_5 anchorectl6("anchorectl v5.3.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 v5.3.0 & delete 4.0.x deployment--> finish;

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

Downtime: Required

Upgrade your Anchore 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 version for updating all your integrations

Upgrade mechanism: normal Anchore Enterprise upgrade process

Step 2: Migrate to Enterprise Chart and PostgreSQL 13

Downtime: Required

Helm Migration Guide

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

Downtime: None for Anchore 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.

IntegrationRecommended V2 API Compatible Version
AnchoreCTLv4.9.0
anchore-k8s-inventoryv1.1.1
anchore-ecs-inventoryv1.2.0
Kubernetes Admission Controllerv0.5.0
Jenkins Pluginv1.1.0
Harbor Scanner Adapterv1.2.0
enterprise-gitlab-scanv4.0.0

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 to Enterprise v5.3.0

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

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

curl -sSfL  https://anchorectl-releases.anchore.io/anchorectl/install.sh  | sh -s -- -b <DESTINATION_DIR> v5.3.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 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.3.0] %% Upgrade to v5.3.0 anchore5("Enterprise v5.3.0") enterpriseChart4["enterprise chart"] pg13_5[("PostgreSQL 13+")] anchore5 --> pg13_5 anchorectl6("anchorectl v5.3.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 to v5.3.0 --> finish;

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

Downtime: Required

Upgrade your Anchore 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 version for updating all your integrations

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

Downtime: Required

Enterprise v5.3.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 version. All 4.x versions of Anchore already support PostgreSQL 13+, so the DB upgrade can be executed outside any changes to the Anchore 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 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.

IntegrationRecommended V2 API Compatible Version
AnchoreCTLv4.9.0
anchore-k8s-inventoryv1.1.1
anchore-ecs-inventoryv1.2.0
Kubernetes Admission Controllerv0.5.0
Jenkins Pluginv1.1.0
Harbor Scanner Adapterv1.2.0
enterprise-gitlab-scanv4.0.0

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 to Enterprise v5.3.0

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

Verifying the Upgrade

Verify the version you’re using of AnchoreCTL

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

anchorectl system status – The system should return v5.3.0

Last modified January 5, 2024