Upgrade di Apigee hybrid alla versione 1.3.6

<0x0A

Se esegui l'upgrade da Apigee hybrid versione 1.0 o 1.1, devi prima eseguire l'upgrade alla versione 1.2 prima di eseguire l'upgrade alla versione 1.3.6. Consulta le istruzioni per l'upgrade di Apigee hybrid alla versione 1.2.

Panoramica dell'upgrade alla versione 1.3.6.

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

  1. preparazione
    1. Crea e aggiorna i service account.
    2. Pianifica i gruppi di ambienti.
    3. Copia e aggiorna il file di override.
  2. Esegui l'upgrade di Istio e cert-manager.
  3. Installa la versione 1.3 del runtime di hybrid.
  4. Eseguire la pulizia.

Prerequisito

preparazione

  1. (Consigliato) Crea una copia di backup della directory $APIGEECTL_HOME/ della versione 1.2. Ad esempio:
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
  2. (Consigliato) Esegui il backup del database Cassandra seguendo le istruzioni riportate in Backup e ripristino di Cassandra.
  3. Esegui l'upgrade della piattaforma Kubernetes come segue. Consulta la documentazione della tua piattaforma se hai bisogno di aiuto:
    Piattaforma Esegui l'upgrade alla versione
    GKE 1.15.x
    Anthos 1,5
    AKS 1.16.x utilizzando i cluster collegati ad Anthos
  4. Se non utilizzi Apigee Connect nell'installazione ibrida, abilita Apigee Connect.
    1. Controlla se l'API Apigee Connect è abilitata:
      gcloud services list | grep apigeeconnect
      
      apigeeconnect.googleapis.com         Apigee Connect API
    2. In caso contrario, abilita l'API:
      gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID

      Dove $PROJECT_ID è l'ID del tuo progetto Google Cloud.

    3. Nella riga di comando, recupera le credenziali di autenticazione gcloud, come mostrato nell'esempio seguente:

      TOKEN=$(gcloud auth print-access-token)

      Per verificare che il token sia stato compilato, utilizza echo, come mostrato nell'esempio seguente:

      echo $TOKEN

      Dovrebbe essere visualizzato il token come stringa codificata.

      Per saperne di più, consulta la panoramica dello strumento a riga di comando gcloud.

    4. Controlla se Apigee Connect è abilitato per la tua organizzazione:
      curl -H "Authorization: Bearer $TOKEN" \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      dove $ORG_NAME è l'ID della tua organizzazione.

      Se l'output contiene:

            "name" : "features.mart.connect.enabled",
            "value" : "true"

      Apigee Connect è abilitato.

    5. Se Apigee Connect non è abilitato, assegna il ruolo Agente Apigee Connect al service account MART:
      gcloud projects add-iam-policy-binding $PROJECT_ID \
        --member serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com \
        --role roles/apigeeconnect.Agent
    6. Abilita Apigee Connect con il seguente comando:
      curl -H "Authorization: Bearer $TOKEN" -X PUT \
        -H "Content-Type: application/json" \
        -d '{
          "name" : "'"$ORG_NAME"'",
          "properties" : {
            "property" : [ {
              "name" : "features.hybrid.enabled",
              "value" : "true"
            }, {
              "name" : "features.mart.connect.enabled",
              "value" : "true"
            } ]
          }
        }' \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"
      

      Se l'output contiene le due proprietà seguenti, Apigee Connect è stato abilitato correttamente:

            {
              "name": "features.mart.connect.enabled",
              "value": "true"
            },
            {
              "name": "features.hybrid.enabled",
              "value": "true"
            }
      
  5. Crea il account di servizio apigee-watcher. Apigee Watcher è un nuovo account di servizio introdotto nella versione 1.3. Monitora il sincronizzatore per le modifiche a livello di organizzazione e applica queste modifiche per configurare l'ingresso Istio.

    Dalla directory ibrida principale:

    ./tools/create-service-account apigee-watcher ./service-accounts
  6. Assegna il ruolo Agente runtime Apigee all'account di servizio Watcher:
    gcloud projects add-iam-policy-binding $PROJECT_ID \
      --member serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com \
      --role roles/apigee.runtimeAgent

    dove PROJECT_ID è l'ID del tuo progetto Google Cloud. Se gli indirizzi email del tuo account di servizio differiscono da questo pattern, sostituiscili di conseguenza.

    L'output deve includere un elenco di tutti i service account e dei relativi ruoli, tra cui:

      ...
    - members:
      - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
      role: roles/apigee.runtimeAgent
      ...
  7. Pianifica i gruppi di ambienti per il routing. Apigee hybrid 1.3 gestisce il routing del percorso di base con i gruppi di ambienti anziché con routingRules. Se utilizzi routingRules nella configurazione ibrida, progetta gruppi di ambienti per replicare il routing.

    Devi creare almeno un gruppo di ambienti.

    Consulta Informazioni sui gruppi di ambienti.

  8. Aggiorna il file di override:
    1. Crea una copia del file di override.
    2. Aggiorna le sezioni gcp e k8sCluster.

      Le seguenti proprietà di configurazione sono state sostituite nella versione 1.3 ibrida:

      • gcpRegion sostituito con gcp:region
      • gcpProjectID sostituito con gcp:projectID
      • gcpProjectIDRuntime sostituito con gcp:gcpProjectIDRuntime
      • k8sClusterName sostituito con k8s:clusterName
      • k8sClusterRegion sostituito con k8s:clusterRegion

      Ad esempio, sostituisci la seguente struttura:

      gcpRegion: gcp region
      gcpProjectID: gcp project ID
      gcpProjectIDRuntime: gcp project ID
      
      k8sClusterName: name
      k8sClusterRegion: region

      with:

      gcp:
       projectID: gcp project ID
       region: gcp region
       gcpProjectIDRuntime: gcp project ID # optional. This is only required if you
                                             # want logger/metrics data to be sent in
                                             # different gcp project.
      
      k8sCluster:
       name: gcp project ID
       region: gcp region
      
    3. Se nel file di override non è già presente un identificatore di istanza univoco, aggiungine uno:
      # unique identifier for this installation. 63 chars length limit
      instanceID: ID

      dove ID è un identificatore univoco per questa installazione ibrida, ad esempio "my-hybrid-131-installation" o "acmecorp-hybrid-131".

    4. Aggiungi il account di servizio Watcher (apigee-watcher) al file di override:
      # Note: the SA should have the "Apigee Runtime Agent" role
      watcher:
       serviceAccountPath: "service account file"
    5. Aggiungi il account di servizio Metriche (apigee-metrics) al file degli override:
      metrics:
       serviceAccountPath: "service account file"
    6. Aggiorna la sezione virtualhosts: per sostituire routingRules con il tuo gruppo di ambienti.
      1. -name: Sostituisci il nome con il nome del tuo gruppo di ambienti. Puoi avere più voci di nome, una per ogni gruppo di ambienti.
      2. hostAliases:[] Elimina questa riga.
      3. Mantieni (o aggiungi) le voci sslCertPath: e sslKeyPath:.
      4. Elimina tutte le voci routingRules.

      Ad esempio:

      virtualhosts:
        - name: default
          hostAliases:
            - "*.acme.com"
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
          routingRules:
            - paths:
              - /foo
              - /bar
            - env: my-environment

      Diventa:

      virtualhosts:
        - name: example-env-group
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
    7. Aggiorna le sezioni mart e connectAgent:.
      1. In mart: rimuovi le voci hostAlias:, sslCertPath: e sslKeyPath:.
      2. Aggiungi una strofa connectAgent:.
      3. In connectAgent: aggiungi una voce serviceAccountPath: e fornisci il percorso del file del service account a cui è assegnato il ruolo Agente Apigee Connect (di solito il account di servizio MART).

      Ad esempio:

      mart:
        hostAlias: "mart.apigee-hybrid-docs.net"
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
        sslCertPath: ./certs/fullchain.pem
        sslKeyPath: ./certs/privkey.key

      Diventa:

      mart:
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json
      
      connectAgent:
        serviceAccountPath: ./service-accounts/hybrid-project-apigee-mart.json

