docs: Getting started guide to set up tbot and workload identity

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)
+