This migration tool assists in migrating anapigeectl-based hybrid cluster to a Helm-based hybrid cluster. This tool performs no actual replacement of any cluster components. It is idempotent and can be run many times on the same cluster, preparing a subset of components and orgs each time.

SeeInstalling and managing Apigee hybrid with Helm charts for information about managing hybrid clusters you have migrated to Helm management with this tool.

Prerequisites

• Helm version v3.10+. SeeInstalling Helm.
• A workingkubeconfig file pointing to a cluster with a working Apigee hybrid 1.11 installation.
• Permissions to modify the metadata and annotations on the Kubernetes resources of the hybrid components that you wish to migrate.

Scope

This tool supports the following options at run-time:

• Customization of namespace forapigee resources. Default namespace:apigee
• Migration of selected hybrid components only. Default: all components are migrated
• Migration of a single org only
• Migration of a single env only
• Migration of a single env-group (apigee-virtualhost) only
• Customization of Helm release names for orgs, envs, and env-groups.

Limitations

• This tool does not support customizing Helm release names for these hybrid components:apigee-operator,apigee-datastore,apigee-redis,apigee-telemetry, andapigee-ingress-manager.
• Interactive customizations made to the Helm release names for orgs, envs, and env-groups do not automatically persist between runs. You can edit the temp file and supply it as an option in later runs.

• Env and env-group filtering is done by name only. In some cases this could result in multiple envs and env-groups being migrated on multi-org clusters.

  For example, on a multi-org cluster with orgsorg1 andorg2, if the envprod is present in both orgs, and only--env=prod is specified, both envs will be migrated. If you wish to only migrate a single env, you must also specify an org filter--org=org1 or--org=org2.

Usage

Syntax

apigee-helm-migration [--apigee-namespace=] [--components=] [--dry-run] [--env=org1] [--env-group=org2] [--org=baz] [--kubeconfig=] [-y] [-v] [-f /path/to/releaseNames.yaml]

Generated Helm release names

Every Helm Chart that is deployed on a cluster needs to have a release name, which must be unique within a namespace. Helm release names don't have any naming convention or restriction relative to the chart name. The migration tool generates unique Helm release names for every component.

Customizing Helm release names

The migration tool allows interactive customization of Helm release names. If you want to customize the Helm release names non-interactively:

1. Run the tool once and exit at the first prompt to create a temporary file containing the auto-generated release names. You should see a line like:

   INFO:21:32:56usingtempfileforreleasenames:/tmp/apigee-helm-migration-1229129207-releaseNames

2. Move or copy and then edit this file. You can pass this edited file in with the-f option when yourun the migration tool. The auto-generated release names look like:

   orgs:example-apigee-org:helmReleaseName:example-apigee-orgenvs:prod:helmReleaseName:prodenvGroups:prod-envgroup:helmReleaseName:prod-envgroup

   To customize the Helm release names for an org, env, or envgroup, edit thehelmReleaseName field of that object. For example, to rename the org release tocustom-org, the env release tocustom-env, and the envgroup release tocustom-group, the resulting file looks like:

   orgs:example-apigee-org:helmReleaseName:custom-orgenvs:prod:helmReleaseName:custom-envenvGroups:prod-envgroup:helmReleaseName:custom-group

Using custom namespaces

Apigee hybrid runs in two Kubernetes namespaces:

• apigee-system: Theapigee-operator component always runs in theapigee-system namespace. The Helm migration tool will update theapigee-operator component in theapigee-system namespace regardless of what you specify with the--apigee-namespace flag.
• apigee: All hybrid components exceptapigee-operator run in this namespace.apigee is the default name. You can use any custom namespace for these components.

  If you use a custom namespace, you must specify the it with the--apigee-namespacemy_custom_namespace flag when you run the Helm migration tool.

  You must also add thenamespace:my_custom_namespace top-level property to your overrides file.

Directions

1. Download the migration tool.

   Linux

   1. Store the latest version number in a variable using the following command:

      export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")

   2. Check that the variable was populated with a version number using the following command. If you want to use a different version, you can save that in an environment variable instead.

      echo $VERSION

      For example:

      1.0.5

   3. Download the release package for your operating system using the following command:

      curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_linux_64.tar.gz

   4. Extract the compressed files using the following command:

      tar -xzf apigee-helm-migration_linux_64.tar.gz

   Mac OS

   1. Store the latest version number in a variable using the following command:

      export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")

   2. Check that the variable was populated with a version number using the following command. If you want to use a different version, you can save that in an environment variable instead.

      echo $VERSION

      For example:

      1.0.5

   3. Download the release package for your operating system using the following command:

      curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_mac_64.tar.gz

   4. Extract the compressed files using the following command:

      tar -xzf apigee-helm-migration_mac_64.tar.gz

   Windows

   1. Store the latest version number in a variable using the following command:

      for /f "tokens=*" %a in ('curl -s https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt') do set VERSION=%a

   2. Check that the variable was populated with a version number using the following command. If you want to use a different version, you can save that in an environment variable instead.

      echo %VERSION%

      For example:

      1.0.5

   3. Download the release package for your operating system using the following command:

      curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/%VERSION%/apigee-helm-migration_windows_64.tar.gz

   4. Extract the compressed files using the following command:

      tar xzvf apigee-helm-migration_windows_64.tar.gz

