Apigee Hybrid von apigeectl zu Helm migrieren

Dieses Migrationstool unterstützt Sie bei der Migration eines apigeectl-basierten Hybridclusters zu einem Helm-basierten Hybridcluster. Dieses Tool führt keine tatsächliche Ersetzung von Clusterkomponenten durch. Es ist idempotent und kann mehrmals für denselben Cluster ausgeführt werden, wobei jedes Mal eine Teilmenge der Komponenten und Organisationen vorbereitet wird.

Sie können alle apigee-Komponenten gleichzeitig migrieren. Das Helm-Upgrade kann nach der Ausführung des Tools pro Komponente durchgeführt werden.

Informationen zum Verwalten von Hybrid-Clustern, die Sie mit diesem Tool zur Helm-Verwaltung migriert haben, finden Sie unter Apigee Hybrid mit Helm-Diagrammen installieren und verwalten.

Vorbereitung

  • Helm-Version Version 3.10 und höher
  • Eine funktionierende kubeconfig-Datei, die auf einen Cluster mit einer funktionierenden Apigee Hybrid 1.13-Installation verweist.
  • Berechtigungen zum Ändern der Metadaten und Annotationen in den Kubernetes-Ressourcen der Hybrid-Komponenten, die Sie migrieren möchten.

Umfang

Dieses Tool unterstützt zur Laufzeit die folgenden Optionen:

  • Anpassung des Namespace für apigee-Ressourcen. Standard-Namespace: apigee
  • Migration nur von ausgewählten Hybrid-Komponenten Standard: Alle Komponenten werden migriert
  • Migration von nur einer Organisation
  • Migration von nur einer Umgebung
  • Migration von nur einer Umgebungsgruppe (apigee-virtualhost)
  • Anpassung der Helm-Releasenamen für Organisationen, Umgebungen und Umgebungsgruppen

Beschränkungen

  • Dieses Tool unterstützt keine Anpassung der Helm-Releasenamen für die folgenden Hybrid-Komponenten: apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry und apigee-ingress-manager.
  • Interaktive Anpassungen der Helm-Releasenamen für Organisationen, Umgebungen und Umgebungsgruppen bleiben nicht automatisch zwischen Ausführungen erhalten. Sie können die temporäre Datei bearbeiten und als Option in späteren Ausführungen bereitstellen.
  • Umgebungs- und Umgebungsgruppenfilterung werden nur nach Namen durchgeführt. In einigen Fällen kann dies dazu führen, dass mehrere Umgebungen und Umgebungsgruppen in Multi-Organisations-Clustern migriert werden.

    Beispiel: In einem Multi-Organisations-Cluster mit den Organisationen org1 und org2, wenn die Umgebung prod in beiden Organisationen vorhanden ist und nur --env=prod angegeben ist, werden beide Umgebungen migriert. Wenn Sie nur eine einzelne Umgebung migrieren möchten, müssen Sie auch den Organisationsfilter --org=org1 oder --org=org2 angeben.

Nutzung

Syntax

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

Generierte Helm-Releasenamen

Jedes Helm-Diagramm, das in einem Cluster bereitgestellt wird, muss einen Releasenamen haben, der innerhalb eines Namespace eindeutig ist. Helm-Releasenamen haben keine Namenskonvention oder Einschränkung in Bezug auf den Diagrammnamen. Das Migrationstool generiert für jede Komponente eindeutige Helm-Releasenamen.

Diagramm Cluster mit einer einzelnen Organisation Cluster mit mehreren Organisationen
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) Namen erhalten das Suffix -env oder -env-group, wenn der generierte Name in Konflikt mit einem anderen generierten Namen steht. Sie haben außerdem das Suffix -1 oder -2 …, wenn sie noch in Konflikt stehen.

Helm-Releasenamen anpassen

