Esegui la migrazione di Apigee hybrid a Helm da apigeectl

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 ibride di cui hai eseguito la migrazione alla gestione Helm con questo strumento.

Prerequisiti

  • Helm versione 3.10+. Vedi Installare Helm.
  • Un file kubeconfig funzionante che punta a un cluster con un l'installazione di Apigee hybrid 1.11 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. Spazio dei nomi predefinito: apigee
  • Migrazione solo dei componenti ibridi selezionati. Predefinito: tutti i componenti vengono migrati
  • Migrazione di una sola organizzazione
  • Migrazione di una sola env
  • Solo migrazione di un singolo gruppo di ambienti (apigee-virtualhost)
  • Personalizzazione dei nomi delle release di Helm per organizzazioni, ambienti ed env-group.

Limitazioni

  • Questo strumento non supporta la personalizzazione dei nomi delle release di Helm per questi componenti ibridi: apigee-operator, apigee-datastore, apigee-redis, apigee-telemetry e apigee-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 il file temporaneo e fornirlo 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 multiorganizzativo con le organizzazioni org1 e org2, se l'ambiente prod è presente in entrambi organizzazioni e solo --env=prod è specificato, entrambi gli ambienti saranno di cui è stata eseguita la migrazione. Se vuoi eseguire la migrazione di una sola env, devi anche specificare un filtro per l'organizzazione --org=org1 o --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 Helm Chart 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 di Helm non hanno alcuna convenzione di denominazione o limitazione relativa al nome del grafico. Lo strumento di migrazione genera nomi di release Helm univoci per ogni componente.

Grafico Cluster a organizzazione singola Cluster multi-organizzazione
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 vengono completati con il suffisso -env o -env-group se il nome generato è in conflitto con un altro nome generato. A questi viene aggiunto il suffisso -1 o -2 … se il conflitto persiste.

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:

  1. 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
  2. Sposta o copia e modifica questo file. Puoi passare questo file modificato con l'opzione -f quando esegui 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 di Helm per un'organizzazione, un ambiente o un gruppo di ambienti, modifica il campo helmReleaseName dell'oggetto. Ad esempio, per rinominare il rilascio dell'organizzazione in custom-org, il rilascio dell'ambiente in custom-env e il rilascio del gruppo di ambienti in custom-group, il file risultante sarà simile al seguente:

    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 viene eseguito in due spazi dei nomi Kubernetes:

  • apigee-system: il componente apigee-operator viene sempre eseguito nello spazio dei nomi apigee-system. Lo strumento di migrazione Helm aggiornerà il componente apigee-operator nello spazio dei nomi apigee-system indipendentemente da ciò che specifichi con il flag --apigee-namespace.
  • apigee: tutti i componenti ibridi, tranne apigee-operator, vengono eseguiti in questo nello spazio dei nomi. apigee è il nome predefinito. Puoi utilizzare qualsiasi spazio dei nomi personalizzato per questi componenti.

    Se utilizzi uno spazio dei nomi personalizzato, devi specificarlo con il flag --apigee-namespace my_custom_namespace quando esegui lo strumento di migrazione Helm.

    Devi anche aggiungere namespace: my_custom_namespace al file di override.

Istruzioni

  1. Scarica lo strumento di migrazione.

    Linux

    1. Archivia il numero della versione più recente in una variabile utilizzando il seguente comando:
      export VERSION=$(curl -s \  "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
    2. Verifica che la variabile sia stata compilata con un numero di versione utilizzando il seguente comando. Se vuoi utilizzare una versione diversa, puoi salvarla in una variabile di ambiente.
      echo $VERSION
      Ad esempio:
      1.0.5
    3. Scarica il pacchetto della release per il tuo sistema operativo utilizzando il seguente comando:

      curl -LO \  https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_linux_64.tar.gz
    4. Estrai i file compressi utilizzando il seguente comando:

      tar -xzf apigee-helm-migration_linux_64.tar.gz

    Mac OS

    1. Archivia il numero della versione più recente in una variabile utilizzando il seguente comando:
      export VERSION=$(curl -s \  "https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/current-version.txt?ignoreCache=1")
    2. Verifica che la variabile sia stata compilata con un numero di versione utilizzando il seguente comando. Se vuoi utilizzare una versione diversa, puoi salvarla in una variabile di ambiente.
      echo $VERSION
      Ad esempio:
      1.0.5
    3. Scarica il pacchetto di release per il tuo sistema operativo utilizzando il seguente comando:

      curl -LO \  https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/${VERSION}/apigee-helm-migration_mac_64.tar.gz
    4. Estrai i file compressi utilizzando il seguente comando:

      tar -xzf apigee-helm-migration_mac_64.tar.gz

    Windows

    1. Memorizza il numero della versione più recente in una variabile utilizzando il seguente comando:
      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. Verifica che la variabile sia stata compilata con un numero di versione utilizzando il seguente comando. Se Se vuoi usare una versione diversa, puoi salvarla in una variabile di ambiente.
      echo %VERSION%
      Ad esempio:
      1.0.5
    3. Scarica il pacchetto della release per il tuo sistema operativo utilizzando il seguente comando:

      curl -LO ^  https://storage.googleapis.com/apigee-release/hybrid/apigee-migration-tool/%VERSION%/apigee-helm-migration_windows_64.tar.gz
    4. Estrai i file compressi utilizzando il seguente comando:

      tar xzvf apigee-helm-migration_windows_64.tar.gz
  2. 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:
    • Un'installazione semplice, che utilizza kubeconfig (~/.kube/config) predefinito, lo spazio dei nomi apigee predefinito e i 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 su base per componente dopo l'esecuzione dello strumento.

      ./apigee-helm-migration
      
    • Esegui la 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 e 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!
    • Fare riferimento a un file kubeconfig specifico e specificare un nome diverso per lo spazio dei nomi apigee.

      ./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 di 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 file dei nomi delle release passato.
    • Risorse non trovate: verifica che Apigee hybrid sia completamente installato e di disporre delle autorizzazioni per accedere alle risorse apigee.

Modifiche alle proprietà di configurazione

Apporta le seguenti modifiche ai file di override:

  • Apigee ibrido gestito 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 in apigeeIngressGateway per il singolo gateway in entrata denominato.

    Leggi apigeeIngressGateway

    • Crea un'altra stanza apigeeIngressGateway nel file delle sostituzioni per tutte le proprietà ingressGateways globali per tutti i gateway di ingresso nel cluster. Ad esempio:
      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. È necessario per l'inizializzazione del gateway di ingresso. Ad esempio:
    • ingressGateways:
      - name: INGRESS_GATEWAY_NAME
      
  • Le proprietà per abilitare Workload Identity sono state modificate:
    • gcp.workloadIdentity.enabled sostituisce gcp.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 delle installazioni di produzione), 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 e Abilitazione di Workload Identity con Helm.

Risoluzione dei problemi

Nella release ibrida v1.11 esiste un problema noto con lo strumento di migrazione di Helm. Fino a quando il problema non sarà risolto, Cassandra backup and restore richiede 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:

  1. Assicurati che il tuo kubeconfig attuale indichi il cluster di cui vuoi eseguire la migrazione. Puoi eseguire questi passaggi da qualsiasi directory.
  2. Crea un file denominato migration-operator-patch.yaml con i seguenti contenuti:
    # 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
  3. 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
  4. 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
  5. 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 di Apigee hybrid seguendo le istruzioni riportate 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