Add custom CAs to the system trust bundle

This page explains how to add custom certificate authority (CA) certificates to the system trust bundle within Google Distributed Cloud (GDC) air-gapped. A trust bundle is a collection of trusted CAs that your organization's services use to verify the identity of other services. By adding your own custom CAs, you can control which certificates your organization trusts, enabling secure connections to your internal resources and other trusted endpoints.

This page covers how to add custom CAs to the trust-store-root-ext system trust bundle. When you modify the trust-store-root-ext trust bundle, the changes automatically propagate to the trust-store-global-root-ext bundle, making your custom CAs available across all zones.

This page is for audiences within the platform administrator group (such as IT admins) who need to manage and secure their organization's resources within GDC. For more information, see Audiences for GDC air-gapped documentation.

Before you begin

  • Required permissions: Ask your Organization IAM Admin to grant you the Trust Store Admin (trust-store-admin) role.

  • Kubeconfig file: Sign in and generate the kubeconfig file for the Infra cluster API server if you don't already have one. You need the path to the kubeconfig file to replace INFRA_CLUSTER_KUBECONFIG in the following steps.

Add custom CAs to the system trust bundle

To add custom CAs to the trust-store-root-ext system trust bundle, you need to prepare your custom CA resource and then apply it to the cluster.

  1. Export the following environment variables:

    export CUSTOM_CA_PEM_FILE=CUSTOM_CA_PEM_FILE
export KUBECONFIG=INFRA_CLUSTER_KUBECONFIG

    Replace the following:

    • CUSTOM_CA_PEM_FILE: the path to the file containing your custom CA certificates, encoded in PEM format.
    • INFRA_CLUSTER_KUBECONFIG: the path to the Infra cluster kubeconfig file.

  2. Encode the CA certificates using base64:

    export ENCODED_CA=$(cat "${CUSTOM_CA_PEM_FILE:?}" | base64 -w 0)

  3. Create the secret YAML file (custom-ca.yaml) that targets the trust-store-root-ext system trust bundle:

    cat > custom-ca.yaml <<EOF
apiVersion: v1
kind: Secret
metadata:
  annotations:
    security.private.gdc.goog/bundles: trust-store-root-ext
  name: custom-ca
  namespace: cert-manager
data:
  ca.crt: ${ENCODED_CA:?}
EOF

    The following is an example of a custom-ca.yaml file:

    apiVersion: v1
kind: Secret
metadata:
  annotations:
    security.private.gdc.goog/bundles: trust-store-root-ext
  name: custom-ca
  namespace: cert-manager
data:
   ca.crt: LS0tLS1CRUdJTiBDRVJUSUZJQ0FURS0tLS0tCk1JSU...LQWZRSUE9PQotLS0tLUVORCBDRVJUSUZJQ0FURS0tLS0tCg==

  4. Apply the secret to the Infra cluster using the kubectl command:

     kubectl apply -f custom-ca.yaml --kubeconfig ${KUBECONFIG:?}

    This step makes your custom CAs available to GDC services by automatically updating the trust-store-root-ext and trust-store-global-root-ext trust bundles.

Verify that the CAs are available

Confirm that your custom CAs were added to the trust bundle:

  1. Download the latest version of the trust-store-root-ext trust bundle by following the steps in Fetch GDC trust bundles.

    If you want to fetch the custom CAs from a different zone, use the trust-store-global-root-ext trust bundle.

  2. Open the downloaded trust bundle file and confirm that each custom CA certificate specified by CUSTOM_CA_PEM_FILE is present.

    Search for each custom CA certificate individually. The order in which they appear can vary; they're not guaranteed to appear at the end of the list.

    The following shows an example of trust-store-root-ext:

    -----BEGIN CERTIFICATE-----
MIIC8DCCAdigAwIBAgIQPLOPa...
-----END CERTIFICATE-----
... other CAs ...
-----BEGIN CERTIFICATE-----
   < Imported CA data>
-----END CERTIFICATE-----
... other CAs ...
-----BEGIN CERTIFICATE-----
MIIDAzCCAeugAwIBAgIRAIV2...
-----END CERTIFICATE-----