Migrer Apigee hybrid vers Helm depuis apigeectl

Cet outil de migration permet de migrer un cluster hybride basé sur apigeectl vers un cluster hybride basé sur Helm. Cet outil n'effectue aucun remplacement réel des composants de cluster. Il est idempotent et peut être exécuté plusieurs fois sur le même cluster, en préparant à chaque fois un sous-ensemble de composants et d'organisations.

Vous pouvez migrer tous les composants apigee en même temps. Les opérations de mise à niveau Helm peuvent être effectuées pour chaque composant après l'exécution de l'outil.

Consultez la page Installer et gérer Apigee hybrid avec des charts Helm pour en savoir plus sur la gestion des clusters hybrides que vous avez migrés vers la gestion Helm avec cet outil.

Prérequis

Helm version 3.14.2 ou ultérieure.
Un fichier kubeconfig opérationnel pointant vers un cluster avec une installation Apigee hybrid 1.12 opérationnelle.
Ce rôle permet de modifier les métadonnées et les annotations des ressources Kubernetes des composants hybrides que vous souhaitez migrer.

Champ d'application

Cet outil est compatible avec les options suivantes au moment de l'exécution :

Personnalisation de l'espace de noms pour les ressources apigee. Espace de noms par défaut : apigee
Migration des composants hybrides sélectionnés uniquement. Par défaut : tous les composants sont migrés
Migration d'une seule organisation uniquement
Migration d'un seul environnement uniquement
Migration d'un seul groupe d'environnements (apigee-virtualhost) uniquement
Personnalisation des noms des versions Helm pour les organisations, les environnements et les groupes d'environnements.

Limites

Cet outil n'est pas compatible avec les noms de versions Helm personnalisés pour ces composants hybrides : apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry et apigee-ingress-manager.
Les personnalisations interactives effectuées sur les noms de version Helm pour les organisations, les environnements et les groupes d'environnement ne sont pas automatiquement conservées entre les exécutions. Vous pouvez modifier le fichier temporaire et le spécifier en tant qu'option lors des exécutions ultérieures.
Le filtrage des environnements et des groupes d'environnements ne s'effectue que par nom. Dans certains cas, plusieurs environnements et groupes d'environnements peuvent être migrés sur des clusters multi-organisation.

Par exemple, sur un cluster multi-organisation avec les organisations org1 et org2, si l'environnement prod est présent dans les deux organisations, et que seul --env=prod est spécifié, les deux environnements seront migrés. Si vous souhaitez migrer un seul environnement, vous devez également spécifier un filtre d'organisation --org=org1 ou --org=org2.

Utilisation

Syntaxe

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

Noms de version générés par Helm

Chaque chart Helm déployé sur un cluster doit posséder un nom de version, qui doit être unique dans un espace de noms. Les noms des versions Helm ne sont soumis à aucune convention d'attribution de noms ni restriction concernant le nom du graphique. L'outil de migration génère des noms de version Helm uniques pour chaque composant.

Graphique	Cluster à organisation unique	Cluster multi-organisation
`apigee-operator`	`operator`	`operator`
`apigee-datastore`	`datastore`	`datastore`
`apigee-telemetry`	`telemetry`	`telemetry`
`apigee-redis`	`redis`	`redis`
`apigee-ingress-manager`	`ingress-manager`	`ingress-manager`
`apigee-org`	`ORG_NAME`	`ORG_NAME`
`apigee-env`	`ENV_NAME[-env[-n]]⁽¹⁾`	`ORG_NAME-ENV_NAME[-env[-n]]`⁽¹⁾
`apigee-virtualhost (envgroup)`	`VH_NAME[-env-group[-n]]`⁽¹⁾	`ORG_NAME-VH_NAME[-env-group[-n]]`⁽¹⁾
⁽¹⁾ Les noms sont présentés sous la forme `-env` ou `-env-group` si le nom généré entre en conflit avec un autre nom généré. Ils présentent également le suffixe `-1` ou `-2 …` s'ils entrent toujours en conflit.

Personnaliser les noms des versions Helm

L'outil de migration permet la personnalisation interactive des noms de version Helm. Si vous souhaitez personnaliser les noms de version Helm de manière non interactive :

Exécutez l'outil une fois et quittez la première requête pour créer un fichier temporaire contenant les noms des versions générés automatiquement. Une ligne semblable à celle-ci doit s'afficher :
```
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
```
Déplacez ou copiez ce fichier, puis modifiez-le. Vous pouvez transmettre ce fichier modifié avec l'option -f lorsque vous exécutez l'outil de migration. Les noms de version générés automatiquement se présentent comme suit :
```
orgs:
  example-apigee-org:
    helmReleaseName: example-apigee-org
    envs:
      prod:
        helmReleaseName: prod
    envGroups:
      prod-envgroup:
        helmReleaseName: prod-envgroup
```
Pour personnaliser les noms de version Helm pour une organisation, un environnement ou un groupe d'environnements, modifiez le champ helmReleaseName de cet objet. Par exemple, pour renommer la version d'organisation en custom-org, la version d'environnement en custom-env et la version de groupe d'environnements en custom-group, le fichier obtenu ressemble à ceci :
```
orgs:
  example-apigee-org:
    helmReleaseName: custom-org
    envs:
      prod:
        helmReleaseName: custom-env
    envGroups:
      prod-envgroup:
        helmReleaseName: custom-group
```

