Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[v15] Fix Vale warnings in the Google Cloud KMS guide #49961

Merged
merged 1 commit into from
Dec 13, 2024
Merged

[v15] Fix Vale warnings in the Google Cloud KMS guide #49961

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
32 changes: 17 additions & 15 deletions docs/pages/admin-guides/deploy-a-cluster/gcp-kms.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand All @@ -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.
Expand Down Expand Up @@ -90,7 +92,7 @@ custom role and must be used in later steps.
$ export IAM_ROLE=<role name output from above>
```

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.

Expand Down Expand Up @@ -125,13 +127,13 @@ It should be considered highly privileged and access should be restricted as
much as possible.
</Admonition>

## 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
Expand All @@ -141,7 +143,7 @@ to learn how to provide them for your preferred environment.
<Details title="Manually checking permissions">

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
Expand All @@ -163,10 +165,10 @@ $ gcloud kms keys versions destroy --keyring "<Var name="teleport-keyring"/>" --

</Details>

## 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)
Expand Down Expand Up @@ -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 "<Var name="teleport-keyring"/>" --location <Var name="location"/>
Expand Down
Loading