Stamm-CA-Zertifikat rotieren

Auf dieser Seite wird das Apigee Hybrid-Zertifizierungsstellenzertifikat (CA) beschrieben, mit dem die internen Zertifikate signiert werden, die von Hybrid-Komponenten für die Kommunikation miteinander verwendet werden. Außerdem wird beschrieben, wie Sie es rotieren, bevor es abläuft. Ab Apigee Hybrid v1.17 können Sie diese Stamm-CA selbst rotieren.

Root-CA-Zertifikat

Jede Apigee Hybrid-Installation hat eine einzelne Stamm-CA, die als cert-manager-Certificate mit dem Namen apigee-ca im Namespace cert-manager gespeichert ist. Es handelt sich um eine selbstsignierte CA (isCA: true, allgemeiner Name apigee-hybrid), die als Vertrauensstamm für die internen Zertifikate dient, die vom Hybrid ausgestellt werden – sowohl für die gegenseitige TLS (mTLS) zwischen Komponenten als auch für die unidirektionale (serverseitige) TLS, die Zulassungs-Webhooks und die Konvertierung benutzerdefinierter Ressourcen schützt. Wenn diese CA abläuft, wird die interne Kommunikation zwischen Hybridkomponenten unterbrochen.

Warum das Root-CA-Zertifikat rotiert wird

Die Stamm-CA, die vom Hybrid-Diagramm generiert wird, hat eine Gültigkeitsdauer von 10 Jahren. Es muss rotiert werden, bevor es abläuft, damit die internen Zertifikate, die es signiert, weiterhin verlängert werden können und die Kommunikation zwischen den Komponenten nie unterbrochen wird. Die Rotation ist so konzipiert, dass keine Ausfallzeiten entstehen: Während der Umstellung vertrauen Ihre Komponenten sowohl der alten als auch der neuen Root-Zertifizierungsstelle. Zertifikate, die von einer der beiden signiert wurden, bleiben also gültig, bis die alte Zertifizierungsstelle entfernt wird.

So funktioniert die Rotation

Sie rotieren die Stamm-CA, indem Sie Ihren Cluster in der richtigen Reihenfolge durch vier Phasen führen. Sie gehen erst zur nächsten Phase über, wenn die aktuelle Phase für jede Komponente abgeschlossen ist. Jede Phase wird durch ein einzelnes Überschreibungsfeld (certRotation.phase) gesteuert, das mit einem helm upgrade des Apigee-Operator-Diagramms (apigee-operator) angewendet wird.

Phase (certRotation.phase) Was passiert dann? Rollback möglich
1. CREATE_NEW_CA Eine neue Root-Zertifizierungsstelle (apigee-ca-2) wird erstellt und dem Truststore jeder Hybrid-Komponente hinzugefügt. Komponenten sind weiterhin vorhanden. Zertifikate, die von der alten CA signiert wurden, daher wurde noch nichts umgestellt. Ja
2. CREATE_NEW_LEAF Es werden neue untergeordnete Zertifikate ausgestellt, die von der neuen Stammzertifizierungsstelle signiert sind. Sowohl die alte als auch die neue Root-Zertifizierungsstelle sind vertrauenswürdig, sodass der Traffic ohne Unterbrechung weitergeleitet wird. Ja
3. HIDE_OLD_CA Die alte Stamm-CA wird aus der aktiven Vertrauenskonfiguration entfernt. Nur die neue Stamm-CA wird weiterhin verwendet. In dieser Phase ist ein Rollback noch möglich. Ja
4. CLEANUP Die alte Stammzertifizierungsstelle und ihre Aussteller werden entfernt und die neue Stammzertifizierungsstelle wird zur Stammzertifizierungsstelle des Clusters hochgestuft. Diese Phase kann nicht rückgängig gemacht werden. Nein

Hinweis

  • Installieren Sie die Befehlszeilentools kubectl und helm und achten Sie darauf, dass Ihr kubectl-Kontext auf den Cluster verweist, den Sie rotieren.
  • Prüfen Sie, ob der Cluster fehlerfrei ist. Jede helm upgrade prüft, ob sich jede ApigeeDeployment im Status running befindet und ob die angeforderte Phase die aktuelle Phase, die nächste Phase oder die Rollback-Phase ist. Wenn der Cluster fehlerhaft ist oder Sie versuchen, eine Phase zu überspringen, wird das Upgrade abgelehnt.
  • Wenn Sie eine multiregionale Bereitstellung ausführen, lesen Sie diesen Abschnitt, bevor Sie beginnen. Jede Region muss auf dieselbe neue Root-Zertifizierungsstelle ausgerichtet sein.

