Ruota il certificato CA radice

Questa pagina descrive il certificato dell'autorità di certificazione (CA) radice ibrida Apigee che firma i certificati interni utilizzati dai componenti ibridi per comunicare tra loro e descrive come eseguirne la rotazione prima della scadenza. A partire da Apigee hybrid v1.17, puoi ruotare autonomamente questa CA radice.

Informazioni sul certificato CA radice

Ogni installazione di Apigee hybrid ha una singola CA radice, archiviata come Certificate di cert-manager denominato apigee-ca nello spazio dei nomi cert-manager. Si tratta di una CA autofirmata (isCA: true, nome comune apigee-hybrid) che funge da radice attendibile per i certificati interni ibridi, ovvero sia la mutual TLS (mTLS) tra i componenti sia la TLS unidirezionale (lato server) che protegge i webhook di ammissione e la conversione delle risorse personalizzate. Se questa CA scade, la comunicazione interna tra i componenti ibridi si interrompe.

Perché il certificato CA radice viene ruotato

L'autorità di certificazione radice generata dal grafico ibrido ha un periodo di validità di 10 anni. Deve essere ruotato prima della scadenza in modo che i certificati interni che firma possano continuare a essere rinnovati e la comunicazione tra i componenti non venga mai interrotta. La rotazione è progettata per non causare tempi di inattività: durante la transizione, i componenti considerano attendibili sia la CA radice precedente sia quella nuova, quindi i certificati firmati da una delle due rimangono validi finché la CA precedente non viene rimossa.

Come funziona la rotazione

Ruota la CA radice facendo avanzare il cluster in quattro fasi, in ordine. Passi alla fase successiva solo dopo che quella attuale è stata completata su ogni componente. Ogni fase è guidata da un singolo campo di override, certRotation.phase, applicato con un helm upgrade del grafico dell'operatore Apigee (apigee-operator).

Fase (certRotation.phase) Che cosa succede Rollback possibile
1. CREATE_NEW_CA Viene creata una nuova CA radice (apigee-ca-2) e aggiunta all'archivio attendibile di ogni componente ibrido. Componenti ancora presenti certificati firmati dalla vecchia CA, quindi non è ancora stato eseguito alcun passaggio. Sì
2. CREATE_NEW_LEAF Vengono emessi nuovi certificati foglia firmati dalla nuova CA radice. Entrambe le CA radice, sia quella precedente che quella nuova, sono attendibili, quindi il traffico continua senza interruzioni. Sì
3. HIDE_OLD_CA La vecchia CA radice viene rimossa dalla configurazione di attendibilità attiva. Viene utilizzata solo la nuova CA radice. Il rollback è ancora disponibile in questa fase. Sì
4. CLEANUP La vecchia CA radice e i relativi emittenti vengono rimossi e la nuova CA radice viene promossa a CA radice del cluster. Questa fase è irreversibile. No

Prima di iniziare

  • Installa gli strumenti a riga di comando kubectl e helm e assicurati che il contesto kubectl punti al cluster che stai ruotando.
  • Assicurati che il cluster sia integro. Ogni helm upgrade verifica che ogni ApigeeDeployment si trovi nello stato running e che la fase richiesta sia quella attuale, la successiva o quella di rollback. Se il cluster non è integro o provi a saltare una fase, l'upgrade viene rifiutato.
  • Se esegui un deployment multiregionale, leggi questa sezione prima di iniziare. Ogni regione deve convergere sulla stessa nuova CA radice.

Ruota la CA radice

Esegui i seguenti passaggi per ogni fase elencata in Come funziona la rotazione, nell'ordine: applica la fase, poi conferma che sia stata completata prima di passare alla successiva. In un deployment multi-regionale, eseguili in ogni regione.

Passaggio 1: imposta la fase e applicala

Aggiungi o aggiorna la sezione certRotation nel file di override, impostando phase sulla fase che stai applicando. Ad esempio, per avviare la rotazione:

certRotation:
  phase: CREATE_NEW_CA

Prova la modifica con un dry run:

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

Quindi, applica la modifica:

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

Passaggio 2: conferma che la fase sia stata completata

Il cluster registra l'avanzamento della rotazione dei record in ConfigMap cert-info nello spazio dei nomi ibrido. Leggi il valore currentPhase: 

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

Una fase viene completata solo quando currentPhase è uguale alla fase che hai appena applicato. currentPhase avanza solo dopo che ogni componente è stato riconciliato con la fase richiesta, quindi non procedere finché non corrisponde.

Quando currentPhase corrisponde, leggi la fase successiva da applicare dallo stesso ConfigMap: 

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

Imposta certRotation.phase su questo valore e ripeti i passaggi 1 e 2. Continua fino al completamento della fase CLEANUP.

Deployment multiregionali

In un deployment multiregionale, ogni cluster ha la propria ConfigMap cert-info, il proprio operatore e i propri truststore e tutte le regioni devono finire per considerare attendibile la stessa nuova CA radice. Il grafico genera una nuova CA radice solo quando il secret apigee-ca-2 non esiste già, quindi crei la nuova CA una volta in una regione primaria e la copi nelle altre regioni prima di ruotarle.