Utiliser des espaces de noms personnalisés

Apigee hybrid s'exécute dans deux espaces de noms Kubernetes :

apigee-system : le composant apigee-operator s'exécute toujours dans l'espace de noms apigee-system. L'outil de migration Helm met à jour le composant apigee-operator dans l'espace de noms apigee-system, quelle que soit la valeur spécifiée avec l'option --apigee-namespace.
apigee : tous les composants hybrides, à l'exception de apigee-operator, s'exécutent dans cet espace de noms. apigee est le nom par défaut. Vous pouvez utiliser n'importe quel espace de noms personnalisé pour ces composants.
Si vous utilisez un espace de noms personnalisé, vous devez le spécifier avec l'option --apigee-namespace my_custom_namespace lorsque vous exécutez l'outil de migration Helm.

Vous devez également ajouter la propriété de premier niveau namespace: my_custom_namespace à votre fichier de remplacement.

Instructions

Téléchargez l'outil de migration.
Linux
1. Stockez le dernier numéro de version dans une variable à l'aide de la commande suivante :
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. À l'aide de la commande suivante, vérifiez que le numéro de version a bien été enregistré dans la variable. Si vous souhaitez utiliser une autre version, vous pouvez l'enregistrer dans une variable d'environnement à la place.
  echo $VERSION
  Exemple :
  echo $VERSION 1.0.5
3. Téléchargez le package de version de votre système d'exploitation à l'aide de la commande suivante :
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_linux_64.tar.gz
4. Extrayez les fichiers compressés à l'aide de la commande suivante :
  tar -xzf apigee-helm-migration_linux_64.tar.gz
macOS
1. Stockez le dernier numéro de version dans une variable à l'aide de la commande suivante :
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. À l'aide de la commande suivante, vérifiez que le numéro de version a bien été enregistré dans la variable. Si vous souhaitez utiliser une autre version, vous pouvez l'enregistrer dans une variable d'environnement à la place.
  echo $VERSION
  Exemple :
  echo $VERSION 1.0.5
3. Téléchargez le package de version de votre système d'exploitation à l'aide de la commande suivante :
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_mac_64.tar.gz
4. Extrayez les fichiers compressés à l'aide de la commande suivante :
  tar -xzf apigee-helm-migration_mac_64.tar.gz
Windows
1. Stockez le dernier numéro de version dans une variable à l'aide de la commande suivante :
  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. À l'aide de la commande suivante, vérifiez que le numéro de version a bien été enregistré dans la variable. Si vous souhaitez utiliser une autre version, vous pouvez l'enregistrer dans une variable d'environnement à la place.
  echo %VERSION%
  Exemple :
  echo %VERSION% 1.0.5
3. Téléchargez le package de version de votre système d'exploitation à l'aide de la commande suivante :
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/%VERSION%/apigee-helm-migration_windows_64.tar.gz
4. Extrayez les fichiers compressés à l'aide de la commande suivante :
  tar xzvf apigee-helm-migration_windows_64.tar.gz

Exécutez l'outil de migration. Si les options par défaut sont acceptables, il est suffisant d'exécuter l'outil sans aucun argument et d'approuver l'invite si les noms de version Helm générés sont satisfaisants. Voici quelques exemples de scénarios :

Pour les mises à jour multi-organisations, il est recommandé d'exécuter apigee-helm-migration sans options pour mettre à niveau tous les composants d'organisation et d'environnement.

Une installation simple, avec les valeurs par défaut kubeconfig (~/.kube/config), l'espace de noms apigee par défaut et les noms de version Helm par défaut.

La commande suivante devrait suffire pour la plupart des installations, si ce n'est toutes. Les opérations de mise à niveau de Helm peuvent être effectuées pour chaque composant après l'exécution de l'outil.
```
./apigee-helm-migration
```

Migrer tous les composants à l'aide d'un espace de noms personnalisé :
```
./apigee-helm-migration --apigee-namespace my_custom_namespace
```

Ne migrer que les composants operator et datastore :

./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!

Pointant vers un fichier kubeconfig spécifique et spécifiant un nom différent pour l'espace de noms apigee.
```
./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
```
Migrer tous les composants, mais une seule organisation :
```
./apigee-helm-migration --org=some-test-org
```

Voici un exemple de résultat d'une migration réussie :

INFO: 21:32:55 using kubeconfig file  /usr/local/google/home/example/.kube/config
INFO: 21:32:55 namespace for apigee resources:
INFO: 21:32:55 	 apigee
INFO: 21:32:55 processing all organizations in cluster
INFO: 21:32:55 processing all components
INFO: 21:32:55 dry-run:
INFO: 21:32:55 	 false
INFO: 21:32:55 cluster Apigee information:
INFO: 21:32:55 Apigee Organizations found:
INFO: 21:32:56 	 example-hybrid-dev
INFO: 21:32:56 Apigee Environments found (org: env):
INFO: 21:32:56 	 example-hybrid-dev : prod
INFO: 21:32:56 Apigee EnvGroups(apigeerouteconfigs) found (org: envGroup):
INFO: 21:32:56 	 example-hybrid-dev : prod-envgroup
INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
INFO: 21:32:56 Helm release names for Apigee orgs/envs/envgroups:
orgs:
example-hybrid-dev:
helmReleaseName: example-hybrid-dev
envs:
  prod:
    helmReleaseName: prod
