From 418cd3e662e3226298697801195ec7a571a8ce11 Mon Sep 17 00:00:00 2001 From: Paul Gottschling Date: Mon, 11 Jul 2022 15:39:29 -0400 Subject: [PATCH] [v9] Edit the Machine ID getting started guide (#13694) * Edit the Machine ID getting started guide Fixes #11806 - Add more scope-specific information to the Prerequisites section - Add the tctl.mdx partial to make it clearer for each scope how to connect to the cluster to run tctl commands. - Add the Cloud tenant address to the "tbot start" example command for Cloud users. * Respond to PR feedback --- docs/pages/machine-id/getting-started.mdx | 97 +++++++++++++++++------ 1 file changed, 74 insertions(+), 23 deletions(-) diff --git a/docs/pages/machine-id/getting-started.mdx b/docs/pages/machine-id/getting-started.mdx index be1421cdcbbcc..b50dfec040c33 100644 --- a/docs/pages/machine-id/getting-started.mdx +++ b/docs/pages/machine-id/getting-started.mdx @@ -3,15 +3,16 @@ title: Machine ID Getting Started Guide description: Getting started with Teleport Machine ID --- -In this getting started guide, you will use Machine ID to create a bot user for -a machine and use that identity to connect to said machine. +In this getting started guide, you will configure Machine ID to issue +certificates that enable a bot user to connect to a remote host. Here's an overview of what you will do: -1. Download and install Teleport (=teleport.version=) -2. Create a bot user -3. Start Machine ID -4. Use certificates issued by Machine ID to connect to a remote machine +1. Download and install `tbot` (=teleport.version=) on the host that will run + Machine ID. +2. Create a bot user. +3. Start Machine ID. +4. Use certificates issued by Machine ID to connect to a remote machine. ## Prerequisites @@ -21,10 +22,15 @@ Here's an overview of what you will do: (!/docs/pages/includes/tctl.mdx!) - -TLS Routing support will be added to Machine ID in [Teleport -9.3](https://goteleport.com/docs/preview/upcoming-releases/#teleport-93). Until -that time, the Teleport Proxy Server will need to be configured with a + + +TLS Routing support was added to Machine ID in [Teleport +9.3](https://goteleport.com/docs/preview/upcoming-releases/#teleport-93). For +earlier versions, the Teleport Proxy Server will need to be configured with a dedicated SSH listener. ```yaml @@ -148,44 +154,89 @@ the foreground to better understand how it works. + + + ```code $ tbot start \ --data-dir=/var/lib/teleport/bot \ --destination-dir=/opt/machine-id \ - --token=00000000000000000000000000000000 \ + --token=(=presets.tokens.first=) \ --join-method=token \ - --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ + --ca-pin=(=presets.ca_pin=) \ --auth-server=auth.example.com:3025 ``` + + + + + ```code + $ tbot start \ + --data-dir=/var/lib/teleport/bot \ + --destination-dir=/opt/machine-id \ + --token=(=presets.tokens.first=) \ + --join-method=token \ + --ca-pin=(=presets.ca_pin=) \ + --auth-server=example.teleport.sh:443 + ``` + + + + + + ```code $ tbot start \ --data-dir=/var/lib/teleport/bot \ --destination-dir=/opt/machine-id \ --token=iam-token \ --join-method=iam \ - --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \ + --ca-pin=(=presets.ca_pin=) \ --auth-server=auth.example.com:3025 ``` + + + + + ```code + $ tbot start \ + --data-dir=/var/lib/teleport/bot \ + --destination-dir=/opt/machine-id \ + --token=iam-token \ + --join-method=iam \ + --ca-pin=(=presets.ca_pin=) \ + --auth-server=example.teleport.sh:443 + ``` + + + Replace the following fields with values from your own cluster. -- `token` is the token output by the `tctl bots add` command or the name of your IAM method token -- `ca-pin` is the CA Pin for your Teleport cluster, and is output by the `tctl bots add` command -- `destination-dir` is where Machine ID writes renewable certificates, which are only used by Machine ID and should not be used by applications and tools -- `data-dir` is where Machine ID writes the short-lived certificate. This certificate should be used by applications and tools -- `auth-server` is the address of your Teleport Cloud Proxy Server, for example `example.teleport.sh:443` + +- `token` is the token output by the `tctl bots add` command or the name of your IAM method token. +- `ca-pin` is the CA Pin for your Teleport cluster, and is output by the `tctl bots add` command. +- `destination-dir` is where Machine ID writes renewable certificates, which are only used by Machine ID and should not be used by applications and tools. +- `data-dir` is where Machine ID writes the short-lived certificate. This certificate should be used by applications and tools. +- `auth-server` is the address of your Teleport Cloud Proxy Server, for example `example.teleport.sh:443`. + -- `token` is the token output by the `tctl bots add` command or the name of your IAM method token -- `ca-pin` is the CA Pin for your Teleport cluster, and is output by the `tctl bots add` command -- `destination-dir` is where Machine ID writes renewable certificates, which are only used by Machine ID and should not be used by applications and tools -- `data-dir` is where Machine ID writes the short-lived certificate. This certificate should be used by applications and tools -- `auth-server` is the address of your Teleport Auth Server, for example `auth.example.com:3025` + +- `token` is the token output by the `tctl bots add` command or the name of your IAM method token. +- `ca-pin` is the CA Pin for your Teleport cluster, and is output by the `tctl bots add` command. +- `destination-dir` is where Machine ID writes renewable certificates, which are only used by Machine ID and should not be used by applications and tools. +- `data-dir` is where Machine ID writes the short-lived certificate. This certificate should be used by applications and tools. +- `auth-server` is the address of your Teleport Auth Server, for example + `auth.example.com:3025`. If your Machine ID host is in a different network + than your Auth Server, use the public web address of your Proxy Service + instead (e.g., `auth.example.com:443`). + Now that Machine ID has successfully started, let's investigate the