2. Run the migration tool. If the default options are acceptable, it is sufficient to run the tool without any arguments, and approve the prompt if the generated helm release names are satisfactory. Some example scenarios are given below:

   • A simple installation, using the defaultkubeconfig (~/.kube/config), defaultapigee namespace, and default Helm release names.

     The following command should be sufficient for most, if not all, installations. Helm upgrade operations can be done on a per-component basis after the tool is run.

     ./apigee-helm-migration

   • Migrating all components using a custom namespace:

     ./apigee-helm-migration --apigee-namespacemy_custom_namespace

   • Migrating only theoperator anddatastore components:

     ./apigee-helm-migration --components operator,datastore

       INFO: 00:22:48 using kubeconfig file  /usr/local/google/home/example/.kube/config  INFO: 00:22:48 namespace for apigee resources:  INFO: 00:22:48  apigee  INFO: 00:22:48 processing all organizations in cluster  INFO: 00:22:48 Components to migrate:  INFO: 00:22:48  operator,datastore  INFO: 00:22:48 dry-run:  INFO: 00:22:48  false  Continue with patching apigee resources for Helm migration? [y/n]: y  INFO: 00:22:52 Processing component:  operator  INFO: 00:22:54 Processing component:  datastore  INFO: 00:22:55 Migration successful!

   • Pointing to a specifickubeconfig file and specifying a different name for theapigee namespace.

     ./apigee-helm-migration --kubeconfig/abs/path/to/kubeconf --namespaceorg1_namespace

   • Migrating all components, but only a single org:

     ./apigee-helm-migration --org=some-test-org

   The following shows an example output from a successful migration:

   INFO:21:32:55usingkubeconfigfile/usr/local/google/home/example/.kube/configINFO:21:32:55namespaceforapigeeresources:INFO:21:32:55apigeeINFO:21:32:55processingallorganizationsinclusterINFO:21:32:55processingallcomponentsINFO:21:32:55dry-run:INFO:21:32:55falseINFO:21:32:55clusterApigeeinformation:INFO:21:32:55ApigeeOrganizationsfound:INFO:21:32:56example-hybrid-devINFO:21:32:56ApigeeEnvironmentsfound(org:env):INFO:21:32:56example-hybrid-dev:prodINFO:21:32:56ApigeeEnvGroups(apigeerouteconfigs)found(org:envGroup):INFO:21:32:56example-hybrid-dev:prod-envgroupINFO:21:32:56usingtempfileforreleasenames:/tmp/apigee-helm-migration-1229129207-releaseNamesINFO:21:32:56HelmreleasenamesforApigeeorgs/envs/envgroups:orgs:example-hybrid-dev:helmReleaseName:example-hybrid-devenvs:prod:helmReleaseName:prodenvGroups:prod-envgroup:helmReleaseName:prod-envgroupMakechangestothereleasenamesforApigeeorgs/env/envgroups? [y/n]:nContinuewithpatchingapigeeresourcesforHelmmigration?[y/n]:yINFO:21:32:59Processingcomponent:operatorINFO:21:33:01Processingcomponent:datastoreINFO:21:33:01Processingcomponent:redisINFO:21:33:02Processingcomponent:ingress-managerINFO:21:33:02Processingcomponent:telemetryINFO:21:33:03Processingcomponent:orgsINFO:21:33:05Processingcomponent:envsINFO:21:33:06Processingcomponent:env-groupsINFO:21:33:07Migrationsuccessful!

   Potential errors:

   • Error parsing release names file: Check the passed in release names file.
   • Resources not found: Check that Apigee hybrid is fully installed, and you have permissions to access theapigee resources.

Configuration properties changes

Make the following changes in your overrides files:

• Usemetrics.appStackdriverExporter.* instead ofmetrics.aggregator.*.
• Apigee hybrid managed with Helm usesapigeeIngressGateway properties to configure all Apigee ingress gateways in your cluster.ingressGateways properties override the settings inapigeeIngressGateway for the individual named ingress gateway.

  SeeapigeeIngressGateway

  • Create an additionalapigeeIngressGateway stanza in your overrides file for anyingressGateways properties that are global to all ingress gateways in your cluster. For example:

    apigeeIngressGateway:  image:    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"    tag: "TAG"

    For example:

    apigeeIngressGateway:  image:    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"    tag: "1.17.8-asm.20-distroless"

  • Make sure to includeingressGateways.name. It is required to instantiate your ingress gateway. For example:

  ingressGateways:- name:INGRESS_GATEWAY_NAME