Esegui la rotazione nel seguente ordine. Conferma currentPhase in una regione (vedi Passaggio 2: conferma che la fase è stata completata) prima di passare alla fase successiva.

  1. Esegui CREATE_NEW_CA nella tua regione principale. Il grafico crea la nuova CA radice e la memorizza nel secret apigee-ca-2.
  2. Copia il secret apigee-ca-2 dallo spazio dei nomi cert-manager della regione principale nello spazio dei nomi cert-manager di ogni altra regione prima di eseguire CREATE_NEW_CA in queste regioni. Si tratta dello stesso pattern di copia segreta che utilizzi quando esegui l'espansione in una nuova regione. Vedi Implementazioni multiregionali.
  3. Esegui CREATE_NEW_CA in ciascuna delle altre regioni, una regione alla volta. Poiché il secret apigee-ca-2 è già presente, il grafico salta la creazione di una nuova CA e associa la regione a quella condivisa.
  4. Esegui CREATE_NEW_LEAF in ogni regione.
  5. Esegui HIDE_OLD_CA in ogni regione.
  6. Esegui CLEANUP in ogni regione.
  7. Rimuovi la sezione certRotation dai file di override di ogni regione per riordinare la configurazione.

Tramite CREATE_NEW_CA, CREATE_NEW_LEAF e HIDE_OLD_CA, ogni regione considera attendibili sia la CA radice precedente sia quella nuova, quindi le regioni possono trovarsi in fasi diverse durante questo periodo senza interrompere il traffico tra loro.

Bring your own CA

Se vuoi utilizzare la tua CA radice anziché una generata dal grafico, crea in anticipo il nuovo secret della CA prima di iniziare la rotazione. Poiché il grafico genera un certificato solo quando il secret di destinazione è assente, un secret esistente viene utilizzato così com'è.

I nomi delle CA radice non sono in formato libero. hybrid prevede che ogni generazione della CA abbia un nome fisso: apigee-ca, poi apigee-ca-2, apigee-ca-3 e così via. Il grafico cerca la CA successiva esattamente con quel nome. Quando porti la tua CA, devi creare il secret con il nome successivo esatto (apigee-ca-2 per la prima rotazione); il grafico non rileva una CA creata con qualsiasi altro nome. Per trovare il nome del secret attuale e il successivo da utilizzare, elenca i certificati CA e i secret che li supportano: 

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

Consulta Monitorare la scadenza della CA radice per altri modi per ispezionare la generazione del tuo cluster.

  1. Prima di eseguire CREATE_NEW_CA, crea un secret con il nome della CA successiva (apigee-ca-2 per la prima rotazione) nello spazio dei nomi cert-manager, contenente il certificato CA e la chiave privata. Il secret deve essere di tipo kubernetes.io/tls e contenere tre chiavi: tls.crt, tls.key e ca.crt. Poiché kubectl create secret tls non può impostare la chiave ca.crt, utilizza il modulo generico: 
    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. Esegui la rotazione come descritto in Ruota la CA radice. Durante CREATE_NEW_CA, il grafico rileva il secret apigee-ca-2, salta la generazione di una CA e associa il nuovo emittente (apigee-ca-issuer-2) alla CA. Tutte le altre fasi rimangono invariate.

Quando porti la tua CA, la sua durata è quella del certificato, non i 10 anni predefiniti del grafico.

Eseguire il rollback di una rotazione

È possibile eseguire il rollback di ogni fase precedente a CLEANUP. Per eseguire il rollback, imposta certRotation.phase sul valore che il cluster segnala come target di rollback e applicalo con helm upgrade, esattamente come applichi una fase di avanzamento.

Leggi la destinazione di rollback da ConfigMap cert-info:

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

I target di avanzamento e rollback per ogni fase sono:

Fase attuale Fase successiva Rollback della fase
PHASE_UNSPECIFIED (non iniziata) 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 — (rotazione completata) — (nessuno; irreversibile)

Monitorare la scadenza della CA radice

Poiché la rotazione ibrida di Apigee è guidata dal cliente, è tua responsabilità ruotare la CA radice prima che scada. Tieni traccia della scadenza del certificato apigee-ca e pianifica la rotazione prima di questa data, in modo da avere il tempo di completare tutte e quattro le fasi in ogni regione.

Per verificare la data di scadenza della CA radice, elenca i certificati CA nello spazio dei nomi cert-manager, quindi leggi la data di scadenza della generazione che stai utilizzando: 

kubectl get certificate -n cert-manager

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

Il primo comando elenca ogni generazione della CA radice (apigee-ca, apigee-ca-2 e così via). Il secondo stampa la data di scadenza del certificato denominato; eseguilo rispetto alla generazione attualmente in uso.

Apigee Hybrid Automated issue surfacing segnala i problemi del cluster rilevati come risorse ApigeeIssue, che puoi elencare con kubectl get apigeeissues. Controlla i problemi rilevati nell'ambito del monitoraggio regolare.

Passaggi successivi