Upgrade di Apigee hybrid alla versione 1.17

Questa procedura riguarda l'upgrade da Apigee hybrid versione 1.16.x ad Apigee hybrid versione 1.17.1 e dalle versioni precedenti di hybrid 1.17.x alla versione 1.17.1.

Utilizza le stesse procedure per gli upgrade delle versioni secondarie (ad esempio dalla versione 1.16 alla 1.17) e per gli upgrade delle release delle patch (ad esempio dalla versione 1.17.0 alla 1.17.1).

Se esegui l'upgrade da Apigee hybrid versione 1.15 o precedente, devi prima eseguire l'upgrade alla versione 1.16 prima di eseguire l'upgrade alla versione 1.17.1. Consulta le istruzioni per l'upgrade di Apigee hybrid alla versione 1.16.

Modifiche apportate da Apigee hybrid v1.16

Tieni presente le seguenti modifiche:

  • Supporto del Model Context Protocol (MCP): Apigee Hybrid versione 1.17 aggiunge il supporto per il Model Context Protocol (MCP), un protocollo aperto che consente alle applicazioni AI agentiche di utilizzare le tue API come strumenti tramite endpoint MCP gestiti. Apigee Hybrid esegue il routing, l'autorizzazione e la protezione di queste chiamate agli strumenti MCP nello stesso modo in cui gestisce le altre API, quindi non devi eseguire o gestire i tuoi server MCP. Per saperne di più, consulta Model Context Protocol (MCP) nella panoramica di Apigee e la guida rapida di MCP.
  • Rotazione del certificato CA radice: Apigee Hybrid versione 1.17 aggiunge il supporto per la rotazione del certificato dell'autorità di certificazione (CA) radice che ancora l'attendibilità per la comunicazione TLS tra i componenti di runtime. Ora puoi sostituire la CA radice prima della scadenza, senza tempi di inattività, seguendo una procedura di rotazione graduale. Per saperne di più, consulta Ruotare il certificato CA radice.
  • Supporto di TLS 1.3: Apigee Hybrid versione 1.17 aggiunge il supporto di TLS 1.3, l'ultima versione del protocollo Transport Layer Security. TLS 1.3 offre handshake di connessione più veloci e una sicurezza maggiore rispetto alle versioni precedenti di TLS. Per informazioni sulla configurazione di TLS sul gateway ingress, vedi Configurazione di TLS e mTLS sul gateway ingress.
  • Supporto del proxy di inoltro per le policy AI: Apigee Hybrid versione 1.17 aggiunge il supporto del proxy di inoltro per le policy AI, come le policy Model Armor e di memorizzazione nella cache semantica. Le chiamate in uscita effettuate da questi criteri ora possono essere instradate tramite un proxy di inoltro HTTP, che non era supportato nelle versioni precedenti di Apigee Hybrid. Per maggiori informazioni, vedi Configura il proxy di inoltro per i proxy API.
  • Supporto dell'endpoint Private Service Connect (PSC) della cache semantica: Apigee Hybrid versione 1.17 aggiunge il supporto dell'endpoint Private Service Connect (PSC) per la memorizzazione nella cache semantica. Le policy di memorizzazione nella cache semantica ora possono raggiungere i servizi di backend tramite un endpoint Private Service Connect, che mantiene il traffico sulla tua rete privata. Per maggiori informazioni, consulta Guida introduttiva alle policy di memorizzazione nella cache semantica.

Per ulteriori informazioni sulle funzionalità della versione 1.17 di Hybrid, consulta le note di rilascio di Apigee Hybrid v1.17.1.

Prerequisiti

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

