Rotacionar o certificado de CA raiz

Esta página explica o certificado da autoridade certificadora raiz híbrida do Apigee, que assina os certificados internos usados pelos componentes híbridos para se comunicar entre si, e descreve como alterná-lo antes que ele expire. A partir da Apigee híbrida v1.17, é possível fazer a rotação dessa CA raiz por conta própria.

Sobre o certificado de CA raiz

Cada instalação híbrida do Apigee tem uma única CA raiz, armazenada como um Certificate do cert-manager chamado apigee-ca no namespace cert-manager. É uma CA autoassinada (isCA: true, nome comum apigee-hybrid) que atua como a raiz de confiança para os certificados internos emitidos pela híbrida — o TLS mútuo (mTLS) entre componentes e o TLS unidirecional (do lado do servidor) que protege webhooks de admissão e conversão de recursos personalizados. Se essa CA expirar, a comunicação interna entre os componentes híbridos será interrompida.

Por que o certificado de CA raiz é alternado

A CA raiz gerada pelo gráfico híbrido tem um período de validade de 10 anos. Ele precisa ser alternado antes de expirar para que os certificados internos que ele assina possam continuar sendo renovados e a comunicação entre componentes nunca seja interrompida. A rotação foi projetada para não ter tempo de inatividade: durante a transição, seus componentes confiam na CA raiz antiga e na nova. Portanto, os certificados assinados por qualquer uma delas permanecem válidos até que a CA antiga seja removida.

Como a rotação funciona

Você gira a CA raiz avançando o cluster por quatro fases, em ordem. Você só passa para a próxima fase depois que a atual é concluída em todos os componentes. Cada fase é impulsionada por um único campo de substituições, certRotation.phase, aplicado com um helm upgrade do gráfico do operador da Apigee (apigee-operator).

Fase (certRotation.phase) O que acontece Reversão possível
1. CREATE_NEW_CA Uma nova AC raiz (apigee-ca-2) é criada e adicionada ao truststore de cada componente híbrido. Os componentes ainda apresentam certificados assinados pela CA antiga, então nada mudou ainda. Sim
2. CREATE_NEW_LEAF Novos certificados folha assinados pela nova CA raiz são emitidos. Como as CA raiz antiga e nova são confiáveis, o tráfego continua sem interrupções. Sim
3. HIDE_OLD_CA A CA raiz antiga é removida da configuração de confiança ativa. Apenas a nova CA raiz continua em uso. A reversão ainda está disponível nesta fase. Sim
4. CLEANUP A CA raiz antiga e os emissores dela são removidos, e a nova CA raiz é promovida a CA raiz do cluster. Essa fase é irreversível. Não

Antes de começar

  • Instale as ferramentas de linha de comando kubectl e helm e verifique se o contexto kubectl aponta para o cluster que você está girando.
  • Verifique se o cluster está íntegro. Cada helm upgrade valida se todos os ApigeeDeployment estão no estado running e se a fase solicitada é a atual, a próxima ou a de reversão. Se o cluster não estiver íntegro ou se você tentar pular uma fase, o upgrade será rejeitado.
  • Se você executar uma implantação multirregional, leia essa seção antes de começar. Todas as regiões precisam convergir para a mesma nova CA raiz.

Rotacionar a CA raiz

Siga as etapas em Como a rotação funciona para cada fase, na ordem: aplique a fase e confirme se ela foi concluída antes de passar para a próxima. Em uma implantação multirregional, faça isso em cada região.

Etapa 1: definir e aplicar a fase

Adicione ou atualize a estrofe certRotation no arquivo de substituições, definindo phase como a fase que você está aplicando. Por exemplo, para iniciar a rotação:

certRotation:
  phase: CREATE_NEW_CA

Teste a mudança com uma simulação:

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml \
  --dry-run=server

Em seguida, aplique a mudança:

helm upgrade operator apigee-operator/ \
  --install \
  --namespace APIGEE_NAMESPACE \
  --atomic \
  -f OVERRIDES_FILE.yaml

Etapa 2: confirmar se a fase foi concluída

O cluster registra o progresso da rotação no ConfigMap cert-info no namespace híbrido. Leia o valor de currentPhase: 

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.currentPhase}'

Uma fase só é concluída quando currentPhase é igual à fase que você acabou de aplicar. currentPhase só avança depois que todos os componentes são reconciliados com a fase solicitada. Portanto, não prossiga até que haja correspondência.

Quando currentPhase corresponder, leia a próxima fase a ser aplicada do mesmo ConfigMap: 

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForNextPhase}'

Defina certRotation.phase como esse valor e repita as etapas 1 e 2. Continue até concluir a fase CLEANUP.

Implantações multirregionais

Em uma implantação multirregional, cada cluster tem seu próprio ConfigMap cert-info, operador e keystores de confiança. Todas as regiões precisam confiar na mesma nova CA raiz. O gráfico gera uma nova AC raiz somente quando o Secret apigee-ca-2 ainda não existe. Portanto, crie a nova AC uma vez em uma região principal e copie para as outras regiões antes de fazer a rotação.

