Richiedi un certificato

Questo documento descrive i passaggi per richiedere un certificato utilizzando Certificate Authority Service (CAS).

Per stabilire l'attendibilità e proteggere le comunicazioni all'interno di Google Distributed Cloud (GDC) air-gapped, richiedi un certificato con o senza ACME abilitato da Certificate Authority Service.

Questo documento è destinato al pubblico del gruppo di operatori di applicazioni, come sviluppatori di applicazioni o data scientist, che gestiscono i cicli di vita dei certificati all'interno del proprio progetto. Per saperne di più, consulta la sezione Pubblico della documentazione di GDC con air gap.

Prima di iniziare

Prima di poter richiedere un certificato, devi richiedere le autorizzazioni necessarie e preparare l'ambiente.

Richiedi i ruoli IAM

Per creare, visualizzare ed eliminare le richieste di certificati, contatta l'amministratore IAM dell'organizzazione per concederti il ruolo Richiedente certificati del servizio CA (certificate-authority-service-certificate-requester) nello spazio dei nomi del progetto dell'autorità di certificazione.

Prepara l'ambiente

Richiedi un certificato utilizzando la CA con la modalità ACME abilitata

Se l'autorità di certificazione è ospitata in modalità ACME, dopo che è pronta, restituisce l'URL del server ACME nel suo stato.

Raccogli l'URL del server ACME della CA dal tuo ambiente Distributed Cloud:

kubectl get certificateauthorities CA_NAME -n USER_PROJECT_NAMESPACE -ojson | jq -r '.status.acme.uri'

Sostituisci quanto segue:

  • CA_NAME: il nome della CA, che può essere una CA radice o una CA secondaria
  • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui risiede il progetto utente

Richiedi un certificato utilizzando la CA con la modalità ACME disabilitata

Per creare una richiesta di certificato con la modalità ACME disabilitata, devi creare e applicare una risorsa CertificateRequest all'istanza air-gapped di Distributed Cloud. Esistono due modi per eseguire questa operazione:

  • Crea una CertificateResource e includi una CSR nella risorsa.
  • Crea una CertificateResource utilizzando una chiave privata generata automaticamente da GDC e fornisci le configurazioni del certificato come valori personalizzati.

Richiedi un certificato utilizzando una CSR

  1. Crea una risorsa CertificateRequest e salvala come file YAML denominato cert-request.yaml. Utilizza la chiave privata per creare una richiesta di firma del certificato (CSR) e aggiungila alla risorsa.

    (Facoltativo) Puoi emettere il certificato con un insieme preconfigurato di parametri X.509 inserendo il nome del modello nel campo certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  csr: CSR
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Sostituisci le seguenti variabili:

    Variabile Descrizione
    CERT_REQ_NAME il nome della risorsa CertificateRequest
    USER_PROJECT_NAMESPACE il nome dello spazio dei nomi in cui risiede il progetto utente
    CA_NAME il nome della CA, che può essere una CA radice o una CA secondaria
    CSR la richiesta di firma del certificato da firmare utilizzando la CA
    SECRET_NAME il nome del secret Kubernetes che contiene la chiave privata e il certificato CA firmato

    Sostituisci le seguenti variabili facoltative:

    Variabile Descrizione
    TEMPLATE_NAME il nome del modello di certificato predefinito che vuoi utilizzare. Per un elenco dei modelli disponibili e dettagli sui conflitti, consulta Modelli di certificati predefiniti.
    VALIDITY_START_TIME l'ora a partire dalla quale il certificato è considerato valido. Questo valore deve essere nel formato YYYY-MM-DDTHH:MM:SSZ (ad esempio, 2025-10-19T21:45:30Z). Se non viene impostato, il certificato è valido immediatamente dopo l'emissione.
    VALIDITY_END_TIME l'ora in cui il certificato scade. Questo valore deve essere nel formato YYYY-MM-DDTHH:MM:SSZ (ad esempio, 2026-01-17T18:25:40Z). Se non viene impostato, il certificato scade 90 giorni dopo l'ora di inizio.
    SUBJECT_OVERRIDE un soggetto personalizzato da utilizzare nel certificato emesso, che sostituisce le informazioni del soggetto nella CSR. Fornisci questo valore come soggetto X.509 non elaborato con codifica ASN.1 DER.

  2. Applica la risorsa personalizzata all'istanza di Distributed Cloud:

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Sostituisci MANAGEMENT_API_SERVER_KUBECONFIG con il percorso del file kubeconfig del server API di gestione.

  3. Verifica la disponibilità della richiesta di certificato:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Sostituisci quanto segue:

    • MANAGEMENT_API_SERVER_KUBECONFIG: il percorso del file kubeconfig del server API di gestione
    • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui risiede il progetto utente
    • CERT_REQ_NAME il nome della risorsa CertificateRequest

    L'output è simile al seguente:

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Recupera il nome del secret del certificato:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Sostituisci quanto segue:

    • MANAGEMENT_API_SERVER_KUBECONFIG: il percorso del file kubeconfig del server API di gestione
    • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui risiede il progetto utente
    • CERT_REQ_NAME il nome della risorsa CertificateRequest

    L'output mostra SECRET_NAME contenente il certificato firmato:

    test-jwk-1

