Actualizar Apigee hybrid a la versión 1.3.6

Si vas a actualizar desde la versión 1.0 o 1.1 de Apigee hybrid, primero debes actualizar a la versión 1.2 antes de actualizar a la 1.3.6. Consulta las instrucciones para actualizar Apigee hybrid a la versión 1.2.

Información general sobre la actualización a la versión 1.3.6.

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

  1. Preparación
    1. Crear y actualizar cuentas de servicio.
    2. Planifica los grupos de entornos.
    3. Copia y actualiza el archivo de anulaciones.
  2. Actualiza Istio y cert-manager.
  3. Instala la versión 1.3 del entorno de ejecución híbrido.
  4. Limpiar.

Requisitos previos

Preparación

  1. (Recomendado) Haz una copia de seguridad del directorio $APIGEECTL_HOME/ de la versión 1.2. Por ejemplo:
    tar -czvf $APIGEECTL_HOME/../apigeectl-v1.2-backup.tar.gz $APIGEECTL_HOME
  2. (Recomendado) Crea una copia de seguridad de tu base de datos de Cassandra siguiendo las instrucciones de Copia de seguridad y recuperación de Cassandra.
  3. Actualiza tu plataforma de Kubernetes de la siguiente manera. Consulta la documentación de tu plataforma si necesitas ayuda:
    Plataforma Actualizar a la versión
    GKE 1.15.x
    Anthos 1,5
    AKS 1.16.x con clústeres vinculados de Anthos
  4. Si no usas Apigee Connect en tu instalación híbrida, habilítalo.
    1. Comprueba si la API Apigee Connect está habilitada:
      gcloud services list | grep apigeeconnect
      
      apigeeconnect.googleapis.com         Apigee Connect API
    2. Si no lo está, habilita la API:
      gcloud services enable apigeeconnect.googleapis.com --project $PROJECT_ID

      Donde $PROJECT_ID es el ID de tu proyecto de Google Cloud.

    3. En la línea de comandos, obtén tus credenciales de autenticación gcloud, como se muestra en el siguiente ejemplo:

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

      Para comprobar que se ha rellenado el token, usa echo, como se muestra en el siguiente ejemplo:

      echo $TOKEN

      Debería mostrar tu token como una cadena codificada.

      Para obtener más información, consulta la descripción general de la herramienta de línea de comandos gcloud.

    4. Comprueba si Apigee Connect está habilitado en tu organización:
      curl -H "Authorization: Bearer $TOKEN" \
        "https://apigee.googleapis.com/v1/organizations/$ORG_NAME"

      Donde $ORG_NAME es el ID de tu organización.

      Si el resultado contiene lo siguiente:

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

      Apigee Connect está habilitado.

    5. Si Apigee Connect no está habilitado, asigna el rol Agente de conexión de Apigee a la cuenta de servicio del servidor de API Management sobre datos del entorno de ejecución:
      gcloud projects add-iam-policy-binding $PROJECT_ID \
        --member serviceAccount:apigee-mart@$PROJECT_ID.iam.gserviceaccount.com \
        --role roles/apigeeconnect.Agent
    6. Habilita Apigee Connect con el siguiente 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"
      

      Si el resultado contiene las dos propiedades siguientes, significa que Apigee Connect se ha habilitado correctamente:

            {
              "name": "features.mart.connect.enabled",
              "value": "true"
            },
            {
              "name": "features.hybrid.enabled",
              "value": "true"
            }
      
  5. Crea la cuenta de servicio apigee-watcher. Apigee Watcher es una nueva cuenta de servicio introducida en la versión 1.3. Monitoriza el sincronizador para detectar cambios a nivel de organización y aplica esos cambios para configurar el ingreso de Istio.

    En el directorio híbrido principal, haz lo siguiente:

    ./tools/create-service-account apigee-watcher ./service-accounts
  6. Asigna el rol Agente de tiempo de ejecución de Apigee a la cuenta de servicio de Watcher:
    gcloud projects add-iam-policy-binding $PROJECT_ID \
      --member serviceAccount:apigee-watcher@$PROJECT_ID.iam.gserviceaccount.com \
      --role roles/apigee.runtimeAgent

    Donde PROJECT_ID es el ID de tu proyecto de Google Cloud. Si las direcciones de correo de tu cuenta de servicio no siguen este patrón, sustitúyelas según corresponda.

    El resultado debe incluir una lista de todas las cuentas de servicio y sus roles, entre los que se incluyen los siguientes:

      ...
    - members:
      - serviceAccount:apigee-watcher@hybrid13rc5.iam.gserviceaccount.com
      role: roles/apigee.runtimeAgent
      ...
  7. Planifica tus grupos de entornos para el enrutamiento. Apigee hybrid 1.3 gestiona el enrutamiento de la ruta base con grupos de entornos en lugar de routingRules. Si usas routingRules en tu configuración híbrida, diseña grupos de entornos para replicar tu enrutamiento.

    Debes crear al menos un grupo de entornos.

    Consulta Acerca de los grupos de entorno.

  8. Actualiza el archivo de anulaciones:
    1. Haz una copia del archivo de anulaciones.
    2. Actualiza las estrofas gcp y k8sCluster.

      Las siguientes propiedades de configuración se han sustituido en la versión híbrida 1.3:

      • Se ha sustituido gcpRegion por gcp:region
      • Se ha sustituido gcpProjectID por gcp:projectID
      • Se ha sustituido gcpProjectIDRuntime por gcp:gcpProjectIDRuntime
      • Se ha sustituido k8sClusterName por k8s:clusterName
      • Se ha sustituido k8sClusterRegion por k8s:clusterRegion

      Por ejemplo, sustituye la siguiente estructura:

      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. Si aún no tienes un identificador de instancia único en tu archivo de anulaciones, añade uno:
      # unique identifier for this installation. 63 chars length limit
      instanceID: ID

      Donde ID es un identificador único de esta instalación híbrida, como "my-hybrid-131-installation" o "acmecorp-hybrid-131".

    4. Añade la cuenta de servicio Watcher (apigee-watcher) al archivo de anulaciones:
      # Note: the SA should have the "Apigee Runtime Agent" role
      watcher:
       serviceAccountPath: "service account file"
    5. Añade la cuenta de servicio de métricas (apigee-metrics) al archivo de anulaciones:
      metrics:
       serviceAccountPath: "service account file"
    6. Actualiza la estrofa virtualhosts: para sustituir routingRules por tu grupo de entornos.
      1. -name: Sustituye el nombre por el de tu grupo de entornos. Puedes tener varias entradas de nombre, una por cada grupo de entornos.
      2. hostAliases:[] Elimina esta línea.
      3. Mantén (o añade) las entradas sslCertPath: y sslKeyPath:.
      4. Elimina todas las entradas de routingRules.

      Por ejemplo:

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

      Se convierte en:

      virtualhosts:
        - name: example-env-group
          sslCertPath: ./certs/keystore.pem
          sslKeyPath: ./certs/keystore.key
    7. Actualiza las estrofas mart y connectAgent:.
      1. En mart:, elimina las entradas hostAlias:, sslCertPath: y sslKeyPath:.
      2. Añade una estrofa connectAgent:.
      3. En connectAgent:, añade una entrada serviceAccountPath: e indica la ruta al archivo de cuenta de servicio que tiene asignado el rol Agente de Apigee Connect (normalmente, la cuenta de servicio de MART).

      Por ejemplo:

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

      Se convierte en:

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

