Upgrade di Apigee hybrid alla versione 1.3.6

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 gli account di servizio.
    2. Pianifica i gruppi di ambienti.
    3. Copia e aggiorna il file delle sostituzioni.
  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 recupero di Cassandra
  3. Esegui l'upgrade della piattaforma Kubernetes come segue. Se hai bisogno di aiuto, segui la documentazione della tua piattaforma:
    Piattaforma Esegui l'upgrade alla versione
    GKE 1.15.x
    Anthos 1,5
    AKS 1.16.x che utilizza cluster collegati ad Anthos
  4. Se non utilizzi Apigee Connect nella tua 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, ottieni le credenziali di autenticazione gcloud, come mostrato nell'esempio seguente:

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

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

      echo $TOKEN

      Il token dovrebbe essere visualizzato come stringa codificata.

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

    4. Verifica se Apigee Connect è attivo 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 all'account di servizio 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 attivato correttamente:

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

    Dalla directory ibrida principale:

    ./tools/create-service-account apigee-watcher ./service-accounts
  6. Assegna il ruolo Agente di 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 progetto Google Cloud. Se gli indirizzi email del tuo account di servizio sono diversi da questo modello, sostituiscili di conseguenza.

    L'output deve includere un elenco di tutti gli account di servizio 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 l'indirizzamento. 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 delle sostituzioni:
    1. Crea una copia del file delle sostituzioni.
    2. Aggiorna le stanza gcp e k8sCluster.

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

      • 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 non hai già un identificatore di istanza univoco nel file delle sostituzioni, 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 l'account di servizio Watcher (apigee-watcher) al file delle sostituzioni:
      # Note: the SA should have the "Apigee Runtime Agent" role
      watcher:
       serviceAccountPath: "service account file"
    5. Aggiungi l'account di servizio Metrics (apigee-metrics) al file delle sostituzioni:
      metrics:
       serviceAccountPath: "service account file"
    6. Aggiorna la stanza virtualhosts: sostituendo routingRules con il tuo gruppo di ambienti.
      1. -name: Sostituisci il nome con il nome del 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 stanza mart e connectAgent:.
      1. In mart:, rimuovi le voci hostAlias:, sslCertPath: e sslKeyPath:.
      2. Aggiungi una stanza connectAgent:.
      3. In connectAgent: aggiungi una voce serviceAccountPath: e fornisci il percorso del file dell'account di servizio a cui è assegnato il ruolo Agente Apigee Connect (di solito l'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

La versione 1.3 di Apigee Hybrid richiede cert-manager 0.14.2 per gestire e verificare i certificati e la distribuzione di Istio fornita con Anthos Service Mesh (ASM) versione 1.5.7 (o successiva) per creare e gestire la porta di ingresso di 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 riposo, i deployment e gli HPA di Istio devono avere almeno due repliche ciascuno. Esegui i seguenti 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 che ha 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 Scaricare e installare ASM.
  5. Dopo l'installazione, esegui il comando version per assicurarti che la versione 1.5.x sia installata correttamente:
    ./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 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 

Installa il runtime di hybrid

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

    Mac 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 a 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 stanza cassandra: nel file delle sostituzioni con una proprietà externalSeedHost. Questa proprietà ti aiuterà ad assicurarti che la nuova installazione della versione 1.3.6 ibrida utilizzi lo stesso cluster Kubernetes dell'installazione della versione 1.2. Si tratta di un passaggio una tantum necessario solo per l'upgrade dalla versione ibrida 1.2 alla versione 1.3.6 (o successiva).
    1. Individua uno degli indirizzi IP di Cassandra esistente nello stesso cluster Kubernetes in cui stai eseguendo l'upgrade dell'installazione 1.2.0.
      kubectl -n namespace get pods -o wide

      dove namespace è il tuo 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 nuova directory apigeectl/, 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. Verifica 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 le sostituzioni. Seleziona e segui le istruzioni per gli ambienti di produzione o demo/sperimentali, a seconda dell'installazione.

      Produzione

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

      1. Applica le sostituzioni per eseguire l'upgrade di Cassandra:
        apigeectl apply -f overrides_1.3.yaml --datastore
      2. Controlla il completamento:
        kubectl -n namespace get pods

        dove namespace è il tuo spazio dei nomi Apigee hybrid.

        Vai al passaggio successivo solo quando i pod sono pronti.

      3. Applica le sostituzioni per eseguire l'upgrade dei componenti di Telemetria e controlla il completamento:
        apigeectl apply -f overrides_1.3.yaml --telemetry
        kubectl -n namespace get pods
      4. Applica le sostituzioni per eseguire l'upgrade dei componenti a livello di organizzazione (MART, Watcher e Apigee Connect) e controlla il completamento:
        apigeectl apply -f overrides_1.3.yaml --org
        kubectl -n namespace get pods
      5. Applica le sostituzioni per eseguire l'upgrade degli ambienti. Hai due opzioni:
        • Applica le sostituzioni a un ambiente alla volta e controlla 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 le sostituzioni a tutti gli ambienti contemporaneamente e controlla 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 le sostituzioni a tutti i componenti contemporaneamente. Se il tuo ambiente di prova/sperimentale è grande e complesso o imita molto 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 hybrid su GKE.

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

      Nell'esempio di output riportato di seguito, 10.68.8.24 è della versione 1.2.0 ed è l'IP del nodo utilizzato come externalSeedHost. 10.68.7.11 è 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 attivi e funzionanti, rimuovi externalSeedHost dal file delle sostituzioni ed esegui di nuovo apigeectl apply con l'opzione --datastore:
      apigeectl apply --datastore -f overrides_1.3.6.yaml

    Esegui la pulizia

    Dopo aver verificato che tutti i pod siano attivi e in esecuzione e che gli endpoint ASM siano validi per la nuova installazione, puoi eseguire la pulizia:

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

    Eliminare le risorse di Hybrid 1.2.0

    1. Rimuovi i dettagli di routing del virtualhost 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 1.2.

    2. Se l'endpoint continua a funzionare come previsto e hai verificato che tutti i componenti 1.3.0 funzionino, esegui il seguente comando per eliminare le risorse ibride 1.2.0:
      $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
        -f 1.2.0_overrides.yaml

    Esegui la disattivazione dell'istanza 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 Istio versione 1.4.6

    1. Esegui il seguente comando per eliminare le risorse Istio 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! Hai eseguito l'upgrade alla versione 1.3.6 di Apigee hybrid.