Note:ingressGateways is a collection of individualingressGateway instances. It manages the configuration of theingressGateway instances. UseingressGateways in your overrides file.
• The properties to enable Workload Identity have changed:
  • gcp.workloadIdentity.enabled replacesgcp.workloadIdentityEnabled.
  • If you are using a single service account for all components, you can specify it with:gcp.workloadIdentity.gsa. For example:

    gcp:  workloadIdentity:    enabled: true    gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"

  • If you are using a separate service account for each component (the standard for most prod installations), specify the service account with the component'sgsa property. For example:

    logger:  gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"

  See:gcp.workloadIdentity.enabled andEnabling Workload Identity with Helm.

Troubleshooting

There is aknown issue with the Helm migration tool in the hybrid v1.11 release. Until theissue is resolved,Cassandra backup and restore requires additional steps.

You can follow these steps:

• Before or after running the migration tool
• Before installing Helm charts

To install the patch for the workaround:

1. Make sure that your currentkubeconfig is pointing to the cluster you want to migrate. You can can perform these steps from any directory.
2. Create a file namedmigration-operator-patch.yaml with the following contents:

   # migration-operator-patch.yamlmetadata:annotations:meta.helm.sh/release-name:operatormeta.helm.sh/release-namespace:apigee-systemlabels:app.kubernetes.io/managed-by:Helm

3. Create a file calledmigration-datastore-patch.yaml with the following contents:

   # migration-datastore-patch.yamlmetadata:annotations:meta.helm.sh/release-name:datastoremeta.helm.sh/release-namespace:apigeelabels:app.kubernetes.io/managed-by:Helm

4. Run the followingkubectl commands:

   kubectl patch clusterrole apigee-cassandra-backup --patch-file ./migration-operator-patch.yamlkubectl patch clusterrole apigee-cassandra-restore --patch-file ./migration-operator-patch.yamlkubectl patch clusterrolebinding apigee-cassandra-backup --patch-file ./migration-operator-patch.yamlkubectl patch clusterrolebinding apigee-cassandra-restore --patch-file ./migration-operator-patch.yamlkubectl patch -n apigee cronjob apigee-cassandra-backup --patch-file ./migration-datastore-patch.yamlkubectl patch -n apigee certificate apigee-cassandra-backup-tls --patch-file ./migration-datastore-patch.yaml --type mergekubectl patch -n apigee secret apigee-cassandra-backup-svc-account --patch-file ./migration-datastore-patch.yamlkubectl patch -n apigee secret apigee-cassandra-backup-key-file --patch-file ./migration-datastore-patch.yamlkubectl patch -n apigee ServiceAccount apigee-cassandra-backup-sa --patch-file ./migration-datastore-patch.yamlkubectl patch -n apigee job apigee-cassandra-restore --patch-file ./migration-datastore-patch.yamlkubectl patch -n apigee certificate apigee-cassandra-restore-tls --patch-file ./migration-datastore-patch.yaml --type mergekubectl patch -n apigee secret apigee-cassandra-restore-svc-account --patch-file ./migration-datastore-patch.yamlkubectl patch -n apigee secret apigee-cassandra-restore-key-file --patch-file ./migration-datastore-patch.yamlkubectl patch -n apigee ServiceAccount apigee-cassandra-restore-sa --patch-file ./migration-datastore-patch.yaml

   Note: You can ignore anynot found errors.
5. Clean up the patch files using the following commands:

   rm migration-operator-patch.yamlrm migration-datastore-patch.yaml

Next step

Continue your installation of the Apigee hybrid Helm charts with the instructions inInstalling and managing Apigee hybrid with Helm charts.

./apigee-helm-migration --help

Usage of ./apigee-helm-migration:  -apigee-namespace string      namespace used for apigee resources (default "apigee")  -components string      CSV of components to migrate. If empty then all components are migrated. Valid values are: operator,datastore,redis,ingress-manager,telemetry,orgs,envs,env-groups  -dry-run      perform a dry-run  -env string      restrict migration to a singular supplied env. If empty then all envs detected in the cluster are migrated  -env-group string      restrict migration to a singular supplied envGroup. If empty then all envGroups detected in the cluster are migrated  -kubeconfig string      (optional) absolute path to the kubeconfig file (default "/usr/local/google/home/example/.kube/config")  -org string      restrict migration to a singular supplied org. If empty then all orgs detected in the cluster are migrated  -vIncreased logging verbosity  -ydon't prompt for confirmation or for configuration of Helm releases