Mettre à niveau d'Apigee hybrid vers la version 1.3.6

Présentation de la mise à niveau vers la version 1.3.6.

Les procédures de mise à niveau d'Apigee hybrid sont organisées dans les sections suivantes :

  1. Préparation
    1. Créez et mettez à jour des comptes de service.
    2. Planifiez des groupes d'environnements.
    3. Copiez et mettez à jour le fichier de remplacement.
  2. Mettez à niveau Istio et cert-manager.
  3. Installez la version 1.3 de l'environnement d'exécution hybride.
  4. effectuer un nettoyage.

Conditions préalables

Préparation

  1. (Recommandé) Créez une copie de sauvegarde du répertoire $APIGEECTL_HOME/ de la version 1.2. Exemple :
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
  2. (Recommandé) Sauvegardez votre base de données Cassandra en suivant les instructions figurant sur la page Sauvegarde et récupération de Cassandra.
  3. Mettez à niveau votre plate-forme Kubernetes comme suit. Si vous avez besoin d'aide, consultez la documentation de votre plate-forme :
    Plate-forme Mise à niveau vers la version
    GKE 1.15.x
    Anthos 1.5
    AKS 1.16.x en utilisant des clusters associés à Anthos
  4. Si vous n'utilisez pas actuellement Apigee Connect dans votre installation hybride, activez ce service.
    1. Vérifiez si l'API Apigee Connect est activée :
      gcloud services list | grep apigeeconnect
      
      apigeeconnect.googleapis.com         Apigee Connect API
    2. Si ce n'est pas le cas, activez-la :
      gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID

      $PROJECT_ID est l'ID de votre projet Google Cloud.

    3. Sur la ligne de commande, obtenez vos identifiants d'authentification gcloud, comme le montre l'exemple suivant :

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

      Pour vérifier que votre jeton a été renseigné, utilisez echo, comme le montre l'exemple suivant :

      echo $TOKEN

      Votre jeton doit s'afficher sous forme de chaîne encodée.

      Pour en savoir plus, consultez la section présentation de l'outil de ligne de commande gcloud.

    4. Vérifiez si Apigee Connect est activé pour votre organisation :
      curl -H "Authorization: Bearer $TOKEN" \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      $ORG_NAME est l'ID de votre organisation.

      Si le résultat contient :

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

      Apigee Connect est activé.

    5. Si Apigee Connect n'est pas activé, attribuez le rôle d'agent Apigee Connect au compte de service MART :
      gcloud projects add-iam-policy-binding $PROJECT_ID \
        --member serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com \
        --role roles/apigeeconnect.Agent
    6. Activez Apigee Connect à l'aide de la commande suivante :
      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"
      

      Si le résultat contient les deux propriétés suivantes, Apigee Connect a bien été activé :

            {
              "name": "features.mart.connect.enabled",
              "value": "true"
            },
            {
              "name": "features.hybrid.enabled",
              "value": "true"
            }
      
  5. Créez le compte de service apigee-watcher : Apigee Watcher est un nouveau compte de service introduit dans la version 1.3. Il surveille l'outil de synchronisation à la recherche de modifications au niveau de l'organisation et les applique pour configurer l'entrée Istio.

    Depuis votre répertoire hybride principal :

    ./tools/create-service-account apigee-watcher ./service-accounts
  6. Attribuez le rôle d'agent d'exécution Apigee au compte de service Watcher :
    gcloud projects add-iam-policy-binding $PROJECT_ID \
      --member serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com \
      --role roles/apigee.runtimeAgent

    PROJECT_ID correspond à l'ID de votre projet Google Cloud. Si les adresses e-mail de votre compte de service diffèrent de ce modèle, remplacez-les en conséquence.

    Le résultat doit inclure la liste de tous les comptes de service et de leurs rôles, y compris :

      ...
    - members:
      - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
      role: roles/apigee.runtimeAgent
      ...
  7. Planifiez vos groupes d'environnements pour le routage. Apigee hybrid version 1.3 gère le routage du chemin de base avec des groupes d'environnements au lieu de routingRules. Si vous utilisez routingRules dans votre configuration hybride, concevez des groupes d'environnements pour répliquer votre routage.

    Vous devez créer au moins un groupe d'environnements.

    Consultez la page À propos des groupes d'environnements.

  8. Mettez à jour votre fichier de remplacement :
    1. Créez une copie de votre fichier de remplacement.
    2. Mettez à jour les stanzas gcp et k8sCluster.

      Les propriétés de configuration suivantes ont été remplacées dans la version 1.3 d'Apigee hybrid :

      • gcpRegion a été remplacée par gcp:region.
      • gcpProjectID a été remplacée par gcp:projectID.
      • gcpProjectIDRuntime a été remplacée par gcp:gcpProjectIDRuntime.
      • k8sClusterName a été remplacée par k8s:clusterName.
      • k8sClusterRegion a été remplacée par k8s:clusterRegion.

      Par exemple, remplacez la structure suivante :

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

      par

      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. Si vous ne possédez pas d'identifiant d'instance unique dans votre fichier de remplacement, ajoutez-en un :
      # unique identifier for this installation. 63 chars length limit
      instanceID: ID

      ID est un identifiant unique pour cette installation hybride, tel que "my-hybrid-131-installation" ou "acmecorp-hybrid-131".

    4. Ajoutez le compte de service Watcher (apigee-watcher) au fichier de remplacement :
      # Note: the SA should have the "Apigee Runtime Agent" role
      watcher:
       serviceAccountPath: "service account file"
    5. Ajoutez le compte de service Metrics (apigee-metrics) au fichier de remplacement :
      metrics:
       serviceAccountPath: "service account file"
    6. Mettez à jour le stanza virtualhosts: pour remplacer routingRules par votre groupe d'environnements.
      1. -name: Remplacez le nom par celui de votre groupe d'environnements. Vous pouvez avoir plusieurs entrées de nom, une pour chaque groupe d'environnements.
      2. hostAliases:[] Supprimez cette ligne.
      3. Conservez (ou ajoutez) les entrées sslCertPath: et sslKeyPath:.
      4. Supprimez toutes les entrées routingRules.

      Exemple :

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

      Devient :

      virtualhosts:
        - name: example-env-group
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
    7. Mettez à jour les stanzas mart et connectAgent:.
      1. Sous mart:, supprimez les entrées hostAlias:, sslCertPath: et sslKeyPath:.
      2. Ajoutez un stanza connectAgent:.
      3. Sous connectAgent:, ajoutez une entrée serviceAccountPath: et indiquez le chemin d'accès au fichier de compte de service auquel le rôle d'agent Apigee Connect est attribué (généralement le compte de service MART).

      Exemple :

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

      Devient :

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

