Actualiza Apigee Hybrid a la versión 1.17

Este procedimiento abarca la actualización de la versión 1.16.x de Apigee hybrid a la versión 1.17.1 de Apigee hybrid y de las versiones anteriores de hybrid 1.17.x a la versión 1.17.1.

Usa los mismos procedimientos para las actualizaciones de versiones secundarias (por ejemplo, de la versión 1.16 a la 1.17) y las actualizaciones de versiones de parches (por ejemplo, de 1.17.0 a 1.17.1).

Si actualizas desde Apigee hybrid 1.15 o desde una versión anterior, primero debes actualizar a la versión 1.16 de Hybrid antes de actualizar a la versión 1.17.1. Consulta las instrucciones para actualizar Apigee Hybrid a la versión 1.16.

Cambios de Apigee Hybrid v1.16

Ten en cuenta los siguientes cambios:

  • Compatibilidad con el Protocolo de contexto del modelo (MCP): La versión 1.17 de Apigee Hybrid agrega compatibilidad con el Protocolo de contexto del modelo (MCP), un protocolo abierto que permite que las aplicaciones de IA basadas en agentes usen tus APIs como herramientas a través de extremos de MCP administrados. Apigee hybrid enruta, autoriza y protege estas llamadas a herramientas del MCP de la misma manera en que administra tus otras APIs, por lo que no necesitas ejecutar ni mantener tus propios servidores del MCP. Para obtener más información, consulta Descripción general del Protocolo de contexto del modelo (MCP) en Apigee y la guía de inicio rápido del MCP.
  • Rotación del certificado de la CA raíz: La versión 1.17 de Apigee Hybrid agrega compatibilidad para rotar el certificado de la autoridad certificadora (CA) raíz que ancla la confianza para la comunicación TLS entre tus componentes del entorno de ejecución. Ahora puedes reemplazar la CA raíz antes de que venza, sin tiempo de inactividad, siguiendo un procedimiento de rotación por fases. Para obtener más información, consulta Rota el certificado de la AC raíz.
  • Compatibilidad con TLS 1.3: La versión 1.17 de Apigee Hybrid agrega compatibilidad con TLS 1.3, la versión más reciente del protocolo de seguridad de la capa de transporte. TLS 1.3 ofrece protocolos de enlace de conexión más rápidos y una seguridad más sólida que las versiones anteriores de TLS. Para obtener información sobre la configuración de TLS en la puerta de enlace de entrada, consulta Configura TLS y mTLS en la puerta de enlace de entrada.
  • Compatibilidad con proxy de reenvío para políticas basadas en IA: La versión 1.17 de Apigee Hybrid agrega compatibilidad con proxy de reenvío para las políticas basadas en IA, como las políticas de Model Armor y de almacenamiento en caché semántico. Las llamadas salientes que realizan estas políticas ahora se pueden enrutar a través de un proxy de reenvío HTTP, que no se admitía en versiones anteriores de Apigee hybrid. Para obtener más información, consulta Configura el proxy de reenvío para los proxies de API.
  • Compatibilidad con extremos de Private Service Connect (PSC) de la caché semántica: La versión 1.17 de Apigee hybrid agrega compatibilidad con extremos de Private Service Connect (PSC) para el almacenamiento en caché semántico. Las políticas de almacenamiento en caché semántico ahora pueden llegar a sus servicios de respaldo a través de un extremo de Private Service Connect, lo que mantiene ese tráfico en tu red privada. Para obtener más información, consulta Primeros pasos con las políticas de almacenamiento en caché semántico.

Para obtener más información sobre las funciones de la versión 1.17 de Hybrid, consulta las notas de la versión 1.17.1 de Apigee Hybrid.

Requisitos previos

Antes de actualizar a la versión 1.17 de hybrid, asegúrate de que la instalación cumpla con los siguientes requisitos:

