Outil de migration Helm Apigee hybrid

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

  • Version 3.10+ d'Helm.
  • Un fichier kubeconfig opérationnel pointant vers un cluster avec une installation Apigee hybrid 1.10 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]](1) ORG_NAME-ENV_NAME[-env[-n]](1)
apigee-virtualhost (envgroup) VH_NAME[-env-group[-n]](1) ORG_NAME-VH_NAME[-env-group[-n]](1)

(1) 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 :

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

Itinéraire

  1. Localisez l'outil de migration.

    L'outil de migration est empaqueté avec apigeectl à partir de la version 1.10.3, sous /tools/migration/.

  2. Extrayez les fichiers compressés à l'aide de l'une des commandes suivantes :

    • Mac :
      tar -xzf apigee-helm-migration_1.0.2_mac_64.tar.gz
    • Linux :
      tar -xzf apigee-helm-migration_1.0.2_linux_64.tar.gz
    • Windows :
      tar -xzf apigee-helm-migration_1.0.2_windows_64.zip
  3. 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 :
    • 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.

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

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