Fetch GDC trust bundles

A trust bundle, also known as a trust list, is a group of trust anchors, such as entities, that are inherently trusted and whose trust is not transferred by another entity (trusted third parties). These trust anchors are delivered as certificate authority (CA) certificates. The certification path-building algorithm uses these CA certificates to establish a chain between a certificate obtaining validation and the trust anchors.

This document is for audiences within the platform administrator group, such as IT admins or security engineers, who want to fetch GDC trust bundles. For more information, see Audiences for GDC air-gapped documentation.

Before you begin

Before fetching GDC trust bundles, you must Establish initial trust for new organizations. This step is required for both the well-known server and kubectl methods, but only if you're connecting to a new organization for the first time.

For the well-known server method, no other prerequisites are required. For the kubectl method, you must also complete the permissions and tooling prerequisites.

Establish initial trust for new organizations

If you connect to a new GDC organization for the first time, you must establish initial trust. This one-time process ensures a secure connection by trusting the organization's Certificate Authority (CA) on your client machine.

Contact a member of your infrastructure operator (IO) group to request the initial trust bundle for the new organization. The IO has the necessary access to fetch this bundle, which is typically sourced from the trust-store-root-ext secret within the org infrastructure cluster.
Obtain the initial trust bundle file from your IO through a secure channel outside of GDC, as defined by your organization's security policies.
Install the trust bundle into your client machine's trust store, following your system's standard procedures for trusting root CA certificates.

If you need access to ServiceNow, also obtain and install the gdchservices organization trust bundle using the same process.

Request IAM roles

To fetch the trust bundle with kubectl, you need permission to view secrets. Contact your Organization IAM Admin to request the Trust Store Viewer (trust-store-viewer) role.

Prepare your environment

To use the kubectl method, prepare your local environment:

Download and install the gdcloud CLI, if you haven't already done so.
Install the kubectl CLI. For more information, see Install components.
Generate a kubeconfig file for the management API server in your targeted zone. You need the path to the kubeconfig file to replace MANAGEMENT_API_SERVER_KUBECONFIG in the kubectl commands.

Trust bundle types

Distributed Cloud provides two types of managed trust bundles for platform administrators:

trust-store-root-ext: contains the internal root CA and web-tls CA. The content is different depending on where it resides, such as the root or the tenant organization. Use this trust bundle to communicate across organization boundaries or to access services like object storage within the organization.
trust-store-global-root-ext: available in the global API server and zonal API server platform namespace. When the global API server is ready, the bundle populates all other zonal trust-store-root-ext data, including local data.

Fetch the trust bundle

You can fetch trust bundles from the well-known server endpoint, or from the cluster using kubectl.

Fetch from the well-known server

GDC provides a secure way to access trust bundles through a well-known server endpoint. Use this method when you need to fetch the trust-store-global-root-ext bundle without directly interacting with the cluster using kubectl.

Make sure you have established initial trust with your organization's specific CAs before performing the steps in this section.

Linux

Export the following environment variables:
```
export STORAGE=STORAGE
export ORG_NAME=ORG_NAME
export DNS_SUFFIX=DNS_SUFFIX
```
Replace the following:
- STORAGE: the directory path where you want to store the trust bundle file.
- ORG_NAME: the name of your organization within GDC.
- DNS_SUFFIX: your DNS suffix. For example, if one of your domains is org-1.zone1.google.gdch.test, your DNS suffix is zone1.google.gdch.test.

Set the WELL_KNOWN_URL environment variable:

export WELL_KNOWN_URL="https://console.${ORG_NAME:?}.${DNS_SUFFIX:?}/.well-known/certificate-authority"

Set the GLOBAL_TRUST_BUNDLE_FILE environment variable. This file stores the GDC trust bundle locally in your specified $STORAGE location.
```
export GLOBAL_TRUST_BUNDLE_FILE="${STORAGE:?}/global/ca-bundles/global-trust-bundle"
```

