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:
- 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
- PostgreSQL Database: required version 13+ for Enterprise v5.3.0
- 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.
- 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
To this ending state where you are in production running Enterprise v5.3.0.
Post Migration: Full v5.3.0 with V2 API Only
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.
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 newenterprise 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
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.3.0
Downtime: required
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.
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 newenterprise 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.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
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.
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 5: Upgrade to Enterprise v5.3.0
Downtime: required
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