Guía de solución de problemas de Cassandra

Estás viendo la documentación de Apigee y Apigee hybrid.
No hay documentación de Apigee Edge equivalente para este tema.

En este tema, se analizan los pasos que puedes seguir para solucionar problemas con el almacén de datos Cassandra. Cassandra es un almacén de datos persistente que se ejecuta en el componente cassandra de la arquitectura del entorno de ejecución híbrida. Consulta también Descripción general de la configuración del servicio del entorno de ejecución.

Los Pods de Cassandra están atascados en el estado de actualización

Síntoma

Después de intentar realizar una actualización en los Pods de Cassandra, el almacén de datos informa que está atascado en el estado de actualización.

Mensaje de error

Cuando uses kubectl para ver los estados de los Pods, verás que uno o más Pods de Cassandra están atascados en el estado de actualización:

Events:
Type Reason Age From Message
---- ------ ---- ---- -------
Normal Ack 57s (x7 over 24h) apigee-datastore release started

Causas posibles

Un Pod atascado en el estado de actualización puede deberse a los siguientes motivos:

Causa	Descripción
Cambios en la capacidad de almacenamiento	Se ejecutaron pasos para cambiar la capacidad de almacenamiento en el archivo `override.yaml`.
Otros cambios de configuración	Se realizaron actualizaciones a las propiedades de Cassandra en el archivo `override.yaml`. Sin embargo, los cambios no se aplicaron.

Cambios en la capacidad de almacenamiento

Diagnóstico

Usa kubectl para ver el estado actual del Pod del almacén de datos apigee:
```
kubectl get apigeeds -n apigee
```
```
NAME STATE AGE
default releasing 122d
```
Verifica si hubo algún cambio en el archivo override.yaml:

Con tu sistema de control de versión, compara la versión anterior del archivo override.yaml con la versión actual:
```
diff OVERRIDES_BEFORE.yaml OVERRIDES_AFTER.yaml
```
El resultado de una diferencia en override.yaml puede mostrar el posible problema con el tamaño de la capacidad de almacenamiento. Por ejemplo:
```
# Overrides.yaml  before:
cassandra:
   storage:
      capacity: 500Gi

# Overrides.yaml after:
cassandra:
   storage:
      capacity: 100Gi
```
Si hubo una operación para cambiar la capacidad de almacenamiento en la que se omitieron los pasos y se aplicó una override.yaml nueva directamente, esto puede causar que el almacén de datos esté en estado de actualización.

Revisa statefulset para asegurarte de que haya uno para apigee-cassandra-default:

kubectl describe sts -n apigee

El resultado debería ser similar a este:

Name:               apigee-cassandra-default
Namespace:          apigee
CreationTimestamp:  Tue, 18 Jul 2023 00:40:57 +0000
Selector:           app=apigee-cassandra,name=default
Labels:             apigee.cloud.google.com.revision=v1-2cc098050836c6b4
                    apigee.cloud.google.com.version=v1
                    apigee.cloud.google.com/platform=apigee
                    app=apigee-cassandra
                    name=default
Annotations:        <none>
Replicas:           3 desired | 3 total
Update Strategy:    RollingUpdate
  Partition:        0