Das Migrationstool ermöglicht die interaktive Anpassung von Helm-Releasenamen. Wenn Sie die Helm-Releasenamen nicht interaktiv anpassen möchten:

  1. Führen Sie das Tool einmal aus und beenden Sie es bei der ersten Eingabeaufforderung, um eine temporäre Datei mit den automatisch generierten Releasenamen zu erstellen. Die Zeile sollte etwa so aussehen:
    INFO: 21:32:56 using temp file for release names:  /tmp/apigee-helm-migration-1229129207-releaseNames
    
  2. Verschieben oder kopieren und bearbeiten Sie diese Datei. Sie können diese bearbeitete Datei mit der Option -f übergeben, wenn Sie das Migrationstool ausführen. Die automatisch generierten Releasenamen sehen so aus:

    orgs:
      example-apigee-org:
        helmReleaseName: example-apigee-org
        envs:
          prod:
            helmReleaseName: prod
        envGroups:
          prod-envgroup:
            helmReleaseName: prod-envgroup
    

    Bearbeiten Sie das Feld helmReleaseName dieses Objekts, um die Helm-Releasenamen für eine Organisation, Umgebung oder Umgebung anzupassen. Wenn Sie beispielsweise den Organisations-Release in custom-org, den Umgebungs-Release in custom-env und den Umgebungsgruppen-Release in custom-group umbenennen möchten, sieht die resultierende Datei so aus:

    orgs:
      example-apigee-org:
        helmReleaseName: custom-org
        envs:
          prod:
            helmReleaseName: custom-env
        envGroups:
          prod-envgroup:
            helmReleaseName: custom-group
    

Benutzerdefinierte Namespaces verwenden

Apigee Hybrid v1.13 und höher wird in einem einzigen Kubernetes-Namespace ausgeführt. Alle Hybrid-Komponenten werden in diesem Namespace ausgeführt. apigee ist der Standardname. Sie können für diese Komponenten einen beliebigen benutzerdefinierten Namespace verwenden.

Wenn Sie einen benutzerdefinierten Namespace verwenden, müssen Sie ihn mit dem Flag --apigee-namespace my_custom_namespace angeben, wenn Sie das Helm-Migrationstool ausführen.

Sie müssen der Überschreibungsdatei auch das Attribut namespace: my_custom_namespace der obersten Ebene hinzufügen.

Anleitung

  1. Suchen Sie das Migrationstool.

    Das Migrationstool ist mit apigeectl unter /tools/migration/ verpackt.

  2. Extrahieren Sie die komprimierten Dateien mit einem der folgenden Befehle:

    • 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. Führen Sie das Migrationstool aus. Wenn die Standardoptionen akzeptabel sind, ist es ausreichend, das Tool ohne Argumente auszuführen und die Eingabeaufforderung zu genehmigen, wenn die generierten Helm-Releasenamen zufriedenstellend sind. Hier einige Beispielszenarien:
    • Eine einfache Installation mit der Standard-kubeconfig (~/.kube/config), dem Standard-apigee-Namespace und den Standard-Helm-Releasenamen.

      Der folgende Befehl sollte für die meisten, wenn nicht für alle Installationen, ausreichen. Helm-Upgradevorgänge können pro Komponente ausgeführt werden, nachdem das Tool ausgeführt wurde.

      ./apigee-helm-migration
      
    • Alle Komponenten mithilfe eines benutzerdefinierten Namespace migrieren:
      ./apigee-helm-migration --apigee-namespace my_custom_namespace
      
    • Nur die Komponenten operator und datastore migrieren:

      ./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!
      
    • Auf eine bestimmte kubeconfig-Datei verweisen und einen anderen Namen für den Namespace apigee angeben.

      ./apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
      
    • Alle Komponenten, aber nur eine Organisation migrieren:

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

    Das folgende Beispiel zeigt eine Ausgabe einer erfolgreichen Migration:

    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!
    

    Mögliche Fehler:

    • Fehler beim Parsen der Releasenamen-Datei: Prüfen Sie die übergebene Releasenamen-Datei.
    • Ressourcen nicht gefunden: Prüfen Sie, ob Apigee Hybrid vollständig installiert ist und ob Sie Berechtigungen für den Zugriff auf die apigee-Ressourcen haben.

