Effectuer une rotation du certificat CA racine

Cette page explique le certificat d'autorité de certification (CA) racine Apigee hybrid qui signe les certificats internes utilisés par les composants hybrides pour communiquer entre eux. Elle explique également comment le renouveler avant son expiration. À partir d'Apigee hybrid v1.17, vous pouvez faire pivoter vous-même cette CA racine.

À propos du certificat de l'autorité de certification racine

Chaque installation Apigee hybrid possède une seule autorité de certification racine, stockée sous la forme d'un Certificate cert-manager nommé apigee-ca dans l'espace de noms cert-manager. Il s'agit d'une autorité de certification autosignée (isCA: true, nom commun apigee-hybrid) qui sert de racine de confiance pour les certificats internes émis par le système hybride : le protocole TLS mutuel (mTLS) entre les composants et le protocole TLS unidirectionnel (côté serveur) qui sécurise les webhooks d'admission et la conversion des ressources personnalisées. Si cette autorité de certification expire, la communication interne entre les composants hybrides est interrompue.

Pourquoi le certificat de l'autorité de certification racine est-il remplacé ?

L'autorité de certification racine générée par le graphique hybride a une période de validité de 10 ans. Il doit être renouvelé avant son expiration afin que les certificats internes qu'il signe puissent continuer à être renouvelés et que la communication entre les composants ne soit jamais interrompue. La rotation est conçue pour ne pas entraîner de temps d'arrêt : pendant la transition, vos composants font confiance à l'ancienne et à la nouvelle autorité de certification racine. Les certificats signés par l'une ou l'autre restent donc valides jusqu'à ce que l'ancienne autorité de certification soit supprimée.

Fonctionnement de la rotation

Pour effectuer la rotation de l'autorité de certification racine, vous devez faire passer votre cluster par quatre phases, dans l'ordre. Vous ne passez à la phase suivante qu'une fois la phase actuelle terminée sur chaque composant. Chaque phase est pilotée par un seul champ de remplacement, certRotation.phase, appliqué avec un helm upgrade du graphique de l'opérateur Apigee (apigee-operator).

Phase (certRotation.phase) Qu'est-ce qui change ? Rollback possible
1. CREATE_NEW_CA Une nouvelle autorité de certification racine (apigee-ca-2) est créée et ajoutée au truststore de chaque composant hybride. Les composants contiennent toujours des certificats signés par l'ancienne autorité de certification. Rien n'a donc encore changé. Oui
2. CREATE_NEW_LEAF De nouveaux certificats feuille signés par la nouvelle autorité de certification racine sont émis. Les anciennes et nouvelles CA racine sont approuvées, ce qui permet au trafic de continuer à circuler sans interruption. Oui
3. HIDE_OLD_CA L'ancienne autorité de certification racine est supprimée de la configuration de confiance active. Seule la nouvelle autorité de certification racine reste utilisée. Le rollback est toujours disponible à cette étape. Oui
4. CLEANUP L'ancienne CA racine et ses émetteurs sont supprimés, et la nouvelle CA racine est promue en tant que CA racine du cluster. Cette phase est irréversible. Non

Avant de commencer

  • Installez les outils de ligne de commande kubectl et helm, et assurez-vous que votre contexte kubectl pointe vers le cluster que vous faites pivoter.
  • Assurez-vous que le cluster est opérationnel. Chaque helm upgrade valide que chaque ApigeeDeployment est à l'état running et que la phase que vous demandez est la phase actuelle, la phase suivante ou la phase de rollback. Si le cluster n'est pas sain ou si vous essayez d'ignorer une phase, la mise à niveau est refusée.
  • Si vous exécutez un déploiement multirégional, lisez cette section avant de commencer. Chaque région doit converger vers la même nouvelle autorité de certification racine.

Effectuer une rotation de l'autorité de certification racine

Pour chaque phase listée dans Fonctionnement de la rotation, procédez comme suit : appliquez la phase, puis vérifiez qu'elle est terminée avant de passer à la suivante. Dans un déploiement multirégional, effectuez-les dans chaque région.

Étape 1 : Définissez la phase et appliquez-la

Ajoutez ou mettez à jour le stanza certRotation dans votre fichier de remplacement, en définissant phase sur la phase que vous appliquez. Par exemple, pour démarrer la rotation :

certRotation:
  phase: CREATE_NEW_CA

Effectuez d'abord un test avec une simulation :

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

Appliquez ensuite la modification :

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

Étape 2 : Vérifiez que la phase est terminée

Le cluster enregistre la progression de la rotation dans le ConfigMap cert-info de l'espace de noms hybride. Lisez sa valeur currentPhase : 

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

Une phase n'est terminée que lorsque currentPhase est égal à la phase que vous venez d'appliquer. currentPhase n'avance qu'une fois que chaque composant a été réconcilié avec la phase demandée. N'avancez donc pas tant que la phase ne correspond pas.

Lorsque currentPhase correspond, lisez la phase suivante à appliquer à partir du même ConfigMap : 

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

Définissez certRotation.phase sur cette valeur, puis répétez les étapes 1 et 2. Continuez jusqu'à la fin de la phase CLEANUP.

Déploiements multirégionaux

Dans un déploiement multirégional, chaque cluster possède sa propre ConfigMap cert-info, son propre opérateur et ses propres magasins de confiance. De plus, toutes les régions doivent finir par faire confiance à la même nouvelle autorité de certification racine. Le graphique ne génère une nouvelle autorité de certification racine que lorsque le secret apigee-ca-2 n'existe pas déjà. Vous devez donc créer la nouvelle autorité de certification une seule fois dans une région principale et la copier dans les autres régions avant de la faire pivoter.

