Questo strumento di migrazione aiuta a eseguire la migrazione di un'istanza basata su apigeectl
da un cluster ibrido a un cluster ibrido basato su Helm.
Questo strumento non esegue effettivamente
la sostituzione di tutti i componenti del cluster. È idempotente e può essere eseguito in molti
volte sullo stesso cluster, preparando un sottoinsieme di componenti e organizzazioni
nel tempo.
Puoi eseguire la migrazione di tutti i componenti apigee
contemporaneamente e Helm
le operazioni di upgrade possono essere eseguite per singolo componente, dopo che lo strumento
vengono eseguiti tutti i test delle unità.
Consulta Installare e gestire Apigee hybrid con i grafici Helm per informazioni sulla gestione dei cluster ibridi di cui hai eseguito la migrazione a Helm con questo strumento.
Prerequisiti
- Helm versione 3.10+.
-
Un file
kubeconfig
funzionante che punta a un cluster con un con l'installazione di Apigee hybrid 1.13 funzionante. - Autorizzazioni per modificare metadati e annotazioni in Kubernetes dei componenti ibridi di cui vuoi eseguire la migrazione.
Ambito
Questo strumento supporta le seguenti opzioni in fase di runtime:
-
Personalizzazione dello spazio dei nomi per
apigee
risorse. Predefinita spazio dei nomi:apigee
- Migrazione solo dei componenti ibridi selezionati. Predefinito: tutti i componenti vengono migrati
- Migrazione di una sola organizzazione
- Migrazione di un solo ambiente
-
Solo migrazione di un singolo gruppo di ambienti (
apigee-virtualhost
) - Personalizzazione dei nomi delle release Helm per organizzazioni, envs e gruppi env.
Limitazioni
-
Questo strumento non supporta la personalizzazione dei nomi delle release di Helm per questi ibridi
componenti:
apigee-operator
,apigee-datastore
,apigee-redis
,apigee-telemetry
eapigee-ingress-manager
. - Personalizzazioni interattive apportate ai nomi delle release di Helm per organizzazioni, ambienti ed env-groups non vengono resi automaticamente permanenti tra le esecuzioni. Puoi modificare temporaneo e fornitolo come opzione nelle esecuzioni successive.
-
I filtri Env e env-group vengono eseguiti solo per nome. In alcuni casi, questo può comportare la migrazione di più env e env-groups su più organizzazioni cluster.
Ad esempio, su un cluster a più organizzazioni con organizzazioni
org1
eorg2
, se l'ambienteprod
è presente in entrambi organizzazioni e solo--env=prod
è specificato, entrambi gli ambienti saranno di cui è stata eseguita la migrazione. Se desideri eseguire la migrazione di un solo ambiente, devi anche specifica un filtro dell'organizzazione--org=org1
oppure--org=org2
.
Utilizzo
Sintassi
apigee-helm-migration [--apigee-namespace=] [--components=] [--dry-run] [--env=org1] [--env-group=org2] [--org=baz] [--kubeconfig=] [-y] [-v] [-f /path/to/releaseNames.yaml]
Nomi release Helm generate
Ogni grafico Helm di cui viene eseguito il deployment in un cluster deve avere un nome release, che deve essere univoco all'interno di uno spazio dei nomi. I nomi delle release Helm non contengono convenzione o restrizione di denominazione rispetto al nome del grafico. La migrazione genera nomi univoci per le release di Helm per ogni componente.
Grafico | Cluster a organizzazione singola | Cluster multiorganizzazione |
---|---|---|
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) I nomi hanno il suffisso |
Personalizzazione dei nomi delle release Helm
Lo strumento di migrazione consente la personalizzazione interattiva dei nomi delle release di Helm. Se vuoi personalizzare i nomi delle release di Helm in modo non interattivo:
-
Esegui lo strumento una volta ed esci al primo prompt per creare un file temporaneo
contenenti i nomi delle release generati automaticamente. Dovresti vedere una riga simile a:
INFO: 21:32:56 using temp file for release names: /tmp/apigee-helm-migration-1229129207-releaseNames
-
Sposta o copia e modifica questo file. Puoi trasferire questo file modificato con l'opzione
-f
quando eseguire lo strumento di migrazione. Il segmento di pubblico generato automaticamente i nomi delle release hanno il seguente aspetto:orgs: example-apigee-org: helmReleaseName: example-apigee-org envs: prod: helmReleaseName: prod envGroups: prod-envgroup: helmReleaseName: prod-envgroup
Per personalizzare i nomi delle release Helm per un'organizzazione, un env o un envgroup, modifica il campo
helmReleaseName
dell'oggetto in questione. Ad esempio, per rinomina la release dell'organizzazione incustom-org
, la release env incustom-env
e la release envgroup percustom-group
, il file risultante ha il seguente aspetto:orgs: example-apigee-org: helmReleaseName: custom-org envs: prod: helmReleaseName: custom-env envGroups: prod-envgroup: helmReleaseName: custom-group
Utilizzo di spazi dei nomi personalizzati
Apigee hybrid v1.13 e versioni successive viene eseguito in un singolo spazio dei nomi Kubernetes. Tutti i componenti ibridi vengono eseguiti in questo
nello spazio dei nomi. apigee
è il nome predefinito. Per questi, puoi utilizzare qualsiasi spazio dei nomi personalizzato
componenti.
Se utilizzi uno spazio dei nomi personalizzato, devi specificarlo con il flag --apigee-namespace my_custom_namespace
quando esegui
strumento di migrazione Helm.
Devi anche aggiungere la proprietà di primo livello namespace: my_custom_namespace
al file degli override.
Istruzioni
-
Individua lo strumento di migrazione.
Lo strumento di migrazione è incluso nel pacchetto
apigeectl
in/tools/migration/
. -
Estrai i file compressi utilizzando uno dei seguenti comandi:
-
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
-
Mac:
-
Esegui lo strumento di migrazione. Se le opzioni predefinite sono accettabili,
sufficiente per eseguire lo strumento senza argomenti e approvare il prompt
se i nomi delle release Helm generati sono soddisfacenti. Alcuni esempi
di seguito sono riportati alcuni scenari:
-
Una semplice installazione, che utilizza l'impostazione predefinita
kubeconfig
(~/.kube/config
), valore predefinitoapigee
dello spazio dei nomi e nomi delle release di Helm predefiniti.Il seguente comando dovrebbe essere sufficiente per la maggior parte dei casi, se non per tutti, per le installazioni di app. Le operazioni di upgrade di Helm possono essere eseguite per componente dopo l'esecuzione dello strumento.
./apigee-helm-migration
- Migrazione di tutti i componenti utilizzando uno spazio dei nomi personalizzato:
./apigee-helm-migration --apigee-namespace my_custom_namespace
-
Esegui la migrazione solo dei componenti
operator
edatastore
:./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!
-
Puntare a un file
kubeconfig
specifico e specificare una un nome diverso per lo spazio dei nomiapigee
../apigee-helm-migration --kubeconfig /abs/path/to/kubeconf --namespace org1_namespace
-
Migrazione di tutti i componenti, ma di una sola organizzazione:
./apigee-helm-migration --org=some-test-org
Di seguito è riportato un esempio di output da una migrazione riuscita:
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!
Potenziali errori:
- Errore durante l'analisi del file dei nomi delle release: controlla il passato dei nomi delle release.
-
Risorse non trovate: verifica che Apigee hybrid sia completamente
installato e di disporre delle autorizzazioni per accedere
apigee
risorse.
-
Modifiche alle proprietà di configurazione
Apporta le seguenti modifiche ai file di override:
-
Apigee ibrida, gestita con Helm, utilizza le proprietà
apigeeIngressGateway
per configurare tutti i gateway Apigee in entrata nel tuo cluster. Le proprietàingressGateways
eseguono l'override delle impostazioni inapigeeIngressGateway
per il singolo gateway in entrata denominato.Leggi
apigeeIngressGateway
- Modifica tutte le proprietà
ingressGateways
globali a tutti i gateway in entrata nel cluster nelle proprietàapigeeIngressGateway
. Il file degli override deve contenere almeno:apigeeIngressGateway: image: url: "PATH_TO_REPOSITORY/apigee-asm-ingress" tag: "TAG"
Ad esempio:
apigeeIngressGateway: image: url: "gcr.io/apigee-release/hybrid/apigee-asm-ingress" tag: "1.17.8-asm.20-distroless"
-
Assicurati di includere
ingressGateways.name
. È necessaria un'istanza del gateway in entrata. Ad esempio:
ingressGateways: name: INGRESS_GATEWAY_NAME
- Modifica tutte le proprietà
- Le proprietà per abilitare Workload Identity sono state modificate:
gcp.workloadIdentity.enabled
sostituiscegcp.workloadIdentityEnabled
.- Se utilizzi un solo account di servizio per tutti i componenti, puoi specificarlo con:
gcp.workloadIdentity.gsa
. Ad esempio:gcp: workloadIdentity: enabled: true gsa: "apigee-non-prod@my-hybrid-project.iam.gserviceaccount.com"
- Se utilizzi un account di servizio separato per ogni componente (lo standard per la maggior parte dei
), specifica l'account di servizio con la proprietà
gsa
del componente. Ad esempio:logger: gsa: "apigee-logger@my-hybrid-project.iam.gserviceaccount.com"
Consulta:
gcp.workloadIdentity.enabled
,gcp.federatedWorkloadIdentity.enabled
, Abilitazione di Workload Identity su GKE o Attivazione della federazione delle identità per i carichi di lavoro su AKS ed EKS.
Risoluzione dei problemi
Nella release ibrida v1.12 esiste un problema noto con lo strumento di migrazione di Helm. Fino al è stato risolto, per il backup e il ripristino di Cassandra sono necessari passaggi aggiuntivi.
Puoi procedere nel seguente modo:
- Prima o dopo l'esecuzione dello strumento di migrazione
- Prima di installare i grafici Helm
Per installare la patch per la soluzione alternativa:
- Assicurati che il tuo
kubeconfig
attuale punti al cluster di cui vuoi eseguire la migrazione. Puoi eseguire questi passaggi da qualsiasi directory. - Crea un file denominato
migration-operator-patch.yaml
con il seguente contenuto:# 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
- Crea un file denominato
migration-datastore-patch.yaml
con i seguenti contenuti:# 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
- Esegui questi comandi
kubectl
: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
- Pulisci i file patch utilizzando i seguenti comandi:
rm migration-operator-patch.yaml
rm migration-datastore-patch.yaml
Passaggio successivo
Continua l'installazione dei grafici Helm ibridi Apigee con le istruzioni in Installazione e gestione di Apigee hybrid con i grafici Helm.
Output di -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