Mettre à niveau Apigee hybrid vers la version 1.17

Cette procédure concerne la mise à niveau d'Apigee hybrid de la version 1.16.x vers la version 1.17.1 et depuis les versions précédentes d'Apigee hybrid de la version 1.17.x vers la version 1.17.1.

Utilisez les mêmes procédures pour les mises à niveau de versions mineures (par exemple, de la version 1.16 vers la version 1.17) et pour les mises à niveau de versions de correctifs (par exemple, de la version 1.17.0 vers la version 1.17.1).

Si vous effectuez une mise à niveau à partir de la version 1.15 d'Apigee hybrid ou d'une version antérieure, vous devez d'abord passer à la version 1.16 avant de migrer vers la version 1.17.1. Consultez les instructions de mise à niveau d'Apigee hybrid vers la version 1.16.

Modifications par rapport à Apigee hybrid v1.16

Notez les modifications suivantes :

  • Compatibilité avec le protocole MCP (Model Context Protocol) : Apigee hybrid version 1.17 est désormais compatible avec le protocole MCP (Model Context Protocol), un protocole ouvert qui permet aux applications d'IA agentives d'utiliser vos API comme outils via des points de terminaison MCP gérés. Apigee hybrid achemine, autorise et sécurise ces appels d'outils MCP de la même manière qu'il gère vos autres API. Vous n'avez donc pas besoin d'exécuter ni de gérer vos propres serveurs MCP. Pour en savoir plus, consultez Présentation du protocole MCP (Model Context Protocol) dans Apigee et le démarrage rapide MCP.
  • Rotation du certificat de l'autorité de certification racine : la version 1.17 d'Apigee hybrid permet de faire tourner le certificat de l'autorité de certification (CA) racine qui ancre la confiance pour la communication TLS entre vos composants d'exécution. Vous pouvez désormais remplacer l'autorité de certification racine avant son expiration, sans temps d'arrêt, en suivant une procédure de rotation par étapes. Pour en savoir plus, consultez Effectuer une rotation du certificat CA racine.
  • Compatibilité avec TLS 1.3 : Apigee hybrid version 1.17 est désormais compatible avec TLS 1.3, la dernière version du protocole Transport Layer Security. TLS 1.3 offre des handshakes de connexion plus rapides et une sécurité renforcée par rapport aux versions antérieures de TLS. Pour savoir comment configurer TLS sur la passerelle d'entrée, consultez Configurer TLS et mTLS sur la passerelle d'entrée.
  • Compatibilité avec le proxy de transfert pour les règles d'IA : Apigee hybrid version 1.17 est désormais compatible avec le proxy de transfert pour les règles d'IA, telles que les règles Model Armor et de mise en cache sémantique. Les appels sortants effectués par ces règles peuvent désormais être routés via un proxy de transfert HTTP, ce qui n'était pas possible dans les versions antérieures d'Apigee hybrid. Pour en savoir plus, consultez Configurer le proxy de transfert pour les proxys d'API.
  • Compatibilité du point de terminaison Private Service Connect (PSC) avec le cache sémantique : Apigee hybrid version 1.17 ajoute la compatibilité du point de terminaison Private Service Connect (PSC) avec la mise en cache sémantique. Les règles de mise en cache sémantique peuvent désormais atteindre leurs services de backend via un point de terminaison Private Service Connect, ce qui permet de maintenir le trafic sur votre réseau privé. Pour en savoir plus, consultez Premiers pas avec les règles de mise en cache sémantique.

Pour en savoir plus sur les fonctionnalités de la version 1.17 d'Apigee hybrid, consultez les notes de version d'Apigee hybrid v1.17.1.

Prérequis

Avant de passer à la version 1.17 d'Apigee hybrid, assurez-vous que votre installation remplit les conditions suivantes :

