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.13.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.13.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.13.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.13.0
3. Enterprise Helm Chart:
   • v5.13.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.13.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.13.0.

Post Migration: Full v5.13.0 with V2 API Only

graph
anchore("Enterprise v5.13.0 w/V2 API")
db[("PostgreSQL 13+")]
chart["enterprise chart"]
ctl["anchorectl v5.13.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.13.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.13.0"]
    %% Upgrade to v5.13.0
        anchore5("Enterprise v5.13.0")
        enterpriseChart3["enterprise chart"]
        pg13_5[("PostgreSQL 13+")]
        anchore5 --> pg13_5
        anchorectl6("anchorectl v5.13.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.13.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, 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 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 v5.13.0

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

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 v5.13.0

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

Verifying the Upgrade

Verify the version you’re using of AnchoreCTL

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

anchorectl system status – The system should return v5.13.0