Richiedi un certificato

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

Per stabilire una comunicazione sicura e affidabile all'interno di Google Distributed Cloud (GDC) con air gap, richiedi un certificato abilitato o disabilitato per ACME da Certificate Authority Service.

Questo documento è rivolto ai gruppi di operatori di applicazioni, come sviluppatori di applicazioni o data scientist, che gestiscono i cicli di vita dei certificati all'interno del loro progetto. Per saperne di più, consulta la documentazione sui segmenti di pubblico per GDC con air gap.

Prima di iniziare

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

Richiedi ruoli IAM

Per creare, visualizzare ed eliminare le richieste di certificato, contatta l'amministratore dell'organizzazione IAM per farti concedere il ruolo Richiedente certificati di Certificate Authority Service (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, l'URL del server ACME viene visualizzato nel suo stato quando diventa pronto.

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 principale o secondaria
  • USER_PROJECT_NAMESPACE: il nome dello spazio dei nomi in cui si trova 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 alla tua istanza Distributed Cloud con air gap. Esistono due modi per eseguire questa operazione:

  • Crea un CertificateResource e includi una CSR nella risorsa.
  • Crea un 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 tua chiave privata per creare una richiesta di firma del certificato (CSR) e aggiungerla alla risorsa.

    Facoltativamente, puoi emettere il certificato con un insieme preconfigurato di parametri X.509 inserendo il nome del template 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 si trova il progetto utente
    CA_NAME il nome della CA, che può essere una CA principale o secondaria
    CSR la richiesta di firma del certificato da firmare utilizzando la CA
    SECRET_NAME il nome del secret di Kubernetes che contiene la chiave privata e il certificato CA firmato

    Sostituisci le seguenti variabili facoltative:

    Variabile Descrizione
    TEMPLATE_NAME il nome del template di certificato predefinito che vuoi utilizzare. Per un elenco dei template disponibili e i dettagli relativi ai conflitti, consulta Template di certificato 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 di scadenza del certificato. 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 oggetto personalizzato da utilizzare nel certificato emesso, eseguendo l'override delle informazioni sull'oggetto nella CSR. Fornisci questo valore come oggetto X.509 non elaborato, codificato in ASN.1 DER.

  2. Applica la risorsa personalizzata alla tua istanza 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 l'idoneità 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 si trova 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 si trova il progetto utente
    • CERT_REQ_NAME il nome della risorsa CertificateRequest

    L'output mostra il 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. Compila i valori scelti per il certificato.

    Facoltativamente, puoi emettere il certificato con un insieme preconfigurato di parametri X.509 inserendo il nome del template 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 si trova il progetto utente
    CA_NAME il nome della CA, che può essere una CA principale o secondaria
    SECRET_NAME il nome del secret di 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 organizzazione da utilizzare nel certificato
    LOCALITY la località del certificato
    STATE Stato o provincia da utilizzare nel certificato
    COUNTRY il paese del certificato
    DNS_NAMES un elenco di dNSName subjectAltNames da impostare sul certificato
    IP_ADDRESS un elenco di ipAddress subjectAltNames da impostare sul certificato
    RFC822_NAMES un elenco di rfc822Name subjectAltNames da impostare sul certificato
    URIS un elenco di uniformResourceIdentifier subjectAltNames da impostare sul certificato
    TEMPLATE_NAME il nome del template di certificato predefinito che vuoi utilizzare. Per un elenco dei template disponibili e i dettagli relativi ai conflitti, consulta Template di certificato 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 di scadenza del certificato. 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 oggetto personalizzato da utilizzare nel certificato emesso, eseguendo l'override delle informazioni sull'oggetto nella CSR. Fornisci questo valore come oggetto X.509 non elaborato, codificato in ASN.1 DER.

  2. Applica la risorsa personalizzata alla tua istanza 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 l'idoneità 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 si trova 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 si trova il progetto utente
    • CERT_REQ_NAME: il nome della risorsa CertificateRequest

    L'output mostra il 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 si trova il progetto utente

Di seguito è riportato un esempio di comando 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 della CertificateRequest che vuoi eliminare. Puoi elencare le richieste di certificato 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 si trova il progetto utente
    • CERT_REQ_NAME: il nome della risorsa CertificateRequest

Limiti e pulizia delle richieste di certificato

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.

Man mano che il numero totale di risorse CertificateRequest si avvicina alla quota (ad esempio, all'80% e al 90% del limite), vedrai degli avvisi nell'output comando quando crei nuove richieste. Se tenti di creare un 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 si verifica questo errore, potresti dover eliminare le risorse CertificateRequest obsolete o non necessarie. Per modificare la quota, contatta un membro del gruppo di operatori dell'infrastruttura all'interno della tua organizzazione. Può eseguire l'override della 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 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.