Upgrade di Apigee hybrid alla versione 1.13

Questa procedura riguarda l'upgrade da Apigee hybrid dalla versione 1.12.x alla versione ibrida di Apigee 1.13.1.

Modifiche rispetto alla versione 1.12 di Apigee hybrid

Tieni presente le seguenti modifiche:

  • apigee-operator nello spazio dei nomi Apigee: a partire dalla versione 1.13, apigee-operator viene eseguito nello stesso spazio dei nomi Kubernetes degli altri componenti ibridi di Apigee, apigee per impostazione predefinita. Puoi fornire qualsiasi nome per lo spazio dei nomi. Nelle versioni precedenti, apigee-operator doveva essere eseguito nel proprio spazio dei nomi, apigee-system.
  • Anthos (on bare metal o VMware) è ora Google Distributed Cloud (per bare metal o VMware): per altro informazioni, consulta le panoramiche dei prodotti Google Distributed Cloud for bare metal e Google Distributed Cloud for VMware.

Prerequisiti

Prima di eseguire l'upgrade alla versione ibrida 1.13, assicurati che la tua installazione soddisfi i seguenti requisiti:

Panoramica dell'upgrade alla versione 1.13.1

Le procedure per l'upgrade di Apigee hybrid sono organizzate nelle seguenti sezioni:

  1. Prepara l'upgrade.
  2. Installa il runtime ibrido versione 1.13.1.

Prepara l'upgrade alla versione 1.13

Esegui il backup dell'installazione ibrida

  1. Queste istruzioni utilizzano la variabile di ambiente APIGEE_HELM_CHARTS_HOME per la directory nel file system in cui hai installato i grafici Helm. Se necessario, cambia directory in questa directory e definisci la variabile con il seguente comando:

    Linux 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Mac OS 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Windows 

    set APIGEE_HELM_CHARTS_HOME=%CD%
echo %APIGEE_HELM_CHARTS_HOME%
  2. Crea una copia di backup della versione 1.12 Directory $APIGEE_HELM_CHARTS_HOME/. Puoi utilizzare qualsiasi processo di backup. Ad esempio: puoi creare un file tar dell'intera directory con: 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.12-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Esegui il backup del tuo database Cassandra seguendo le istruzioni in Backup e ripristino di Cassandra.
  4. Se utilizzi i file di certificato di servizio (.json) in per autenticare gli account di servizio, assicurati che i file del certificato degli account di servizio la directory corretta del grafico Helm. I grafici Helm non possono leggere i file esterni a ciascuna directory del grafico.

    Questo passaggio non è necessario se utilizzi i secret Kubernetes o Workload Identity per autenticare gli account di servizio.

    La tabella seguente mostra la destinazione di ciascun servizio dell'account di servizio, a seconda del tipo di installazione:

    Produzione

    Service account Nome file predefinito Directory dei grafici Helm
    apigee-cassandra PROJECT_ID-apigee-cassandra.json $APIGEE_HELM_CHARTS_HOME/apigee-datastore/
    apigee-logger PROJECT_ID-apigee-logger.json $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    apigee-mart PROJECT_ID-apigee-mart.json $APIGEE_HELM_CHARTS_HOME/apigee-org/
    apigee-metrics PROJECT_ID-apigee-metrics.json $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    apigee-runtime PROJECT_ID-apigee-runtime.json $APIGEE_HELM_CHARTS_HOME/apigee-env
    apigee-synchronizer PROJECT_ID-apigee-synchronizer.json $APIGEE_HELM_CHARTS_HOME/apigee-env/
    apigee-udca PROJECT_ID-apigee-udca.json $APIGEE_HELM_CHARTS_HOME/apigee-org/
    apigee-watcher PROJECT_ID-apigee-watcher.json $APIGEE_HELM_CHARTS_HOME/apigee-org/

    Non prod

    Crea una copia del file dell'account di servizio apigee-non-prod in ciascuno dei seguenti directory:

    Service account Nome file predefinito Directory dei grafici Helm
    apigee-non-prod PROJECT_ID-apigee-non-prod.json $APIGEE_HELM_CHARTS_HOME/apigee-datastore/
    $APIGEE_HELM_CHARTS_HOME/apigee-telemetry/
    $APIGEE_HELM_CHARTS_HOME/apigee-org/
    $APIGEE_HELM_CHARTS_HOME/apigee-env/
  5. Assicurati che i file del certificato e della chiave TLS (.crt, .key e/o .pem) si trovino nella directory $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/.

Esegui l'upgrade della versione di Kubernetes

Controlla la versione della piattaforma Kubernetes e, se necessario, esegui l'upgrade a una versione supportata sia da hybrid 1.12 sia da hybrid 1.13. Se hai bisogno di assistenza, segui la documentazione della piattaforma.

