Create a root certificate authority

This page describes the steps to create a root certificate authority (CA) in Google Distributed Cloud (GDC) air-gapped.

A root CA, which sits atop the public key infrastructure (PKI) hierarchy, establishes the trust anchor for the PKI. To use certificates within a PKI, devices, software, and components must trust the root CA. This configuration ensures trust in all certificates issued by the root CA, thereby enabling trust in the PKI itself.

Before you begin

To get the permissions you need to create a root certificate authority, ask your Organization IAM Admin to grant you the Certificate Authority Service Admin (certificate-authority-service-admin) role. For more information on roles, see Role definitions.

Get the kubeconfig file

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

1. Sign in and generate the kubeconfig file for the Management API server if you don't have one.

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

Create a root certificate authority

To create a root CA, apply a custom resource to your Distributed Cloud air-gapped instance.

1. Create a CertificateAuthority resource and save it as a YAML file called root-ca.yaml:

   apiVersion: pki.security.gdc.goog/v1
   kind: CertificateAuthority
   metadata:
     name: ROOT_CA_NAME
     namespace: USER_PROJECT_NAMESPACE
   spec:
     caProfile:
       commonName: COMMON_NAME
       duration: DURATION
       renewBefore: RENEW_BEFORE
       organizations:
       - ORGANIZATION
       organizationalUnits:
       - ORGANIZATIONAL_UNITS
       countries:
       - COUNTRIES
       localities:
       - LOCALTIES
       provinces:
       - PROVINCES
       streetAddresses:
       - STREET_ADDRESSES
       postalCodes:
       - POSTAL_CODES
     caCertificate:
       selfSignedCA: {}
     certificateProfile:
       keyUsage:
         - digitalSignature
         - keyCertSign
         - crlSign
       extendedKeyUsage:
         - EXTENDED_KEY_USAGE
     secretConfig:
       secretName: SECRET_NAME
       privateKeyConfig:
         algorithm: KEY_ALGORITHM
         size: KEY_SIZE
     acme:
       enabled: ACME_ENABLED
   

   Replace the following variables:

   Variable	Description
   ROOT_CA_NAME	The name of the root CA.
   USER_PROJECT_NAMESPACE	The name of the namespace where the user project resides.
   COMMON_NAME	The common name of the CA certificate.
   DURATION	The requested lifetime of the CA certificate.
   SECRET_NAME	The name of the Kubernetes Secret that holds the private key and signed CA certificate.

   The following variables are optional values:

   Variable	Description
   RENEW_BEFORE	The rotation time before the CA certificate expires.
   ORGANIZATION	Organization to be used on the certificate.
   ORGANIZATIONAL_UNITS	Organizational units to be used on the certificate.
   COUNTRIES	Countries to be used on the certificate.
   LOCALITIES	Cities to be used on the certificate.
   PROVINCES	State or Provinces to be used on the certificate.
   STREET_ADDRESSES	Street addresses to be used on the certificate.
   POSTAL_CODES	Postal codes to be used on the certificate.
   EXTENDED_KEY_USAGE	The extended key usage for the certificate. If provided, the allowed values are serverAuth and clientAuth.
   KEY_ALGORITHYM	The private key algorithm used for this certificate. Allowed values are RSA, Ed25519, or ECDSA. If the size is not provided, it defaults to 256 for ECDSA and 2048 for RSA. Key size is ignored for Ed25519.
   KEY_SIZE	The size, in bits, of the private key for this certificate depends on the algorithm. RSA allows 2048, 3072, 4096, or 8192 (default 2048). ECDSA allows 256, 384, or 521 (default 256). Ed25519 ignores size.
   ACME_ENABLED	If set to true, CA runs in ACME mode and outputs the ACME server URL. You can then use the ACME client and protocol to manage certificates.

2. Apply the custom resource to your Distributed Cloud instance:

   kubectl apply -f root-ca.yaml –kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG
   

   Replace MANAGEMENT_API_SERVER_KUBECONFIG with the path to the kubeconfig file of the Management API server.

3. Verify the readiness of the root CA. It normally takes around 40 minutes for the CA to become ready:

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

   The output looks similar to the following:

   {
     "lastTransitionTime": "2025-01-24T17:09:19Z",
     "message": "CA reconciled",
     "observedGeneration": 2,
     "reason": "Ready",
     "status": "True",
     "type": "Ready"
   }
   

List CAs

To list all of the Certificate Authority Service resources in your Distributed Cloud air-gapped instance, do the following:

Use the certificateauthorities parameter to list all CertificateAuthority resources:

   kubectl --kubeconfig MANAGEMENT_API_SERVER_KUBECONFIG -n USER_PROJECT_NAMESPACE get certificateauthorities

The output looks similar to the following:

   NAMESPACE    NAME              READY   REASON   AGE
   foo          root-ca           True    Ready    7h24m
   foo          sub-ca            True    Ready    7h24m