Avant de passer à la version 1.17.1 : limites et remarques importantes

  • La mise à niveau vers la version 1.17 d'Apigee hybrid peut nécessiter un temps d'arrêt.

    Lors de la mise à niveau du contrôleur Apigee vers la version 1.17.1, tous les déploiements Apigee font l'objet d'un redémarrage progressif. Pour minimiser les temps d'arrêt dans les environnements hybrides de production lors d'un redémarrage progressif, assurez-vous d'exécuter au moins deux clusters (dans la même région ou dans un centre de données différent). Dirigez l'ensemble du trafic de production vers un seul cluster et sélectionnez le cluster que vous êtes sur le point de mettre à niveau hors connexion, puis poursuivez le processus de mise à niveau. Répétez cette procédure pour chaque cluster.

    Apigee vous recommande de mettre à niveau tous les clusters dès que possible afin de réduire les risques d'impact sur la production. Après la mise à niveau du premier cluster, il n'y a pas de date limite pour procéder à la mise à niveau de l'ensemble des clusters restants. Toutefois, jusqu'à ce que tous les clusters restants aient été mis à niveau, la sauvegarde et la restauration de bases de données Cassandra ne peuvent pas fonctionner avec les versions mixtes. Par exemple, une sauvegarde Hybrid 1.16 ne peut pas être utilisée pour restaurer une instance Hybrid 1.17.

  • Les modifications du plan de gestion n'ont pas besoin d'être entièrement suspendues lors d'une mise à niveau. Les suspensions temporaires requises pour les modifications du plan de gestion sont indiquées dans les instructions de mise à niveau ci-dessous.

Présentation de la mise à niveau vers la version 1.17.1

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

  1. Préparez la mise à niveau.
  2. Installez la version 1.17.1 de l'environnement d'exécution hybride.

Préparer la mise à niveau vers la version 1.17

Sauvegarder votre installation hybrid

  1. Ces instructions utilisent la variable d'environnement APIGEE_HELM_CHARTS_HOME pour le répertoire de votre système de fichiers dans lequel vous avez installé les charts Helm. Si nécessaire, accédez au répertoire et définissez la variable en utilisant la commande suivante :

    Linux 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    macOS 

    export APIGEE_HELM_CHARTS_HOME=$PWD
echo $APIGEE_HELM_CHARTS_HOME

    Windows 

    set APIGEE_HELM_CHARTS_HOME=%CD%
echo %APIGEE_HELM_CHARTS_HOME%
  2. Créez une copie de sauvegarde de votre répertoire $APIGEE_HELM_CHARTS_HOME/ version 1.16. Vous pouvez utiliser n'importe quel processus de sauvegarde. Par exemple, vous pouvez créer un fichier tar contenant l'intégralité de votre répertoire à l'aide de la commande suivante : 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Sauvegardez votre base de données Cassandra en suivant les instructions figurant sur la page Sauvegarde et récupération de Cassandra.
  4. Assurez-vous que votre certificat TLS et vos fichiers de clé (.crt, .key et/ou .pem) se trouvent dans le répertoire $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/.

Mettre à niveau votre version de Kubernetes

Vérifiez la version de votre plate-forme Kubernetes et, si nécessaire, mettez à niveau votre plate-forme Kubernetes vers une version compatible avec les versions 1.16 et 1.17 d'Apigee hybrid. Si vous avez besoin d'aide, consultez la documentation de votre plate-forme.

Extrayez les graphiques Helm Apigee.

Les charts Apigee hybrid sont hébergés dans Google Artifact Registry :

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

À l'aide de la commande pull, copiez tous les charts Helm Apigee hybrid sur votre espace de stockage local à l'aide de la commande suivante : 

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

Modifier kustomization.yaml pour un espace de noms Apigee personnalisé

Si votre espace de noms Apigee n'est pas apigee, modifiez le fichier apigee-operator/etc/crds/default/kustomization.yaml et remplacez la valeur namespace par votre espace de noms Apigee.

apiVersion: kustomize.config.k8s.io/v1beta1
kind: Kustomization

