This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Upgrading Anchore Enterprise

Upgrading from one version of Anchore Enterprise to another is normally handled seamlessly by the Helm chart or the docker compose configuration files that are provided along with each release. Those follow the general methods from this guide. See Specific Instructions section for special instructions related to specific versions.

Upgrade scenarios

Anchore Enterprise is distributed as a docker image, which is composed of smaller micro-services that can be deployed in a single container or scaled out to handle load.

To retrieve the version of a running instance of Anchore, the anchorectl system status command can be run. The last column titled “CODE VERSION”, will display the running version of each service.

anchorectl system status
 ✔ Status system                                                                                                                                                                                                                                                            
┌─────────────────┬────────────────────┬─────────────────────────────┬──────┬────────────────┬────────────┬──────────────┐
│ SERVICE         │ HOST ID            │ URL                         │ UP   │ STATUS MESSAGE │ DB VERSION │ CODE VERSION │
├─────────────────┼────────────────────┼─────────────────────────────┼──────┼────────────────┼────────────┼──────────────┤
│ analyzer        │ anchore-quickstart │ http://analyzer:8228        │ true │ available      │ 25         │ 4.9.5        │
│ apiext          │ anchore-quickstart │ http://api:8228             │ true │ available      │ 25         │ 4.9.5        │
│ rbac_manager    │ anchore-quickstart │ http://rbac-manager:8228    │ true │ available      │ 25         │ 4.9.5        │
│ notifications   │ anchore-quickstart │ http://notifications:8228   │ true │ available      │ 25         │ 4.9.5        │
│ catalog         │ anchore-quickstart │ http://catalog:8228         │ true │ available      │ 25         │ 4.9.5        │
│ rbac_authorizer │ anchore-quickstart │ http://rbac-authorizer:8228 │ true │ available      │ 25         │ 4.9.5        │
│ reports_worker  │ anchore-quickstart │ http://reports-worker:8228  │ true │ available      │ 25         │ 4.9.5        │
│ reports         │ anchore-quickstart │ http://reports:8228         │ true │ available      │ 25         │ 4.9.5        │
│ simplequeue     │ anchore-quickstart │ http://queue:8228           │ true │ available      │ 25         │ 4.9.5        │
│ policy_engine   │ anchore-quickstart │ http://policy-engine:8228   │ true │ available      │ 25         │ 4.9.5        │
└─────────────────┴────────────────────┴─────────────────────────────┴──────┴────────────────┴────────────┴──────────────┘

In this example the Anchore version is 4.9.5 and the database schema is version 25. In cases where the database schema is changed between releases, Anchore will upgrade the database schema at launch.

Pre-upgrade Procedure

Prior to upgrading Anchore, it is highly recommended to perform a database backup/snapshot by stopping your Anchore installation, and backup the database in its entirety. There is no automatic downgrade capability, thus the only way to downgrade after an upgrade (whether it succeeds or fails) is to restore your database contents to a state from a prior version of Anchore, and explicitly run the compatible version of Anchore against the corresponding database contents.

Whether you wish to have the ability to downgrade or not, we recommend backing up your Anchore database prior to upgrading the software as a best practice.

Upgrade Procedure (for deployments using Helm)

A Helm pre-upgrade hook initiates a Kubernetes job that scales down all active Anchore Enterprise pods and handles the Anchore 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, follow the logs of the upgrade jobs. These jobs are automatically removed after a subsequent successful Helm upgrade.

An optional post-upgrade hook is available to perform Anchore Enterprise upgrades without forcing all pods to terminate prior to running the upgrade. This is the same upgrade behavior that was enabled by default in the legacy anchore-engine chart. To enable the post-upgrade hook, set upgradeJob.usePostUpgradeHook=true in your values file.

For the latest upgrade instructions using the Helm chart, please refer to the official Anchore Helm Chart documentation

Anchore Engine Helm Chart (deprecated)
- Enterprise v4.9.5 will be the last supported deployment with this chart.
Anchore Enterprise Helm Chart
- Supports deployments of Enterprise v4.9.5 and greater.

Performing the Upgrade

View the release notes for the latest Anchore Enterprise chart version and perform any necessary steps prior to upgrading.
Update the Helm repository to get the latest chart version.
```
helm repo update
```

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

Upgrade Procedure (example with docker compose)

Stop all running instances of Anchore
```
docker compose down
```
Make a copy of your original docker-compose.yaml file as backup
```
cp docker-compose.yaml docker.compose.yaml.backup
```