Antes de actualizar a la versión 1.17.1: limitaciones y notas importantes

  • La actualización a la versión 1.17 de Apigee Hybrid puede requerir tiempo de inactividad.

    Cuando se actualiza el controlador de Apigee a la versión 1.17.1, todas las implementaciones de Apigee se someten a un reinicio progresivo. Para minimizar el tiempo de inactividad en entornos híbridos de producción durante un reinicio progresivo, asegúrate de ejecutar al menos dos clústeres (en el mismo centro de datos o en uno diferente, o en la misma región o en una diferente). Divide todo el tráfico de producción en un solo clúster, toma el clúster que estás a punto de actualizar sin conexión y, luego, continúa con el proceso de actualización. Repite el proceso para cada clúster.

    Apigee recomienda que, una vez que comiences la actualización, actualices todos los clústeres lo antes posible para reducir las posibilidades de impacto en la producción. No hay límite para que se actualicen todos los clústeres restantes después de que se actualice el primero. Sin embargo, hasta que se actualicen todos los clústeres restantes, la copia de seguridad y restablecimiento de Cassandra no podrá funcionar con versiones mixtas. Por ejemplo, no se puede usar una copia de seguridad de Hybrid 1.16 para restablecer una instancia de Hybrid 1.17.

  • No es necesario suspender por completo los cambios del plano de administración durante una actualización. Cualquier suspensión temporal necesaria para los cambios en el plano de administración se indica en las instrucciones de actualización que se incluyen a continuación.

Descripción general de la actualización a la versión 1.17.1

Los procedimientos para actualizar Apigee Hybrid se organizan en las siguientes secciones:

  1. Prepárate para la actualización.
  2. Instala la versión 1.17.1 del entorno de ejecución de Hybrid.

Prepárate para actualizar a la versión 1.17

Haz una copia de seguridad de tu instalación híbrida

  1. En estas instrucciones, se usa la variable de entorno APIGEE_HELM_CHARTS_HOME para el directorio en tu sistema de archivos en el que instalaste los charts de Helm. Si es necesario, cambia el directorio a este directorio y define la variable con el siguiente comando:

    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. Realiza una copia de seguridad de tu directorio $APIGEE_HELM_CHARTS_HOME/ versión 1.16. Puedes usar cualquier proceso de copia de seguridad. Por ejemplo, puedes crear un archivo tar de todo tu directorio con lo siguiente: 
    tar -czvf $APIGEE_HELM_CHARTS_HOME/../apigee-helm-charts-v1.16-backup.tar.gz $APIGEE_HELM_CHARTS_HOME
  3. Realiza una copia de seguridad de tu base de datos de Cassandra según las instrucciones que se indican en Copia de seguridad y recuperación de Cassandra.
  4. Asegúrate de que el certificado TLS y los archivos de claves (.crt, .key o .pem) residan en el directorio $APIGEE_HELM_CHARTS_HOME/apigee-virtualhost/.

Actualiza tu versión de Kubernetes

Verifica tu versión de la plataforma de Kubernetes y, si es necesario, actualiza tu plataforma de Kubernetes a una versión compatible con Hybrid 1.16 y Hybrid 1.17. Si necesitas ayuda, sigue la documentación de la plataforma.

Extrae los charts de Helm para Apigee.

Los gráficos de Apigee Hybrid se alojan en Google Artifact Registry:

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

Con el comando pull, copia todos los gráficos de Helm de Apigee Hybrid en tu almacenamiento local con el siguiente 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

Edita kustomization.yaml para un espacio de nombres de Apigee personalizado

Si tu espacio de nombres de Apigee no es apigee, edita el archivo apigee-operator/etc/crds/default/kustomization.yaml y reemplaza el valor namespace por tu espacio de nombres de Apigee.

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

namespace: APIGEE_NAMESPACE

