Usar um armazenamento de dados externo do Cassandra

Neste tópico, explicamos como conectar um ambiente de execução da Apigee híbrida a um repositório de dados do Cassandra em um cluster diferente do Kubernetes. Nessa configuração, o cluster de ambiente de execução não tem pods do Cassandra. O nome dessa configuração é o modo armazenamento de dados externo.

Topologia de dois clusters

O modo de repositório de dados externo usa dois clusters do Kubernetes:

  • O cluster do Cassandra executa o anel do Cassandra. Ele não executa os componentes do ambiente de execução híbrido.
  • O cluster de ambiente de execução executa os componentes de ambiente de execução híbrido, mas não tem pods do Cassandra. Os componentes de ambiente de execução se conectam ao anel do Cassandra no cluster do Cassandra pela rede.

O operador da Apigee é executado nos dois clusters. Você instala o cert-manager, as definições de recursos personalizados (CRDs) da Apigee e o gráfico apigee-operator em cada cluster. A tabela a seguir mostra os componentes em cada cluster:

Componente Cluster do Cassandra Cluster de ambiente de execução
cert-manager. Sim Sim
CRDs da Apigee e o gráfico apigee-operator Sim Sim
gráfico apigee-datastore Sim, com os pods do Cassandra Sim, com replicaCount: 0 e sem pods do Cassandra
Todos os outros gráficos híbridos, como apigee-telemetry, apigee-redis, apigee-ingress-manager, apigee-org, apigee-env e apigee-virtualhost Não Sim

O operador do Apigee faz um trabalho diferente em cada cluster:

  • No cluster do Cassandra, o operador cria os pods do Cassandra. Ele também gerencia o ciclo de vida do Cassandra, por exemplo, quando você dimensiona o anel.
  • No cluster de ambiente de execução, o operador não cria pods do Cassandra. Ele cria um serviço headless e um objeto Endpoints que apontam para o anel do Cassandra no cluster do Cassandra. Se você ativar a sincronização dinâmica de endpoints, o operador no cluster de ambiente de execução também vai ler os endpoints do Cassandra no cluster do Cassandra.

Visão geral da configuração

Siga estas etapas na sequência abaixo. A sequência é importante. A autoridade de certificação (CA) compartilhada precisa estar no cluster de ambiente de execução antes que ele emita certificados. Para mais informações, consulte Compartilhar a AC da Apigee antes de instalar o operador.

  1. No cluster do Cassandra, instale o cert-manager, os CRDs da Apigee, o gráfico apigee-operator e o gráfico apigee-datastore.
  2. Verifique se os pods do Cassandra no cluster do Cassandra estão prontos.
  3. No cluster de execução, instale o cert-manager.
  4. Copie o secret apigee-ca do cluster do Cassandra para o cluster de ambiente de execução. Faça esta etapa antes de instalar o gráfico apigee-operator no cluster de ambiente de execução.
  5. No cluster de ambiente de execução, instale os componentes do ambiente de execução híbrido. Use as substituições de repositório de dados externos para o gráfico apigee-datastore. Use as mesmas credenciais do Cassandra que no cluster do Cassandra.
  6. (Recomendado) Ative a sincronização dinâmica de endpoints.
  7. Verifique a conexão.

Para conferir as etapas de instalação de cada gráfico, consulte Instalar a Apigee híbrida usando o Helm.

Antes de começar

Verifique se o ambiente atende aos seguintes requisitos:

  • Conexão de rede com o Cassandra. O cluster de ambiente de execução precisa se conectar aos pods do Cassandra na porta TCP 9042. Coloque os dois clusters em uma VPC compartilhada ou em redes com uma conexão privada entre eles.
  • Uma região. Coloque os dois clusters na mesma região. O tempo de retorno entre os clusters aumenta a latência de cada solicitação de tempo de execução.
  • cert-manager em ambos os clusters. Em cada cluster, o cert-manager emite os certificados para a conexão mTLS entre o ambiente de execução e o Cassandra. Instale o cert-manager no cluster do Cassandra e no cluster de ambiente de execução.
  • Uma rota para cada pod do Cassandra. O driver do cliente Cassandra se conecta diretamente a cada pod do Cassandra. O cluster de execução precisa se conectar ao endereço IP de cada pod do Cassandra, não apenas a um endereço. Um balanceador de carga ou um único endereço IP virtual na frente do anel não atende a esse requisito.
  • Conexão de rede com o servidor da API Kubernetes. Essa exigência só se aplica se você usar a sincronização dinâmica de endpoints. O cluster de ambiente de execução precisa se conectar ao servidor da API Kubernetes do cluster do Cassandra.

Compartilhe a CA da Apigee antes de instalar o operador

Instale o cert-manager no cluster de ambiente de execução. Em seguida, copie o secret da CA do cluster do Cassandra para o cluster de ambiente de execução:

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 -