Stamm-CA rotieren

Führen Sie die folgenden Schritte für jede Phase aus, die unter So funktioniert die Rotation aufgeführt ist. Wenden Sie die Phase an und bestätigen Sie dann, dass sie abgeschlossen ist, bevor Sie mit der nächsten fortfahren. Führen Sie sie in einer multiregionalen Bereitstellung in jeder Region aus.

Schritt 1: Phase festlegen und anwenden

Fügen Sie die certRotation-Stanza in Ihrer Überschreibungsdatei hinzu oder aktualisieren Sie sie und legen Sie phase auf die Phase fest, die Sie anwenden. So starten Sie beispielsweise die Rotation:

certRotation:
  phase: CREATE_NEW_CA

Testen Sie die Änderung zuerst mit einem Probelauf:

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

Wenden Sie die Änderung an:

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

Schritt 2: Bestätigen, dass die Phase abgeschlossen ist

Der Cluster zeichnet den Rotationsfortschritt in der cert-info-ConfigMap im Hybrid-Namespace auf. Lesen Sie den Wert currentPhase: 

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

Eine Phase ist erst abgeschlossen, wenn currentPhase der Phase entspricht, die Sie gerade angewendet haben. currentPhase wird erst aktualisiert, wenn alle Komponenten mit der angeforderten Phase übereinstimmen. Warten Sie also, bis dies der Fall ist.

Wenn currentPhase übereinstimmt, lesen Sie die nächste Phase, die aus derselben ConfigMap angewendet werden soll: 

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

Legen Sie certRotation.phase auf diesen Wert fest und wiederholen Sie Schritt 1 und Schritt 2. Fahren Sie fort, bis Sie die Phase CLEANUP abgeschlossen haben.

Multiregionale Bereitstellungen

Bei einer Bereitstellung in mehreren Regionen hat jeder Cluster seine eigene cert-info-ConfigMap, seinen eigenen Operator und seine eigenen Truststores. Alle Regionen müssen der gleichen neuen Stammzertifizierungsstelle vertrauen. Das Diagramm generiert nur dann eine neue Root-CA, wenn das apigee-ca-2-Secret noch nicht vorhanden ist. Sie erstellen die neue CA also einmal in einer primären Region und kopieren sie in die anderen Regionen, bevor Sie sie rotieren.

Führen Sie die Rotation in der folgenden Reihenfolge durch. Bestätigen Sie currentPhase in einer Region (siehe Schritt 2: Phase abschließen), bevor Sie mit der nächsten Phase für diese Region fortfahren.

  1. Führen Sie CREATE_NEW_CA in Ihrer primären Region aus. Das Diagramm erstellt die neue Stammzertifizierungsstelle und speichert sie im Secret apigee-ca-2.
  2. Kopieren Sie das Secret apigee-ca-2 aus dem Namespace cert-manager der primären Region in den Namespace cert-manager jeder anderen Region, bevor Sie CREATE_NEW_CA in diesen Regionen ausführen. Dies ist dasselbe Muster für das Kopieren von Secrets, das Sie verwenden, wenn Sie in eine neue Region expandieren. Weitere Informationen finden Sie unter Bereitstellungen in mehreren Regionen.
  3. Führen Sie CREATE_NEW_CA in jeder der anderen Regionen aus, jeweils in einer Region. Da das apigee-ca-2-Secret bereits vorhanden ist, wird im Diagramm keine neue Zertifizierungsstelle erstellt und die Region wird an die freigegebene gebunden.
  4. Führen Sie CREATE_NEW_LEAF in jeder Region aus.
  5. Führen Sie HIDE_OLD_CA in jeder Region aus.
  6. Führen Sie CLEANUP in jeder Region aus.
  7. Entfernen Sie den certRotation-Abschnitt aus der Überschreibungsdatei jeder Region, um die Konfiguration zu bereinigen.

Über CREATE_NEW_CA, CREATE_NEW_LEAF und HIDE_OLD_CA vertraut jede Region sowohl der alten als auch der neuen Root-Zertifizierungsstelle. Regionen können sich in diesem Zeitraum also in unterschiedlichen Phasen befinden, ohne dass der Traffic zwischen ihnen unterbrochen wird.

Eigene Zertifizierungsstelle verwenden

