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.
-
No cluster do Cassandra, instale o cert-manager, os CRDs da Apigee, o gráfico
apigee-operatore o gráficoapigee-datastore. - Verifique se os pods do Cassandra no cluster do Cassandra estão prontos.
- No cluster de execução, instale o cert-manager.
-
Copie o secret
apigee-cado cluster do Cassandra para o cluster de ambiente de execução. Faça esta etapa antes de instalar o gráficoapigee-operatorno cluster de ambiente de execução. -
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. - (Recomendado) Ative a sincronização dinâmica de endpoints.
- 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,jmxejolokia. -
Defina
cassandra.auth.secret. Em cada cluster, o secret precisa conter os mesmos usuários e senhas. Consulte Criar o Secret. -
Defina
cassandra.auth.secretProviderClasscomo 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: 0informa 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çosexternalHost. -
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çãoApigeeDatastoresempre verificastorageSize. 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,listewatchnoendpointsprincipal. Não use outros verbos, comocreate,update,patchoudelete. 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
EndpointSyncDegradedno status do recursoApigeeDatastore. A condição se tornaTrueapós três leituras consecutivas com falha. O motivo éRemoteReadFailedouNoReadyRemoteEndpoints. Depois de uma leitura bem-sucedida, a condição se tornaFalsecom o motivoSyncSucceeded. -
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:
-
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. -
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
ENDPOINTSmostra 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. -
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
COMPLETIONSmostra1/1para 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
externalHostapós cada operação de escalonamento.
Para mais informações, consulte Como escalonar o Cassandra.
A seguir
- Para instalar os gráficos em cada cluster, consulte Instalar a Apigee híbrida usando o Helm.
- Para mTLS e credenciais do Cassandra, consulte Configurar a autenticação do Cassandra.
- Para adicionar capacidade ao anel do Cassandra, consulte Como escalonar o Cassandra.