Si usas apigee como espacio de nombres, no es necesario que edites el archivo.

  • Instala las CRD de Apigee actualizadas:

    1. Usa la función de ejecución de prueba kubectl mediante la ejecución del siguiente comando:

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

    2. Después de validar con el comando de ejecución de prueba, ejecuta el siguiente comando:

      kubectl apply -k  apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false
    3. Valida la instalación con el comando kubectl get crds: 
      kubectl get crds | grep apigee

      La respuesta debería ser similar a la siguiente:

      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

  • Verifica las etiquetas en los nodos del clúster. De forma predeterminada, Apigee programa los Pods de datos en los nodos con la etiqueta cloud.google.com/gke-nodepool=apigee-data y los Pods del entorno de ejecución se programan en nodos con la etiqueta cloud.google.com/gke-nodepool=apigee-runtime. Puedes personalizar las etiquetas de tu grupo de nodos en el archivo overrides.yaml.

    Para obtener más información, consulta Configura grupos de nodos dedicados.

    • Actualiza cert-manager

    Apigee Hybrid v1.17 admite las versiones de cert-manager de la 1.16 a la 1.19. Hay un cambio en cert-manager 1.18 que puede causar un problema con tu tráfico. En la versión 1.18 de cert-manager, el valor predeterminado de Certificate.Spec.PrivateKey.rotationPolicy cambió de Never a Always. En el caso de las instalaciones actualizadas de Apigee Hybrid, esto puede causar un problema con tu tráfico. Cuando actualices a la versión 1.17 de hybrid desde una versión anterior, debes editar tu certificado apigee-ca para compensar este cambio o mantener tu versión de cert-manager en la versión 1.17.x o inferior.

    Antes de actualizar cert-manager a la versión 1.18 o 1.19, sigue el procedimiento que se indica a continuación para editar tu certificado apigee-ca y establecer el valor de Certificate.Spec.PrivateKey.rotationPolicy en Never.

    1. Verifica el contenido de tu certificado apigee-ca para ver si rotationPolicy está configurado: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      Busca los valores en spec.privateKey en el resultado:

      ...
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 no está configurado o si se configura como Always, edita el certificado apigee-ca para establecer el valor de rotationPolicy en Never:
      1. Realiza primero una ejecución de prueba: 
        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. Aplica el parche al certificado: 
        kubectl patch Certificate \
  -n cert-manager \
  --type=json \
  -p='[{"op": "replace", "path": "/spec/privateKey/rotationPolicy", "value": "Never"}]' \
  -o=yaml \
  apigee-ca
    3. Verifica que el valor de rotationPolicy ahora esté establecido en Never: 
      kubectl get certificate apigee-ca -n cert-manager -o yaml

      El resultado debería ser similar al siguiente:

      ...
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. Actualiza cert-manager. Con el siguiente comando, se descargará e instalará cert-manager v1.19.2: 
      kubectl apply -f https://github.com/cert-manager/cert-manager/releases/download/v1.19.2/cert-manager.yaml

      Consulta Plataformas y versiones compatibles: cert-manager para obtener una lista de las versiones compatibles.

    Consulta los siguientes vínculos:

    Instala el entorno de ejecución de Hybrid 1.17.1

    1. Si no lo hiciste, navega a tu directorio APIGEE_HELM_CHARTS_HOME. Ejecuta los siguientes comandos desde ese directorio.
    2. Actualiza el operador o controlador de Apigee:

      Prueba de validación:

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

      Actualiza el chart:

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

      Verifica la instalación del operador de 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

      Para verificar que esté en funcionamiento, comprueba su disponibilidad:

      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. Actualiza el almacén de datos de Apigee:

      Ejecución de prueba:

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

      Actualiza el chart:

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

      Para verificar que apigeedatastore esté en funcionamiento, comprueba su estado:

      kubectl -n APIGEE_NAMESPACE get apigeedatastore default

      NAME      STATE       AGE
default   running    2d
    4. Actualiza la telemetría de Apigee:

      Ejecución de prueba:

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

      Actualiza el chart:

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

      Para verificar que esté en funcionamiento, comprueba su estado:

      kubectl -n APIGEE_NAMESPACE get apigeetelemetry apigee-telemetry

      NAME               STATE     AGE