namespace: APIGEE_NAMESPACE

Si vous utilisez apigee comme espace de noms, vous n'avez pas besoin de modifier le fichier.

  • Installez les CRD Apigee mises à jour :

    1. Utilisez la fonctionnalité de simulation kubectl en exécutant la commande suivante :

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

    2. Après avoir validé la commande avec la simulation, exécutez la commande suivante :

      kubectl apply -k  apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
    3. Validez l'installation à l'aide de la commande kubectl get crds : 
      kubectl get crds | grep apigee

      Le résultat doit se présenter sous la forme suivante :

      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

  • Vérifiez les libellés sur les nœuds de cluster. Par défaut, Apigee planifie les pods de données sur les nœuds portant le libellé cloud.google.com/gke-nodepool=apigee-data et les pods d'exécution sont programmés sur les nœuds portant le libellé cloud.google.com/gke-nodepool=apigee-runtime. Vous pouvez personnaliser les libellés de votre pool de nœuds dans le fichier overrides.yaml.

    Pour en savoir plus, consultez la page Configurer des pools de nœuds dédiés.

    • Mettre à niveau cert-manager

    Apigee hybrid v1.17 est compatible avec les versions 1.16 à 1.19 de cert-manager. Une modification apportée à cert-manager 1.18 peut entraîner un problème avec votre trafic. Dans la version 1.18 de cert-manager, la valeur par défaut de Certificate.Spec.PrivateKey.rotationPolicy est passée de Never à Always. Pour les installations Apigee hybrid mises à niveau, cela peut entraîner un problème avec votre trafic. Lorsque vous passez à la version 1.17 d'hybrid à partir d'une version antérieure, vous devez modifier votre certificat apigee-ca pour compenser ce changement ou conserver votre version de cert-manager à la version 1.17.x ou antérieure.

    Avant de mettre à niveau cert-manager vers la version 1.18 ou 1.19, suivez la procédure ci-dessous pour modifier votre certificat apigee-ca afin de définir la valeur de Certificate.Spec.PrivateKey.rotationPolicy sur Never.

    1. Vérifiez le contenu de votre certificat apigee-ca pour voir si rotationPolicy est défini : 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      Recherchez les valeurs sous spec.privateKey dans le résultat :

      ...
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. Si rotationPolicy n'est pas défini ou s'il est défini sur Always, modifiez le certificat apigee-ca pour définir la valeur de rotationPolicy sur Never :
      1. Effectuez d'abord 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. Corrigez le certificat : 
        kubectl patch Certificate \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
    3. Vérifiez que la valeur de rotationPolicy est désormais définie sur Never : 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      Le résultat doit ressembler à ce qui suit :

      ...
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. Mettez à niveau cert-manager. La commande suivante permet de télécharger et d'installer cert-manager v1.19.2 : 
      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

      Consultez la page Plates-formes et versions prises en charge : cert-manager pour obtenir la liste des versions prises en charge.

    Consultez les pages suivantes :

    Installer l'environnement d'exécution hybride 1.17.1

    1. Si ce n'est pas le cas, accédez à votre répertoire APIGEE_HELM_CHARTS_HOME. Exécutez les commandes suivantes à partir de ce répertoire.
    2. Mettez à niveau l'opérateur ou le contrôleur Apigee :

      Effectuez un dry run :

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

      Mettez à niveau le graphique :

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

      Vérifiez l'installation de l'opérateur 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

      Vérifiez qu'il est opérationnel en vérifiant sa 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. Mettez à niveau le datastore Apigee :

      Effectuez un dry run :

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

      Mettez à niveau le graphique :

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

      Vérifiez que apigeedatastore est opérationnel en vérifiant son état :

      kubectl -n APIGEE_NAMESPACE get apigeedatastore default

      NAME      STATE       AGE
