Usa un almacén de datos externo de Cassandra

En este tema, se explica cómo conectar un entorno de ejecución de Apigee Hybrid a un almacén de datos de Cassandra en un clúster de Kubernetes diferente. En esta configuración, el clúster de entorno de ejecución no tiene pods de Cassandra. El nombre de esta configuración es el modo almacén de datos externo.

Topología de dos clústeres

El modo Datastore externo usa dos clústeres de Kubernetes:

  • El clúster de Cassandra ejecuta el anillo de Cassandra. No ejecuta los componentes del entorno de ejecución híbrido.
  • El clúster de entorno de ejecución ejecuta los componentes del entorno de ejecución híbrido, pero no tiene pods de Cassandra. Los componentes del entorno de ejecución se conectan al anillo de Cassandra en el clúster de Cassandra a través de la red.

El operador de Apigee se ejecuta en ambos clústeres. Instala cert-manager, las definiciones de recursos personalizados (CRD) de Apigee y el gráfico apigee-operator en cada clúster. En la siguiente tabla, se muestran los componentes de cada clúster:

Componente Clúster de Cassandra Clúster de entorno de ejecución
cert-manager Sí Sí
CRD de Apigee y el gráfico apigee-operator Sí Sí
Gráfico apigee-datastore Sí, con los pods de Cassandra Sí, con replicaCount: 0 y sin pods de Cassandra
Todos los demás gráficos híbridos, como apigee-telemetry, apigee-redis, apigee-ingress-manager, apigee-org, apigee-env y apigee-virtualhost No Sí

El operador de Apigee realiza un trabajo diferente en cada clúster:

  • En el clúster de Cassandra, el operador crea los Pods de Cassandra. También administra el ciclo de vida de Cassandra, por ejemplo, cuando escalas el anillo.
  • En el clúster de entorno de ejecución, el operador no crea pods de Cassandra. Crea un objeto Service sin interfaz gráfica y un objeto Endpoints que apuntan al anillo de Cassandra en el clúster de Cassandra. Si habilitas la sincronización dinámica de extremos, el operador del clúster de entorno de ejecución también lee los extremos de Cassandra del clúster de Cassandra.

Descripción general de la configuración

Sigue estos pasos en el orden que se indica a continuación. La secuencia es importante. La autoridad certificadora (CA) compartida debe estar en el clúster de entorno de ejecución antes de que este emita certificados. Para obtener más información, consulta Comparte la AC de Apigee antes de instalar el operador.

  1. En el clúster de Cassandra, instala cert-manager, las CRD de Apigee, el gráfico apigee-operator y el gráfico apigee-datastore.
  2. Asegúrate de que los Pods de Cassandra en el clúster de Cassandra estén listos.
  3. En el clúster de entorno de ejecución, instala cert-manager.
  4. Copia el secreto apigee-ca del clúster de Cassandra al clúster de entorno de ejecución. Realiza este paso antes de instalar el gráfico apigee-operator en el clúster del entorno de ejecución.
  5. En el clúster de entorno de ejecución, instala los componentes del entorno de ejecución híbrido. Usa las invalidaciones de almacén de datos externos para el gráfico de apigee-datastore. Usa las mismas credenciales de Cassandra que en el clúster de Cassandra.
  6. (Recomendado) Habilita la sincronización dinámica de extremos.
  7. Verifica la conexión.

Para conocer los pasos que instalan cada gráfico, consulta Instala Apigee Hybrid con Helm.

Antes de comenzar

Asegúrate de que tu entorno cumpla con los siguientes requisitos:

  • Conexión de red a Cassandra. El clúster de tiempo de ejecución debe conectarse a los pods de Cassandra en el puerto TCP 9042. Coloca los dos clústeres en una VPC compartida o en redes con una conexión privada entre ellas.
  • Una región. Coloca los dos clústeres en la misma región. El tiempo de ida y vuelta entre los clústeres se suma a la latencia de cada solicitud de tiempo de ejecución.
  • cert-manager en ambos clústeres En cada clúster, cert-manager emite los certificados para la conexión mTLS entre el entorno de ejecución y Cassandra. Instala cert-manager en el clúster de Cassandra y en el clúster de entorno de ejecución.
  • Una ruta a cada pod de Cassandra. El controlador del cliente de Cassandra se conecta directamente a cada pod de Cassandra. El clúster del entorno de ejecución debe conectarse a la dirección IP de cada pod de Cassandra, no solo a una dirección. Un balanceador de cargas o una sola dirección IP virtual frente al anillo no cumplen con este requisito.
  • Conexión de red al servidor de la API de Kubernetes. Este requisito solo se aplica si usas la sincronización dinámica de extremos. El clúster de tiempo de ejecución debe conectarse al servidor de la API de Kubernetes del clúster de Cassandra.

