Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Simplify Machine ID "Getting Started" guide #47554

Merged
merged 2 commits into from
Oct 16, 2024
Merged
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
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 @@ -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`.

<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-*"
```
Use `tctl bots add` to create our bot:

Next, create the bot user.

```
$ 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 @@ -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.

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