Esegui l'upgrade di Istio e cert-manager

Apigee hybrid versione 1.3 richiede cert-manager v0.14.2 per gestire e verificare i certificati e la distribuzione Istio fornita con Anthos Service Mesh (ASM) versione 1.5.7 (o successive) per creare e gestire il gateway di ingresso runtime.

Esegui l'upgrade di Istio 1.4.6 ad ASM 1.5.7 (o versioni successive)

  1. Per ridurre al minimo i tempi di inattività, i deployment Istio e gli HPA devono avere almeno due repliche ciascuno. Esegui questi comandi per determinare il numero di repliche:
    kubectl -n istio-system get deployments # list of deployments
    kubectl -n istio-system get hpa # list of hpa
  2. Modifica ogni deployment con una sola replica e aumenta replicas: a 2 o più:
    kubectl -n istio-system edit deployment name

    Ad esempio:

    spec:
      progressDeadlineSeconds: 600
      replicas: 2
  3. Modifica ogni HPA con una sola replica e aumenta minReplicas: a 2 o più:
    kubectl -n istio-system edit hpa name

    Ad esempio:

    spec:
      maxReplicas: 5
      minReplicas: 2
    
  4. Scarica e installa ASM seguendo le istruzioni di installazione riportate in Scaricare e installare ASM.
  5. Dopo l'installazione, esegui il comando della versione per assicurarti di aver installato correttamente la versione 1.5.x:
    ./bin/istioctl version
    
    client version: 1.5.8-asm.0
    apigee-mart-ingressgateway version:
    citadel version: 1.4.6
    galley version: 1.4.6
    ingressgateway version: 1.5.8-asm.0
    pilot version: 1.4.6
    policy version: 1.4.6
    sidecar-injector version: 1.4.6
    telemetry version: 1.4.6
    pilot version: 1.5.8-asm.0
    data plane version: 1.4.6 (1 proxies), 1.5.8-asm.0 (2 proxies)