Mettre à niveau Istio et cert-manager

La version 1.3 d'Apigee hybrid nécessite cert-manager v0.14.2 pour gérer et valider les certificats, ainsi que la distribution Istio fournie avec Anthos Service Mesh (ASM) version 1.5.7 (ou ultérieure) pour créer et gérer la passerelle d'entrée de l'environnement d'exécution.

Mettre à niveau Istio 1.4.6 vers ASM 1.5.7 (ou version ultérieure)

  1. Pour minimiser le temps d'arrêt, les déploiements Istio et les HPA doivent comporter au moins deux instances dupliquées chacun. Exécutez les commandes suivantes pour déterminer le nombre d'instances dupliquées :
    kubectl -n istio-system get deployments # list of deployments
    kubectl -n istio-system get hpa # list of hpa
  2. Modifiez chaque déploiement ne comportant qu'une seule instance dupliquée et faites passer la valeur de replicas: à 2 ou plus :
    kubectl -n istio-system edit deployment name

    Exemple :

    spec:
      progressDeadlineSeconds: 600
      replicas: 2
  3. Modifiez chaque HPA ne comportant qu'une seule instance dupliquée et faites passer la valeur de minReplicas: à 2 ou plus :
    kubectl -n istio-system edit hpa name

    Exemple :

    spec:
      maxReplicas: 5
      minReplicas: 2
    
  4. Téléchargez et installez ASM en suivant les instructions d'installation décrites dans la section Télécharger et installer ASM.
  5. Après l'installation, exécutez la commande version pour vérifier que la version 1.5.x est correctement installée :
    ./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)

Mettre à niveau cert-manager

  1. Supprimez le déploiement de cert-manager actuel :
    kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
  2. Vérifiez votre version de Kubernetes :
    kubectl version
  3. Exécutez la commande suivante pour installer cert-manager à partir de Jetstack :
    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml 

