diff --git a/docs/config.json b/docs/config.json index ebc5c1cd516..699257f6133 100644 --- a/docs/config.json +++ b/docs/config.json @@ -634,13 +634,17 @@ "slug": "/management/join-services-to-your-cluster/azure/" }, { - "title": "Joining Services via Kubernetes ServiceAccount", + "title": "Via Kubernetes ServiceAccount", "slug": "/management/join-services-to-your-cluster/kubernetes/", "forScopes": [ "oss", "enterprise" ] }, + { + "title": "Via GCP", + "slug": "/management/join-services-to-your-cluster/gcp/" + }, { "title": "Via a Join Token", "slug": "/management/join-services-to-your-cluster/join-token/" diff --git a/docs/pages/management/join-services-to-your-cluster.mdx b/docs/pages/management/join-services-to-your-cluster.mdx index a5a540091d9..2c746f9fa6a 100644 --- a/docs/pages/management/join-services-to-your-cluster.mdx +++ b/docs/pages/management/join-services-to-your-cluster.mdx @@ -17,5 +17,6 @@ Service. Choose the method that best suits your infrastructure: |[AWS IAM](./join-services-to-your-cluster/aws-iam.mdx)|A Teleport process uses AWS credentials to join the cluster, whether running on EC2 or not.|At least some of your infrastructure runs on AWS and your Teleport cluster is self hosted.| |[Azure Managed Identity](./join-services-to-your-cluster/azure.mdx)|A Teleport process demonstrates that it runs in your Azure subscription by sending a signed attested data document and access token to the Teleport Auth Service.|Your Teleport process will run on Azure.| |[Kubernetes ServiceAccount](./join-services-to-your-cluster/kubernetes.mdx)|A Teleport process uses a Kubernetes-signed proof to establish a trust relationship with your Teleport cluster.|Your Teleport process will run on Kubernetes.| +|[GCP IAM](./join-services-to-your-cluster/gcp.mdx)|A Teleport process uses a GCP-signed token to establish a trust relationship with your Teleport cluster.|Your Teleport process will run on a GCP VM.| |[Join Token](./join-services-to-your-cluster/join-token.mdx)|A Teleport process presents a join token provided when starting the service.|There is no other supported method for your cloud provider.| diff --git a/docs/pages/management/join-services-to-your-cluster/gcp.mdx b/docs/pages/management/join-services-to-your-cluster/gcp.mdx new file mode 100644 index 00000000000..a5d922d5adc --- /dev/null +++ b/docs/pages/management/join-services-to-your-cluster/gcp.mdx @@ -0,0 +1,101 @@ +--- +title: Join Services with GCP +description: Use the GCP join method to add services to your Teleport cluster. +--- + +This guide will explain how to use the **GCP join method** to configure Teleport +processes to join your Teleport cluster without sharing any secrets when they +are running in a GCP VM. + +The GCP join method is available to any Teleport process running on a GCP VM. +The VM must have a +[service account](https://cloud.google.com/compute/docs/access/create-enable-service-accounts-for-instances) +assigned to it (the default service account is fine). No IAM roles are required +on the Teleport process joining the cluster. + +## Prerequisites + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- A GCP VM to host a Teleport service, with a service account assigned to it + and with the Teleport binary installed. +- (!docs/pages/includes/tctl.mdx!) + +## Step 1/3. Create the GCP joining token + +Configure your Teleport Auth Service with a special dynamic token which will +allow services from your GCP projects to join your Teleport cluster. + +Under the hood, services will prove that they are running in your GCP project +by sending a signed ID token which matches an allow rule configured in your GCP +joining token. + +Create the following `token.yaml` file with a `gcp.allow` rule specifying your GCP +project ID(s), service account(s), and location(s) in which your GCP instances +will run: + +```yaml +# token.yaml +kind: token +version: v2 +metadata: + # the token name is not a secret because instances must prove that they are + # running in your GCP project to use this token + name: gcp-token +spec: + # use the minimal set of roles required (e.g. Node, Proxy, App, Kube, DB, WindowsDesktop) + roles: [Node] + + # set the join method allowed for this token + join_method: gcp + + gcp: + allow: + # The GCP project ID(s) that VMs can join from. + - project_ids: ["example-project-id"] + # (Optional) The locations that VMs can join from. Note: both regions and + # zones are accepted. + locations: ["us-west1", "us-west2-a"] + # (Optional) The email addresses of service accounts that VMs can join + # with. + service_accounts: ["example@example.com"] +``` + +Run the following command to create the token: + +```code +$ tctl create token.yaml +``` + +## Step 2/3. Configure your services + +The GCP join method can be used for Teleport processes running the SSH (`Node`), Proxy, +Kubernetes, Application, Database, or Windows Desktop Services. The Teleport +process should be run directly on a GCP VM. + +Configure your Teleport process with a custom `teleport.yaml` file. Use the +`join_params` section with `token_name` matching your token created in Step 1 +and `method: gcp` as shown in the following example config: + +```yaml +# /etc/teleport.yaml +version: v3 +teleport: + join_params: + token_name: gcp-token + method: gcp + proxy_server: https://teleport.example.com:443 +ssh_service: + enabled: yes +auth_service: + enabled: no +proxy_service: + enabled: no +``` + +## Step 3/3. Launch your Teleport process + +(!docs/pages/includes/start-teleport.mdx!) + +Once you have started Teleport, confirm that your service is able to connect to +and join your cluster. \ No newline at end of file