Faça a rotação na seguinte ordem. Confirme currentPhase em uma região (consulte Etapa 2: confirmar se a fase foi concluída) antes de mover essa região para a próxima fase.

  1. Execute CREATE_NEW_CA na sua região principal. O gráfico cria a nova CA raiz e a armazena no secreto apigee-ca-2.
  2. Copie o secret apigee-ca-2 do namespace cert-manager da região principal para o namespace cert-manager de todas as outras regiões antes de executar CREATE_NEW_CA nessas regiões. Esse é o mesmo padrão de cópia secreta usado quando você expande para uma nova região. Consulte Implantações multirregionais.
  3. Execute CREATE_NEW_CA em cada uma das outras regiões, uma por vez. Como o secret apigee-ca-2 já está presente, o gráfico pula a criação de uma nova CA e vincula a região à compartilhada.
  4. Execute CREATE_NEW_LEAF em cada região.
  5. Execute HIDE_OLD_CA em cada região.
  6. Execute CLEANUP em cada região.
  7. Remova a seção certRotation do arquivo de substituições de cada região para organizar sua configuração.

Com CREATE_NEW_CA, CREATE_NEW_LEAF e HIDE_OLD_CA, todas as regiões confiam na AC raiz antiga e na nova. Assim, elas podem estar em fases diferentes durante esse período sem interromper o tráfego entre elas.

Traga sua própria CA

Se você quiser usar sua própria CA raiz em vez de uma gerada pelo gráfico, crie o novo secret da CA antes de iniciar a rotação. Como o gráfico gera uma CA somente quando o secret de destino está ausente, um secret existente é usado como está.

Os nomes das CAs raiz não são de formato livre. O hybrid espera que cada geração da CA tenha um nome fixo: apigee-ca, apigee-ca-2, apigee-ca-3 e assim por diante. O gráfico procura a próxima CA exatamente com esse nome. Ao trazer sua própria CA, crie o secret com o nome exato a seguir (apigee-ca-2 para a primeira rotação). O gráfico não detecta uma CA criada com qualquer outro nome. Para encontrar o nome do secret atual e o próximo nome a ser usado, liste os certificados da CA e os secrets que os apoiam: 

kubectl get certificate -n cert-manager \
  -o custom-columns=CERTIFICATE:.metadata.name,SECRET:.spec.secretName

Consulte Acompanhar a expiração da CA raiz para saber mais maneiras de inspecionar em qual geração seu cluster está.

  1. Antes de executar CREATE_NEW_CA, crie um secret com o próximo nome da CA (apigee-ca-2 para a primeira rotação) no namespace cert-manager, que contém seu certificado de CA e chave privada. O segredo precisa ser do tipo kubernetes.io/tls e conter três chaves: tls.crt, tls.key e ca.crt. Como kubectl create secret tls não pode definir a chave ca.crt, use o formato genérico: 
    kubectl create secret generic apigee-ca-2 \
  --namespace cert-manager \
  --type=kubernetes.io/tls \
  --from-file=tls.crt=CERT_FILE \
  --from-file=tls.key=KEY_FILE \
  --from-file=ca.crt=CA_FILE
  2. Execute a rotação conforme descrito em Alternar a AC raiz. Durante CREATE_NEW_CA, o gráfico detecta seu segredo apigee-ca-2 , pula a geração de uma CA e vincula o novo emissor (apigee-ca-issuer-2) à sua CA. Todas as outras fases permanecem inalteradas.

Quando você traz sua própria CA, a validade dela é a mesma do certificado, não o padrão de 10 anos do gráfico.

Reverter uma rotação

Todas as fases antes de CLEANUP podem ser revertidas. Para reverter, defina certRotation.phase como o valor que o cluster informa como o destino de rollback e aplique-o com helm upgrade, exatamente como você aplica uma fase de avanço.

Leia o destino do rollback no ConfigMap cert-info:

kubectl get configmap cert-info -n APIGEE_NAMESPACE \
  -o jsonpath='{.data.readyForRollbackPhase}'

Os destinos de encaminhamento e rollback para cada fase são:

Fase atual Próxima fase Fase de reversão
PHASE_UNSPECIFIED (não iniciado) CREATE_NEW_CA PHASE_UNSPECIFIED
CREATE_NEW_CA CREATE_NEW_LEAF PHASE_UNSPECIFIED
CREATE_NEW_LEAF HIDE_OLD_CA CREATE_NEW_CA
HIDE_OLD_CA CLEANUP CREATE_NEW_LEAF
CLEANUP — (rotação concluída) — (nenhum; irreversível)

Rastrear a expiração da CA raiz

Como a rotação da Apigee híbrida é controlada pelo cliente, você é responsável por fazer a rotação da AC raiz antes que ela expire. Acompanhe o vencimento do certificado apigee-ca e planeje a rotação antes dessa data para ter tempo de concluir todas as quatro fases em todas as regiões.

Para verificar quando a AC raiz expira, liste os certificados da AC no namespace cert-manager e leia a data de validade da geração que você está usando no momento: 

kubectl get certificate -n cert-manager

kubectl get certificate apigee-ca -n cert-manager \
  -o jsonpath='{.status.notAfter}'

O primeiro comando lista cada geração da CA raiz (apigee-ca, apigee-ca-2 e assim por diante). O segundo imprime a data de validade do certificado nomeado. Execute-o na geração em uso no momento.

A Apigee híbrida Descoberta automatizada de problemas informa os problemas do cluster detectados como recursos ApigeeIssue, que podem ser listados com kubectl get apigeeissues. Verifique se há problemas como parte do seu monitoramento regular.

A seguir