default   running    2d
    4. Mettez à niveau la télémétrie Apigee :

      Effectuez un dry run :

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

      Mettez à niveau le graphique :

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

      Vérifiez qu'elle est opérationnelle en vérifiant son état :

      kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry

      NAME               STATE     AGE
apigee-telemetry   running   2d
    5. Mettez à niveau Apigee Redis :

      Effectuez un dry run :

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

      Mettez à niveau le graphique :

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

      Vérifiez qu'elle est opérationnelle en vérifiant son état :

      kubectl -n APIGEE_NAMESPACE get apigeeredis default

      NAME      STATE     AGE
default   running   2d
    6. Mettez à niveau le gestionnaire d'entrée Apigee :

      Effectuez un dry run :

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

      Mettez à niveau le graphique :

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

      Vérifiez qu'il est opérationnel en vérifiant sa 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. Mettez à niveau l'organisation Apigee :

      Effectuez un dry run :

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

      Mettez à niveau le graphique :

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

      Vérifiez qu'elle est opérationnelle en vérifiant l'état de l'organisation correspondante :

      kubectl -n APIGEE_NAMESPACE get apigeeorg

      NAME                      STATE     AGE
apigee-my-org-my-env      running   2d
    8. Mettez à niveau l'environnement.

      Vous devez installer un environnement à la fois. Spécifiez l'environnement avec --set env=ENV_NAME.

      Effectuez un 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 est un nom utilisé pour suivre l'installation et les mises à niveau du chart apigee-env. Ce nom doit être différent des autres noms de versions Helm de votre installation. Il s'agit généralement de la même valeur que ENV_NAME. Toutefois, si votre environnement porte le même nom que votre groupe d'environnements, vous devez utiliser des noms de version différents pour l'environnement et le groupe d'environnements (par exemple, dev-env-release et dev-envgroup-release). Pour en savoir plus sur les versions dans Helm, consultez Trois grands concepts dans la documentation Helm.
      • ENV_NAME est le nom de l'environnement que vous mettez à niveau.
      • OVERRIDES_FILE est votre nouveau fichier de remplacement pour la version 1.17.1.

      Mettez à niveau le graphique :

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

      Vérifiez qu'il est opérationnel en vérifiant l'état de l'environnement correspondant :

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      NAME                          STATE       AGE   GATEWAYTYPE
apigee-my-org-my-env          running     2d
    9. Mettez à jour les groupes d'environnement (virtualhosts).
      1. Vous devez installer un groupe d'environnements (hôte virtuel) à la fois. Spécifiez le groupe d'environnement avec --set envgroup=ENV_GROUP_NAME. Répétez les commandes suivantes pour chaque groupe d'environnements mentionné dans le fichier overrides.yaml :

        Effectuez un 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 est le nom avec lequel vous avez déjà installé le graphique apigee-virtualhost. Il s'agit généralement de ENV_GROUP_NAME.

        Mettez à niveau le graphique :

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE
      2. Vérifiez l'état de la ressource ApigeeRoute (AR).

        L'installation de virtualhosts crée ApigeeRouteConfig (ARC) qui crée ApigeeRoute en interne une fois que l'observateur Apigee extrait les détails liés au groupe d'environnement du plan de contrôle. Par conséquent, vérifiez que l'état d'AR correspondant est en cours d'exécution : 

        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

    Effectuer un rollback vers la version précédente

    Pour revenir à la version précédente, utilisez l'ancienne version du chart pour effectuer un rollback du processus de mise à niveau dans l'ordre inverse. Commencez par apigee-virtualhost, puis revenez à apigee-operator et restaurez les CRD.

    1. Rétablissez les graphiques. Les commandes suivantes supposent que vous utilisez les graphiques de la version précédente (v1.16.x).

      1. Exécutez la commande suivante pour chaque groupe d'environnements :

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

      2. Exécutez la commande suivante pour chaque environnement :

        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. Rétablissez les CRD en réinstallant les anciennes. 
      kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false