apigee-telemetry   running   2d
    5. Actualiza Apigee Redis:

      Ejecución de prueba:

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

      Actualiza el chart:

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

      Para verificar que esté en funcionamiento, comprueba su estado:

      kubectl -n APIGEE_NAMESPACE get apigeeredis default

      NAME      STATE     AGE
default   running   2d
    6. Actualiza el administrador de entrada de Apigee:

      Ejecución de prueba:

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

      Actualiza el chart:

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

      Para verificar que esté en funcionamiento, comprueba su disponibilidad:

      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. Actualiza la organización de Apigee:

      Ejecución de prueba:

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

      Actualiza el chart:

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

      Para verificar que esté en funcionamiento, comprueba el estado de la organización correspondiente:

      kubectl -n APIGEE_NAMESPACE get apigeeorg

      NAME                      STATE     AGE
apigee-my-org-my-env      running   2d
    8. Actualiza el entorno.

      Debes instalar un entorno a la vez. Especifica el entorno con --set env=ENV_NAME.

      Prueba de validación:

      helm upgrade ENV_RELEASE_NAME apigee-env/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set env=ENV_NAME \
  -f OVERRIDES_FILE \
  --dry-run=server
      • ENV_RELEASE_NAME es un nombre que se usa para hacer un seguimiento de la instalación y las actualizaciones del chart apigee-env. Este nombre debe ser único y diferente de los demás nombres de versiones de Helm en tu instalación. Por lo general, es igual a ENV_NAME. Sin embargo, si tu entorno tiene el mismo nombre que tu grupo de entornos, debes usar nombres de versión diferentes para el entorno y el grupo de entornos, por ejemplo, dev-env-release y dev-envgroup-release. Para obtener más información sobre las versiones en Helm, consulta Tres conceptos importantes en la documentación de Helm.
      • ENV_NAME es el nombre del entorno que estás actualizando.
      • OVERRIDES_FILE es tu nuevo archivo de anulaciones para v.1.17.1

      Actualiza el chart:

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

      Para verificar que esté en funcionamiento, comprueba el estado del entorno correspondiente:

      kubectl -n APIGEE_NAMESPACE get apigeeenv

      NAME                          STATE       AGE   GATEWAYTYPE
apigee-my-org-my-env          running     2d
    9. Actualiza los grupos de entornos (virtualhosts).
      1. Debes actualizar un grupo de entornos (virtualhost) a la vez. Especifica el grupo de entornos con --set envgroup=ENV_GROUP_NAME. Repite los siguientes comandos para cada grupo de entornos mencionado en el archivo overrides.yaml:

        Prueba de validación:

        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 es el nombre con el que se instaló el chart apigee-virtualhost. Por lo general, es ENV_GROUP_NAME.

        Actualiza el chart:

        helm upgrade ENV_GROUP_RELEASE_NAME apigee-virtualhost/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --set envgroup=ENV_GROUP_NAME \
  -f OVERRIDES_FILE
      2. Verifica el estado de ApigeeRouter (AR).

        La instalación de virtualhosts crea ApigeeRouteConfig (ARC), que crea de forma interna ApigeeRoute (AR) una vez que Apigee Watcher extrae detalles relacionados del grupo de entornos desde el plano de control. Por lo tanto, verifica que el estado de AR correspondiente esté en ejecución: 

        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

    Revierte a una versión anterior

    Para revertir a la versión anterior, usa la versión anterior del gráfico para revertir el proceso de actualización en el orden inverso. Comienza con apigee-virtualhost y avanza hasta apigee-operator. Luego, revierte los CRD.

    1. Revierte los gráficos. En los siguientes comandos, se supone que usas los gráficos de la versión anterior (v1.16.x).

      1. Ejecuta el siguiente comando para cada grupo de entorno:

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

      2. Ejecuta el siguiente comando para cada entorno:

        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. Para revertir las CRD, vuelve a instalar las CRD anteriores. 
      kubectl apply -k apigee-operator/etc/crds/default/ \
  --server-side \
  --force-conflicts \
  --validate=false