Prima di eseguire l'upgrade alla versione 1.17.1: limitazioni e note importanti

  • L'upgrade alla versione 1.17 di Apigee hybrid potrebbe richiedere tempi di inattività.

    Quando esegui l'upgrade del controller Apigee alla versione 1.17.1, tutti i deployment Apigee vengono riavviati in sequenza. Per ridurre al minimo i tempi di inattività negli ambienti ibridi di produzione durante un riavvio graduale, assicurati di eseguire almeno due cluster (nello stesso o in un data center/regione diverso). Devia tutto il traffico di produzione a un singolo cluster e metti offline il cluster di cui stai per eseguire l'upgrade, quindi procedi con la procedura di upgrade. Ripeti la procedura per ogni cluster.

    Apigee consiglia di eseguire l'upgrade di tutti i cluster il prima possibile per ridurre le probabilità di impatto sulla produzione. Non esiste un limite di tempo per l'aggiornamento di tutti i cluster rimanenti dopo l'aggiornamento del primo. Tuttavia, finché non vengono eseguiti l'upgrade di tutti i cluster rimanenti, il backup e il ripristino di Cassandra non possono funzionare con versioni miste. Ad esempio, un backup di Hybrid 1.16 non può essere utilizzato per ripristinare un'istanza di Hybrid 1.17.

  • Le modifiche al piano di gestione non devono essere sospese completamente durante un upgrade. Eventuali sospensioni temporanee richieste alle modifiche del piano di gestione sono indicate nelle istruzioni di upgrade riportate di seguito.

Panoramica dell'upgrade alla versione 1.17.1

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

  1. Preparati all'upgrade.
  2. Installa la versione 1.17.1 del runtime ibrido.

Prepararsi all'upgrade alla versione 1.17

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, passa a 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 directory $APIGEE_HELM_CHARTS_HOME/ della versione 1.16. Puoi utilizzare qualsiasi procedura di backup. Ad esempio, puoi creare un file tar dell'intera directory con: 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Esegui il backup del database Cassandra seguendo le istruzioni riportate in Backup e ripristino di Cassandra.
  4. Assicurati che i file di chiave e certificato 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.16 sia da hybrid 1.17. Se hai bisogno di aiuto, consulta la documentazione della tua piattaforma.

Estrai i grafici Helm di Apigee.

I grafici Apigee hybrid sono ospitati in Google Artifact Registry:

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

Utilizzando il comando pull, copia tutti i grafici Helm di Apigee Hybrid 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.17.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

Modifica kustomization.yaml per uno spazio dei nomi Apigee personalizzato

Se il tuo spazio dei nomi Apigee non è apigee, modifica il file apigee-operator/etc/crds/default/kustomization.yaml e sostituisci il valore namespace con il tuo 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.

  • Installa le CRD Apigee aggiornate:

    1. Utilizza la funzionalità dry run di 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 questo 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

  • 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 saperne di più, consulta Configurazione dei pool di nodi dedicati.

    • Esegui l'upgrade di cert-manager

    Apigee hybrid v1.17 supporta le release di cert-manager dalla 1.16 alla 1.19. In cert-manager 1.18 è stata apportata una modifica che può causare un problema con il traffico. Nella release 1.18 di cert-manager, il valore predefinito di Certificate.Spec.PrivateKey.rotationPolicy è stato modificato da Never a Always. Per le installazioni di Apigee hybrid aggiornate, questo può causare un problema con il traffico. Quando esegui l'upgrade alla versione ibrida 1.17 da una versione precedente, devi modificare il certificato apigee-ca per compensare questa modifica o mantenere la versione di cert-manager alla release 1.17.x o precedente.

    Prima di eseguire l'upgrade di cert-manager alla versione 1.18 o 1.19, utilizza la seguente procedura per modificare il certificato apigee-ca in modo da impostare il valore di Certificate.Spec.PrivateKey.rotationPolicy su Never.

    1. Controlla i contenuti del certificato apigee-ca per verificare se rotationPolicy è impostato: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      Cerca i valori in spec.privateKey nell'output:

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    # Note: rotationPolicy would appear here if it is set.
    size: 256
  secretName: apigee-ca