Download the latest docker-compose.yaml

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

Review the latest docker-compose.yaml and merge any edits/changes from your original docker-compose.yaml.backup to the latest docker-compose.yaml
Restart the Anchore containers
```
docker compose up -d
```

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

docker compose logs -f catalog

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

anchorectl system status

Advanced / Manual Upgrade Procedure

If for any reason the automated upgrade fails, or you would like to perform the upgrade of the anchore database manually, you can use the following (general) procedure. This should only be done by advanced operators after backing up the anchore database, ensuring that the anchore database is up and running, and that all running anchore components are stopped.

Install the desired Anchore container manually.
Run the Anchore container but override the entrypoint to run an interactive shell instead of the default ‘anchore-manager service start’ entrypoint command.
Manually execute the database upgrade command, using the appropriate db_connect string. For example, if using Postgres, the db_connect string will look like postgresql://$ANCHORE_DB_HOST/$ANCHORE_DB_NAME?user=$ANCHORE_DB_USER&password=$ANCHORE_DB_PASSWORD

$ anchore-manager db --db-connect "postgresql://$ANCHORE_DB_HOST/$ANCHORE_DB_NAME?user=$ANCHORE_DB_USER&password=$ANCHORE_DB_PASSWORD" upgrade

[MainThread] [anchore_manager.cli.utils/connect_database()] [INFO] DB params: {"db_connect_args": {"timeout": 86400, "ssl": false}, "db_pool_size": 30, "db_pool_max_overflow": 100}
[MainThread] [anchore_manager.cli.utils/connect_database()] [INFO] DB connection configured: True
[MainThread] [anchore_manager.cli.utils/connect_database()] [INFO] DB attempting to connect...
[MainThread] [anchore_manager.cli.utils/connect_database()] [INFO] DB connected: True
...
...

The output will indicate whether or not a database upgrade is needed. It will then prompt for confirmation if it is, and will display upgrade progress output before completing.

Specific Version Upgrades

This section is intended as a guide for any special instructions and information related to upgrading to specific versions of Enterprise.

Upgrading Enterprise v4.x to Enterprise v5.11.1

5.X Migration Guide

Upgrading Enterprise to 4.4.1

If you are upgrading from an Anchore Enterprise version prior to 4.2.0, there is a known issue that will require you to upgrade to 4.2.0 or 4.3.0 first. Once completed, you will have no issues upgrading to 4.4.1. Please contact Anchore Support if you need further assistance.

Please Note: This issue was addressed in 4.5.0. Upgrading from a version prior to 4.2.0 will succeed in 4.5.0 and newer releases.

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

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.11.1 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:

Anchore Enterprise: provides a new V2 API.
- v5.11.1 only supports the new V2 API
- v4.9.x supports both V1 and V2 APIs
PostgreSQL Database: required version 13+ for Enterprise v5.11.1
Enterprise Helm Chart:
- v5.11.1 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.
Integrations & Clients: all Anchore-provided integrations have new released versions that are compatible with v5.11.1 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.11.1.

Post Migration: Full v5.11.1 with V2 API Only

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

It is supported by both the legacy anchore-engine helm chart and the new enterprise helm chart
It supports PostgreSQL 9.6+ and newer (13+), so it provides a stable base to execute the other upgrade steps
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.

Integration	Recommended V2 API Compatible Version
AnchoreCTL	v4.9.0
anchore-k8s-inventory	v1.1.1
anchore-ecs-inventory	v1.2.0
Kubernetes Admission Controller	v0.5.0
Jenkins Plugin	v1.1.0
Harbor Scanner Adapter	v1.2.0
enterprise-gitlab-scan	v4.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.11.1

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

It is supported by both the legacy anchore-engine helm chart and the new enterprise helm chart
It supports PostgreSQL 9.6+ and newer (13+), so it provides a stable base to execute the other upgrade steps
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.11.1 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

Integration	Recommended V2 API Compatible Version
AnchoreCTL	v4.9.0
anchore-k8s-inventory	v1.1.1
anchore-ecs-inventory	v1.2.0
Kubernetes Admission Controller	v0.5.0
Jenkins Plugin	v1.1.0
Harbor Scanner Adapter	v1.2.0
enterprise-gitlab-scan	v4.0.0

Upgrading AnchoreCTL Usage in CI

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

Step 5: Upgrade to Enterprise v5.11.1

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

Verifying the Upgrade

Verify the version you’re using of AnchoreCTL

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

anchorectl system status – The system should return v5.11.1