Richiedi un certificato utilizzando una chiave generata automaticamente

  1. Crea una risorsa CertificateRequest e salvala come file YAML denominato cert-request.yaml. Inserisci i valori scelti per il certificato.

    (Facoltativo) Puoi emettere il certificato con un insieme preconfigurato di parametri X.509 inserendo il nome del modello nel campo certificateTemplate.

    apiVersion: pki.security.gdc.goog/v1
kind: CertificateRequest
metadata:
  name: CERT_REQ_NAME
  namespace: USER_PROJECT_NAMESPACE
spec:
  certificateAuthorityRef:
    name: CA_NAME
    namespace: USER_PROJECT_NAMESPACE
  certificateConfig:
    subjectConfig:
      commonName: COMMON_NAME
      organization: ORGANIZATION
      locality: LOCALITY
      state: STATE
      country: COUNTRY
      dnsNames:
      - DNS_NAMES
      ipAddresses:
      - IP_ADDRESSES
      rfc822Names:
      - RFC822NAMES
      uris:
      - URIS
  certificateTemplate: TEMPLATE_NAME
  signedCertificateSecret: SECRET_NAME
  notBefore: VALIDITY_START_TIME
  notAfter: VALIDITY_END_TIME
  subjectOverride: SUBJECT_OVERRIDE

    Sostituisci le seguenti variabili:

    Variabile Descrizione
    CERT_REQ_NAME il nome della risorsa CertificateRequest
    USER_PROJECT_NAMESPACE il nome dello spazio dei nomi in cui risiede il progetto utente
    CA_NAME il nome della CA, che può essere una CA radice o una CA secondaria
    SECRET_NAME il nome del secret Kubernetes che contiene la chiave privata e il certificato CA firmato

    Sostituisci le seguenti variabili facoltative. Devi includere almeno uno dei campi del blocco spec.certificateConfig.subjectConfig della risorsa CertificateRequest:

    Variabile Descrizione
    COMMON_NAME il nome comune del certificato
    ORGANIZATION l'organizzazione da utilizzare nel certificato
    LOCALITY la località del certificato
    STATE lo stato o la provincia da utilizzare nel certificato
    COUNTRY il paese del certificato
    DNS_NAMES un elenco di dNSName subjectAltNames da impostare nel certificato
    IP_ADDRESS un elenco di ipAddress subjectAltNames da impostare nel certificato
    RFC822_NAMES un elenco di rfc822Name subjectAltNames da impostare nel certificato
    URIS un elenco di uniformResourceIdentifier subjectAltNames da impostare nel certificato
    TEMPLATE_NAME il nome del modello di certificato predefinito che vuoi utilizzare. Per un elenco dei modelli disponibili e dettagli sui conflitti, consulta Modelli di certificati predefiniti.
    VALIDITY_START_TIME l'ora a partire dalla quale il certificato è considerato valido. Questo valore deve essere nel formato YYYY-MM-DDTHH:MM:SSZ (ad esempio, 2025-10-19T21:45:30Z). Se non viene impostato, il certificato è valido immediatamente dopo l'emissione.
    VALIDITY_END_TIME l'ora in cui il certificato scade. Questo valore deve essere nel formato YYYY-MM-DDTHH:MM:SSZ (ad esempio, 2026-01-17T18:25:40Z). Se non viene impostato, il certificato scade 90 giorni dopo l'ora di inizio.
    SUBJECT_OVERRIDE un soggetto personalizzato da utilizzare nel certificato emesso, che sostituisce le informazioni del soggetto nella CSR. Fornisci questo valore come soggetto X.509 non elaborato con codifica ASN.1 DER.

  2. Applica la risorsa personalizzata all'istanza di Distributed Cloud:

    kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG

    Sostituisci MANAGEMENT_API_SERVER_KUBECONFIG con il percorso del file kubeconfig del server API di gestione.

  3. Verifica la disponibilità della richiesta di certificato:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r ' .status.conditions[] | select( .type as $id | "Ready" | index($id))'

    Sostituisci quanto segue:

    • MANAGEMENT_API_SERVER_KUBECONFIG: il percorso del file kubeconfig del server API di gestione
    • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui risiede il progetto utente
    • CERT_REQ_NAME il nome della risorsa CertificateRequest

    L'output è simile al seguente:

    {
  "lastTransitionTime": "2025-01-27T12:22:59Z",
  "message": "Certificate is issued",
  "observedGeneration": 1,
  "reason": "Issued",
  "status": "True",
  "type": "Ready"
}

  4. Recupera il nome del secret del certificato:

    kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME -ojson | jq -r '.spec.signedCertificateSecret'

    Sostituisci quanto segue:

    • MANAGEMENT_API_SERVER_KUBECONFIG: il percorso del file kubeconfig del server API di gestione
    • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui risiede il progetto utente
    • CERT_REQ_NAME: il nome della risorsa CertificateRequest

    L'output mostra SECRET_NAME contenente il certificato firmato:

    test-jwk-1