Comparte la CA de Apigee antes de instalar el operador

Instala cert-manager en el clúster del entorno de ejecución. Luego, copia el secreto de la CA del clúster de Cassandra al clúster de tiempo de ejecución:

kubectl --context CASSANDRA_CLUSTER -n cert-manager get secret apigee-ca -o yaml \
  | grep -v -E '^\s+(resourceVersion|uid|creationTimestamp|selfLink):' \
  | kubectl --context RUNTIME_CLUSTER -n cert-manager apply -f -

Reemplaza lo siguiente:

  • CASSANDRA_CLUSTER: Es el contexto de kubectl del clúster de Cassandra.
  • RUNTIME_CLUSTER: Es el contexto de kubectl del clúster de entorno de ejecución.

El comando grep quita los campos de metadatos que pertenecen al clúster de Cassandra. El servidor de la API de Kubernetes no crea un objeto que tenga un valor de resourceVersion.

Las instalaciones multirregionales usan el mismo principio de CA compartida. Para ver un paso de copia similar, consulta Rota el certificado de la AC raíz. Para la configuración de mTLS de Cassandra, consulta Configura la autenticación para Cassandra.

Usa las mismas credenciales de Cassandra en ambos clústeres

Usa uno de estos métodos en los archivos de anulación de los dos clústeres:

  • Establece los mismos nombres de usuario y contraseñas en cassandra.auth: default, admin, ddl, dml, jmx y jolokia.
  • Establece cassandra.auth.secret. En cada clúster, el secreto debe contener los mismos usuarios y contraseñas. Consulta Cómo crear el Secret.
  • Establece cassandra.auth.secretProviderClass en un SecretProviderClass que lea el mismo almacén de secretos. Consulta Almacena secrets de Cassandra en Hashicorp Vault.

No copias el secreto de las credenciales del clúster de Cassandra. El gráfico del clúster de tiempo de ejecución crea el secreto a partir de tus anulaciones. Para encontrar una falla de autenticación, consulta Verifica la conexión.

Configura el almacén de datos externo

En el clúster de entorno de ejecución, el gráfico apigee-datastore no debe crear pods de Cassandra. Debe apuntar al anillo de Cassandra en el clúster de Cassandra. Agrega estos parámetros de configuración de cassandra al archivo de anulaciones del clúster de entorno de ejecución:

cassandra:
  # No Cassandra pods in the runtime cluster.
  replicaCount: 0
  properties:
    # A comma-separated list of the Cassandra pod IP addresses.
    externalHost: "CASSANDRA_IP_ADDRESSES"
  storage:
    # Required, even with replicaCount: 0.
    storageSize: "10Gi"

Aquí:

  • CASSANDRA_IP_ADDRESSES es una lista separada por comas de las direcciones IP de los Pods de Cassandra en el clúster de Cassandra. Por ejemplo: 10.0.0.1:9042,10.0.0.2:9042,10.0.0.3:9042 El sufijo :9042 es opcional. Para obtener la lista, ejecuta este comando:
    kubectl --context CASSANDRA_CLUSTER -n APIGEE_NAMESPACE get pods -l app=apigee-cassandra \
      -o jsonpath='{.items[*].status.podIP}' | tr ' ' ','
  • APIGEE_NAMESPACE es el espacio de nombres de Apigee. El valor predeterminado es apigee.
  • replicaCount: 0 le indica al operador que no cree pods de Cassandra en el clúster de entorno de ejecución. El operador crea un objeto Service sin interfaz gráfica y un objeto Endpoints que apuntan a las direcciones externalHost.
  • cassandra.properties.externalHost es una lista de direcciones IP de Cassandra separadas por comas. Cada dirección puede tener un sufijo :port, pero el operador ignora el puerto y siempre usa el puerto 9042. El operador solo acepta direcciones IP. Ignora los nombres de host y los nombres de DNS, y escribe una advertencia en su registro para cada entrada ignorada.
  • cassandra.storage.storageSize es obligatorio, pero el clúster de entorno de ejecución no crea PersistentVolumes para Cassandra. El webhook de validación ApigeeDatastore siempre verifica storageSize. Usa una cantidad válida, por ejemplo, 10Gi.