envGroups:
  prod-envgroup:
    helmReleaseName: prod-envgroup
Make changes to the release names for Apigee orgs/env/envgroups? [y/n]: n
Continue with patching apigee resources for Helm migration? [y/n]: y
INFO: 21:32:59 Processing component:  operator
INFO: 21:33:01 Processing component:  datastore
INFO: 21:33:01 Processing component:  redis
INFO: 21:33:02 Processing component:  ingress-manager
INFO: 21:33:02 Processing component:  telemetry
INFO: 21:33:03 Processing component:  orgs
INFO: 21:33:05 Processing component:  envs
INFO: 21:33:06 Processing component:  env-groups
INFO: 21:33:07 Migration successful!

Erreurs potentielles :

Erreur lors de l'analyse du fichier de noms de version : vérifiez le fichier de noms des versions transmis.
Ressources introuvables : vérifiez que Apigee hybrid est entièrement installé et que vous êtes autorisé à accéder aux ressources apigee.

Modifications des propriétés de configuration

Apportez les modifications suivantes dans vos fichiers de remplacement:

Apigee hybrid géré avec Helm utilise des propriétés apigeeIngressGateway pour configurer toutes les passerelles d'entrée Apigee dans votre cluster. Les propriétés ingressGateways remplacent les paramètres de apigeeIngressGateway pour la passerelle d'entrée nommée individuelle.
Consultez apigeeIngressGateway
- Créez un stanza apigeeIngressGateway supplémentaire dans votre fichier de remplacement pour toutes les propriétés ingressGateways qui sont globales à toutes les passerelles d'entrée de votre cluster. Exemple :
```
apigeeIngressGateway:
  image:
    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
    tag: "TAG"
```
  Exemple :
```
apigeeIngressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.8-asm.20-distroless"
```
- Veillez à inclure ingressGateways.name. Il est nécessaire pour instancier votre passerelle d'entrée. Exemple :
Les propriétés permettant d'activer Workload Identity ont été modifiées :
- Remplacement de gcp.workloadIdentityEnabled par gcp.workloadIdentity.enabled.
- Si vous utilisez un seul compte de service pour tous les composants, vous pouvez le spécifier à l'aide de la commande suivante : gcp.workloadIdentity.gsa. Exemple :
```
gcp:
  workloadIdentity:
    enabled: true
    gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
```
- Si vous utilisez un compte de service distinct pour chaque composant (standard pour la plupart des installations de production), spécifiez le compte de service avec la propriété gsa du composant. Exemple :
```
logger:
  gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
```
Consultez les pages suivantes : gcp.workloadIdentity.enabled, gcp.federatedWorkloadIdentity.enabled, Activer Workload Identity sur GKE ou Activer la fédération d'identité de charge de travail sur AKS et EKS.

Dépannage

Il existe un problème connu avec l'outil de migration Helm dans la version hybride 1.12. En attendant que le problème soit résolu, la sauvegarde et la restauration de bases de données Cassandra nécessitent des étapes supplémentaires.

Pour ce faire, procédez comme suit :

Avant ou après l'exécution de l'outil de migration
Avant d'installer des charts Helm

Pour installer le correctif afin de contourner le problème, procédez comme suit:

Assurez-vous que votre fichier kubeconfig actuel pointe vers le cluster que vous souhaitez migrer. Vous pouvez effectuer ces étapes à partir de n'importe quel répertoire.

Créez un fichier nommé migration-operator-patch.yaml avec le contenu suivant :

# migration-operator-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: operator
    meta.helm.sh/release-namespace: apigee-system
  labels:
    app.kubernetes.io/managed-by: Helm

Créez un fichier nommé migration-datastore-patch.yaml avec le contenu suivant :

# migration-datastore-patch.yaml
metadata:
  annotations:
    meta.helm.sh/release-name: datastore
    meta.helm.sh/release-namespace: apigee
  labels:
    app.kubernetes.io/managed-by: Helm

Exécutez les commandes kubectl suivantes :

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

Remarque : Vous pouvez ignorer les erreurs not found.

Nettoyez les fichiers correctif à l'aide des commandes suivantes:

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

Étape suivante

Continuez votre installation des charts Helm Apigee hybrid en suivant les instructions de la section Installer et gérer Apigee hybrid avec les charts Helm.

Important : Lorsque vous suivez les instructions de votre cluster migré, vous devez omettre l'option ‑‑atomic de toutes les commandes Helm afin d'éviter de supprimer accidentellement des ressources si la commande helm upgrade échoue.

Résultat de la commande -help

./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
  -v	Increased logging verbosity
  -y	don't prompt for confirmation or for configuration of Helm releases