Wenn Sie Ihre eigene Stamm-CA anstelle einer vom Chart generierten verwenden möchten, erstellen Sie das neue CA-Secret, bevor Sie mit der Rotation beginnen. Da das Diagramm nur dann eine Zertifizierungsstelle generiert, wenn das Ziel-Secret fehlt, wird ein vorhandenes Secret unverändert verwendet.

Stamm-CA-Namen sind nicht kostenlos wählbar. Für jede Generation der CA wird in Hybrid ein fester Name erwartet – apigee-ca, dann apigee-ca-2, apigee-ca-3 usw. – und das Diagramm sucht nach der nächsten CA mit genau diesem Namen. Wenn Sie Ihre eigene Zertifizierungsstelle verwenden, müssen Sie das Secret unter dem genauen nächsten Namen erstellen (apigee-ca-2 für die erste Rotation). Das Diagramm erkennt keine Zertifizierungsstelle, die unter einem anderen Namen erstellt wurde. So finden Sie den aktuellen Secret-Namen und den nächsten Namen, der verwendet werden soll: 

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

Unter Ablauf der Root-Zertifizierungsstelle im Blick behalten finden Sie weitere Möglichkeiten, um zu prüfen, zu welcher Generation Ihr Cluster gehört.

  1. Bevor Sie CREATE_NEW_CA ausführen, erstellen Sie ein Secret mit dem nächsten CA-Namen (apigee-ca-2 für die erste Rotation) im Namespace cert-manager, das Ihr CA-Zertifikat und Ihren privaten Schlüssel enthält. Das Secret muss vom Typ kubernetes.io/tls sein und drei Schlüssel enthalten: tls.crt, tls.key und ca.crt. Da kubectl create secret tls den Schlüssel ca.crt nicht festlegen kann, verwenden Sie die generische Form: 
    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. Führen Sie die Rotation wie unter Root-CA rotieren beschrieben aus. Während CREATE_NEW_CA wird Ihr apigee-ca-2-Secret erkannt, die Generierung einer CA wird übersprungen und der neue Aussteller (apigee-ca-issuer-2) wird an Ihre CA gebunden. Alle anderen Phasen bleiben unverändert.

Wenn Sie Ihre eigene Zertifizierungsstelle verwenden, richtet sich die Gültigkeitsdauer nach der Ihres Zertifikats und nicht nach dem 10-jährigen Standardwert des Diagramms.

Rotation rückgängig machen

Jede Phase vor CLEANUP kann rückgängig gemacht werden. Um ein Rollback durchzuführen, legen Sie certRotation.phase auf den Wert fest, den der Cluster als Rollback-Ziel meldet, und wenden Sie ihn mit helm upgrade an, genau wie bei einer Forward-Phase.

Lesen Sie das Rollback-Ziel aus der ConfigMap cert-info:

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

Die Forward- und Rollback-Ziele für die einzelnen Phasen sind:

Aktuelle Phase Nächste Phase Rollback-Phase
PHASE_UNSPECIFIED (nicht begonnen) 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 abgeschlossen) – (keine; irreversibel)

Ablauf der Stamm-CA im Blick behalten

Da die Rotation in Apigee Hybrid vom Kunden gesteuert wird, sind Sie dafür verantwortlich, die Stammzertifizierungsstelle zu rotieren, bevor sie abläuft. Behalten Sie das Ablaufdatum des apigee-ca-Zertifikats im Blick und planen Sie die Rotation rechtzeitig, damit Sie genügend Zeit haben, alle vier Phasen in jeder Region abzuschließen.

Um zu prüfen, wann die Root-Zertifizierungsstelle abläuft, listen Sie die CA-Zertifikate im Namespace cert-manager auf und lesen Sie dann das Ablaufdatum der aktuell verwendeten Generation: 

kubectl get certificate -n cert-manager

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

Mit dem ersten Befehl wird jede Generation der Stamm-CA aufgelistet (apigee-ca, apigee-ca-2 usw.). Der zweite Befehl gibt das Ablaufdatum des benannten Zertifikats aus. Führen Sie ihn für die aktuell verwendete Generation aus.

Die automatisierte Problemsuche in Apigee Hybrid meldet Clusterprobleme, die als ApigeeIssue-Ressourcen erkannt werden. Sie können sie mit kubectl get apigeeissues auflisten. Prüfen Sie im Rahmen Ihres regulären Monitorings, ob Probleme aufgetreten sind.

Nächste Schritte