Backport #10775 to branch/v9

docs/config.json

@@ -526,6 +526,20 @@
         }
       ]
     },
+    {
+      "icon": "wand",
+      "title": "Machine ID",
+      "entries": [
+        {
+          "title": "Introduction",
+          "slug": "/machine-id/introduction/"
+        },
+        {
+          "title": "Getting Started",
+          "slug": "/machine-id/getting-started/"
+        }
+      ]
+    },
     {
       "icon": "lock",
       "title": "Access Controls",
@@ -1024,4 +1038,4 @@
       "permanent": true
     }
   ]
-}
+}

docs/pages/machine-id/getting-started.mdx

@@ -0,0 +1,244 @@
+---
+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.
+
+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
+
+## Prerequisites
+
+Before using Machine ID, you will need an existing Teleport cluster or a
+Teleport Cloud account.
+
+If you have not set up a Teleport cluster before, follow the
+[Getting started](https://goteleport.com/docs/getting-started) guide.
+
+## Step 1/4. Download and install Teleport (=teleport.version=)
+
+In this step, you will be downloading and installing Teleport binaries onto the
+machine you wish to assign an identity to. 
+
+Each Teleport package hosted on our
+downloads page ships with several useful binaries, including `teleport`,
+`tctl`, `tsh`, and `tbot`:
+
+- `teleport` is the daemon used to initialize a Teleport cluster; this binary is not used in this guide
+- `tctl` is the administrative tool you will use to create the bot user (step 1/4)
+- `tsh` is the client tool you will use to log in to the Teleport Cluster (steps 2/4 and 4/4)
+- `tbot` is the Machine ID tool you will use to associate a bot user with a machine (step 3/4)
+
+Machine ID is available starting from the Teleport `9.0.0` release. Download
+the appropriate Teleport package for your platform from our
+[downloads page](https://goteleport.com/teleport/download).
+
+## Step 2/4. Create a bot user
+
+Before you create a bot user, you need to determine which role(s) you want to
+assign to it. You can use the `tctl` command below to examine what roles exist
+on your system.
+
+<Details scope={["cloud"]} scopeOnly={true}>
+On your client machine, log in to Teleport using `tsh`, then use `tctl` to examine
+what roles exist on your system.
+</Details>
+<Details scope={["oss","enterprise"]} scopeOnly={true}>
+Connect to the Teleport Auth Server and use `tctl` to examine what roles exist on
+your system.
+</Details>
+
+```code
+$ tctl get roles --format=text
+```
+
+You will see something like the output below on a fresh install of Teleport with the
+default roles—your cluster may have different roles. In this example, let's
+assume you want to give the bot the `access` role to allow it to connect to
+machines within your cluster.
+
+```
+Role    Allowed to login as                           Node Labels Access to resources
+------- --------------------------------------------- ----------- ----------------------------------------
+access  {{internal.logins}}                           <all nodes> event:list,read,session:read,list
+auditor no-login-6566121f-b602-47f1-a118-c9c618ee5aec             session:list,read,event:list,read
+editor                                                            user:list,create,read,update,delete,...
+```
+
+Machine ID can join with a token or the [IAM Method](https://goteleport.com/docs/setup/guides/joining-nodes-aws) on AWS.
+
+<Tabs>
+  <TabItem label="Token-based Joining">
+  ```code
+  $ tctl bots add robot --roles=access
+  ```
+  </TabItem>
+  <TabItem label="IAM Method">
+  First, create an IAM method token that specifies the AWS account from which
+  the bot can join.
+
+  ```
+  kind: token
+  version: v2
+  metadata:
+    # The token name is not a secret because instances must prove that they are
+    # running in your AWS account to use this token.
+    name: iam-token
+    # Set a long expiry time for how long you want to support IAM method for
+    # joining. It is safe to set this value to a very long time.
+    expires: "3000-01-01T00:00:00Z"
+  spec:
+    # Only allow bots to join using this token.
+    roles: [Bot]
+
+    # Set the join method to be IAM.
+    join_method: iam
+
+    # Define the name of the bot that will be allowed to use this token. Note,
+    # the "bot-" prefix is required. The name of the bot you will create is "robot".
+    bot_name: bot-robot
+
+    allow:
+    # Restrict the AWS account and (optionally) ARN that can use this token.
+    # This information can be obtained from running the
+    # "aws sts get-caller-identity" command from the CLI.
+    - aws_account: "111111111111"
+      aws_arn: "arn:aws:sts::111111111111:assumed-role/teleport-bot-role/i-*"
+  ```
+
+  Next, create the bot user.
+
+  ```
+  $ tctl bots add robot --token=iam-token --roles=access
+  ```
+  </TabItem>
+</Tabs>
+
+## Step 3/4. Start Machine ID
+
+Now start Machine ID using the `tbot` binary. The `tbot start` command will
+start running Machine ID in a loop, writing renewable certificates to
+`/var/lib/teleport` and the short-lived certificates your application will use
+to `/opt/machine-id`.
+
+In a production environment you will want to run Machine ID in the background
+using a service manager like systemd. However, in this guide you will run it in
+the foreground to better understand how it works.
+
+<Tabs>
+  <TabItem label="Token-based Joining">
+  ```code
+  $ tbot start \
+     --data-dir=/var/lib/teleport \
+     --destination-dir=/opt/machine-id \
+     --token=00000000000000000000000000000000 \
+     --join-method=token \
+     --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \
+     --auth-server=auth.example.com:3025
+  ```
+  </TabItem>
+  <TabItem label="IAM Method">
+  ```code
+  $ tbot start \
+     --data-dir=/var/lib/teleport \
+     --destination-dir=/opt/machine-id \
+     --token=iam-token \
+     --join-method=iam \
+     --ca-pin=sha256:1111111111111111111111111111111111111111111111111111111111111111 \
+     --auth-server=auth.example.com:3025
+  ```
+  </TabItem>
+</Tabs>
+
+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.
+<Details scope={["cloud"]} scopeOnly={true}>
+- `auth-server` is the address of your Teleport Auth Server
+</Details>
+<Details scope={["oss","enterprise"]} scopeOnly={true}>
+- `auth-server` is the address of your Teleport Cloud Proxy Server
+</Details>
+
+Now that Machine ID has successfully started, let's investigate the
+`/opt/machine-id` directory to see what was written to disk.
+
+```
+$ tree /opt/machine-id
+machine-id
+├── key
+├── key.pub
+├── known_hosts
+├── ssh_config
+├── sshcacerts
+├── sshcert
+├── tlscacerts
+└── tlscert
+
+0 directories, 8 files
+```
+
+This directory contains private key material in the `key.*` files, SSH
+certificates in the `ssh*` files, X.509 certificates in the `tls*` files, and
+OpenSSH configuration in the `ssh_config` and `known_hosts` files to make it easy
+to integrate Machine ID with external applications and tools.
+
+## Step 4/4. Use certificates issued by Machine ID
+
+To use Machine ID, find a host that you want to connect to within your cluster
+using `tsh ls`. You might see output like the following on your system.
+
+```code
+$ tsh ls
+Node Name Address        Labels                        
+--------- -------------- ----------------------------- 
+node-name  127.0.0.1:3022 arch=x86_64,group=api-servers 
+```
+
+To use Machine ID with the OpenSSH integration, run the following command to
+connect to `node-name` within cluster `example.com`.
+
+```
+ssh -F /opt/machine-id/ssh_config [email protected]
+```
+
+<Admonition type="note" title="Roles must have logins defined">
+  If you see the below error, it means the user you are trying to log in as is
+  not specified under `logins` in the role you are using. If you have been
+  following along with the `access` role, run
+  `tctl get roles/access > access.yaml`, update the `logins` field, and update
+  your role with `tctl create -f access.yaml`.
+
+  ```code
+  $ ssh -F /opt/machine-id/ssh_config root@node-name
+  root@node-name: Permission denied (publickey).
+  kex_exchange_identification: Connection closed by remote host
+  ```
+</Admonition>
+
+Now you can replace any invocations of `ssh` with the above command to provide
+your applications and tools a machine identity that can be rotated, audited,
+and controlled with all the familiar Teleport access controls.
+
+{
+/*
+TODO(russjones): Once we have other links, include them here.
+
+## Next Steps
+
+For the next steps, dive deeper into the topics relevant to your Machine ID use-case, for example:
+
+* Check out configuration [guides](./guides.mdx).
+* See [frequently asked questions](./faq.mdx).
+
+*/
+}

docs/pages/machine-id/introduction.mdx

@@ -0,0 +1,56 @@
+---
+title: Machine ID
+description: Teleport Machine ID introduction, demo and resources.
+---
+
+# Machine ID
+
+Machine ID is a service that programmatically issues and renews short-lived
+certificates to any service account (e.g., a CI/CD server) by retrieving
+credentials from the Teleport Auth Service. This enables fine-grained
+role-based access controls and audit.
+
+Some of the things you can do with Machine ID:
+
+- Machines can retrieve short-lived SSH certificates for CI/CD pipelines.
+- Machines can retrieve short-lived X.509 certificates for use with databases or applications.
+- Configure role-based access controls and locking for machines.
+- Capture access events in the audit log.
+
+{
+/*
+TODO(russjones): Once we have a demo video for Machine ID, include it here.
+
+## Demo
+
+Let's create a bot and use the machine identity to connect to a server.
+
+<video
+  autoPlay
+  loop
+  muted
+  playsInline
+  controls
+>
+  <source
+    src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.mp4"
+    type="video/mp4"
+  />
+
+  <source
+    src="https://goteleport.com/teleport/videos/database-access-preview/dbaccessdemo.webm"
+    type="video/webm"
+  />
+
+  Your browser does not support the video tag.
+</video>
+*/
+}
+
+## Getting started
+
+<TileSet>
+  <Tile icon="wand" title="Getting started" href="./getting-started.mdx">
+    Getting started with Teleport Machine ID
+  </Tile>
+</TileSet>