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.3        │
│ apiext          │ anchore-quickstart │ http://api:8228             │ true │ available      │ 25         │ 4.9.3        │
│ rbac_manager    │ anchore-quickstart │ http://rbac-manager:8228    │ true │ available      │ 25         │ 4.9.3        │
│ notifications   │ anchore-quickstart │ http://notifications:8228   │ true │ available      │ 25         │ 4.9.3        │
│ catalog         │ anchore-quickstart │ http://catalog:8228         │ true │ available      │ 25         │ 4.9.3        │
│ rbac_authorizer │ anchore-quickstart │ http://rbac-authorizer:8228 │ true │ available      │ 25         │ 4.9.3        │
│ reports_worker  │ anchore-quickstart │ http://reports-worker:8228  │ true │ available      │ 25         │ 4.9.3        │
│ reports         │ anchore-quickstart │ http://reports:8228         │ true │ available      │ 25         │ 4.9.3        │
│ simplequeue     │ anchore-quickstart │ http://queue:8228           │ true │ available      │ 25         │ 4.9.3        │
│ policy_engine   │ anchore-quickstart │ http://policy-engine:8228   │ true │ available      │ 25         │ 4.9.3        │
└─────────────────┴────────────────────┴─────────────────────────────┴──────┴────────────────┴────────────┴──────────────┘

In this example the Anchore version is 4.9.3 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.3 will be the last supported deployment with this chart.
Anchore Enterprise Helm Chart
- Supports deployments of Enterprise v4.9.3 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 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 - 5.0 Migration Guide

This guide will help you understand, plan, and execute the migration of your Anchore deployment from Enterprise 4.x to 5.0. The Enterprise 5.0 motion involves several breaking changes and is a migration that is more complex than the regular Anchore feature release upgrade.

There are 4 significant component changes required to migrate to Enterprise 5.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:

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

Note: This is a recommended migration process that ends with a running 5.0 deployment, but you may start the migration today or wait until after 5.0 is released. The Anchore software does not force you to upgrade at new releases so take your time and plan the migration steps when it makes sense for you.

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

Post Migration: Full 5.0 with V2 API Only

graph anchore("Enterprise v5.0.x w/V2 API") db[("PostgreSQL 13+")] chart["enterprise chart"] ctl["anchorectl v5.0.x"] 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 5.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.0"] %% Upgrade to v5.0 anchore5("Enterprise v5.x") enterpriseChart3["enterprise chart"] pg13_5[("PostgreSQL 13+")] anchore5 --> pg13_5 anchorectl6("anchorectl v5.0.x") --V2 api calls--> anchore5 enterpriseChart3 --deploys--> anchore5 end Start --Upgrade Anchore Enterprise to latest v4.9.x release--> step1; step1 --Migrate to Enterprise Chart and PG13+ DB--> step2; step2 --Migrate integrations & anchorectl to use V2 API--> step3; step3 --Upgrade Anchore Enterprise to v5.x & delete 4.0.x deployment--> finish;

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

Downtime: Required

Upgrade your Anchore 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.0

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

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.0.x] %% Upgrade to v5.0.x anchore5("Enterprise v5.0.x") enterpriseChart4["enterprise chart"] pg13_5[("PostgreSQL 13+")] anchore5 --> pg13_5 anchorectl6("anchorectl v5.0.x") --V2 api calls--> anchore5 enterpriseChart4 --deploys--> anchore5 end Start --Upgrade to latest v4.9.x Enterprise--> step1; step1 --Migrate to Enterprise Helm Chart--> step2; step2 --Upgrade External DB to PostgreSQL 13+--> step3; step3 --Migrate Integrations and AnchoreCTL to use V2 API--> step4; step4 --Upgrade Anchore to v5.0.x --> 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.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

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

Downtime: required

Helm Upgrade Guide

Upgrading AnchoreCTL

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

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

Verifying the Upgrade

Verify the version you’re using of AnchoreCTL anchorectl version – All users should see ‘5.0.1’ for the AnchoreCTL version anchorectl system status – The system should return ‘v5.0.0’