diff --git a/docs/pages/machine-workload-identity/mwi_tbot_aws_guide.mdx b/docs/pages/machine-workload-identity/mwi_tbot_aws_guide.mdx new file mode 100644 index 0000000000000..5969c6455023e --- /dev/null +++ b/docs/pages/machine-workload-identity/mwi_tbot_aws_guide.mdx @@ -0,0 +1,298 @@ +--- +title: Deploying tbot with Workload Identity on AWS +description: How to deploy a tbot and configure Workload Identity on an AWS EC2 instance +tags: + - how-to + - get-started + - mwi + - infrastructure-identity + - aws +--- + +{/* lint disable page-structure remark-lint */} + +This guide walks you through deploying `tbot` on an Amazon EC2 instance and setting up Machine and Workload Identity (MWI). +By the end, you'll have a working `tbot` service that issues SPIFFE-compatible credentials to workloads running on your EC2 instance. + +## Prerequisites + +(!docs/pages/includes/edition-prereqs-tabs.mdx!) + +- (!docs/pages/includes/tctl.mdx!) +- An AWS IAM role that you wish to grant access to your Teleport cluster. This + role must be granted `sts:GetCallerIdentity`. In this guide, this role will + be named `teleport-bot-role`. +- An AWS EC2 virtual machine that you wish to install Machine ID onto configured + with the IAM role attached. + +## Step 1/9. Install `tbot` + +**This step is completed on the AWS EC2 instance.** + +Install `tbot` on the EC2 instance that will use Machine ID. + +Download and install the appropriate Teleport package for your platform: + +(!docs/pages/includes/install-linux.mdx!) + +## Step 2/9. Create a Bot + +**This step is completed on your local machine.** + +(!docs/pages/includes/machine-id/create-a-bot.mdx!) + +## Step 3/9. Create a join token + +**This step is completed on your local machine.** + +Create `bot-token.yaml`: + +```yaml +kind: token +version: v2 +metadata: + # name will be specified in the `tbot` to use this token + name: example-bot +spec: + roles: [Bot] + # bot_name should match the name of the bot created earlier in this guide. + bot_name: example + join_method: iam + # 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. + allow: + - aws_account: "111111111111" + aws_arn: "arn:aws:sts::111111111111:assumed-role/teleport-bot-role/i-*" +``` + +Replace: + +- `111111111111` with the ID of your AWS account. +- `teleport-bot-role` with the name of the AWS IAM role you created and assigned + to the EC2 instance. +- `example` with the name of the bot you created in the second step. +- `i-*` indicates that any instance with the specified role can use the join + method. If you wish to restrict this to an individual instance, replace `i-*` + with the full instance ID. + +Use `tctl` to apply this file: + +```code +$ tctl create -f bot-token.yaml +``` + +## Step 4/9. Configure `tbot` + +**This step is completed on the AWS EC2 instance.** + +Create `/etc/tbot.yaml`: + +```yaml +version: v2 +proxy_server: example.teleport.sh:443 +onboarding: + join_method: iam + token: example-bot +storage: + type: memory +# outputs will be filled in during the completion of an access guide. +outputs: [] +``` + +Replace: + +- `example.teleport.sh:443` with the address of your Teleport Proxy Service or + Auth Service. Prefer using the address of a Teleport Proxy Service instance. +- `example-bot` with the name of the token you created in the second step. + +(!docs/pages/includes/machine-id/daemon-or-oneshot.mdx!) + +## Step 5/9. Configure outputs + +(!docs/pages/includes/machine-id/configure-outputs.mdx!) + +## Step 6/9. Configure Workload Identity + +Next, we'll configure Workload Identity on the target resource you just created. +A Workload Identity defines how a specific workload, or group of workloads, receives SPIFFE-based credentials from Teleport. + +You’ll: + +- Create a Workload Identity resource that defines your workload’s SPIFFE ID. +- Configure RBAC so your Bot can issue credentials for that identity. +- Update your tbot instance to expose a SPIFFE Workload API endpoint that workloads can connect to for SPIFFE SVID-compatible credentials. + +Before proceeding, you'll want to determine the SPIFFE ID path that your workload will use. In our example, we'll use `/svc/foo`. We provide more +guidance on choosing a SPIFFE ID structure in the [Best Practices](./workload-identity/best-practices.mdx) guide. + +Create a new file called `workload-identity.yaml`: + +```yaml +kind: workload_identity +version: v1 +metadata: + name: example-workload-identity + labels: + example: getting-started +spec: + spiffe: + id: /svc/foo +``` + +Replace: + +- `example-workload-identity` with a name that describes your use-case. +- `/svc/foo` with the SPIFFE ID path you have decided on issuing. + +Use `tctl create -f ./workload-identity.yaml` to create the Workload Identity. + +You'll need to create a role that will grant access to the Workload Identity +that you have just created. As with other Teleport resources, access is granted +by specifying label matchers on the role that will match the labels on the +resource itself. + +In addition to granting access to the resource, we will also need to grant the +ability to read and list the Workload Identity resource type. + +Create `workload-identity-issuer-role.yaml`: + +```yaml +kind: role +version: v6 +metadata: + name: example-workload-identity-issuer +spec: + allow: + workload_identity_labels: + example: ["getting-started"] + rules: + - resources: + - workload_identity + verbs: + - list + - read +``` + +Use `tctl create -f ./workload-identity-issuer-role.yaml` to create the role. + +Now, use `tctl bots update` to add the role to the Bot. Replace `example-bot` +with the name of the Bot you created in the deployment guide and +`example-workload-identity-issuer` with the name of the role you just created: + +```code +$ tctl bots update example-bot --add-roles example-workload-identity-issuer +``` + +## Step 7/9. Expose a Workload API endpoint + +Configure `workload-identity-api` service in `tbot`. To issue SPIFFE credentials to workloads, +`tbot` must expose a Workload API endpoint.You’ll configure this by adding the `workload-identity-api` +service to your `tbot` configuration. + +First, determine where you wish this socket to be created. In our example, +we'll use `/opt/machine-id/workload.sock`. You may wish to choose a directory +that is only accessible by the processes that will need to connect to the +Workload API. + +Modify your `tbot` configuration file to include the `workload-identity-api` service: + +```yaml +services: +- type: workload-identity-api + listen: unix:///opt/machine-id/workload.sock + selector: + name: example-workload-identity +``` + +Replace: + +- `/opt/machine-id/workload.sock` with the path to the socket you wish to create. +- `example-workload-identity` with the name of the Workload Identity resource you + created earlier. + +Start or restart your `tbot` instance to apply the new configuration. + +## Step 8/9. Testing the Workload API with `tbot spiffe-inspect` + +Use `tbot spiffe-inspect` to verify that the Workload API endpoint is issuing SPIFFE credentials correctly. +This command connects to the endpoint, requests SVIDs, and prints detailed debug information. + +Before configuring your workload to use the Workload API, we recommend using +this command to ensure that the Workload API is behaving as expected. + +Use the `spiffe-inspect` command with `--path` to specify the path to the +Workload API socket, replacing `/opt/machine-id/workload.sock` with the path you +configured in the previous step: + +```code +$ tbot spiffe-inspect --path unix:///opt/machine-id/workload.sock +INFO [TBOT] Inspecting SPIFFE Workload API Endpoint unix:///opt/machine-id/workload.sock tbot/spiffe.go:31 +INFO [TBOT] Received X.509 SVID context from Workload API bundles_count:1 svids_count:1 tbot/spiffe.go:46 +SVIDS +- spiffe://example.teleport.sh/svc/foo + - Expiry: 2024-03-20 10:55:52 +0000 UTC +Trust Bundles +- example.teleport.sh +``` + +## Step 9/9. Configuring your workload to use the Workload API + +Now that you know that the Workload API is behaving as expected, you can +configure your workload to use it. The exact steps will depend on the workload. + +In cases where you have used the SPIFFE SDKs, you can configure the +`SPIFFE_ENDPOINT_SOCKET` environment variable to point to the socket created by `tbot`. + +### Configuring Unix Workload Attestation + +By default, an SVID listed under the Workload API service will be issued to any +workload that connects to the Workload API. You may wish to restrict which SVIDs +are issued based on certain characteristics of the workload. This is known as +Workload Attestation. + +When using the Unix listener, `tbot` supports workload attestation based on +three characteristics of the workload process: + +- `uid`: The UID of the user that the workload process is running as. +- `gid`: The primary GID of the user that the workload process is running as. +- `pid`: The PID of the workload process. + +Within a Workload Identity, you can configure rules based on the attributes +determined via workload attestation. Each rule contains a number of tests and +all tests must pass for the rule to pass. At least one rule must pass for the +Workload Identity to be allowed to issue a credential. + +For example, to configure a Workload Identity to be issued only to workloads that +are running as the user with ID 1000 or running as a user with a primary group +ID of 50: + +```yaml +kind: workload_identity +version: v1 +metadata: + name: example-workload-identity + labels: + example: getting-started +spec: + rules: + allow: + - conditions: + - attribute: workload.unix.uid + eq: + value: 1000 + - conditions: + - attribute: workload.unix.gid + eq: + value: 50 + spiffe: + id: /svc/foo +``` + + +## Next steps + +- Read the [configuration reference](../reference/machine-workload-identity/machine-id/configuration.mdx) to explore + all the available configuration options. +- [More information about `TELEPORT_ANONYMOUS_TELEMETRY`.](../reference/machine-workload-identity/machine-id/telemetry.mdx) +