diff --git a/docs/pages/admin-guides/deploy-a-cluster/gcp-kms.mdx b/docs/pages/admin-guides/deploy-a-cluster/gcp-kms.mdx index 383f20e2fd721..c69d3e0742a14 100644 --- a/docs/pages/admin-guides/deploy-a-cluster/gcp-kms.mdx +++ b/docs/pages/admin-guides/deploy-a-cluster/gcp-kms.mdx @@ -8,8 +8,10 @@ This guide will show you how to set up your Teleport Cluster to use the Google Cloud Key Management Service (KMS) to store and handle the CA private key material used to sign all certificates issued by your Teleport cluster. +## How it works + Teleport generates private key material for its internal Certificate Authorities -(CAs) during the first Auth Server's initial startup. +(CAs) during the first Auth Service instance's initial startup. These CAs are used to sign all certificates issued to clients and hosts in the Teleport cluster. When configured to use Google Cloud KMS, all private key material for these CAs @@ -35,12 +37,12 @@ learn more. ## Step 1/5. Create a key ring in GCP -Each Teleport Auth Server will need to be configured to use a GCP key ring -which will hold all keys generated and used by that Auth Server. +Each Teleport Auth Service instance will need to be configured to use a GCP key +ring which will hold all keys generated and used by that Auth Service instance. If running a High-Availability Teleport cluster with two or more Auth Servers, -every Auth Server can be configured to use the same key ring, or if desired each -can be configured to use a unique key ring in a different region (for redundancy -or to decrease latency). +every Auth Service instance can be configured to use the same key ring, or if +desired each can be configured to use a unique key ring in a different region +(for redundancy or to decrease latency). It is recommended to create a dedicated key ring for use by Teleport to logically separate it from any other keys in your cloud account. @@ -90,7 +92,7 @@ custom role and must be used in later steps. $ export IAM_ROLE= ``` -If you don't already have a GCP service account for your Teleport Auth Server +If you don't already have a GCP service account for your Teleport Auth Service you can create one with the following command, otherwise use your existing service account. @@ -125,13 +127,13 @@ It should be considered highly privileged and access should be restricted as much as possible. -## Step 3/5. Provide the service account credentials to your Auth Server +## Step 3/5. Provide the service account credentials to the Auth Service -The Teleport Auth Server will use Application Default Credentials to make +The Teleport Auth Service will use Application Default Credentials to make requests to the GCP KMS service. Provide credentials for the `teleport-auth-server` service account created in step 2 to the Application Default Credentials of the environment you are running -your Teleport Auth Server in. +your Teleport Auth Service in. Supported environments include GCE VMs, GKE pods, and others. See the GCP docs for @@ -141,7 +143,7 @@ to learn how to provide them for your preferred environment.
To make sure the credentials have been configured correctly, you can run the -`gcloud` CLI tool from your Teleport Auth Server's environment. Some example +`gcloud` CLI tool from your Teleport Auth Service's environment. Some example commands you could use to debug are listed here: ```code @@ -163,10 +165,10 @@ $ gcloud kms keys versions destroy --keyring "" --
-## Step 4/5. Configure your Auth Server to use KMS keys +## Step 4/5. Configure the Auth Service to use KMS keys CA key parameters are statically configured in the `teleport.yaml` configuration -file of the Teleport Auth Server(s) in your cluster. +file of the Teleport Auth Service instances in your cluster. Find the fully qualified name of the KMS key ring you created in [step 1](#step-15-create-a-key-ring-in-gcp) @@ -220,9 +222,9 @@ KMS keys, read on to ## Step 5/5. Make sure everything is working -After starting up your Auth Server with the `gcp_kms` configuration, you can +After starting up your Auth Service with the `gcp_kms` configuration, you can confirm that Teleport has generated keys in your keyring in the GCP Console or -by running +by running: ```code $ gcloud kms keys list --keyring "" --location