Substitua:

  • CASSANDRA_CLUSTER: o contexto do kubectl do cluster do Cassandra.
  • RUNTIME_CLUSTER: o contexto do kubectl do cluster de execução.

O comando grep remove os campos de metadados que pertencem ao cluster do Cassandra. O servidor da API Kubernetes não cria um objeto com um valor resourceVersion.

As instalações multirregionais usam o mesmo princípio de CA compartilhada. Para uma etapa de cópia semelhante, consulte Alternar o certificado de CA raiz. Para a configuração do mTLS do Cassandra, consulte Configurar a autenticação do Cassandra.

Use as mesmas credenciais do Cassandra nos dois clusters

Use um destes métodos nos arquivos de substituição dos dois clusters:

  • Defina os mesmos nomes de usuário e senhas em cassandra.auth: default, admin, ddl, dml, jmx e jolokia.
  • Defina cassandra.auth.secret. Em cada cluster, o secret precisa conter os mesmos usuários e senhas. Consulte Criar o Secret.
  • Defina cassandra.auth.secretProviderClass como uma SecretProviderClass que lê o mesmo repositório de secrets. Consulte Como armazenar secrets do Cassandra no Hashicorp Vault.

Não copie o secret de credenciais do cluster do Cassandra. O gráfico no cluster de runtime cria o secret com base nas suas substituições. Para encontrar uma falha de autenticação, consulte Verificar a conexão.

Configurar o armazenamento de dados externo

No cluster de ambiente de execução, o gráfico apigee-datastore não pode criar pods do Cassandra. Ele precisa apontar para o anel do Cassandra no cluster do Cassandra. Adicione estas configurações cassandra ao arquivo de substituições do cluster de ambiente de execução:

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"

Em que:

  • CASSANDRA_IP_ADDRESSES é uma lista separada por vírgulas dos endereços IP dos pods do Cassandra no cluster do Cassandra. Por exemplo, 10.0.0.1:9042,10.0.0.2:9042,10.0.0.3:9042. O sufixo :9042 é opcional. Para receber a lista, execute este comando:
    kubectl --context CASSANDRA_CLUSTER -n APIGEE_NAMESPACE get pods -l app=apigee-cassandra \
      -o jsonpath='{.items[*].status.podIP}' | tr ' ' ','
  • APIGEE_NAMESPACE é seu namespace da Apigee. O padrão é apigee.
  • replicaCount: 0 informa ao operador para não criar pods do Cassandra no cluster de runtime. O operador cria um serviço sem comando e um objeto Endpoints que apontam para os endereços externalHost.
  • cassandra.properties.externalHost é uma lista separada por vírgulas de endereços IP do Cassandra. Cada endereço pode ter um sufixo :port, mas o operador ignora a porta e sempre usa a 9042. O operador aceita apenas endereços IP. Ele ignora nomes de host e de DNS e grava um aviso no registro para cada entrada ignorada.
  • cassandra.storage.storageSize é obrigatório, mas o cluster de ambiente de execução não cria PersistentVolumes para o Cassandra. O webhook de validação ApigeeDatastore sempre verifica storageSize. Use uma quantidade válida, por exemplo, 10Gi.

O endereço IP de um pod muda quando você dimensiona o anel e quando o Kubernetes reprograma um pod. Então, a lista em externalHost fica incorreta. Por isso, recomendamos a sincronização dinâmica de endpoints. A sincronização dinâmica de endpoints mantém a lista de endereços IP de pods do Cassandra atualizada automaticamente. Use externalHost sozinho apenas para uma instalação simples ou para a primeira configuração.

Mantenha os endpoints atualizados com a sincronização dinâmica de endpoints

Com apenas externalHost, você precisa editar as substituições sempre que o anel do Cassandra mudar. A sincronização dinâmica de endpoints elimina essa etapa manual. O operador no cluster de ambiente de execução lê os endpoints prontos do Cassandra no cluster do Cassandra em um intervalo regular. Em seguida, ele copia esses endpoints para o objeto "Endpoints" no cluster de execução.

Recomendamos a sincronização dinâmica de endpoints. Os endereços IP do pod mudam sempre que você dimensiona o anel ou o Kubernetes reagenda um pod. A sincronização dinâmica de endpoints lê os endereços IP dos pods prontos do serviço sem comando do Cassandra. Assim, o objeto Endpoints no cluster de ambiente de execução sempre contém os endereços IP atuais do pod do Cassandra.

Com a sincronização dinâmica de endpoints, o externalHost ainda é necessário. O operador usa isso nestas duas condições:

  • Antes da primeira leitura bem-sucedida do cluster do Cassandra.
  • Quando uma leitura do cluster do Cassandra falha e não há endpoints de uma leitura bem-sucedida anterior.

Se uma leitura falhar e houver endpoints de uma leitura anterior bem-sucedida, o operador vai manter esses endpoints. O ambiente de execução mantém a conexão com o Cassandra.

