Richiedi un certificato

Questa pagina descrive i passaggi per richiedere un certificato utilizzando Certificate Authority Service.

Per stabilire l'attendibilità e la comunicazione sicura all'interno del tuo Google Distributed Cloud (GDC) air-gapped, richiedi un certificato abilitato o disabilitato per ACME dal servizio Certificate Authority Service.

Prima di iniziare

Prima di poter richiedere un certificato, assicurati di disporre delle autorizzazioni necessarie e di un file kubeconfig.

Autorizzazioni obbligatorie

Per ottenere le autorizzazioni necessarie per richiedere un certificato, chiedi all'amministratore IAM dell'organizzazione di concederti il ruolo Richiedente certificati del servizio CA (certificate-authority-service-certificate-requester). Per ulteriori informazioni sui ruoli, consulta Definizioni dei ruoli.

Recupera il file kubeconfig

Per eseguire comandi sul server dell'API Management, procedi nel seguente modo:

  1. Accedi e genera il file kubeconfig per il server API Management se non ne hai uno.

  2. Utilizza il percorso del file kubeconfig del server API di gestione per sostituire MANAGEMENT_API_SERVER_KUBECONFIG in queste istruzioni.

Richiedere un certificato utilizzando la CA con la modalità ACME attivata

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

Raccogli l'URL del server ACME 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 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 disattivata

Per creare una richiesta di certificato con la modalità ACME disattivata, devi creare e applicare una risorsa CertificateRequest all'istanza air-gapped di Distributed Cloud. 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.

Richiedere 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 aggiungila alla risorsa.

    Se vuoi, 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 del certificato.
    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 radice o 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 è impostato, il certificato è valido immediatamente dopo l'emissione.
    VALIDITY_END_TIME L'ora in cui scade il 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 soggetto personalizzato da utilizzare nel certificato emesso, ignorando le informazioni sul soggetto nella CSR. Fornisci questo valore come soggetto X.509 con codifica ASN.1 DER non elaborato.

  2. Applica la risorsa personalizzata all'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 Management.

  3. Verifica la preparazione 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))'

    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'

    L'output mostra il SECRET_NAME contenente il certificato firmato:

    test-jwk-1

Richiedere 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.

    Se vuoi, 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 del certificato.
    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 radice o 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 Stato o provincia da utilizzare nel certificato.
    COUNTRY Il paese del certificato.
    DNS_NAMES DNSNames è 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 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 è impostato, il certificato è valido immediatamente dopo l'emissione.
    VALIDITY_END_TIME L'ora in cui scade il 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 soggetto personalizzato da utilizzare nel certificato emesso, ignorando le informazioni sul soggetto nella CSR. Fornisci questo valore come soggetto X.509 con codifica ASN.1 DER non elaborato.

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

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

  3. Verifica la preparazione 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))'

    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'

    L'output mostra il SECRET_NAME contenente il certificato firmato:

    test-jwk-1

Elenca richieste di certificati

Utilizza il parametro certificaterequests per elencare tutte le risorse CertificateRequest:

   kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificaterequests

L'output è simile al seguente:

   NAMESPACE    NAME               READY   AGE
   foo          cert-req           True    30s