La dirección IP del Pod cambia cuando ajustas la escala del anillo y cuando Kubernetes reprograma un Pod. Entonces, la lista en externalHost se vuelve incorrecta. Por lo tanto, recomendamos la sincronización dinámica de extremos. La sincronización dinámica de extremos mantiene actualizada automáticamente la lista de direcciones IP de los Pods de Cassandra. Usa externalHost solo para una instalación simple o para la primera configuración.

Mantén los extremos actualizados con la sincronización dinámica de extremos

Con solo externalHost, debes editar tus anulaciones cada vez que cambie el anillo de Cassandra. La sincronización dinámica de extremos elimina este paso manual. El operador del clúster de entorno de ejecución lee los extremos de Cassandra listos del clúster de Cassandra a intervalos regulares. Luego, copia estos extremos en el objeto Endpoints del clúster de tiempo de ejecución.

Recomendamos la sincronización dinámica de extremos. Las direcciones IP de los Pods cambian cada vez que ajustas la escala del anillo o Kubernetes reprograma un Pod. La sincronización dinámica de extremos lee las direcciones IP de los Pods listos del Service sin interfaz gráfica de Cassandra. Por lo tanto, el objeto Endpoints en el clúster del entorno de ejecución siempre contiene las direcciones IP actuales de los Pods de Cassandra.

Con la sincronización dinámica de extremos, externalHost sigue siendo necesaria. El operador lo usa en estas dos condiciones:

  • Antes de la primera lectura exitosa del clúster de Cassandra.
  • Cuando falla una lectura del clúster de Cassandra y no hay extremos de una lectura anterior exitosa.

Si falla una lectura y hay extremos de una lectura anterior exitosa, el operador conserva esos extremos. El entorno de ejecución mantiene su conexión con Cassandra.

Para habilitar la sincronización dinámica de extremos, agrega el bloque externalEndpointsSync al archivo de anulaciones del clúster de ejecución:

cassandra:
  replicaCount: 0
  properties:
    # The first endpoints, and the fallback if a read fails.
    externalHost: "CASSANDRA_IP_ADDRESSES"
    externalEndpointsSync:
      # A secret in the runtime cluster. Its "kubeconfig" key holds the
      # kubeconfig for the Cassandra cluster.
      secretRef: apigee-remote-cass-kubeconfig
      # The namespace of the Cassandra headless Service in the Cassandra cluster.
      namespace: apigee
      # The Cassandra headless Service in the Cassandra cluster.
      serviceName: apigee-cassandra-default
      # The interval between reads, in seconds. The default is 30.
      intervalSeconds: 30
  storage:
    storageSize: "10Gi"

Crea una cuenta de servicio de solo lectura en el clúster de Cassandra

El operador del clúster de tiempo de ejecución usa un kubeconfig para conectarse al clúster de Cassandra. Este kubeconfig debe usar una ServiceAccount de solo lectura con el privilegio mínimo. Esta cuenta de servicio solo puede leer los extremos de Cassandra. No puede cambiar los recursos en el clúster de Cassandra.

En el clúster de Cassandra, crea estos recursos:

  • Un ServiceAccount, por ejemplo, apigee-endpoint-reader.
  • Un rol y un RoleBinding en el espacio de nombres de Cassandra El rol otorga solo los verbos get, list y watch en endpoints principal. No uses otros verbos, como create, update, patch o delete. No otorgues acceso a otros recursos.
  • Es un Secret de token de larga duración para la ServiceAccount.

Luego, crea un archivo kubeconfig para el servidor de la API de Kubernetes del clúster de Cassandra. Este kubeconfig debe usar el token de ServiceAccount. En el clúster de ejecución, crea un secreto con el nombre que estableciste en externalEndpointsSync.secretRef. Coloca el kubeconfig en la clave kubeconfig:

kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE create secret generic \
  apigee-remote-cass-kubeconfig --from-file=kubeconfig=READER_KUBECONFIG_FILE

Reemplaza READER_KUBECONFIG_FILE por la ruta de acceso al archivo kubeconfig de la cuenta de servicio de solo lectura.

El archivo kubeconfig contiene un token de larga duración. Protege este secreto como si fuera cualquier otra credencial.

Supervisa la sincronización de extremos dinámicos

Si falla una lectura del clúster de Cassandra, el entorno de ejecución mantiene su conexión. Sin embargo, los extremos del clúster de tiempo de ejecución no cambian hasta que se vuelve a realizar una lectura correctamente. Supervisa la sincronización para detectar una falla persistente antes de que cambie el anillo de Cassandra.

El operador del clúster de tiempo de ejecución proporciona estos indicadores:

  • La condición EndpointSyncDegraded en el estado del recurso ApigeeDatastore. La condición se convierte en True después de tres lecturas fallidas consecutivas. El motivo es RemoteReadFailed o NoReadyRemoteEndpoints. Después de una lectura correcta, la condición se convierte en False con el motivo SyncSucceeded.
  • Es la métrica external_endpoint_sync_last_success_timestamp. Esta métrica indica la hora de la última lectura exitosa, en segundos de Unix.
  • Es la métrica external_endpoint_sync_failures_total. Esta métrica cuenta las lecturas fallidas.

Las dos métricas tienen las etiquetas namespace y name del recurso ApigeeDatastore. El operador los muestra en su extremo de métricas.

Para ver la condición, ejecuta este comando:

kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get apigeedatastore default \
  -o jsonpath='{.status.conditions}'

Te recomendamos que configures una alerta para la condición EndpointSyncDegraded. El estado ApigeeDatastore mantiene la condición cuando se reinicia el operador. Solo una lectura exitosa establece la condición en False.

Si también usas una alerta en la métrica, envía una alerta cuando una de estas dos expresiones sea verdadera:

  • time() - external_endpoint_sync_last_success_timestamp > 300
  • absent(external_endpoint_sync_last_success_timestamp)

El operador establece la métrica solo después de una lectura exitosa. Si el operador se reinicia mientras fallan las lecturas, la métrica estará ausente. Entonces, la primera expresión no coincide y solo la segunda envía la alerta.

Verifica la conexión

Después de instalar los componentes del entorno de ejecución, realiza estas verificaciones en el clúster del entorno de ejecución:

  1. Asegúrate de que el clúster de entorno de ejecución no tenga Pods de Cassandra:

    kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get pods -l app=apigee-cassandra

    El resultado es No resources found.

  2. Asegúrate de que el objeto Endpoints apunte al anillo de Cassandra:

    kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get endpoints apigee-cassandra-default

    La columna ENDPOINTS muestra las direcciones IP de Cassandra. Si usas la sincronización dinámica de extremos, estas son las direcciones IP de los Pods de Cassandra listos en el clúster de Cassandra.

  3. Asegúrate de que se hayan completado los trabajos de configuración de Cassandra:

    kubectl --context RUNTIME_CLUSTER -n APIGEE_NAMESPACE get jobs \
      | grep -E 'apigee-cassandra-(schema|user)-setup'

    La columna COMPLETIONS muestra 1/1 para cada trabajo. Si un trabajo no se completa, examina su registro para detectar errores de autenticación. Luego, asegúrate de que los dos clústeres usen las mismas credenciales de Cassandra.

Escala el anillo de Cassandra

El operador de Apigee en el clúster de Cassandra es propietario del ciclo de vida de Cassandra. Escala Cassandra en el clúster de Cassandra. No puedes escalar Cassandra desde el clúster de entorno de ejecución.

Cumple con las mismas reglas que para un anillo de Cassandra en el clúster de tiempo de ejecución:

  • Escala Cassandra en múltiplos de tres. Esto mantiene el anillo balanceado en tres zonas de disponibilidad.
  • Antes de aumentar la cantidad de Pods, asegúrate de que el clúster de Cassandra tenga suficiente capacidad de nodos.
  • Si no usas la sincronización dinámica de extremos, actualiza externalHost después de cada operación de ajuste.

Para obtener más información, consulta Escalamiento de Cassandra.

¿Qué sigue?