Installazione del runtime ibrido 1.13.1

Prepararsi per l'upgrade dei grafici Helm

  1. Estrai i grafici Helm di Apigee.

    I grafici ibridi Apigee sono ospitati in Google Artifact Registry:

    oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts

    Con il comando pull, copia tutti i pod ibridi di Apigee nello spazio di archiviazione locale con il seguente comando: 

    export CHART_REPO=oci://us-docker.pkg.dev/apigee-release/apigee-hybrid-helm-charts
export CHART_VERSION=1.13.1
helm pull $CHART_REPO/apigee-operator --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-datastore --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-env --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-ingress-manager --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-org --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-redis --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-telemetry --version $CHART_VERSION --untar
helm pull $CHART_REPO/apigee-virtualhost --version $CHART_VERSION --untar
  2. Se necessario, esegui l'upgrade di cert-manager.

    Se devi eseguire l'upgrade della versione di cert-manager, installa la nuova versione con il seguente comando:

    kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.15.1/cert-manager.yaml

    Vedi Piattaforme e versioni supportate: cert-manager per un elenco delle versioni supportate.

  3. Se lo spazio dei nomi Apigee non è apigee, modifica il file apigee-operator/etc/crds/default/kustomization.yaml e sostituisci il valore namespace con lo spazio dei nomi Apigee. 
    apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE

    Se utilizzi apigee come spazio dei nomi, non devi modificare il file.

  4. Installa i CRD di Apigee aggiornati: di Gemini Advanced. di Gemini Advanced.

    1. Utilizza la funzionalità di prova simulata kubectl eseguendo il seguente comando:

      kubectl apply -k  apigee-operator/etc/crds/default/ --server-side --force-conflicts --validate=false --dry-run=server

    2. Dopo la convalida con il comando dry-run, esegui il seguente comando:

      kubectl apply -k  apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
    3. Convalida l'installazione con il comando kubectl get crds: 
      kubectl get crds | grep apigee

      L'output dovrebbe essere simile al seguente:

      apigeedatastores.apigee.cloud.google.com                    2024-08-21T14:48:30Z
apigeedeployments.apigee.cloud.google.com                   2024-08-21T14:48:30Z
apigeeenvironments.apigee.cloud.google.com                  2024-08-21T14:48:31Z
apigeeissues.apigee.cloud.google.com                        2024-08-21T14:48:31Z
apigeeorganizations.apigee.cloud.google.com                 2024-08-21T14:48:32Z
apigeeredis.apigee.cloud.google.com                         2024-08-21T14:48:33Z
apigeerouteconfigs.apigee.cloud.google.com                  2024-08-21T14:48:33Z
apigeeroutes.apigee.cloud.google.com                        2024-08-21T14:48:33Z
apigeetelemetries.apigee.cloud.google.com                   2024-08-21T14:48:34Z
cassandradatareplications.apigee.cloud.google.com           2024-08-21T14:48:35Z
  5. Esegui la migrazione di apigee-operator dallo spazio dei nomi apigee-system a APIGEE_NAMESPACE.
    1. Aggiungi un'annotazione a clusterIssuer con il nuovo spazio dei nomi 
      kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='APIGEE_NAMESPACE'
    2. Se stai modificando il nome della release per apigee-operator, annota la clusterIssuer con il nome della nuova release. 
      kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-name='APIGEE_OPERATOR_RELEASE_NAME'
  6. Aggiorna le repliche del deployment dell'operatore Apigee esistente nello spazio dei nomi apigee-system impostandole su 0 (zero) per evitare la riconciliazione dei due controller. 
    kubectl scale deployment apigee-controller-manager -n apigee-system --replicas=0
  7. Aggiorna le repliche del tuo deployment di Apigee Operator esistente nello spazio dei nomi apigee-system su 0 (zero) per evitare la riconciliazione dei due controller. 
    kubectl delete mutatingwebhookconfiguration apigee-mutating-webhook-configuration
kubectl delete validatingwebhookconfiguration apigee-validating-webhook-configuration

  8. Controlla le etichette sui nodi del cluster. Per impostazione predefinita, Apigee pianifica i pod di dati sui nodi con l'etichetta cloud.google.com/gke-nodepool=apigee-data e i pod di runtime vengono pianificati sui nodi con l'etichetta cloud.google.com/gke-nodepool=apigee-runtime. Puoi personalizzare le etichette del pool di nodi nel file overrides.yaml.

    Per ulteriori informazioni, vedi Configurazione di pool di nodi dedicati.

Installa i grafici Helm ibridi Apigee

  1. In caso contrario, vai alla directory APIGEE_HELM_CHARTS_HOME. Esegui i seguenti comandi da questa directory.
  2. Esegui l'upgrade di Apigee Operator/Controller:

    Prova:

    helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run

    Esegui l'upgrade del grafico:

    helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

    Verifica l'installazione dell'operatore Apigee:

    helm ls -n APIGEE_NAMESPACE

    NAME       NAMESPACE       REVISION   UPDATED                                STATUS     CHART                   APP VERSION
