Request a certificate

This page describes the steps to request a certificate using the Certificate Authority Service.

To establish trust and secure communication within your Google Distributed Cloud (GDC) air-gapped, request an ACME-enabled or disabled certificate from the Certificate Authority Service.

Before you begin

To get the permissions you need to request a certificate, ask your Organization IAM Admin to grant you the Certificate Authority Service Admin (certificate-authority-service-admin) role.

Get the kubeconfig file

To run commands against the Management API server, ensure you have the following resources:

Use the path to the kubeconfig file of the Management API server to replace MANAGEMENT_API_SERVER_KUBECONFIG in these instructions.

Request a certificate using CA with ACME mode enabled

If the certificate authority is hosted in ACME mode, it outputs the ACME server URL in its status after it becomes ready.

Gather the CA ACME server URL from your Distributed Cloud environment:

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

Replace the following:

CA_NAME: The name of the CA, which can be a root or sub CA.
USER_PROJECT_NAMESPACE: The name of the namespace where the user project resides.

Request a certificate using CA with ACME mode disabled

To create a certificate request with ACME mode disabled, you must create and apply a CertificateRequest resource to your Distributed Cloud air-gapped instance. There are two ways to do this:

Create a CertificateResource and include a CSR in the resource.
Create a CertificateResource using a GDC auto-generated private key and provide the certificate configurations as custom values.

Request a certificate using a CSR

Create a CertificateRequest resource and save it as a YAML file called cert-request.yaml. Use your private key to create a Certificate Signing Request (CSR) and add it to your resource:

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
  signedCertificateSecret: SECRET_NAME

Replace the following variables:

Variable	Description
`CERT_REQ_NAME`	The name of the certificate.
`USER_PROJECT_NAMESPACE`	The name of the namespace where the user project resides.
`CA_NAME`	The name of the CA, which can be a root or sub CA.
`CSR`	The Certificate Signing Request to sign using CA.
`SECRET_NAME`	The name of the Kubernetes Secret that holds the private key and signed CA certificate.

Apply the custom resource to your Distributed Cloud instance:
```
kubectl apply -f cert-request.yaml --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
```
Replace MANAGEMENT_API_SERVER_KUBECONFIG with the path to the kubeconfig file of the Management API server.

Verify the readiness of the certificate request:

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))'

The output is similar to the following:

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

Get the certificate secret name:

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

The output shows the SECRET_NAME containing the signed certificate:

test-jwk-1

Request a certificate using an auto-generated key

Create a CertificateRequest resource and save it as a YAML file called cert-request.yaml. Populate the chosen values for the certificate:

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
  signedCertificateSecret: SECRET_NAME

Replace COMMON_NAME with the common name of the certificate.

Replace the following optional variables. You must include at least one of these values in the CertificateRequest resource:

Variable	Description
`ORGANIZATION`	Organization to be used on the certificate.
`LOCALITY`	The locality of the certificate.
`STATE`	State or Province to be used on the certificate.
`COUNTRY`	The country of the certificate.
`DNS_NAMES`	`DNSNames` is a list of `dNSName subjectAltNames` to be set on the certificate.
`IP_ADDRESS`	A list of `ipAddress subjectAltNames` to be set on the certificate.
`RFC822_NAMES`	A list of `rfc822Name subjectAltNames` to be set on the certificate.
`URIS`	A list of `uniformResourceIdentifier subjectAltNames` to be set on the certificate.

Apply the custom resource to your Distributed Cloud instance:

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