Installer l'environnement d'exécution hybride

  1. Stockez le numéro de la dernière version dans une variable :
    export VERSION=$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
  2. Vérifiez que la variable a bien été renseignée avec un numéro de version. Si vous souhaitez utiliser une autre version, vous pouvez l'enregistrer dans une variable d'environnement à la place. Exemple :
    echo $VERSION
      1.3.6
  3. Téléchargez le package de version pour votre système d'exploitation :

    Mac 64 bits :

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

    Linux 64 bits :

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

    Mac 32 bits :

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

    Linux 32 bits :

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
  4. Remplacez le nom du répertoire apigeectl/ actuel par un nom de répertoire de sauvegarde. Exemple :
    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
  5. Extrayez le contenu du fichier gzip téléchargé dans votre répertoire de base hybride. Exemple :

    tar xvzf filename.tar.gz -C hybrid-base-directory
  6. cd dans le répertoire de base.
  7. Le contenu du fichier tar est, par défaut, développé dans un répertoire dont le nom contient la version et la plate-forme. Exemple : ./apigeectl_1.0.0-f7b96a8_linux_64. Renommez ce répertoire en apigeectl :

    mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
  8. Supprimez la tâche apigee-resources-install de apigee-system :
    kubectl -n apigee-system delete job apigee-resources-install
  9. Supprimez l'ancienne CRD :
    kubectl delete crd apigeetelemetries.apigee.cloud.google.com
  10. Mettez à jour le stanza cassandra: dans votre fichier de remplacement avec une propriété externalSeedHost. Cette propriété permet de garantir que votre nouvelle installation d'Apigee hybrid version 1.3.6 utilise le même cluster Kubernetes que l'installation de la version 1.2. Cette étape ne doit être effectuée qu'une seule fois : lors de la mise à niveau d'Apigee hybrid de la version 1.2 à la version 1.3.6 (ou ultérieure).
    1. Recherchez l'une des adresses IP de l'instance Cassandra existante dans le même cluster Kubernetes que celui où vous mettez à niveau l'installation 1.2.0.
      kubectl -n namespace get pods -o wide

      namespace est votre espace de noms Apigee hybrid.

      Notez l'adresse IP d'un nœud Cassandra. Exemple :

      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. Ajoutez la valeur de la propriété externalSeedHost :
      cassandra:
       externalSeedHost: Cassandra_node_IP

      Cassandra_node_IP correspond à l'adresse IP du nœud Cassandra (10.68.8.24 dans l'exemple précédent).

  11. Dans le nouveau répertoire apigeectl/, exécutez apigeectl init, apigeectl apply et apigeectl check-ready :
    1. Initialisez Apigee hybrid 1.3.6 :
      apigeectl init -f overrides_1.3.yaml

      overrides_1.3.yaml correspond à votre fichier overrides.yaml modifié.

    2. Dans la version 1.3 d'Apigee hybrid, la syntaxe de l'option --dry-run dépend de la version de kubectl que vous exécutez. Vérifiez la version de kubectl :
      gcloud version
    3. Recherchez les erreurs à l'aide d'une simulation :

      kubectl version 1.17 et antérieure :

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

      kubectl version 1.18 et ultérieure :

      apigeectl apply -f overrides_1.3.yaml --dry-run=client
    4. Appliquez vos remplacements. Sélectionnez et suivez les instructions pour les environnements de production ou les environnements de démonstration/expérimentaux, selon votre installation.

      Production

      Pour les environnements de production, vous devez mettre à niveau chaque composant Apigee hybrid individuellement, puis vérifier l'état du composant mis à niveau avant de passer au composant suivant.

      1. Appliquez vos remplacements pour mettre à niveau Cassandra :
        apigeectl apply -f overrides_1.3.yaml --datastore
      2. Vérifiez que l'opération est terminée :
        kubectl -n namespace get pods

        namespace est votre espace de noms Apigee hybrid.

        Ne passez à l'étape suivante que lorsque les pods sont prêts.

      3. Appliquez vos remplacements pour mettre à niveau les composants Telemetry, puis vérifiez que l'opération est terminée :
        apigeectl apply -f overrides_1.3.yaml --telemetry
        kubectl -n namespace get pods
      4. Appliquez vos remplacements pour mettre à niveau les composants au niveau de l'organisation (MART, Watcher et Apigee Connect), puis vérifiez que l'opération est terminée :
        apigeectl apply -f overrides_1.3.yaml --org
        kubectl -n namespace get pods
      5. Appliquez vos remplacements pour mettre à niveau vos environnements. Deux possibilités s'offrent à vous :
        • Appliquez vos remplacements à un environnement à la fois, puis vérifiez que l'opération est terminée. Répétez cette étape pour chaque environnement :
          apigeectl apply -f overrides_1.3.yaml --env env_name
          kubectl -n namespace get pods

          env_name est le nom de l'environnement que vous mettez à niveau.

        • Appliquez vos remplacements à tous les environnements en même temps, puis vérifiez que l'opération est terminée :
          apigeectl apply -f overrides_1.3.yaml --all-envs
          kubectl -n namespace get pods

      Démo/Expérimental

      Dans la plupart des environnements de démonstration ou expérimentaux, vous pouvez appliquer les remplacements à tous les composants en une seule fois. Si votre environnement de démonstration/expérimental est volumineux et complexe, ou s'il imite fidèlement un environnement de production, vous pouvez suivre les instructions de mise à niveau des environnements de production.

      1. apigeectl apply -f overrides_1.3.yaml
      2. Vérifiez l'état :
        apigeectl check-ready -f overrides_1.3.yaml

      Pour en savoir plus, consultez la page Configuration hybride de GKE – Étape 5 : Installer Apigee hybrid sur GKE.

    5. Une fois Apigee hybrid version 1.3 configuré et en cours d'exécution, vérifiez que tous les nœuds Cassandra (anciens et nouveaux) font partie du même cluster Cassandra. Exécutez la commande suivante sur l'un des nœuds Cassandra :
      kubectl -n namespace get pods
      kubectl -n namespace exec old Cassandra pod -- nodetool status

      Dans l'exemple de résultat suivant, la version 10.68.8.24 provient de la version 1.2.0 et correspond à l'adresse IP du nœud que vous avez utilisée comme externalSeedHost. 10.68.7.11 provient de la version 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

      S'ils ne se trouvent pas dans le même cluster, vérifiez la valeur externalSeedHost.

    6. Une fois que tous les pods sont opérationnels, supprimez externalSeedHost du fichier de remplacement et exécutez à nouveau apigeectl apply avec l'option --datastore :
      apigeectl apply --datastore -f overrides_1.3.6.yaml

    Nettoyer

    Après avoir vérifié que tous les pods sont opérationnels et en bon état, et que les points de terminaison ASM sont valides pour la nouvelle installation, vous pouvez procéder au nettoyage :

    • Ressources Apigee hybrid 1.2
    • Ancienne instance Cassandra
    • Ressources Istio 1.4.6

    Supprimer Apigee hybrid 1.2.0

    1. Supprimez les détails de routage de l'hôte virtuel 1.2.0 :
      $APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml

      $APIGEECTL_HOME-v1.2 correspond au répertoire dans lequel vous avez sauvegardé votre répertoire apigeectl version 1.2.

    2. Si le point de terminaison fonctionne toujours comme prévu et que vous avez vérifié que tous les composants 1.3.0 fonctionnent, exécutez la commande suivante pour supprimer les ressources Apigee hybrid 1.2.0 :
      $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
        -f 1.2.0_overrides.yaml

    Mettre hors service l'ancienne instance Cassandra

    1. Exécutez cd dans le nouveau répertoire apigeectl installé.
    2. Exécutez le script tools/cas_cleanup.sh.

      Ce script met hors service l'ancien pod Cassandra de l'anneau Cassandra, supprime l'ancien STS et supprime les PVC.

      bash cas_cleanup.sh Apigee namespace

    Supprimer les ressources Istio version 1.4.6

    1. Exécutez la commande suivante pour supprimer les ressources Istio version 1.4.6 les plus récentes :
      kubectl delete all -n istio-system --selector \
        'app in (apigee-mart-istio-ingressgateway, galley, security, istio-nodeagent, istio-mixer, sidecarInjectorWebhook, istio-mixer)'
    2. Exécutez les commandes suivantes pour supprimer les anciennes tâches de l'installation d'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

    Félicitations ! Vous êtes passé à la version 1.3.6 d'Apigee hybrid.