operator   apigee   3          2024-08-21 00:42:44.492009 -0800 PST   deployed   apigee-operator-1.13.1   1.13.1

    Verifica che sia attivo e funzionante controllandone la disponibilità:

    kubectl -n APIGEE_NAMESPACE get deploy apigee-controller-manager

    NAME                        READY   UP-TO-DATE   AVAILABLE   AGE
apigee-controller-manager   1/1     1            1           7d20h
  3. Esegui l'upgrade del datastore Apigee:

    Prova:

    helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run=server

    Esegui l'upgrade del grafico:

    helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

    Verifica che apigeedatastore sia attivo controllandone lo stato:

    kubectl -n APIGEE_NAMESPACE get apigeedatastore default

    NAME      STATE       AGE
default   running    2d
  4. Esegui l'upgrade della telemetria Apigee:

    Prova:

    helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run

    Esegui l'upgrade del grafico:

    helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

    Verifica che sia attivo e funzionante controllandone lo stato:

    kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry

    NAME               STATE     AGE
apigee-telemetry   running   2d
  5. Esegui l'upgrade di Apigee Redis:

    Prova:

    helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run

    Esegui l'upgrade del grafico:

    helm upgrade redis apigee-redis/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

    Verifica che sia attivo e funzionante controllandone lo stato:

    kubectl -n APIGEE_NAMESPACE get apigeeredis default

    NAME      STATE     AGE
default   running   2d
  6. Esegui l'upgrade di Apigee Ingress Manager:

    Prova:

    helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run

    Esegui l'upgrade del grafico:

    helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

    Verifica che sia attivo e funzionante controllandone la disponibilità:

    kubectl -n APIGEE_NAMESPACE get deployment apigee-ingressgateway-manager

    NAME                            READY   UP-TO-DATE   AVAILABLE   AGE
apigee-ingressgateway-manager   2/2     2            2           2d
  7. Esegui l'upgrade dell'organizzazione Apigee:

    Prova:

    helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE \
  --dry-run

    Esegui l'upgrade del grafico:

    helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  -f OVERRIDES_FILE

    Verifica che sia attivo e funzionante controllando lo stato dell'organizzazione corrispondente:

    kubectl -n APIGEE_NAMESPACE get apigeeorg

    NAME                      STATE     AGE
apigee-org1-xxxxx          running   2d
  8. Esegui l'upgrade dell'ambiente.

    Devi installare un ambiente alla volta. Specifica l'ambiente con --set env=ENV_NAME.

    Prova:

    helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run
    • ENV_RELEASE_NAME è il nome con cui hai installato in precedenza il grafico apigee-env. In Hybrid v1.10, in genere è apigee-env-ENV_NAME. Nella versione ibrida v1.11 e successive in genere è ENV_NAME.
    • ENV_NAME è il nome dell'ambiente di cui stai eseguendo l'upgrade.
    • OVERRIDES_FILE è il nuovo file di override per la versione 1.13.1

    Esegui l'upgrade del grafico:

    helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE

    Verifica che sia attivo controllando lo stato del rispettivo env:

    kubectl -n APIGEE_NAMESPACE get apigeeenv

    NAME                          STATE       AGE   GATEWAYTYPE
apigee-org1-dev-xxx            running     2d
  9. Esegui l'upgrade dei gruppi di ambienti (virtualhosts).
    1. Devi eseguire l'upgrade di un gruppo di ambienti (virtualhost) alla volta. Specifica l'ambiente gruppo con --set envgroup=ENV_GROUP_NAME. Ripeti i seguenti comandi per ogni gruppo di ambienti menzionato nel file overrides.yaml:

      Prova:

      helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE \
  --dry-run

      ENV_GROUP_RELEASE_NAME è il nome con cui hai installato in precedenza la Grafico apigee-virtualhost. Nella versione ibrida v1.10, di solito viene apigee-virtualhost-ENV_GROUP_NAME. Nella versione ibrida v1.11 e successive viene di solito ENV_GROUP_NAME.

      Esegui l'upgrade del grafico:

      helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE
    2. Controlla lo stato di ApigeeRoute (AR).

      L'installazione del virtualhosts crea ApigeeRouteConfig (ARC), che internamente crea ApigeeRoute (AR) quando lo watcher Apigee estrae i dettagli relativi al gruppo di ambienti dal control plane. Pertanto, verifica che lo stato corrispondente dell'AR sia in esecuzione: 

      kubectl -n APIGEE_NAMESPACE get arc

      NAME                                STATE   AGE
