From f81da23d2e892c2a278507055dc75cd1dc4eae1b Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Mon, 14 Oct 2024 14:05:52 +0100 Subject: [PATCH 1/2] Simplify Machine ID "Getting Started" guide --- .../machine-id/getting-started.mdx | 98 +++++-------------- 1 file changed, 25 insertions(+), 73 deletions(-) diff --git a/docs/pages/enroll-resources/machine-id/getting-started.mdx b/docs/pages/enroll-resources/machine-id/getting-started.mdx index dfdaf84dc424..7f7d72fa32d2 100644 --- a/docs/pages/enroll-resources/machine-id/getting-started.mdx +++ b/docs/pages/enroll-resources/machine-id/getting-started.mdx @@ -43,7 +43,18 @@ Download the appropriate Teleport package for your platform: (!docs/pages/includes/install-linux.mdx!) -## Step 2/4. Create a bot user +## Step 2/4. Create a Bot + +In Teleport, a **Bot** represents an identity for a machine. This is similar to +how a user represents the identity of a human. Like users, bots are assigned +roles to manage their access to resources. However, unlike users, bots do not +authenticate using a username and password or SSO, instead they initially +authenticate in a process called joining. + +Teleport supports a number of secure join methods specific to the platform the +bot is running on, but for the purposes of this guide, we will use the simpler +`token` join method. You can follow a deployment guide later to learn about the +secure join methods available for your platform. 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 @@ -83,55 +94,15 @@ database. For full details on how traits work in Teleport roles, see the [Teleport Access Controls Reference](../../reference/access-controls/roles.mdx). -Machine ID can join with a token or the [IAM Method](../agents/join-services-to-your-cluster/aws-iam.mdx) on AWS. - Assuming that you are using the default `access` role, ensure that you use the `--logins` flag when adding your bot to specify the SSH logins that you wish to allow the bot to access on hosts. For our example, we will be using `root`. - - - ```code - $ tctl bots add robot --roles=access --logins=root - ``` - - - First, create an IAM method token that specifies the AWS account from which - the bot can join. Create the below file as `iam-token.yaml` then run `tctl - create -f iam-token.yaml`. - - ``` - 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 - 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. - bot_name: 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-*" - ``` +Use `tctl bots add` to create our bot: - Next, create the bot user. - - ``` - $ tctl bots add robot --token=iam-token --roles=access --logins=root - ``` - - +```code +$ tctl bots add robot --roles=access --logins=root +``` ## Step 3/4. Start Machine ID @@ -144,34 +115,15 @@ 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. - - - - ```code - $ export TELEPORT_ANONYMOUS_TELEMETRY=1 - $ sudo tbot start \ - --data-dir=/var/lib/teleport/bot \ - --destination-dir=/opt/machine-id \ - --token=(=presets.tokens.first=) \ - --join-method=token \ - --proxy-server=example.teleport.sh:443 - ``` - - - - - ```code - $ export TELEPORT_ANONYMOUS_TELEMETRY=1 - $ sudo tbot start \ - --data-dir=/var/lib/teleport/bot \ - --destination-dir=/opt/machine-id \ - --token=iam-token \ - --join-method=iam \ - --proxy-server=example.teleport.sh:443 - ``` - - - +```code +$ export TELEPORT_ANONYMOUS_TELEMETRY=1 +$ sudo tbot start \ + --data-dir=/var/lib/teleport/bot \ + --destination-dir=/opt/machine-id \ + --token=(=presets.tokens.first=) \ + --join-method=token \ + --proxy-server=example.teleport.sh:443 +``` `TELEPORT_ANONYMOUS_TELEMETRY` enables the submission of anonymous usage telemetry. This helps us shape the future development of `tbot`. You can disable From 9c32f3fd8d31e29733ff18bf943643648d1460d5 Mon Sep 17 00:00:00 2001 From: Noah Stride Date: Wed, 16 Oct 2024 10:33:50 +0100 Subject: [PATCH 2/2] Update docs/pages/enroll-resources/machine-id/getting-started.mdx Co-authored-by: Paul Gottschling --- docs/pages/enroll-resources/machine-id/getting-started.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/pages/enroll-resources/machine-id/getting-started.mdx b/docs/pages/enroll-resources/machine-id/getting-started.mdx index 7f7d72fa32d2..ea7319a9dc2c 100644 --- a/docs/pages/enroll-resources/machine-id/getting-started.mdx +++ b/docs/pages/enroll-resources/machine-id/getting-started.mdx @@ -48,7 +48,7 @@ Download the appropriate Teleport package for your platform: In Teleport, a **Bot** represents an identity for a machine. This is similar to how a user represents the identity of a human. Like users, bots are assigned roles to manage their access to resources. However, unlike users, bots do not -authenticate using a username and password or SSO, instead they initially +authenticate using a username and password or SSO. Instead, they initially authenticate in a process called joining. Teleport supports a number of secure join methods specific to the platform the