Use Bot resource in Machine ID deployment guides (#40944)

* Use bot yaml resource in machine id deployment guides * Update the number for the k8s guide steps * Update docs/pages/includes/machine-id/create-a-bot.mdx Co-authored-by: Gavin Frazar <[email protected]> * Update docs/pages/includes/machine-id/create-a-bot.mdx Co-authored-by: Gavin Frazar <[email protected]> * Update docs/pages/machine-id/deployment/spacelift.mdx Co-authored-by: Gavin Frazar <[email protected]> * Update docs/pages/machine-id/deployment/spacelift.mdx Co-authored-by: Gavin Frazar <[email protected]> * Fix heading level --------- Co-authored-by: Gavin Frazar <[email protected]>
gravitational · Apr 30, 2024 · 590407d · 590407d
1 parent c6408c8
commit 590407d
Show file tree

Hide file tree

Showing 9 changed files with 167 additions and 136 deletions.
diff --git a/docs/pages/includes/machine-id/create-a-bot.mdx b/docs/pages/includes/machine-id/create-a-bot.mdx
@@ -0,0 +1,26 @@
+Next, you need to create a Bot. A Bot is a Teleport identity for a machine or
+group of machines. Like users, bots have a set of roles and traits which define
+what they can access.
+
+Create `bot.yaml`:
+
+```yaml
+kind: bot
+version: v1
+metadata:
+  # name is a unique identifier for the Bot in the cluster.
+  name: example
+spec:
+  # roles is a list of roles to grant to the Bot. Don't worry if you don't know
+  # what roles you need to specify here, the Access Guides will walk you through
+  # creating and assigning roles to the already created Bot.
+  roles: []
+```
+
+Make sure you replace `example` with a unique, descriptive name for your Bot.
+
+Use `tctl` to apply this file:
+
+```code
+$ tctl create bot.yaml
+```
diff --git a/docs/pages/machine-id/deployment/aws.mdx b/docs/pages/machine-id/deployment/aws.mdx
@@ -32,7 +32,7 @@ guidance on deploying Machine ID as a workload on Kubernetes.
 - An AWS EC2 virtual machine that you wish to install Machine ID onto configured
   with the IAM role attached.
 
-## Step 1/4. Install `tbot`
+## Step 1/5. Install `tbot`
 
 **This step is completed on the AWS EC2 instance.**
 
@@ -43,7 +43,13 @@ Download and install the appropriate Teleport package for your platform:
 
 (!docs/pages/includes/install-linux.mdx!)
 
-## Step 2/4. Create the bot
+## Step 2/5. Create a Bot
+
+**This step is completed on your local machine.**
+
+(!docs/pages/includes/machine-id/create-a-bot.mdx!)
+
+## Step 3/5. Create a join token
 
 **This step is completed on your local machine.**
 
@@ -57,7 +63,7 @@ metadata:
   name: example-bot
 spec:
   roles: [Bot]
-  # bot_name will match the name of the bot created later in this guide.
+  # 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.
@@ -73,6 +79,7 @@ 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.
@@ -83,13 +90,7 @@ Use `tctl` to apply this file:
 $ tctl create -f bot-token.yaml
 ```
 
-Create the bot, specifying the token that you have created:
-
-```code
-$ tctl bots add example --token example-bot
-```
-
-## Step 3/4. Configure `tbot`
+## Step 4/5. Configure `tbot`
 
 **This step is completed on the AWS EC2 instance.**
 
@@ -115,7 +116,7 @@ Replace:
 
 (!docs/pages/includes/machine-id/daemon-or-oneshot.mdx!)
 
-## Step 4/4. Configure outputs
+## Step 5/5. Configure outputs
 
 (!docs/pages/includes/machine-id/configure-outputs.mdx!)
 

diff --git a/docs/pages/machine-id/deployment/azure.mdx b/docs/pages/machine-id/deployment/azure.mdx
@@ -29,7 +29,7 @@ occur without the use of a long-lived secret.
 - An Azure VM you wish to install Machine ID onto with the managed identity
   configured as a user-assigned managed identity.
 
-## Step 1/4. Install `tbot`
+## Step 1/5. Install `tbot`
 
 **This step is completed on the Azure VM.**
 
@@ -40,7 +40,13 @@ Download and install the appropriate Teleport package for your platform:
 
 (!docs/pages/includes/install-linux.mdx!)
 
-## Step 2/4. Create a join token and bot user
+## Step 2/5. Create a Bot
+
+**This step is completed on your local machine.**
+
+(!docs/pages/includes/machine-id/create-a-bot.mdx!)
+
+## Step 3/5. Create a join token
 
 **This step is completed on your local machine.**
 
@@ -54,7 +60,7 @@ metadata:
   name: example-bot
 spec:
   roles: [Bot]
-  # bot_name will match the name of the bot created later in this guide.
+  # bot_name should match the name of the bot created earlier in this guide.
   bot_name: example
   join_method: azure
   azure:
@@ -71,6 +77,7 @@ spec:
 Replace:
 
 - `11111111-1111-1111-1111-111111111111` with the UID of your Azure subscription
+- `example` with the name of the bot you created in the second step
 - `group1` with the name of the resource group that the VM resides within or
   omit this entirely to allow joining from any VM within the subscription
 
@@ -80,13 +87,7 @@ Use `tctl` to apply this file:
 $ tctl create -f bot-token.yaml
 ```
 
-Create the bot, specifying the token that you have created:
-
-```code
-$ tctl bots add example --token example-bot
-```
-
-## Step 3/4. Configure `tbot`
+## Step 4/5. Configure `tbot`
 
 **This step is completed on the Azure VM.**
 
@@ -116,7 +117,7 @@ Replace:
 
 (!docs/pages/includes/machine-id/daemon-or-oneshot.mdx!)
 
-## Step 4/4. Configure outputs
+## Step 5/5. Configure outputs
 
 (!docs/pages/includes/machine-id/configure-outputs.mdx!)
 

diff --git a/docs/pages/machine-id/deployment/circleci.mdx b/docs/pages/machine-id/deployment/circleci.mdx
@@ -60,9 +60,13 @@ https://app.circleci.com/settings/organization/github/gravitational/contexts/000
 In this case, the context ID is: `00000000-0000-0000-0000-000000000000`.
 
 Note this value down and substitute `$CONTEXT_ID` in configuration examples
-with this.
+with this
 
-## Step 2/5. Create the join token for CircleCI
+## Step 2/5. Create the Machine ID bot
+
+(!docs/pages/includes/machine-id/create-a-bot.mdx!)
+
+## Step 3/5. Create the join token for CircleCI
 
 In order to allow your CircleCI workflow to authenticate with your Teleport
 cluster, you'll first need to create a join token. These tokens set out criteria
@@ -110,14 +114,6 @@ Apply this to your Teleport cluster using `tctl`:
 $ tctl create -f bot-token.yaml
 ```
 
-## Step 3/5. Create the Machine ID bot
-
-Create the bot, specifying the token that you have created:
-
-```code
-$ tctl bots add example --token=example-bot
-```
-
 ## Step 4/5. Configure a CircleCI workflow
 
 With the bot and join token created, you can now configure a CircleCI

diff --git a/docs/pages/machine-id/deployment/gcp.mdx b/docs/pages/machine-id/deployment/gcp.mdx
@@ -32,7 +32,7 @@ guidance on deploying Machine ID as a workload on Kubernetes.
 - A GCP Compute Engine VM that you wish to install Machine ID onto that has
   been configured with the GCP service account.
 
-## Step 1/4. Install `tbot`
+## Step 1/5. Install `tbot`
 
 **This step is completed on the GCP VM.**
 
@@ -43,7 +43,13 @@ Download and install the appropriate Teleport package for your platform:
 
 (!docs/pages/includes/install-linux.mdx!)
 
-## Step 2/4. Create a join token and bot user
+## Step 2/5. Create a Bot
+
+**This step is completed on your local machine.**
+
+(!docs/pages/includes/machine-id/create-a-bot.mdx!)
+
+## Step 3/5. Create a join token
 
 **This step is completed on your local machine.**
 
@@ -57,7 +63,7 @@ metadata:
   name: example-bot
 spec:
   roles: [Bot]
-  # bot_name will match the name of the bot created later in this guide.
+  # bot_name should match the name of the bot created earlier in this guide.
   bot_name: example
   join_method: gcp
   gcp:
@@ -75,6 +81,7 @@ spec:
 Replace:
 
 - `my-project-123456` with the ID of your GCP project
+- `example` with the name of the bot you created in the second step.
 - `[email protected]` with the email
   of the service account configured in the previous step. The default compute
   service account is not supported.
@@ -85,13 +92,7 @@ Use `tctl` to apply this file:
 $ tctl create -f bot-token.yaml
 ```
 
-Create the bot, specifying the token that you have created:
-
-```code
-$ tctl bots add example --token example-bot
-```
-
-## Step 3/4. Configure `tbot`
+## Step 4/5. Configure `tbot`
 
 **This step is completed on the GCP VM.**
 
@@ -117,7 +118,7 @@ Replace:
 
 (!docs/pages/includes/machine-id/daemon-or-oneshot.mdx!)
 
-## Step 4/4. Configure outputs
+## Step 5/5. Configure outputs
 
 (!docs/pages/includes/machine-id/configure-outputs.mdx!)
 

diff --git a/docs/pages/machine-id/deployment/github-actions.mdx b/docs/pages/machine-id/deployment/github-actions.mdx
@@ -20,7 +20,11 @@ Actions runners as well as GitHub Enterprise Server.
   `gravitational/example` repo, however this value should be replaced with
   your own unique repo.
 
-## Step 1/3. Create a join token for GitHub Actions
+## Step 1/3. Create a Bot
+
+(!docs/pages/includes/machine-id/create-a-bot.mdx!)
+
+## Step 2/3. Create a join token for GitHub Actions
 
 In order to allow your GitHub Actions workflow to authenticate with your
 Teleport cluster, you'll first need to create a join token. These tokens set out
@@ -47,7 +51,7 @@ spec:
   roles: [Bot]
   join_method: github
   # The bot_name indicates which bot user this token grants access to. This
-  # should match the name of the bot that you will create in the next step.
+  # should match the name of the bot that you created in the previous step.
   bot_name: example
   github:
     # allow specifies rules that control which GitHub Actions runs will be
@@ -114,14 +118,6 @@ Token       Type Labels Expiry Time (UTC)
 example-bot Bot         01 Jan 00 00:00 UTC (2562047h47m16.854775807s)
 ```
 
-## Step 2/3. Create a Machine ID bot
-
-Create the bot, specifying the token that you have created:
-
-```code
-$ tctl bots add example --roles=example-bot --token=example-bot
-```
-
 ## Step 3/3. Configure a GitHub Actions Workflow
 
 Now that the bot has been successfully created, you now need to configure your

diff --git a/docs/pages/machine-id/deployment/gitlab.mdx b/docs/pages/machine-id/deployment/gitlab.mdx
@@ -28,7 +28,11 @@ using a self-hosted GitLab instance, your Teleport Auth Server must be able to
 connect to your GitLab instance and your GitLab instance must be configured with
 a valid TLS certificate.**
 
-## Step 1/4. Create a join token
+## Step 1/4. Create a Bot
+
+(!docs/pages/includes/machine-id/create-a-bot.mdx!)
+
+## Step 2/4. Create a join token
 
 To allow GitLab CI to authenticate to your Teleport cluster, you'll first need
 to create a join token. A GitLab join token contains allow rules that describe
@@ -55,7 +59,7 @@ spec:
   roles: [Bot]
   join_method: gitlab
   # The bot_name indicates which bot user this token grants access to. This
-  # should match the name of the bot that you create in step 2.
+  # should match the name of the bot that you created in step 1.
   bot_name: example
   gitlab:
     # domain should be the domain of your GitLab instance. If you are using
@@ -80,14 +84,6 @@ Apply this to your Teleport cluster using `tctl`:
 $ tctl create -f bot-token.yaml
 ```
 
-## Step 2/4. Create a Machine ID bot
-
-Create the bot, specifying the token that you have created:
-
-```code
-$ tctl bots add example --token=example-bot
-```
-
 ## Step 3/4. Configure a GitLab Pipeline
 
 With the bot and join token created, you can now configure a GitLab pipeline
@@ -167,7 +163,7 @@ Commit and push these two files to the repository.
 Check your GitLab CI status, and examine the log results from the commit for
 failure.
 
-### Step 4/4. Configure outputs
+## Step 4/4. Configure outputs
 
 (!docs/pages/includes/machine-id/configure-outputs.mdx!)
 

diff --git a/docs/pages/machine-id/deployment/kubernetes.mdx b/docs/pages/machine-id/deployment/kubernetes.mdx
@@ -57,7 +57,7 @@ The examples in this guide will install a `tbot` deployment in the `default`
 Namespace of the Kubernetes cluster. Adjust references to `default` to the
 Namespace you wish to use.
 
-## Step 1/4. Prepare Kubernetes RBAC
+## Step 1/5. Prepare Kubernetes RBAC
 
 In order to prepare the Kubernetes cluster for Machine ID, several Kubernetes
 RBAC resources must be created.
@@ -118,7 +118,11 @@ Apply this file to your Kubernetes cluster:
 $ kubectl apply -f ./k8s-rbac.yaml
 ```
 
-## Step 2/4. Create a join token and bot user
+## Step 2/5. Create a Bot
+
+(!docs/pages/includes/machine-id/create-a-bot.mdx!)
+
+## Step 3/5. Create a join token
 
 Next, a join token needs to be configured. This will be used by `tbot` to join
 the cluster. As the `kubernetes` join method will be used, the public key of the
@@ -146,7 +150,7 @@ metadata:
   name: example-bot
 spec:
   roles: [Bot]
-  # bot_name will match the name of the bot created later in this guide.
+  # bot_name should match the name of the bot created earlier in this guide.
   bot_name: example
   join_method: kubernetes
   kubernetes:
@@ -169,13 +173,7 @@ Use `tctl` to apply this file:
 $ tctl create -f bot-token.yaml
 ```
 
-Create the bot, specifying the token that you have created:
-
-```code
-$ tctl bots add example --token example-bot
-```
-
-## Step 3/4. Create a `tbot` deployment
+## Step 4/5. Create a `tbot` deployment
 
 First, a ConfigMap will be created to contain the configuration file for `tbot`.
 This will then be mounted into the Pod.
@@ -311,7 +309,7 @@ $ kubectl logs deployment/tbot
 With this complete, `tbot` is now successfully deployed to your cluster.
 However, it is not yet producing any useful output.
 
-## Step 4/4. Configure outputs
+## Step 5/5. Configure outputs
 
 Follow one of the [access guides](../access-guides.mdx) to configure an output
 that meets your access needs.