Create the directory for the trust bundle file:

mkdir -p "$(dirname "${GLOBAL_TRUST_BUNDLE_FILE:?}")"

Obtain the trust-store-global-root-ext trust bundle from the well-known server and store it in the file specified by the GLOBAL_TRUST_BUNDLE_FILE environment variable:
```
curl "${WELL_KNOWN_URL:?}" | sed '$a\' > "${GLOBAL_TRUST_BUNDLE_FILE:?}"
```

Windows

Set the following PowerShell variables:
```
$STORAGE = "STORAGE"
$ORG_NAME = "ORG_NAME"
$DNS_SUFFIX = "DNS_SUFFIX"
```
Replace the following:
- STORAGE: the directory path where you want to store the trust bundle file, such as C:\Users\username\bundles.
- ORG_NAME: the name of your organization within GDC.
- DNS_SUFFIX: your DNS suffix. For example, if one of your domains is org-1.zone1.google.gdch.test, your DNS suffix is zone1.google.gdch.test.

Create the directory for the trust bundle file:

New-Item -ItemType Directory -Force -Path (Split-Path -Path "STORAGE\global\ca-bundles\global-trust-bundle")

Obtain the trust-store-global-root-ext trust bundle from the well-known server and store it in trust bundle file:

Invoke-WebRequest -Uri "https://console.ORG_NAME.DNS_SUFFIX/.well-known/certificate-authority" -OutFile "STORAGE\global\ca-bundles\global-trust-bundle"

The fetched trust bundle file contains one or more CA certificates. The output is similar to the following:

Fetch from the cluster using kubectl

You can fetch trust bundles directly from the GDC cluster using the kubectl command-line tool. Use this method if you have direct access to the cluster and its configuration, and you need to fetch either the trust-store-root-ext or the trust-store-global-root-ext trust bundles.

Make sure you have established initial trust with your organization's specific CAs before performing the steps in this section.

Fetch the trust bundle from the cluster using kubectl:

Export the following environment variables:
```
export KUBECONFIG=MANAGEMENT_API_SERVER_KUBECONFIG
export STORAGE=STORAGE
export ZONE=ZONE
```
Replace the following:
- MANAGEMENT_API_SERVER_KUBECONFIG: the path to the Management API server kubeconfig.
- STORAGE: the directory path where you want to store the trust bundle file.
- ZONE: your GDC zone name.

Set the TRUST_BUNDLE_FILE environment variable. This file stores the GDC trust bundle locally in your specified $STORAGE location for your GDC $ZONE:

export TRUST_BUNDLE_FILE="${STORAGE:?}/${ZONE:?}/ca-bundles/trust-bundle"
export GLOBAL_TRUST_BUNDLE_FILE="${STORAGE:?}/global/ca-bundles/global-trust-bundle"

Set the NS namespace environment variable for the namespace:
```
export NS=platform
```

Create the directories for the trust bundle files:

mkdir -p "$(dirname "${TRUST_BUNDLE_FILE:?}")"
mkdir -p "$(dirname "${GLOBAL_TRUST_BUNDLE_FILE:?}")"

Obtain the certificate authorities (CA) and store them in the files specified by the TRUST_BUNDLE_FILE and GLOBAL_TRUST_BUNDLE_FILE environment variables:

For trust-store-root-ext:

kubectl --kubeconfig ${KUBECONFIG:?} get secret trust-store-root-ext -n ${NS:?} -o go-template='{{ index .data "ca.crt" }}' | base64 -d | sed '$a\' > ${TRUST_BUNDLE_FILE:?}

For trust-store-global-root-ext:

kubectl --kubeconfig ${KUBECONFIG:?} get secret trust-store-global-root-ext -n ${NS:?} -o go-template='{{ index .data "ca.crt" }}' | base64 -d | sed '$a\' > ${GLOBAL_TRUST_BUNDLE_FILE:?}