Elenca le richieste di certificati

Utilizza il parametro certificaterequests per elencare tutte le risorse CertificateRequest:

kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequest.pki.security.gdc.goog

Sostituisci quanto segue:

  • MANAGEMENT_API_SERVER_KUBECONFIG: il percorso del file kubeconfig del server API di gestione
  • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui risiede il progetto utente

Di seguito è riportato un comando di esempio che utilizza lo spazio dei nomi agtest-project:

kubectl --kubeconfig /root/release/root-admin/root-admin-kubeconfig  -n agtest-project get certificaterequest.pki.security.gdc.goog

L'output previsto è simile al seguente:

NAME                                               READY   AGE
test-externalca-subca-cert-req-with-csr            True    17h
test-externalca-subca-cert-req-with-csr-override   True    17h

Elimina un certificato

Per eliminare un certificato, devi eliminare la risorsa personalizzata CertificateRequest corrispondente. Questa azione rimuove la risorsa dal database CAS.

  1. Trova il nome di CertificateRequest che vuoi eliminare. Puoi elencare le richieste di certificati per trovare il nome.

  2. Elimina la risorsa CertificateRequest:

    kubectl --kubeconfig  MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE delete certificaterequest.pki.security.gdc.goog/CERT_REQ_NAME

    Sostituisci quanto segue:

    • MANAGEMENT_API_SERVER_KUBECONFIG: il percorso del file kubeconfig del server API di gestione
    • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui risiede il progetto utente
    • CERT_REQ_NAME: il nome della risorsa CertificateRequest

Limiti e pulizia delle richieste di certificati

Per contribuire a mantenere la stabilità del sistema e prevenire un utilizzo elevato delle risorse, CAS applica limiti al numero di risorse personalizzate CertificateRequest e offre una funzionalità di pulizia automatica facoltativa.

Quota per le richieste di certificati

CAS applica una quota al numero di risorse personalizzate CertificateRequest per organizzazione, con un limite predefinito di 5000. Il superamento di questo limite può ridurre le prestazioni di CAS e del server API di gestione.

Quando il numero totale di risorse CertificateRequest si avvicina alla quota (ad esempio, all'80% e al 90% del limite), vedrai degli avvisi nell'output del comando quando crei nuove richieste. Se tenti di creare una CertificateRequest dopo aver raggiunto la quota, la richiesta viene rifiutata. Potresti visualizzare un messaggio di errore simile al seguente:

Error from server (Forbidden): error when creating "cert-request.yaml":
admission webhook "certificaterequests.pki.security.gdc.goog" denied the
request: the number of certificate requests has exceeded the per organization
limit of {LIMIT}. Please refer to the guide PLATAUTH-G2102 for troubleshooting
this issue

Se riscontri questo errore, potresti dover eliminare le risorse CertificateRequest vecchie o non necessarie. Per modificare la quota, contatta un membro del gruppo di operatori dell'infrastruttura all'interno della tua organizzazione. Può sostituire la quota seguendo le istruzioni riportate nel runbook PLATAUTH-G2102.

Pulizia automatica

Puoi attivare la pulizia automatica per eliminare le risorse CertificateRequest scadute. Questa funzionalità consente di liberare le risorse rimuovendole dopo un periodo di tolleranza configurabile. Il periodo di tolleranza definisce il periodo di tempo che intercorre tra la scadenza di un certificato e l'eliminazione della risorsa CertificateRequest.

La pulizia automatica è disattivata per impostazione predefinita. Un membro del gruppo di operatori dell'infrastruttura all'interno della tua organizzazione può attivare questa funzionalità e configurare il periodo di tolleranza seguendo le istruzioni riportate nel runbook PLATAUTH-G2103. La funzionalità rimane disattivata se il periodo di tolleranza non è impostato o è impostato su zero.