Pods Status:        3 Running / 0 Waiting / 0 Succeeded / 0 Failed
Pod Template:
  Labels:       apigee.cloud.google.com/apigee_servicename=production
                apigee.cloud.google.com/billing_type=subscription
                apigee.cloud.google.com/platform=apigee
                app=apigee-cassandra
                name=default
                revision=v1
                runtime_type=hybrid
  Annotations:  apigee.cloud.google.com/pod-template-spec-hash: 2cc098050836c6b4
                prometheus.io/path: /metrics
                prometheus.io/port: 7070
                prometheus.io/scheme: https
                prometheus.io/scrape: true
  Containers:
   apigee-cassandra:
    Image:       gcr.io/apigee-release/hybrid/apigee-hybrid-cassandra:1.10.1
    Ports:       7000/TCP, 7001/TCP, 7199/TCP, 9042/TCP, 8778/TCP
    Host Ports:  7000/TCP, 7001/TCP, 7199/TCP, 9042/TCP, 8778/TCP
    Requests:
      cpu:      500m
      memory:   1Gi
    Readiness:  exec [/bin/bash -c /opt/apigee/ready-probe.sh] delay=0s timeout=5s period=10s #success=1 #failure=2
    Environment:
      POD_NAME:                  (v1:metadata.name)
      POD_IP:                    (v1:status.podIP)
      MAX_HEAP_SIZE:            512M
      HEAP_NEWSIZE:             100M
      CASSANDRA_SEEDS:          apigee-cassandra-default-0.apigee-cassandra-default.apigee.svc.cluster.local
      CASSANDRA_CLUSTER_NAME:   apigeecluster
      CASSANDRA_DC:             dc-1
      CASSANDRA_RACK:           ra-1
      CASSANDRA_OPEN_JMX:       true
      CPS_ADMIN_USER:           <set to the key 'admin.user' in secret 'apigee-datastore-default-creds'>        Optional: false
      CPS_ADMIN_PASSWORD:       <set to the key 'admin.password' in secret 'apigee-datastore-default-creds'>    Optional: false
      APIGEE_JMX_USER:          <set to the key 'jmx.user' in secret 'apigee-datastore-default-creds'>          Optional: false
      APIGEE_JMX_PASSWORD:      <set to the key 'jmx.password' in secret 'apigee-datastore-default-creds'>      Optional: false
      CASS_PASSWORD:            <set to the key 'default.password' in secret 'apigee-datastore-default-creds'>  Optional: false
      APIGEE_JOLOKIA_USER:      <set to the key 'jolokia.user' in secret 'apigee-datastore-default-creds'>      Optional: false
      APIGEE_JOLOKIA_PASSWORD:  <set to the key 'jolokia.password' in secret 'apigee-datastore-default-creds'>  Optional: false
    Mounts:
      /opt/apigee/apigee-cassandra/conf from appsfs (rw)
      /opt/apigee/customer from cwc-volume (ro)
      /opt/apigee/data from cassandra-data (rw)
      /opt/apigee/ssl from tls-volume (ro)
      /var/secrets/google from apigee-cassandra-backup (rw)
      /var/secrets/keys from apigee-cassandra-backup-key-file (rw)
  Volumes:
   cwc-volume:
    Type:        Secret (a volume populated by a Secret)
    SecretName:  config-cassandra-default
    Optional:    false
   tls-volume:
    Type:        Secret (a volume populated by a Secret)
    SecretName:  apigee-cassandra-default-tls
    Optional:    false
   appsfs:
    Type:       EmptyDir (a temporary directory that shares a pod's lifetime)
    Medium:
    SizeLimit:  <unset>
   apigee-cassandra-backup:
    Type:        Secret (a volume populated by a Secret)
    SecretName:  apigee-cassandra-backup-svc-account
    Optional:    true
   apigee-cassandra-backup-key-file:
    Type:        Secret (a volume populated by a Secret)
    SecretName:  apigee-cassandra-backup-key-file
    Optional:    true
Volume Claims:
  Name:          cassandra-data
  StorageClass:
  Labels:        <none>
  Annotations:   <none>
  Capacity:      10Gi
  Access Modes:  [ReadWriteOnce]
Events:
  Type    Reason            Age   From                    Message
  ----    ------            ----  ----                    -------
  Normal  SuccessfulCreate  47m   statefulset-controller  create Pod apigee-cassandra-default-2 in StatefulSet apigee-cassandra-default successful

Verifica si hay errores en el controlador de Apigee:

kubectl logs -f apigee-controller-manager-59cf595c77-wtwnr -n apigee-system -c manager | grep apigeedatastore

Resultados:

"error creating
apigee-cassandra object: failed to update resource
apigee/apigee-cassandra-default: StatefulSet.apps \"apigee-cassandra-default\"
is invalid: spec: Forbidden: updates to statefulset spec for fields other than
'replicas', 'template', 'updateStrategy', 'persistentVolumeClaimRetentionPolicy'
and 'minReadySeconds' are forbiddenerror creating apigee-cassandra object:
failed to update resource apigee/apigee-cassandra-default: StatefulSet.apps
\"apigee-cassandra-default\" is invalid: spec: Forbidden: updates to statefulset
spec for fields other than 'replicas', 'template', 'updateStrategy',
'persistentVolumeClaimRetentionPolicy' and 'minReadySeconds' are forbidden"

Solución

Para restablecer el estado de Cassandra y volver a un estado de ejecución, sigue estos pasos:

Inhabilita el apigee-controller:

kubectl -n apigee-system edit deployments and set --enable-controllers=true to --enable-controllers=false

Regresa el almacén de datos a un estado en ejecución con el comando PATCH:

curl -XPATCH \-H "Accept: application/json" -H "Content-Type: application/json-patch+json" --data '[{"op": "replace", "path": "/status/nestedState", "value": ""},{"op": "replace", "path": "/status/state", "value": "running"}]' 'http://127.0.0.1:8001/apis/apigee.cloud.google.com/v1alpha1/namespaces/apigee/apigeedatastores/default/status'

Vuelve a aplicar el archivo override.yaml original:

./apigeectl apply --datastore -f overrides.yaml

Habilita el apigee-controller:

kubectl -n apigee-system edit deployments and set --enable-controllers=false to --enable-controllers=true

Espera a que el almacén de datos vuelva a crearse y se valide usando lo siguiente:
```
kubectl get apigeeds --namespace apigee
```
Valida que las implementaciones y los Pods de Apigee estén en estado de ejecución y que apigeeds ya no esté en estado de actualización:
```
kubectl get ad -n apigee
```
```
kubectl get pods -n apigee
```
```
kubectl get apigeeds -n apigee
```
```
NAME      STATE     AGE
default   running   24d
```

Otros cambios de configuración

Las actualizaciones realizadas a las propiedades cassandra en override.yaml y los cambios no se aplicaron. Esto puede ser un cambio de contraseña o un cambio en los recursos de override.yaml. O aplicar erróneamente el override.yaml incorrecto a un clúster.

Diagnóstico

Consulta los pasos en Diagnóstico.

Solución

Consulta los pasos que se indican en Resolución.

Se debe recopilar información de diagnóstico

Si el problema persiste incluso después de seguir las instrucciones anteriores, recopila la siguiente información de diagnóstico y, luego, comunícate con Atención al cliente de Google Cloud:

Overrides.yaml para cada clúster de la instalación.

Un volcado de la información del clúster de Kubernetes de la instalación de Hybrid:

Genera cluster-info dump de Kubernetes:

kubectl cluster-info dump -A --output-directory=/tmp/kubectl-cluster-info-dump

Comprime con zip cluster-info dump de Kubernetes:

zip -r kubectl-cluster-info-dump`date +%Y.%m.%d_%H.%M.%S`.zip /tmp/kubectl-cluster-info-dump/*

Los pods de Cassandra están atascados en el estado pendiente

Síntoma

Cuando se inician, los pods de Cassandra permanecen en el estado Pending.

Mensaje de error

Cuando usas kubectl para ver los estados de los pods, verás que uno o más pods de Cassandra están atascados en el estado Pending. El estado Pending indica que Kubernetes no puede programar el pod en un nodo: el pod no se puede crear. Por ejemplo:

kubectl get pods -n NAMESPACE

NAME                                     READY   STATUS      RESTARTS   AGE
adah-resources-install-4762w             0/4     Completed   0          10m
apigee-cassandra-default-0               0/1     Pending     0          10m
...

Causas posibles

Un pod atascado en el estado Pending puede producirse por varias causas. Por ejemplo:

Causa	Descripción
Recursos insuficientes	No hay CPU ni memoria disponibles para crear el pod.
No se creó el volumen.	El pod está esperando a que se cree el volumen persistente.
Falta el controlador CSI de Amazon EBS	Para las instalaciones de EKS, el controlador de CSI de Amazon EBS necesario no está instalado.

Diagnóstico

Usa kubectl para describir el pod a fin de determinar el origen del error. Por ejemplo:

kubectl -n NAMESPACE describe pods POD_NAME

Por ejemplo:

kubectl describe pods apigee-cassandra-default-0 -n apigee

Puede que la salida muestre uno de estos problemas posibles:

Si el problema es que no hay recursos suficiente, verás un mensaje de advertencia que indica que la CPU o la memoria son insuficientes.
Si el mensaje de error indica que el pod tiene PersistentVolumeClaims (PVC) inmediatos desvinculados, significa que el pod no puede crear su volumen persistente.

Solución

Recursos insuficientes

Modifica el grupo de nodos de Cassandra para que tenga recursos suficientes de CPU y memoria. Consulta Cambia el tamaño de un grupo de nodos para obtener más detalles.

No se creó el volumen persistente.

Si determinas que hay un problema con el volumen persistente, describe el PersistentVolumeClaim (PVC) para determinar por qué no se está creando:

Obtén una lista de los PVC en el clúster:

kubectl -n NAMESPACE get pvc

NAME                                        STATUS   VOLUME                                     CAPACITY   ACCESS MODES   STORAGECLASS   AGE
cassandra-data-apigee-cassandra-default-0   Bound    pvc-b247faae-0a2b-11ea-867b-42010a80006e   10Gi       RWO            standard       15m
...

Describe el PVC para el pod que falla. Por ejemplo, el siguiente comando describe el PVC vinculado al pod apigee-cassandra-default-0:

kubectl apigee describe pvc cassandra-data-apigee-cassandra-default-0

Events:
  Type     Reason              Age                From                         Message
  ----     ------              ----               ----                         -------
  Warning  ProvisioningFailed  3m (x143 over 5h)  persistentvolume-controller  storageclass.storage.k8s.io "apigee-sc" not found

Ten en cuenta que, en este ejemplo, no existe la StorageClass llamada apigee-sc. Para resolver este problema, crea la StorageClass faltante en el clúster, como se explica en Cambia la StorageClass predeterminada.

Consulta también Depura pods.

Falta el controlador CSI de Amazon EBS

Si la instancia híbrida se ejecuta en un clúster de EKS, asegúrate de que el clúster de EKS use el controlador de la interfaz de almacenamiento de contenedores (CSI) de Amazon EBS. Consulta las Preguntas frecuentes sobre la migración de Amazon EBS a la CSI para obtener más detalles.

Los pods de Cassandra están atascados en el estado CrashLoopBackoff.

Síntoma

Cuando se inician, los pods de Cassandra permanecen en el estado CrashLoopBackoff.

Mensaje de error

Cuando usas kubectl para ver los estados de los Pods, verás que uno o más pods de Cassandra tienen el estado CrashLoopBackoff. Este estado indica que Kubernetes no puede crear el pod. Por ejemplo:

kubectl get pods -n NAMESPACE

NAME                                     READY   STATUS            RESTARTS   AGE
adah-resources-install-4762w             0/4     Completed         0          10m
apigee-cassandra-default-0               0/1     CrashLoopBackoff  0          10m
...

Causas posibles

Un pod atascado en el estado CrashLoopBackoff puede producirse por varias causas. Por ejemplo:

Causa	Descripción
El centro de datos difiere del centro de datos anterior	Este error indica que el pod de Cassandra tiene un volumen persistente que contiene datos de un clúster anterior, y los pods nuevos no pueden unirse al clúster anterior. Esto suele ocurrir cuando los volúmenes persistentes inactivos persisten desde el clúster anterior de Cassandra en el mismo nodo de Kubernetes. Este problema puede ocurrir si borras y vuelves a crear Cassandra en el clúster.
Actualización de Kubernetes	Una actualización de Kubernetes puede afectar el clúster de Cassandra. Esto puede suceder cuando los nodos trabajadores de Anthos que alojan los Pods de Cassandra se actualizan a una versión nueva del SO.

Diagnóstico

Revisa el registro de errores de Cassandra para determinar la causa del problema.

Enumera los pods para obtener el ID del pod de Cassandra que está fallando:
```
kubectl get pods -n NAMESPACE
```
Verifica el registro del Pod que falla:
```
kubectl logs POD_ID -n NAMESPACE
```

Solución

Busca las siguientes pistas en el registro del Pod:

El centro de datos difiere del centro de datos anterior

Si ves este mensaje de registro, haz lo siguiente:

Cannot start node if snitch's data center (us-east1) differs from previous data center

Verifica si hay algún PVC obsoleto o antiguo en el clúster y bórralo.
Si se trata de una instalación nueva, borra todos los PVC y vuelve a intentar la configuración. Por ejemplo:
```
kubectl -n NAMESPACE get pvc
kubectl -n NAMESPACE delete pvc cassandra-data-apigee-cassandra-default-0
```

La actualización de Anthos cambia la configuración de seguridad

Revisa los registros de Cassandra en busca de este mensaje de error:

/opt/apigee/run.sh: line 68: ulimit: max locked memory:
  cannot modify limit: Operation not permitted

Si la instancia híbrida es multirregional, retira la instancia híbrida afectada y vuelve a expandirla a la región afectada.
Si la instancia de Hybrid es una sola región, realiza un reinicio progresivo en cada Pod de Cassandra en la instancia de Hybrid.

Crea un contenedor del cliente para depurar

En esta sección, se explica cómo crear un contenedor de cliente desde el que puedes acceder a las utilidades de depuración de Cassandra, como cqlsh. Estas utilidades te permiten consultar tablas de Cassandra y pueden ser útiles para fines de depuración.

Crea el contenedor del cliente

Para crear el contenedor del cliente, sigue estos pasos:

El contenedor debe usar el certificado TLS del Pod apigee-cassandra-user-setup. Esto se almacena como un secret de Kubernetes. Recupera el nombre del secret que almacena este certificado:
```
kubectl get secrets -n apigee --field-selector type=kubernetes.io/tls | grep apigee-cassandra-user-setup | awk '{print $1}'
```
Este comando muestra el nombre del Secret. Por ejemplo: apigee-cassandra-user-setup-rg-hybrid-b7d3b9c-tls. La usarás a continuación en el campo secretName del archivo YAML.

Abre un archivo nuevo y pega en él las siguientes especificaciones del pod:

apiVersion: v1
kind: Pod
metadata:
  labels:
  name: CASSANDRA_CLIENT_NAME   # For example: my-cassandra-client
  namespace: apigee
spec:
  containers:
  - name: CASSANDRA_CLIENT_NAME
    image: "gcr.io/apigee-release/hybrid/apigee-hybrid-cassandra-client:YOUR_APIGEE_HYBRID_VERSION" # For example, 1.10.5.
    imagePullPolicy: Always
    command:
    - sleep
    - "3600"
    env:
    - name: CASSANDRA_SEEDS
      value: apigee-cassandra-default.apigee.svc.cluster.local
    - name: APIGEE_DML_USER
      valueFrom:
        secretKeyRef:
          key: dml.user
          name: apigee-datastore-default-creds
    - name: APIGEE_DML_PASSWORD
      valueFrom:
        secretKeyRef:
          key: dml.password
          name: apigee-datastore-default-creds
    volumeMounts:
    - mountPath: /opt/apigee/ssl
      name: tls-volume
      readOnly: true
  volumes:
  - name: tls-volume
    secret:
      defaultMode: 420
      secretName: YOUR_SECRET_NAME    # For example: apigee-cassandra-user-setup-rg-hybrid-b7d3b9c-tls
  restartPolicy: Never

Guarda el archivo con una extensión .yaml. Por ejemplo: my-spec.yaml

Aplica las especificaciones a tu clúster:

kubectl apply -f YOUR_SPEC_FILE.yaml -n apigee

Accede al contenedor:

kubectl exec -n apigee CASSANDRA_CLIENT_NAME -it -- bash

Conéctate a la interfaz cqlsh de Cassandra con el siguiente comando. Ingresa el comando exactamente como se muestra:
```
cqlsh ${CASSANDRA_SEEDS} -u ${APIGEE_DML_USER} -p ${APIGEE_DML_PASSWORD} --ssl
```

Borra el pod del cliente

Usa este comando para borrar el Pod de cliente de Cassandra:

kubectl delete pods -n apigee cassandra-client

Expansión de región mal configurada: todos los nodos de Cassandra en un centro de datos

Esta situación se produce en una expansión multirregional en las plataformas de GKE y GKE On-Prem (Anthos). Evita intentar crear todos los nodos de Cassandra en el mismo centro de datos.

Síntoma

Los nodos de Cassandra no pueden crearse en el centro de datos para la segunda región.

Mensaje de error

failed to rebuild from dc-1: java.lang.RuntimeException : Error while rebuilding node: Stream failed

Solución

Repara la expansión de región mal configurada con los siguientes pasos:

Actualiza la replicaCount de Cassandra a 1 en el archivo overrides.yaml para el segundo centro de datos. Por ejemplo:
```
cassandra:
  . . .
  replicaCount: 1
```
Aplica la configuración con apigeectl apply:
```
$APIGEECTL_HOME/apigeectl apply -f 2ND_DATACENTER_OVERRIDES.yaml
```
Usa kubectl exec para acceder al Pod de Cassandra restante con el siguiente comando:
```
kubectl exec -it -n apigee apigee-cassandra-default-0 -- /bin/bash
```

Inhabilita el Pod de Cassandra restante con el siguiente comando:

nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD decommission

Borra los Pods de Cassandra del segundo centro de datos mediante apigeectl delete con el argumento --datastore. Por ejemplo:
```
$APIGEECTL_HOME/apigeectl delete -f 2ND_DATACENTER_OVERRIDES.yaml --datastore
```
Cambia tu contexto de Kubernetes al clúster de tu primer centro de datos:
```
kubectl config use-context FIRST_DATACENTER_CLUSTER
```
Verifica que no haya nodos de Cassandra en un estado de inactividad en el primer centro de datos.
```
nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status
```
Verifica que los nodos de Cassandra mal configurados (que están destinados al segundo centro de datos) se hayan quitado del primer centro de datos. Asegúrate de que las direcciones IP que se muestran en el resultado del estado de nodetool sean solo las direcciones IP para los Pods de Cassandra destinados a tu primer centro de datos. Por ejemplo, en el siguiente resultado, la dirección IP 10.100.0.39 debe ser para un Pod en tu primer centro de datos.
```
kubectl exec -it -n apigee apigee-cassandra-default-0 -- /bin/bash
nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status

  Datacenter: dc-1
  ================
  Status=U/D (Up/Down) | State=N/L/J/M (Normal/Leaving/Joining/Moving)
  --  Address      Load      Tokens  Owns (effective)  Host ID                               Rack
  UN  10.100.0.39  4.21 MiB  256     100.0%            a0b1c2d3-e4f5-6a7b-8c9d-0e1f2a3b4c5d  ra-1
```
Verifica el archivo overrides.yaml para el segundo centro de datos contiene la configuración del nombre del centro de datos en la sección Cassandra. Por ejemplo:
```
cassandra:
  datacenter: DATA_CENTER_2
  rack: "RACK_NAME" # "ra-1" is the default value.
  . . .
```
Actualiza la configuración cassandra:replicaCount en el archivo overrides.yaml del segundo centro de datos al número deseado. Por ejemplo:
```
cassandra:
  datacenter: DATA_CENTER_2
  . . .
  replicaCount: 3
```
Nota: El valor de cassandra:replicaCount debe ser un múltiplo de 3. Usa el mismo valor de replicaCount que especificaste para tu primer centro de datos.
Aplica el archivo overrides.yaml para el segundo centro de datos con el argumento --datastore. Por ejemplo:
```
$APIGEECTL_HOME/apigeectl apply -f 2ND_DATACENTER_OVERRIDES.yaml --datastore
```
Usa kubectl exec para acceder a uno de los Pods de Cassandra nuevos en el segundo centro de datos y verifica que haya dos centros de datos:
```
 "nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status"
```

Recursos adicionales

Consulta Introducción a las guías de Apigee X y Apigee Hybrid.