Skip to content

Commit

Permalink
Simplify Machine ID "Getting Started" guide (#47554)
Browse files Browse the repository at this point in the history
* Simplify Machine ID "Getting Started" guide

* Update docs/pages/enroll-resources/machine-id/getting-started.mdx

Co-authored-by: Paul Gottschling <[email protected]>

---------

Co-authored-by: Paul Gottschling <[email protected]>
  • Loading branch information
strideynet and ptgott authored Oct 16, 2024
1 parent bd6fdbf commit b191e6d
Showing 1 changed file with 25 additions and 73 deletions.
98 changes: 25 additions & 73 deletions docs/pages/enroll-resources/machine-id/getting-started.mdx
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -74,55 +85,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`.

<Tabs>
<TabItem label="Token-based Joining">
```code
$ tctl bots add robot --roles=access --logins=root
```
</TabItem>
<TabItem label="IAM Method">
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-*"
```

Next, create the bot user.
Use `tctl bots add` to create our bot:

```
$ tctl bots add robot --token=iam-token --roles=access --logins=root
```
</TabItem>
</Tabs>
```code
$ tctl bots add robot --roles=access --logins=root
```

## Step 3/4. Start Machine ID

Expand All @@ -135,34 +106,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.

<Tabs>
<TabItem label="Token-based Joining">

```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
```

</TabItem>
<TabItem label="IAM Method">

```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
```

</TabItem>
</Tabs>
```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
Expand Down

0 comments on commit b191e6d

Please sign in to comment.