apigee-org1-dev-egroup                       2d
       
      kubectl -n APIGEE_NAMESPACE get ar

      NAME                                        STATE     AGE
apigee-org1-dev-egroup-xxxxxx                running   2d
  10. Dopo aver verificato che l'upgrade di tutte le installazioni è andato a buon fine, elimina la versione precedente di apigee-operator dallo spazio dei nomi apigee-system.
    1. Disinstalla la release precedente di operator: 
      helm delete operator -n apigee-system
    2. Elimina lo spazio dei nomi apigee-system: 
      kubectl delete namespace apigee-system
  11. Esegui di nuovo l'upgrade di operator nello spazio dei nomi Apigee per reinstallare le risorse con ambito cluster eliminate: 
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f overrides.yaml
di Gemini Advanced.

Eseguire il rollback a una versione precedente

Per eseguire il rollback alla versione precedente, utilizza la versione precedente del grafico per eseguire il rollback della procedura di upgrade nell'ordine inverso. Inizia con apigee-virtualhost e torna a apigee-operator, quindi ripristina i CRD.

A causa della modifica nello spazio dei nomi per apigee-operator, devi eseguire passaggi aggiuntivi per eliminare gli hook di ammissione Convalida e modifica. In questo modo, quando installi di nuovo apigee-operator nello spazio dei nomi apigee-system, questi verranno ricreati in modo da puntare all'endpoint dell'operatore Apigee corretto.

  1. Aggiorna le repliche del deployment di Apigee Operator esistente in Apigee su 0 (zero) per evitare che i due controller riconcilino le risorse personalizzate per evitare conflitti durante il rollback nello spazio dei nomi apigee-system. 
    kubectl scale deployment apigee-controller-manager -n APIGEE_NAMESPACE --replicas=0

kubectl delete mutatingwebhookconfiguration \
  apigee-mutating-webhook-configuration-APIGEE_NAMESPACE

kubectl delete validatingwebhookconfiguration \
  apigee-validating-webhook-configuration-APIGEE_NAMESPACE
  2. Ripristina tutti i grafici da apigee-virtualhost a apigee-datastore. I comandi riportati di seguito presuppongono che tu stia utilizzando i grafici della versione precedente (v1.12.x).

    Esegui questo comando per ogni gruppo di ambienti:

    helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace apigee \
  --atomic \
  --set envgroup=ENV_GROUP_NAME \
  -f 1.12_OVERRIDES_FILE

    Esegui questo comando per ogni ambiente:

    helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace apigee \
  --atomic \
  --set env=ENV_NAME \
  -f 1.12_OVERRIDES_FILE

    Ripristina i grafici rimanenti, ad eccezione di apigee-operator.

    helm upgrade ORG_NAME apigee-org/ \
  --install \
  --namespace apigee \
  --atomic \
  -f 1.12_OVERRIDES_FILE

    helm upgrade ingress-manager apigee-ingress-manager/ \
  --install \
  --namespace apigee \
  --atomic \
  -f 1.12_OVERRIDES_FILE

    helm upgrade redis apigee-redis/ \
  --install \
  --namespace apigee \
  --atomic \
  -f 1.12_OVERRIDES_FILE

    helm upgrade telemetry apigee-telemetry/ \
  --install \
  --namespace apigee \
  --atomic \
  -f 1.12_OVERRIDES_FILE

    helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace apigee \
  --atomic \
  -f 1.12_OVERRIDES_FILE
  3. Crea lo spazio dei nomi apigee-system. 
    kubectl create namespace apigee-system
  4. Applica la patch dell'annotazione della risorsa allo spazio dei nomi apigee-system. 
    kubectl annotate --overwrite clusterIssuer apigee-ca-issuer meta.helm.sh/release-namespace='apigee-system'
  5. Se hai modificato anche il nome della release, aggiorna l'annotazione con il nome della release operator. 
    kubectl annotate --overwrite cluseterIssuer apigee-ca-issuer meta.helm.sh/release-name='operator'
  6. Installa di nuovo apigee-operator nello spazio dei nomi apigee-system. 
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace apigee-system \
  --atomic \
  -f 1.12_OVERRIDES_FILE
  7. Ripristina i CRD reinstallando quelli precedenti. 
    kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
  8. Esegui la pulizia della release apigee-operator dallo spazio dei nomi APIGEE_NAMESPACE per completare il processo di rollback. 
    helm uninstall operator -n APIGEE_NAMESPACE
  9. Alcune risorse con ambito cluster, come clusterIssuer, vengono eliminate quando operator viene disinstallato. Reinstallali con il seguente comando: 
    helm upgrade operator apigee-operator/ \
  --install \
  --namespace apigee-system \
  --atomic \
  -f 1.12_OVERRIDES_FILE