Actualizar Istio y cert-manager

La versión 1.3 de Apigee hybrid requiere cert-manager v0.14.2 para gestionar y verificar certificados, y la distribución de Istio proporcionada con la versión 1.5.7 (o posterior) de Anthos Service Mesh (ASM) para crear y gestionar la pasarela de entrada de tiempo de ejecución.

Actualizar Istio 1.4.6 a ASM 1.5.7 (o una versión posterior)

  1. Para minimizar el tiempo de inactividad, las implementaciones de Istio y los HPA deben tener al menos dos réplicas cada uno. Ejecuta los siguientes comandos para determinar el número de réplicas:
    kubectl -n istio-system get deployments # list of deployments
    kubectl -n istio-system get hpa # list of hpa
  2. Edita cada despliegue que tenga una sola réplica y aumenta el replicas: a 2 o más:
    kubectl -n istio-system edit deployment name

    Por ejemplo:

    spec:
      progressDeadlineSeconds: 600
      replicas: 2
  3. Edita cada HPA que tenga una sola réplica y aumenta el minReplicas: a 2 o más:
    kubectl -n istio-system edit hpa name

    Por ejemplo:

    spec:
      maxReplicas: 5
      minReplicas: 2
    
  4. Descarga e instala ASM siguiendo las instrucciones de instalación que se indican en el artículo Descargar e instalar ASM.
  5. Después de la instalación, ejecuta el comando de versión para asegurarte de que has instalado correctamente la versión 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)