...
    2. Se rotationPolicy non è impostato o se è impostato su Always, modifica il certificato apigee-ca per impostare il valore di rotationPolicy su Never:
      1. Esegui prima un dry run: 
        kubectl patch Certificate \
  --dry-run=server \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
      2. Applica la patch al certificato: 
        kubectl patch Certificate \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
    3. Verifica che il valore di rotationPolicy sia ora impostato su Never: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      L'output dovrebbe essere simile al seguente:

      ...
spec:
  commonName: apigee-hybrid
  duration: 87600h
  isCA: true
  issuerRef:
    group: cert-manager.io
    kind: ClusterIssuer
    name: apigee-root-certificate-issuer
  privateKey:
    algorithm: ECDSA
    rotationPolicy: Never
    size: 256
  secretName: apigee-ca
...
    4. Esegui l'upgrade di cert-manager. Il comando seguente scarica e installa cert-manager v1.19.2: 
      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

      Per un elenco delle versioni supportate, consulta Piattaforme e versioni supportate: cert-manager.

    Vedi:

    Installa il runtime ibrido 1.17.1

    1. In caso contrario, vai alla directory APIGEE_HELM_CHARTS_HOME. Esegui i seguenti comandi da questa directory.
    2. Esegui l'upgrade dell'operatore/controller Apigee:

      Dry run:

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

      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.17.1   1.17.1

      Verifica che sia attivo e funzionante controllando la sua 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:

      Dry run:

      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 in esecuzione controllandone lo stato:

      kubectl -n APIGEE_NAMESPACE get apigeedatastore default

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

      Dry run:

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

      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:

      Dry run:

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

      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:

      Dry run:

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

      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 controllando la sua 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:

      Dry run:

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

      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-my-org-my-env      running   2d
    8. Esegui l'upgrade dell'ambiente.

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

      Dry run:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server
      • ENV_RELEASE_NAME è un nome utilizzato per tenere traccia dell'installazione e degli upgrade del grafico apigee-env. Questo nome deve essere univoco rispetto agli altri nomi delle release Helm nell'installazione. Di solito è uguale a ENV_NAME. Tuttavia, se l'ambiente ha lo stesso nome del gruppo di ambienti, devi utilizzare nomi di release diversi per l'ambiente e il gruppo di ambienti, ad esempio dev-env-release e dev-envgroup-release. Per saperne di più sulle release in Helm, consulta Tre concetti importanti nella documentazione di Helm.
      • ENV_NAME è il nome dell'ambiente di cui stai eseguendo l'upgrade.
      • OVERRIDES_FILE è il nuovo file di override per la versione 1.17.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 e funzionante controllando lo stato dell'ambiente corrispondente:

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      NAME                          STATE       AGE   GATEWAYTYPE
apigee-my-org-my-env          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 il gruppo di ambienti con --set envgroup=ENV_GROUP_NAME. Ripeti i seguenti comandi per ogni gruppo di ambienti menzionato nel file overrides.yaml:

        Dry run:

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

        ENV_GROUP_RELEASE_NAME è il nome con cui hai installato in precedenza il grafico apigee-virtualhost. 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 di virtualhosts crea ApigeeRouteConfig (ARC) che crea internamente ApigeeRoute (AR) una volta che il watcher Apigee estrae i dettagli relativi al gruppo di ambienti dal control plane. Pertanto, verifica che lo stato del AR corrispondente 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-123abc               running   2d

    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 in ordine inverso. Inizia con apigee-virtualhost e torna indietro fino a apigee-operator, quindi ripristina i CRD.

    1. Ripristina i grafici. I seguenti comandi presuppongono che tu stia utilizzando i grafici della versione precedente (v1.16.x).

      1. Esegui questo comando per ogni gruppo di ambienti:

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

      2. Esegui questo comando per ogni ambiente:

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

      3. apigee-org:

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

      4. apigee-ingress-manager:

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

      5. apigee-redis:

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

      6. apigee-telemetry:

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

      7. apigee-datastore:

        helm upgrade datastore apigee-datastore/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE

      8. apigee-operator:

        helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f 1.16_OVERRIDES_FILE
    2. Ripristina i CRD reinstallando i CRD precedenti. 
      kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false