Para ativar a sincronização dinâmica de endpoints, adicione o bloco externalEndpointsSync ao arquivo de substituições do cluster de execução:

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"

Criar uma conta de serviço somente leitura no cluster do Cassandra

O operador no cluster de execução usa um kubeconfig para se conectar ao cluster do Cassandra. Esse kubeconfig precisa usar uma conta de serviço somente leitura com privilégio mínimo. Essa ServiceAccount só pode ler os endpoints do Cassandra. Ele não pode mudar recursos no cluster do Cassandra.

No cluster do Cassandra, crie estes recursos:

  • Uma ServiceAccount, por exemplo, apigee-endpoint-reader.
  • Um papel e uma vinculação de papel no namespace do Cassandra. A função concede apenas os verbos get, list e watch no endpoints principal. Não use outros verbos, como create, update, patch ou delete. Não conceder acesso a outros recursos.
  • Um Secret de token de longa duração para a ServiceAccount.

Em seguida, crie um arquivo kubeconfig para o servidor da API Kubernetes do cluster do Cassandra. Esse kubeconfig precisa usar o token da ServiceAccount. No cluster de execução, crie um secret com o nome definido em externalEndpointsSync.secretRef. Coloque o kubeconfig na chave kubeconfig:

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

Substitua READER_KUBECONFIG_FILE pelo caminho para o arquivo kubeconfig da ServiceAccount somente leitura.

O kubeconfig contém um token de longa duração. Mantenha esse secret tão seguro quanto suas outras credenciais.

Monitorar a sincronização dinâmica de endpoints

Se uma leitura do cluster do Cassandra falhar, o ambiente de execução vai manter a conexão. Mas os endpoints no cluster de execução não mudam até que uma leitura seja bem-sucedida novamente. Monitore a sincronização para encontrar uma falha persistente antes que o anel do Cassandra mude.

O operador no cluster de execução envia estes indicadores:

  • A condição EndpointSyncDegraded no status do recurso ApigeeDatastore. A condição se torna True após três leituras consecutivas com falha. O motivo é RemoteReadFailed ou NoReadyRemoteEndpoints. Depois de uma leitura bem-sucedida, a condição se torna False com o motivo SyncSucceeded.
  • A métrica external_endpoint_sync_last_success_timestamp. Essa métrica é o horário da última leitura bem-sucedida, em segundos do Unix.
  • A métrica external_endpoint_sync_failures_total. Essa métrica conta as leituras com falha.

As duas métricas têm os rótulos namespace e name do recurso ApigeeDatastore. O operador os mostra no endpoint de métricas.

Para conferir a condição, execute este comando:

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

Recomendamos um alerta na condição EndpointSyncDegraded. O status ApigeeDatastore mantém a condição quando o operador é reiniciado. Somente uma leitura bem-sucedida define a condição como False.

Se você também usar um alerta na métrica, envie um alerta quando uma destas duas expressões for verdadeira:

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

O operador define a métrica somente após uma leitura bem-sucedida. Se o operador for reiniciado enquanto as leituras falham, a métrica não vai aparecer. Então, a primeira expressão não vai corresponder, e apenas a segunda vai enviar o alerta.

Verifique a conexão

Depois de instalar os componentes de ambiente de execução, faça estas verificações no cluster de ambiente de execução:

  1. Verifique se o cluster de ambiente de execução não tem pods do Cassandra:

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

    A resposta é No resources found.

  2. Verifique se o objeto Endpoints aponta para o anel do Cassandra:

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

    A coluna ENDPOINTS mostra os endereços IP do Cassandra. Se você usa a sincronização dinâmica de endpoints, esses são os endereços IP dos pods do Cassandra prontos no cluster do Cassandra.

  3. Verifique se os jobs de configuração do Cassandra foram concluídos:

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

    A coluna COMPLETIONS mostra 1/1 para cada job. Se um job não for concluído, examine o registro dele para encontrar erros de autenticação. Em seguida, verifique se os dois clusters usam as mesmas credenciais do Cassandra.

Escalonar o anel do Cassandra

O operador da Apigee no cluster do Cassandra é proprietário do ciclo de vida do Cassandra. Escalone o Cassandra no cluster do Cassandra. Não é possível escalonar o Cassandra no cluster de ambiente de execução.

Obedeça às mesmas regras de um anel do Cassandra no cluster de ambiente de execução:

  • Escalone o Cassandra em múltiplos de três. Isso mantém o anel balanceado em três zonas de disponibilidade.
  • Antes de aumentar o número de pods, verifique se o cluster do Cassandra tem capacidade de nó suficiente.
  • Se você não usar a sincronização dinâmica de endpoints, atualize externalHost após cada operação de escalonamento.

Para mais informações, consulte Como escalonar o Cassandra.

A seguir