Actualizar cert-manager

  1. Elimina la implementación actual de cert-manager:
    kubectl delete -n cert-manager deployment cert-manager cert-manager-cainjector cert-manager-webhook
  2. Verifica tu versión de Kubernetes:
    kubectl version
  3. Ejecuta el siguiente comando para instalar cert-manager de Jetstack:
    kubectl apply --validate=false -f https://github.com/jetstack/cert-manager/releases/download/v0.14.2/cert-manager.yaml 

Instalar el entorno de ejecución híbrido

  1. Almacena el número de la última versión en una variable:
    export VERSION=$(curl -s \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/current-version.txt?ignoreCache=1)
  2. Comprueba que la variable se haya rellenado con un número de versión. Si quieres usar otra versión, puedes guardarla en una variable de entorno. Por ejemplo:
    echo $VERSION
      1.3.6
  3. Descarga el paquete de lanzamiento para tu sistema operativo:

    Mac de 64 bits:

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

    Linux de 64 bits:

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

    Mac de 32 bits:

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

    Linux de 32 bits:

    curl -LO \
        https://storage.googleapis.com/apigee-public/apigee-hybrid-setup/$VERSION/apigeectl_linux_32.tar.gz
  4. Cambia el nombre del directorio apigeectl/ actual por el de un directorio de copia de seguridad. Por ejemplo:
    mv $APIGEECTL_HOME/ $APIGEECTL_HOME-v1.2/ 
  5. Extrae el contenido del archivo gzip descargado en el directorio base híbrido. Por ejemplo:

    tar xvzf filename.tar.gz -C hybrid-base-directory
  6. cd al directorio base.
  7. De forma predeterminada, el contenido de tar se expande en un directorio con la versión y la plataforma en su nombre. Por ejemplo: ./apigeectl_1.0.0-f7b96a8_linux_64. Cambia el nombre de ese directorio a apigeectl:

    mv apigeectl_1.0.0-f7b96a8_linux_64 apigeectl
  8. Elimina el trabajo apigee-resources-install de apigee-system:
    kubectl -n apigee-system delete job apigee-resources-install
  9. Elimina el CRD anterior:
    kubectl delete crd apigeetelemetries.apigee.cloud.google.com
  10. Actualiza la estrofa cassandra: de tu archivo de anulaciones con una propiedad externalSeedHost. Esta propiedad ayudará a que tu nueva instalación de la versión 1.3.6 híbrida utilice el mismo clúster de Kubernetes que tu instalación de la versión 1.2. Este paso solo es necesario una vez para actualizar de la versión híbrida 1.2 a la 1.3.6 (o una versión posterior).
    1. Busca una de las direcciones IP de la instalación de Cassandra en el mismo clúster de Kubernetes en el que vas a actualizar la instalación de la versión 1.2.0.
      kubectl -n namespace get pods -o wide

      Donde namespace es el espacio de nombres de Apigee hybrid.

      Anota la dirección IP de un nodo de Cassandra. Por ejemplo:

      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. Añade el valor de la propiedad externalSeedHost:
      cassandra:
       externalSeedHost: Cassandra_node_IP

      Cassandra_node_IP es la IP del nodo de Cassandra (10.68.8.24 en el ejemplo anterior).

  11. En el directorio new apigeectl/, ejecuta apigeectl init, apigeectl apply y apigeectl check-ready:
    1. Inicializa la versión 1.3.6 de Hybrid:
      apigeectl init -f overrides_1.3.yaml

      Donde overrides_1.3.yaml es el archivo overrides.yaml editado.

    2. En la versión híbrida 1.3, la sintaxis de la marca --dry-run depende de la versión de kubectl que estés usando. Comprueba la versión de kubectl:
      gcloud version
    3. Comprueba si hay errores con una prueba de funcionamiento:

      kubectl versión 1.17 y anteriores:

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

      kubectl versión 1.18 y posteriores:

      apigeectl apply -f overrides_1.3.yaml --dry-run=client
    4. Aplica las anulaciones. Selecciona y sigue las instrucciones para entornos de producción o de demostración/experimentales, según tu instalación.

      Producción

      En los entornos de producción, debes actualizar cada componente híbrido por separado y comprobar el estado del componente actualizado antes de pasar al siguiente.

      1. Aplica las anulaciones para actualizar Cassandra:
        apigeectl apply -f overrides_1.3.yaml --datastore
      2. Comprobación completada:
        kubectl -n namespace get pods

        Donde namespace es el espacio de nombres de Apigee hybrid.

        Continúa con el siguiente paso solo cuando los pods estén listos.

      3. Aplica las anulaciones para actualizar los componentes de Telemetría y comprueba que se han completado:
        apigeectl apply -f overrides_1.3.yaml --telemetry
        kubectl -n namespace get pods
      4. Aplica las anulaciones para actualizar los componentes a nivel de organización (MART, Watcher y Apigee Connect) y comprueba si se han completado:
        apigeectl apply -f overrides_1.3.yaml --org
        kubectl -n namespace get pods
      5. Aplica las anulaciones para actualizar tus entornos. Tienes dos opciones:
        • Aplica las anulaciones a un entorno cada vez y comprueba si se han completado. Repite este paso para cada entorno:
          apigeectl apply -f overrides_1.3.yaml --env env_name
          kubectl -n namespace get pods

          Donde env_name es el nombre del entorno que vas a actualizar.

        • Aplica las anulaciones a todos los entornos a la vez y comprueba si se han completado:
          apigeectl apply -f overrides_1.3.yaml --all-envs
          kubectl -n namespace get pods

      Demo o experimental

      En la mayoría de los entornos de demostración o experimentales, puedes aplicar las anulaciones a todos los componentes a la vez. Si tu entorno de demostración o experimental es grande y complejo, o bien se parece mucho a un entorno de producción, te recomendamos que sigas las instrucciones para actualizar entornos de producción.

      1. apigeectl apply -f overrides_1.3.yaml
      2. Comprueba el estado:
        apigeectl check-ready -f overrides_1.3.yaml

      Para obtener más instrucciones, consulta el paso 5 de la configuración híbrida de GKE: instala la configuración híbrida en GKE.

    5. Una vez que hayas configurado y puesto en marcha la versión híbrida 1.3, verifica que todos los nodos de Cassandra (antiguos y nuevos) formen parte del mismo clúster de Cassandra. Ejecuta el siguiente comando en uno de los nodos de Cassandra:
      kubectl -n namespace get pods
      kubectl -n namespace exec old Cassandra pod -- nodetool status

      En el siguiente ejemplo de salida, 10.68.8.24 es de la versión 1.2.0 y es la IP del nodo que has usado como externalSeedHost. 10.68.7.11 es de la versión 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

      Si no están en el mismo clúster, comprueba el valor de externalSeedHost.

    6. Una vez que todos los pods estén en funcionamiento, elimina externalSeedHost del archivo de anulaciones y vuelve a ejecutar apigeectl apply con la opción --datastore:
      apigeectl apply --datastore -f overrides_1.3.6.yaml

    Limpieza

    Una vez que hayas verificado que todos los pods están activos y en buen estado, y que los endpoints de ASM son válidos para la nueva instalación, puedes hacer lo siguiente:

    • Recursos de Hybrid 1.2.
    • La instancia de Cassandra anterior
    • Recursos de Istio 1.4.6.

    Eliminar recursos de Hybrid 1.2.0

    1. Elimina los detalles de enrutamiento del host virtual 1.2.0:
      $APIGEECTL_HOME-v1.2/apigeectl delete -s virtualhost -f 1.2.0_overrides.yaml

      Donde $APIGEECTL_HOME-v1.2 es el directorio en el que has creado una copia de seguridad de tu directorio de la versión 1.2 de apigeectl.

    2. Si el endpoint sigue funcionando correctamente y has verificado que todos los componentes de la versión 1.3.0 funcionan, ejecuta el siguiente comando para eliminar los recursos híbridos de la versión 1.2.0:
      $APIGEECTL_HOME-v1.2/apigeectl delete -c "mart,connect-agent,synchronizer,runtime,udca,metrics,logger" \
        -f 1.2.0_overrides.yaml

    Desactivar la instancia de Cassandra anterior

    1. cd en el directorio apigeectl recién instalado.
    2. Ejecuta la secuencia de comandos tools/cas_cleanup.sh.

      Esta secuencia de comandos retira el pod de Cassandra antiguo del anillo de Cassandra, elimina el STS antiguo y elimina los PVCs.

      bash cas_cleanup.sh Apigee namespace

    Eliminar recursos de la versión 1.4.6 de Istio

    1. Ejecuta el siguiente comando para eliminar los recursos de Istio v.1.4.6 más recientes:
      kubectl delete all -n istio-system --selector \
        'app in (apigee-mart-istio-ingressgateway, galley, security, istio-nodeagent, istio-mixer, sidecarInjectorWebhook, istio-mixer)'
    2. Ejecuta los siguientes comandos para eliminar las tareas antiguas de la instalación de 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

    ¡Enhorabuena! Has actualizado correctamente a la versión 1.3.6 de Apigee Hybrid.