Effectuez la rotation dans l'ordre suivant. Confirmez currentPhase dans une région (voir Étape 2 : Confirmer que la phase est terminée) avant de passer à la phase suivante pour cette région.

  1. Exécutez CREATE_NEW_CA dans votre région principale. Le graphique crée la nouvelle CA racine et la stocke dans le secret apigee-ca-2.
  2. Copiez le secret apigee-ca-2 de l'espace de noms cert-manager de la région principale dans l'espace de noms cert-manager de chaque autre région, avant d'exécuter CREATE_NEW_CA dans ces régions. Il s'agit du même modèle de copie secrète que celui que vous utilisez lorsque vous vous étendez à une nouvelle région. Pour en savoir plus, consultez Déploiements multirégionaux.
  3. Exécutez CREATE_NEW_CA dans chacune des autres régions, une région à la fois. Comme le secret apigee-ca-2 est déjà présent, le graphique ne crée pas d'autorité de certification et associe la région à celle partagée.
  4. Exécutez CREATE_NEW_LEAF dans chaque région.
  5. Exécutez HIDE_OLD_CA dans chaque région.
  6. Exécutez CLEANUP dans chaque région.
  7. Supprimez la strophe certRotation du fichier de remplacement de chaque région pour nettoyer votre configuration.

Grâce à CREATE_NEW_CA, CREATE_NEW_LEAF et HIDE_OLD_CA, chaque région fait confiance à l'ancienne et à la nouvelle autorité de certification racine. Les régions peuvent donc se trouver à différentes phases pendant cette période sans interrompre le trafic entre elles.

Utiliser votre propre autorité de certification

Si vous souhaitez utiliser votre propre autorité de certification racine au lieu de celle générée par le graphique, précréez le nouveau secret de l'autorité de certification avant de commencer la rotation. Étant donné que le graphique ne génère une autorité de certification que lorsque le secret cible est absent, un secret existant est utilisé tel quel.

Les noms des autorités de certification racines ne sont pas au format libre. hybrid s'attend à ce que chaque génération de l'autorité de certification porte un nom fixe (apigee-ca, puis apigee-ca-2, apigee-ca-3, etc.). Le graphique recherche la prochaine autorité de certification portant exactement ce nom. Lorsque vous apportez votre propre autorité de certification, vous devez créer le secret sous le nom exact suivant (apigee-ca-2 pour la première rotation). Le graphique ne détecte pas les autorités de certification créées sous un autre nom. Pour trouver le nom du secret actuel et le prochain nom à utiliser, listez les certificats de l'autorité de certification et les secrets qui les soutiennent : 

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

Consultez Suivre l'expiration de l'autorité de certification racine pour découvrir d'autres façons de vérifier la génération de votre cluster.

  1. Avant d'exécuter CREATE_NEW_CA, créez un Secret avec le nom de l'autorité de certification suivante (apigee-ca-2 pour la première rotation) dans l'espace de noms cert-manager, en conservant votre certificat CA et votre clé privée. Le secret doit être de type kubernetes.io/tls et contenir trois clés : tls.crt, tls.key et ca.crt. Étant donné que kubectl create secret tls ne peut pas définir la clé ca.crt, utilisez le formulaire générique : 
    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. Effectuez la rotation comme décrit dans la section Effectuer la rotation de l'autorité de certification racine. Pendant CREATE_NEW_CA, le graphique détecte votre secret apigee-ca-2, ignore la génération d'une autorité de certification et lie le nouvel émetteur (apigee-ca-issuer-2) à votre autorité de certification. Toutes les autres phases restent inchangées.

Lorsque vous apportez votre propre autorité de certification, sa durée de vie est celle de votre certificat, et non la durée par défaut de 10 ans du graphique.

Effectuer un rollback d'une rotation

Chaque phase avant CLEANUP peut faire l'objet d'un rollback. Pour effectuer un rollback, définissez certRotation.phase sur la valeur que le cluster indique comme cible de rollback et appliquez-la avec helm upgrade, exactement comme vous appliquez une phase de mise à jour.

Lisez la cible de restauration à partir du fichier ConfigMap cert-info :

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

Voici les cibles de transfert et de rétablissement pour chaque phase :

Phase actuelle Phase suivante Phase de rollback
PHASE_UNSPECIFIED (pas encore commencé) 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 — (rotation terminée) — (aucune ; irréversible)

Suivre l'expiration de l'autorité de certification racine

Étant donné que la rotation Apigee hybrid est gérée par le client, vous êtes responsable de la rotation de l'autorité de certification racine avant son expiration. Suivez l'expiration du certificat apigee-ca et planifiez la rotation avant cette date afin d'avoir le temps de terminer les quatre phases dans chaque région.

Pour vérifier la date d'expiration de l'autorité de certification racine, listez les certificats CA dans l'espace de noms cert-manager, puis lisez la date d'expiration de la génération que vous utilisez actuellement : 

kubectl get certificate -n cert-manager

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

La première commande liste chaque génération de l'autorité de certification racine (apigee-ca, apigee-ca-2, etc.). La deuxième commande affiche la date d'expiration du certificat nommé. Exécutez-la sur la génération actuellement utilisée.

L'identification automatique des problèmes d'Apigee hybrid signale les problèmes de cluster qu'elle détecte en tant que ressources ApigeeIssue, que vous pouvez lister avec kubectl get apigeeissues. Vérifiez si des problèmes ont été détectés dans le cadre de votre surveillance régulière.

Étapes suivantes