[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
gravitational · Jul 11, 2022 · 418cd3e · 418cd3e
1 parent 38321e8
commit 418cd3e
Showing 1 changed file with 74 additions and 23 deletions.
diff --git 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!)
 
-<Admonition type="note" title="Machine ID and TLS Routing">
-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
+<Admonition 
+type="note" 
+title="Machine ID and TLS Routing" 
+scopeOnly scope={["oss", "enterprise"]}
+>
+
+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.
 
 <Tabs>
   <TabItem label="Token-based Joining">
+
+  <ScopedBlock scope={["oss", "enterprise"]}>
+
   ```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
   ```
+
+  </ScopedBlock>
+  <ScopedBlock scope={["cloud"]}>
+
+  ```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
+  ```
+
+  </ScopedBlock>
+
   </TabItem>
   <TabItem label="IAM Method">
+
+  <ScopedBlock scope={["oss", "enterprise"]}>
+
   ```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
   ```
+
+  </ScopedBlock>
+  <ScopedBlock scope={["cloud"]}>
+
+  ```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
+  ```
+
+  </ScopedBlock>
+
   </TabItem>
 </Tabs>
 
 Replace the following fields with values from your own cluster.
 
 <ScopedBlock scope={["cloud"]}>
-- `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`.
+
 </ScopedBlock>
 <ScopedBlock scope={["oss","enterprise"]}>
-- `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`). 
+
 </ScopedBlock>
 
 Now that Machine ID has successfully started, let's investigate the