Änderungen der Konfigurationsattribute

Nehmen Sie die folgenden Änderungen in Ihren Überschreibungsdateien vor:

  • Apigee Hybrid, das mit Helm verwaltet wird, verwendet apigeeIngressGateway-Attribute, um alle Apigee-Ingress-Gateways in Ihrem Cluster zu konfigurieren. ingressGateways-Properties überschreiben die Einstellungen in apigeeIngressGateway für das einzelne benannte Ingress-Gateway.

    Siehe apigeeIngressGateway

    • Ändern Sie alle globalen ingressGateways-Attribute für alle Ingress-Gateways in Ihrem Cluster in apigeeIngressGateway-Attribute. Die Datei mit den Überschreibungen sollte mindestens Folgendes enthalten:
      apigeeIngressGateway:
        image:
          url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
          tag: "TAG"
      

      Beispiele:

      apigeeIngressGateway:
        image:
          url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
          tag: "1.17.8-asm.20-distroless"
      
    • Geben Sie ingressGateways.name an: Ihr Ingress-Gateway muss instanziiert werden. Beispiele:
    • ingressGateways:
        name: INGRESS_GATEWAY_NAME
      
  • Die Attribute zum Aktivieren von Workload Identity haben sich geändert:
    • gcp.workloadIdentity.enabled ersetzt gcp.workloadIdentityEnabled.
    • Wenn Sie ein einzelnes Dienstkonto für alle Komponenten verwenden, können Sie es mit gcp.workloadIdentity.gsa angeben. Beispiele:
      gcp:
        workloadIdentity:
          enabled: true
          gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
      
    • Wenn Sie für jede Komponente ein separates Dienstkonto verwenden (den Standard für die meisten Produktionsinstallationen), geben Sie das Dienstkonto mit dem Attribut gsa der Komponente an. Beispiele:
      logger:
        gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
      

    Weitere Informationen finden Sie unter: gcp.workloadIdentity.enabled, gcp.federatedWorkloadIdentity.enabled, Workload Identity in GKE aktivieren oder Identitätsföderation von Arbeitslasten auf AKS und EKS aktivieren.

Fehlerbehebung

Es gibt ein bekanntes Problem mit dem Helm-Migrationstool im Hybrid-Release v1.12. Bis das Problem behoben ist, sind für die Cassandra-Sicherung und -Wiederherstellung zusätzliche Schritte erforderlich.

Gehen Sie dazu so vor:

  • Vor oder nach der Ausführung des Migrationstools
  • Vor der Installation von Helm-Diagrammen

So installieren Sie den Patch für die Problemumgehung:

  1. Achten Sie darauf, dass Ihr aktueller kubeconfig auf den Cluster verweist, den Sie migrieren möchten. Sie können diese Schritte von jedem beliebigen Verzeichnis aus ausführen.
  2. Erstellen Sie eine Datei mit dem Namen migration-operator-patch.yaml und mit folgendem Inhalt:
    # migration-operator-patch.yaml
    metadata:
      annotations:
        meta.helm.sh/release-name: operator
        meta.helm.sh/release-namespace: APIGEE_NAMESPACE
      labels:
        app.kubernetes.io/managed-by: Helm
  3. Erstellen Sie eine Datei mit dem Namen migration-datastore-patch.yaml und mit folgendem Inhalt:
    # 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
  4. Führen Sie folgende kubectl-Befehle aus:
    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
  5. Bereinigen Sie die Patchdateien mit den folgenden Befehlen:
    rm migration-operator-patch.yaml
    rm migration-datastore-patch.yaml

Nächster Schritt

Fahren Sie mit der Installation der Apigee Hybrid-Helm-Diagramme fort, wie in Apigee Hybrid mit Helm-Diagrammen installieren und verwalten beschrieben.

Ausgabe von -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