Guia de solução de problemas do Cassandra

Esta é a documentação da Apigee e da Apigee híbrida.
Não há documentação equivalente do Apigee Edge para esse tópico.

Neste tópico, você verá etapas para resolver e corrigir problemas com o armazenamento de dados do Cassandra. O Cassandra é um armazenamento de dados persistente executado no componente cassandra da arquitetura de ambiente de execução híbrida. Consulte também Visão geral da configuração do serviço de ambiente de execução.

Os pods do Cassandra estão presos no estado de lançamento

Sintoma

Depois de tentar fazer uma atualização nos pods do Cassandra, o repositório de dados está informando que está parado no estado de lançamento.

Mensagem de erro

Ao usar kubectl para visualizar os estados do pod, um ou mais pods do Cassandra estarão presos no estado de lançamento:

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

Causas possíveis

Um pod travado no estado de lançamento pode ser causado pelo seguinte:

Causa	Descrição
Mudanças na capacidade de armazenamento	Etapas foram executadas para alterar a capacidade de armazenamento no arquivo `override.yaml`.
Outras mudanças na configuração	Foram feitas atualizações nas propriedades do cassandra no arquivo `override.yaml`. No entanto, as mudanças não entraram em vigor.

Mudanças na capacidade de armazenamento

Diagnóstico

Use kubectl para ver o estado atual do pod do repositório de dados apigee:
```
kubectl get apigeeds -n apigee
```
```
NAME STATE AGE
default releasing 122d
```
Verifique se houve alguma alteração no arquivo override.yaml:

Usando seu sistema de controle de versões, compare a versão anterior do arquivo override.yaml com a versão atual:
```
diff OVERRIDES_BEFORE.yaml OVERRIDES_AFTER.yaml
```
A saída de uma diferença no override.yaml pode mostrar o possível problema com o tamanho da capacidade de armazenamento. Por exemplo:
```
# Overrides.yaml  before:
cassandra:
   storage:
      capacity: 500Gi

# Overrides.yaml after:
cassandra:
   storage:
      capacity: 100Gi
```
Se houve uma operação para alterar a capacidade de armazenamento em que as etapas foram ignoradas e um novo override.yaml foi aplicado diretamente, isso pode fazer com que o repositório de dados esteja no estado de lançamento.

Verifique se há um statefulset para apigee-cassandra-default:

kubectl describe sts -n apigee

A saída terá a seguinte aparência:

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

Verifique se há erros no controlador da 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"

Resolução

Para redefinir o estado do Cassandra a um estado de execução, siga as etapas abaixo:

Desative apigee-controller:

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

Retorne o repositório de dados a um estado de execução usando o 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'

Aplique novamente o arquivo override.yaml original:

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

Ative a apigee-controller:

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

Aguarde o repositório de dados voltar e validar usando o seguinte:
```
kubectl get apigeeds --namespace apigee
```

Confirmar se as implantações e os pods da Apigee estão no status em execução e apigeeds não está mais no estado de lançamento:

kubectl get ad -n apigee

kubectl get pods -n apigee

kubectl get apigeeds -n apigee

NAME      STATE     AGE
default   running   24d

Outras mudanças na configuração

As atualizações feitas nas propriedades cassandra no override.yaml e as mudanças não entraram em vigor. Isso pode ser uma mudança de senha ou uma mudança de recursos na override.yaml. Ou aplicar erroneamente o override.yaml a um cluster.

Diagnóstico

Consulte as etapas em Diagnóstico.

Resolução

Consulte as etapas em Resolução.

É necessário coletar informações de diagnóstico

Se o problema persistir mesmo depois de seguir as instruções acima, reúna as seguintes informações de diagnóstico e entre em contato com o Suporte da Apigee:

Overrides.yaml para cada cluster na instalação.

Um despejo de informações do cluster do Kubernetes da instalação híbrida:

Gere cluster-info dump do Kubernetes:

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

Compacte usando o ZIP cluster-info dump do Kubernetes:

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

Os pods do Cassandra estão presos no estado pendente

Sintoma

Ao serem iniciados, os pods do Cassandra permanecem no estado Pendente.

Mensagem de erro

Ao usar kubectl para visualizar os estados do pod, você verá que um ou mais pods do Cassandra estão parados no estado Pending. O estado Pending indica que o Kubernetes não pode agendar o pod em um nó: o pod não pode ser criado. Exemplo:

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 possíveis

Um pod preso no estado pendente pode ter várias causas. Exemplo:

Causa	Descrição
Recursos insuficientes	Não há CPU ou memória suficiente disponível para criar o pod.
Volume não criado	O pod aguarda a criação do volume permanente para ser criado.
Driver CSI do Amazon EBS ausente	Para instalações do EKS, o driver CSI necessário do Amazon EBS não está instalado.

Diagnóstico

Use kubectl para descrever o pod a fim de determinar a origem do erro. Exemplo:

kubectl -n NAMESPACE describe pods POD_NAME

Exemplo:

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

A saída pode mostrar um dos seguintes problemas:

Se o problema for recursos insuficientes, você verá uma mensagem de aviso que indica CPU ou memória insuficientes.
Se a mensagem de erro indicar que o pod tem PersistentVolumeClaims (PVC) imediatos desvinculados, isso significa que o pod não pode criar o volume permanente dele.

Resolução

Recursos insuficientes

Modifique o pool de nós do Cassandra para que tenha recursos de CPU e memória suficientes. Consulte Como redimensionar um pool de nós para detalhes.

Volume permanente não criado

Se você determinar um problema de volume permanente, descreva o PersistentVolumeClaim (PVC) para determinar por que ele não está sendo criado:

Liste os PVCs no cluster:

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
...

Descreva o PVC para o pod que está falhando. Por exemplo, o comando a seguir descreve o PVC vinculado ao 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

Neste exemplo, o StorageClass chamado apigee-sc não existe. Para resolver esse problema, crie o StorageClass ausente no cluster, conforme explicado em Alterar o StorageClass padrão.

Consulte também Como depurar pods.

Driver CSI do Amazon EBS ausente

Se a instância híbrida estiver em execução em um cluster do EKS, verifique se o cluster do EKS está usando o driver da interface de armazenamento de contêiner (CSI, na sigla em inglês) do Amazon EBS. Consulte as Perguntas frequentes sobre a migração do CSI do Amazon EBS para saber mais detalhes.

Os pods do Cassandra estão presos no estado CrashLoopBackoff

Sintoma

Durante a inicialização, os pods do Cassandra permanecem no estado CrashLoopBackoff.

Mensagem de erro

Ao usar kubectl para visualizar os estados do pod, você verá que um ou mais pods do Cassandra estão no estado CrashLoopBackoff. Esse estado indica que o Kubernetes não pode criar o pod. Exemplo:

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 possíveis

Um pod parado no estado CrashLoopBackoff pode ter várias causas. Exemplo:

Causa	Descrição
O data center é diferente do data center anterior.	Esse erro indica que o pod do Cassandra tem um volume permanente que tem dados de um cluster anterior e os novos pods não podem unir o cluster antigo. Isso geralmente acontece quando os volumes permanentes desatualizados persistem do cluster do Cassandra anterior no mesmo nó do Kubernetes. Esse problema pode ocorrer se você excluir e recriar o Cassandra no cluster.
Upgrade do Kubernetes	Um upgrade do Kubernetes pode afetar o cluster do Cassandra. Isso pode acontecer quando os nós de trabalho do Anthos que hospedam os pods do Cassandra são atualizados para uma nova versão do sistema operacional.

Diagnóstico

Verifique o registro de erros do Cassandra para determinar a causa do problema.

Liste os pods para conseguir o ID do pod do Cassandra que está apresentando falhas:
```
kubectl get pods -n NAMESPACE
```
Verifique o registro do pod com falha:
```
kubectl logs POD_ID -n NAMESPACE
```

Resolução

Procure as seguintes dicas no registro do pod:

O data center é diferente do data center anterior.

Se você vir esta mensagem de registro:

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

Verifique se há PVC desatualizado ou antigo no cluster e exclua-os.

Se for uma nova instalação, exclua todos os PVCs e tente novamente. Exemplo:

kubectl -n NAMESPACE get pvc
kubectl -n NAMESPACE delete pvc cassandra-data-apigee-cassandra-default-0

O upgrade do Anthos altera as configurações de segurança

Verifique se há esta mensagem de erro nos registros do Cassandra:

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

Se a instância híbrida for multirregional, desative a instância híbrida afetada e expanda novamente para a região afetada.
Se a instância híbrida for uma única região, execute uma reinicialização contínua em cada pod do Cassandra na instância híbrida.

Criar um contêiner do cliente para depuração

Nesta seção, explicamos como criar um contêiner do cliente em que é possível acessar utilitários de depuração do Cassandra, como cqlsh. Esses utilitários permitem consultar tabelas do Cassandra e podem ser úteis para fins de depuração.

Criar o contêiner do cliente

Para criar o contêiner do cliente, siga estas etapas:

O contêiner precisa usar o certificado TLS do pod apigee-cassandra-user-setup. Ele é armazenado como um secret do Kubernetes. Busque o nome do secret que armazena esse certificado:
```
kubectl get secrets -n apigee --field-selector type=kubernetes.io/tls | grep apigee-cassandra-user-setup | awk '{print $1}'
```
Esse comando retorna o nome do secret. Por exemplo, apigee-cassandra-user-setup-rg-hybrid-b7d3b9c-tls. Ele será usado abaixo no campo secretName do arquivo YAML.

Abra um novo arquivo e cole a seguinte especificação de pod nele:

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.4.
    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

Salve o arquivo com uma extensão .yaml. Por exemplo, my-spec.yaml.

Aplique a especificação ao cluster:

kubectl apply -f YOUR_SPEC_FILE.yaml -n apigee

Faça login no contêiner:

kubectl exec -n apigee CASSANDRA_CLIENT_NAME -it -- bash

Conecte-se à interface cqlsh do Cassandra com o comando a seguir. Digite o comando exatamente como mostrado:
```
cqlsh ${CASSANDRA_SEEDS} -u ${APIGEE_DML_USER} -p ${APIGEE_DML_PASSWORD} --ssl
```

Como excluir o pod cliente

Use este comando para excluir o pod de cliente do Cassandra:

kubectl delete pods -n apigee cassandra-client

Expansão de região configurada incorretamente: todos os nós do Cassandra em um data center

Essa situação ocorre em uma expansão multirregional nas plataformas GKE e GKE On-Prem (Anthos). Evite criar todos os nós do Cassandra no mesmo data center.

Sintoma

Os nós do Cassandra não são criados no data center da segunda região.

Mensagem de erro

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

Resolução

Siga estas etapas para corrigir a expansão de região configurada incorretamente:

Atualize o replicaCount do Cassandra para 1 no arquivo overrides.yaml do segundo data center. Por exemplo:
```
cassandra:
  . . .
  replicaCount: 1
```
Aplique a configuração com apigeectl apply:
```
$APIGEECTL_HOME/apigeectl apply -f 2ND_DATACENTER_OVERRIDES.yaml
```
Use kubectl exec para acessar o pod restante do Cassandra com o seguinte comando:
```
kubectl exec -it -n apigee apigee-cassandra-default-0 -- /bin/bash
```

Desative o pod restante do Cassandra com o seguinte comando:

nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD decommission

Exclua os pods do Cassandra do segundo data center usando apigeectl delete com o argumento --datastore. Exemplo:
```
$APIGEECTL_HOME/apigeectl delete -f 2ND_DATACENTER_OVERRIDES.yaml --datastore
```
Altere o contexto do Kubernetes para o cluster do seu primeiro data center:
```
kubectl config use-context FIRST_DATACENTER_CLUSTER
```
Verifique se não há nós do Cassandra com estado inativo no primeiro data center.
```
nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status
```

Verifique se os nós do Cassandra configurados incorretamente (destinados ao segundo data center) foram removidos do primeiro. Verifique se os endereços IP exibidos na saída de status do nodetool são apenas os endereços IP dos pods do Cassandra destinados ao primeiro data center. Por exemplo, na saída a seguir, o endereço IP 10.100.0.39 precisa ser de um pod no primeiro data center.

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

Verifique se o arquivo overrides.yaml para que o segundo data center contenha a configuração de nome na seção Cassandra. Por exemplo:
```
cassandra:
  datacenter: DATA_CENTER_2
  rack: "RACK_NAME" # "ra-1" is the default value.
  . . .
```
Atualize a configuração cassandra:replicaCount no arquivo overrides.yaml do segundo data center para o número desejado. Por exemplo:
```
cassandra:
  datacenter: DATA_CENTER_2
  . . .
  replicaCount: 3
```
Observação: o valor de cassandra:replicaCount precisa ser um múltiplo de 3. Use o mesmo valor de replicaCount especificado para seu primeiro data center.
Aplique o arquivo overrides.yaml ao segundo data center com o argumento --datastore. Exemplo:
```
$APIGEECTL_HOME/apigeectl apply -f 2ND_DATACENTER_OVERRIDES.yaml --datastore
```
Use kubectl exec para acessar um dos novos pods do Cassandra no segundo data center e verifique se há dois data centers:
```
 "nodetool -u CASSANDRA_DB_USER -pw CASSANDRA_DB_PASSWORD status"
```

Recursos adicionais

Consulte Introdução aos manuais da Apigee X e da Apigee híbrida