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.14.2 und höher
Eine funktionierende kubeconfig-Datei, die auf einen Cluster mit einer funktionierenden Apigee Hybrid 1.12-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]]⁽¹⁾`	`ORG_NAME-ENV_NAME[-env[-n]]`⁽¹⁾
`apigee-virtualhost (envgroup)`	`VH_NAME[-env-group[-n]]`⁽¹⁾	`ORG_NAME-VH_NAME[-env-group[-n]]`⁽¹⁾
⁽¹⁾ 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:

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
```
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 wird in zwei Kubernetes-Namespaces ausgeführt:

apigee-system: Die Komponente apigee-operator wird immer im Namespace apigee-system ausgeführt. Das Helm-Migrationstool aktualisiert die Komponente apigee-operator im Namespace apigee-system, unabhängig davon, was Sie mit dem Flag --apigee-namespace angeben.
apigee: Alle Hybrid-Komponenten außer apigee-operator 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

Laden Sie das Migrationstool herunter.
Linux
1. Speichern Sie die aktuelle Versionsnummer mit dem folgenden Befehl in einer Variablen:
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. Prüfen Sie mit dem folgenden Befehl, ob die Variable mit einer Versionsnummer ausgefüllt wurde. Wenn Sie eine andere Version verwenden möchten, können Sie diese stattdessen in einer Umgebungsvariablen speichern.
  echo $VERSION
  Beispiel:
  echo $VERSION 1.0.5
3. Laden Sie das Releasepaket für Ihr Betriebssystem mit dem folgendem Befehl herunter:
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_linux_64.tar.gz
4. Extrahieren Sie die komprimierten Dateien mit dem folgenden Befehl:
  tar -xzf apigee-helm-migration_linux_64.tar.gz
Mac OS
1. Speichern Sie die aktuelle Versionsnummer mit dem folgenden Befehl in einer Variablen:
  export VERSION=$(curl -s "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
2. Prüfen Sie mit dem folgenden Befehl, ob die Variable mit einer Versionsnummer ausgefüllt wurde. Wenn Sie eine andere Version verwenden möchten, können Sie diese stattdessen in einer Umgebungsvariablen speichern.
  echo $VERSION
  Beispiel:
  echo $VERSION 1.0.5
3. Laden Sie das Releasepaket für Ihr Betriebssystem mit dem folgendem Befehl herunter:
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_mac_64.tar.gz
4. Extrahieren Sie die komprimierten Dateien mit dem folgenden Befehl:
  tar -xzf apigee-helm-migration_mac_64.tar.gz
Windows
1. Speichern Sie die aktuelle Versionsnummer mit dem folgenden Befehl in einer Variablen:
  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. Prüfen Sie mit dem folgenden Befehl, ob die Variable mit einer Versionsnummer ausgefüllt wurde. Wenn Sie eine andere Version verwenden möchten, können Sie diese stattdessen in einer Umgebungsvariablen speichern.
  echo %VERSION%
  Beispiel:
  echo %VERSION% 1.0.5
3. Laden Sie das Releasepaket für Ihr Betriebssystem mit dem folgendem Befehl herunter:
  curl -LO https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/%VERSION%/apigee-helm-migration_windows_64.tar.gz
4. Extrahieren Sie die komprimierten Dateien mit dem folgenden Befehl:
  tar xzvf apigee-helm-migration_windows_64.tar.gz

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:

Bei Updates für mehrere Organisationen wird empfohlen, apigee-helm-migration ohne Optionen auszuführen, um alle Komponenten der Organisation und Umgebung zu aktualisieren.

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:

Bei Apigee Hybrid, das mit Helm verwaltet wird, werden apigeeIngressGateway-Attribute verwendet, um alle Apigee-Ingress-Gateways in Ihrem Cluster zu konfigurieren. ingressGateways-Attribute überschreiben die Einstellungen in apigeeIngressGateway für das einzelne benannte Ingress-Gateway.
Siehe apigeeIngressGateway
- Erstellen Sie in der Überschreibungsdatei eine zusätzliche apigeeIngressGateway-Stanza für alle ingressGateways-Attribute, die für alle Ingress-Gateways in Ihrem Cluster global sind. Beispiel:
```
apigeeIngressGateway:
  image:
    url: "PATH_TO_REPOSITORY/apigee-asm-ingress"
    tag: "TAG"
```
  Beispiel:
```
apigeeIngressGateway:
  image:
    url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress"
    tag: "1.17.8-asm.20-distroless"
```
- Geben Sie ingressGateways.name an: Sie müssen Ihr Ingress-Gateway instanziieren. Beispiel:
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. Beispiel:
```
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. Beispiel:
```
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:

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.

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-system
  labels:
    app.kubernetes.io/managed-by: Helm

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

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

Hinweis: Sie können alle not found-Fehler ignorieren.

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.

Wichtig: Wenn Sie der Anleitung für Ihren migrierten Cluster folgen, müssen Sie das ‑‑atomic-Flag in allen Helm-Befehlen weglassen, um zu vermeiden, dass Ressourcen versehentlich gelöscht werden, falls der helm upgrade-Befehl fehlschlägt.

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