Esegui l'upgrade di cert-manager

  1. Elimina il deployment di cert-manager corrente:
    kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
  2. Verifica la tua versione di Kubernetes:
    kubectl version
  3. Esegui il seguente comando per installare cert-manager da Jetstack:
    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml 

Installare il runtime di hybrid

  1. Memorizza il numero dell'ultima versione in una variabile:
    export VERSION=$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
  2. Controlla che la variabile sia stata compilata con un numero di versione. Se vuoi utilizzare una versione diversa, puoi salvarla in una variabile di ambiente. Ad esempio:
    echo $VERSION
      1.3.6
  3. Scarica il pacchetto di rilascio per il tuo sistema operativo:

    Mac a 64 bit:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_64.tar.gz

    Linux a 64 bit:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_64.tar.gz

    Mac 32 bit:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_mac_32.tar.gz

    Linux a 32 bit:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
  4. Rinomina la directory apigeectl/ attuale con il nome di una directory di backup. Ad esempio:
    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
  5. Estrai i contenuti del file gzip scaricato nella directory di base ibrida. Ad esempio:

    tar xvzf filename.tar.gz -C hybrid-base-directory
  6. cd alla directory di base.
  7. Per impostazione predefinita, i contenuti del file tar vengono espansi in una directory con la versione e la piattaforma nel nome. Ad esempio: ./apigeectl_1.0.0-f7b96a8_linux_64. Rinomina la directory in apigeectl:

    mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
  8. Elimina il job apigee-resources-install da apigee-system:
    kubectl -n apigee-system delete job apigee-resources-install
  9. Elimina il CRD precedente:
    kubectl delete crd apigeetelemetries.apigee.cloud.google.com
  10. Aggiorna la sezione cassandra: nel file di override con una proprietà externalSeedHost. Questa proprietà contribuirà a garantire che la nuova versione 1.3.6 di hybrid utilizzi lo stesso cluster Kubernetes della versione 1.2. Questo passaggio viene eseguito una sola volta ed è necessario solo per l'upgrade dalla versione ibrida 1.2 alla versione 1.3.6 (o versioni successive).
    1. Trova uno degli indirizzi IP dell'istanza di Cassandra esistente nello stesso cluster Kubernetes in cui esegui l'upgrade dell'installazione 1.2.0.
      kubectl -n namespace get pods -o wide

      dove namespace è lo spazio dei nomi Apigee hybrid.

      Prendi nota dell'indirizzo IP di un nodo Cassandra. Ad esempio:

      kubectl -n apigee get pods -o wide
      NAME                  READY   STATUS    RESTARTS   AGE   IP          NODE
      apigee-cassandra-0    1/1     Running   0          33d   10.68.8.24   gke-example-cluster-rc5-apigee-data-c8bf1234-09kc
      apigee-cassandra-1    1/1     Running   0          16d   10.68.8.33   gke-example-cluster-rc5-apigee-data-c9221ee7-10kc
      apigee-cassandra-2    1/1     Running   0          23h   10.68.9.11   gke-example-cluster-rc5-apigee-data-d123e456-11kc
    2. Aggiungi il valore per la proprietà externalSeedHost:
      cassandra:
       externalSeedHost: Cassandra_node_IP

      Dove Cassandra_node_IP è l'IP del nodo Cassandra (10.68.8.24 nell'esempio precedente).

  11. Nella directory apigeectl/ nuova, esegui apigeectl init, apigeectl apply e apigeectl check-ready:
    1. Inizializza hybrid 1.3.6:
      apigeectl init -f overrides_1.3.yaml

      Dove overrides_1.3.yaml è il file overrides.yaml modificato.

    2. Nella versione ibrida 1.3, la sintassi del flag --dry-run dipende dalla versione di kubectl in esecuzione. Controlla la versione di kubectl:
      gcloud version
    3. Controlla la presenza di errori con una prova:

      kubectl versione 1.17 e precedenti:

      apigeectl apply -f overrides_1.3.yaml --dry-run=true

      kubectl versione 1.18 e successive:

      apigeectl apply -f overrides_1.3.yaml --dry-run=client
    4. Applica gli override. Seleziona e segui le istruzioni per gli ambienti di produzione o per gli ambienti demo/sperimentali, a seconda dell'installazione.

      Produzione

      Per gli ambienti di produzione, devi eseguire l'upgrade di ogni componente ibrido singolarmente e controllare lo stato del componente di cui è stato eseguito l'upgrade prima di procedere con il componente successivo.

      1. Applica gli override per eseguire l'upgrade di Cassandra:
        apigeectl apply -f overrides_1.3.yaml --datastore
      2. Completamento del controllo:
        kubectl -n namespace get pods

        dove namespace è lo spazio dei nomi Apigee hybrid.

        Procedi al passaggio successivo solo quando i pod sono pronti.

      3. Applica gli override per eseguire l'upgrade dei componenti di Telemetry e verifica il completamento:
        apigeectl apply -f overrides_1.3.yaml --telemetry
        kubectl -n namespace get pods
      4. Applica gli override per eseguire l'upgrade dei componenti a livello di organizzazione (MART, Watcher e Apigee Connect) e verifica il completamento:
        apigeectl apply -f overrides_1.3.yaml --org
        kubectl -n namespace get pods
      5. Applica gli override per eseguire l'upgrade degli ambienti. Hai due opzioni:
        • Applica gli override a un ambiente alla volta e verifica il completamento. Ripeti questo passaggio per ogni ambiente:
          apigeectl apply -f overrides_1.3.yaml --env env_name
          kubectl -n namespace get pods

          dove env_name è il nome dell'ambiente di cui stai eseguendo l'upgrade.

        • Applica gli override a tutti gli ambienti contemporaneamente e verifica il completamento:
          apigeectl apply -f overrides_1.3.yaml --all-envs
          kubectl -n namespace get pods

      Demo/Sperimentale

      Nella maggior parte degli ambienti demo o sperimentali, puoi applicare gli override a tutti i componenti contemporaneamente. Se il tuo ambiente demo/sperimentale è grande e complesso o imita da vicino un ambiente di produzione, ti consigliamo di utilizzare le istruzioni per l'upgrade degli ambienti di produzione.

      1. apigeectl apply -f overrides_1.3.yaml
      2. Controlla lo stato:
        apigeectl check-ready -f overrides_1.3.yaml

      Per ulteriori istruzioni, consulta Configurazione di GKE Hybrid - Passaggio 5: installa GKE Hybrid su GKE.

    5. Una volta configurato e in esecuzione ibrido 1.3, verifica che tutti i nodi Cassandra (vecchi e nuovi) facciano parte dello stesso cluster Cassandra. Esegui questo comando su uno dei nodi Cassandra:
      kubectl -n namespace get pods
      kubectl -n namespace exec old Cassandra pod -- nodetool status

      Nell'output di esempio seguente, 10.68.8.24 proviene dalla versione 1.2.0 ed è l'IP del nodo che hai utilizzato come externalSeedHost. 10.68.7.11 proviene dalla versione 1.3.6:

      Datacenter: dc-1
      ================
      Status=Up/Down
      |/ State=Normal/Leaving/Joining/Moving
      --  Address     Load        Tokens       Owns (effective)  Host ID                               Rack
      UN  10.68.8.24  379.41 KiB  256          50.8%             11bbd43b-af64-464b-a96d-0d6dd0521de1  ra-1
      UN  10.68.7.11  1.35 MiB    256          49.2%             0b4d9e08-f353-413a-b4a9-7d18a8d07e58  ra-1

      Se non si trovano nello stesso cluster, controlla il valore externalSeedHost.

    6. Una volta che tutti i pod sono in funzione, rimuovi externalSeedHost dal file di override ed esegui di nuovo apigeectl apply con l'opzione --datastore:
      apigeectl apply --datastore -f overrides_1.3.6.yaml

    Esegui la pulizia

    Una volta verificato che tutti i pod sono attivi e integri e che gli endpoint ASM sono validi per la nuova installazione, puoi eseguire la pulizia:

    • Risorse di Hybrid 1.2.
    • L'istanza di Cassandra precedente
    • Risorse di Istio 1.4.6.

    Elimina le risorse di Hybrid 1.2.0

    1. Rimuovi i dettagli di routing del virtual host 1.2.0:
      $APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml

      dove $APIGEECTL_HOME-v1.2 è la directory in cui hai eseguito il backup della directory apigeectl versione 1.2.

    2. Se l'endpoint funziona ancora come previsto e hai verificato che tutti i componenti della versione 1.3.0 funzionano, esegui questo comando per eliminare le risorse ibride della versione 1.2.0:
      $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
        -f 1.2.0_overrides.yaml

    Ritirare l'istanza di Cassandra precedente

    1. cd nella directory apigeectl appena installata.
    2. Esegui lo script tools/cas_cleanup.sh.

      Questo script ritira il vecchio pod Cassandra dall'anello Cassandra, elimina i vecchi STS ed elimina i PVC.

      bash cas_cleanup.sh Apigee namespace

    Elimina le risorse di Istio versione 1.4.6

    1. Esegui questo comando per eliminare le risorse Istio v.1.4.6 più recenti:
      kubectl delete all -n istio-system --selector \
        'app in (apigee-mart-istio-ingressgateway, galley, security, istio-nodeagent, istio-mixer, sidecarInjectorWebhook, istio-mixer)'
    2. Esegui i seguenti comandi per eliminare i job precedenti dall'installazione di Istio 1.4.6:
      kubectl -n istio-system delete job istio-init-crd-10-1.4.6
      kubectl -n istio-system delete job istio-init-crd-11-1.4.6
      kubectl -n istio-system delete job istio-init-crd-14-1.4.6

    Complimenti! L'upgrade ad Apigee hybrid versione 1.3.6 è stato eseguito correttamente.