Catch misuses of the Var component

Closes #29905 Add a Vale style rule to catch docs pages in which there is a single instance of a Var. This ensures that Vars reuse information as intended. Also fix single-instance Vars that violate the rule. For the most part, this means either: - Instructing the user to assign the Var, meaning that there are no easy-to-miss Vars hiding in a configuration snippet - Removing unnecessary Vars, e.g., if an example command is meant to illustrate a possibility and is not mean to be copied and pasted - Fixing mistakes in Var usage, e.g., a Proxy Service address variable that has two possible names, `teleport.example.com` and `example.teleport.sh`.
gravitational · Jan 17, 2025 · 3095082 · 3095082
1 parent 27ba490
commit 3095082
Show file tree

Hide file tree

Showing 52 changed files with 222 additions and 153 deletions.
diff --git a/...dmin-guides/deploy-a-cluster/deployments/aws-ha-autoscale-cluster-terraform.mdx b/...dmin-guides/deploy-a-cluster/deployments/aws-ha-autoscale-cluster-terraform.mdx
@@ -144,7 +144,7 @@ These are regions that support [DynamoDB encryption at rest](https://docs.aws.am
 ### cluster_name
 
 ```code
-$ export TF_VAR_cluster_name="<Var name="teleport-example" />"
+$ export TF_VAR_cluster_name="teleport-example"
 ```
 
 This is the internal Teleport cluster name to use. This should be unique, and not contain spaces, dots (.) or other

diff --git a/docs/pages/admin-guides/deploy-a-cluster/gcp-kms.mdx b/docs/pages/admin-guides/deploy-a-cluster/gcp-kms.mdx
@@ -62,7 +62,7 @@ $ gcloud kms keyrings create "<Var name="teleport-keyring" description="The name
 ## Step 2/5. Create a GCP service account
 
 Teleport needs permissions to create, list, destroy, sign with, and view KMS
-keys in your key ring. Start by creating the following custom IAM role.
+keys in your key ring. Start by defining the following custom IAM role.
 
 ```yaml
 # teleport_kms_role.yaml
@@ -78,6 +78,8 @@ includedPermissions:
 - cloudkms.cryptoKeyVersions.viewPublicKey
 ```
 
+Create the role, assigning <Var name="GCP-Project-ID" /> to your Google Cloud project ID:
+
 ```code
 $ gcloud iam roles create teleport_kms_role \
     --project <Var name="GCP-Project-ID" description="Your GCP project ID"/> \

diff --git a/docs/pages/admin-guides/deploy-a-cluster/helm-deployments/azure.mdx b/docs/pages/admin-guides/deploy-a-cluster/helm-deployments/azure.mdx
@@ -53,6 +53,7 @@ $ az aks update --resource-group <Var name="aks-rg" /> --name <Var name="aks-nam
 
 For convenience, we'll create all the resources necessary in a brand new
 resource group; if you want to use an existing one, you can skip this step.
+Assign <Var name="region" /> to your Azure region:
 
 ```code
 $ az group create --name <Var name="teleport-rg" /> --location <Var name="region" />
@@ -90,7 +91,7 @@ access can be restricted to just the AKS outbound address, or the account can be
 made part of the virtual network that the AKS cluster is using.
 
 ```code
-$ az storage account create --resource-group <Var name="teleport-rg" /> --name <Var name="teleport-blob" /> \
+$ az storage account create --resource-group <Var name="teleport-rg" /> --name "teleport-blob" \
     --allow-blob-public-access false
 $ az role assignment create --role "Storage Blob Data Owner" --assignee-principal-type ServicePrincipal \
     --assignee-object-id "$(az identity show --resource-group <Var name="teleport-rg" /> --name teleport-id --query principalId -o tsv)" \

diff --git a/docs/pages/admin-guides/deploy-a-cluster/hsm.mdx b/docs/pages/admin-guides/deploy-a-cluster/hsm.mdx
@@ -32,7 +32,9 @@ to use.
 
 1. Wait for the newly created cluster to enter the "Uninitialized" state.
 
-1. Add an HSM to the new cluster, using the AWS Console or the AWS CLI:
+1. Add an HSM to the new cluster, using the AWS Console or the AWS CLI,
+   assigning <Var name="region"/> to your AWS region and <Var name="availability zone"/>
+   to your availability zone:
 
    ```code
    $ aws --region <Var name="region"/> cloudhsmv2 create-hsm --cluster-id <Var name="cluster ID"/> --availability-zone <Var name="availability zone"/>

diff --git a/docs/pages/admin-guides/deploy-a-cluster/linux-demo.mdx b/docs/pages/admin-guides/deploy-a-cluster/linux-demo.mdx
@@ -164,10 +164,11 @@ Install `tsh` on your local workstation:
 
 (!docs/pages/includes/install-tsh.mdx!)
 
-Log in to receive short-lived certificates from Teleport:
+Log in to receive short-lived certificates from Teleport. Replace 
+<Var name="teleport.example.com" /> with your Teleport cluster's public address
+as configured above:
 
 ```code
-# Replace teleport.example.com with your Teleport cluster's public address as configured above.
 $ tsh login --proxy=<Var name="teleport.example.com" /> --user=teleport-admin
 > Profile URL:        https://teleport.example.com:443
   Logged in as:       teleport-admin

diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/ci-or-cloud.mdx
@@ -150,7 +150,8 @@ spec:
 
 (!docs/pages/includes/machine-id/recover-circle-ci-claims.mdx!)
 
-Then, create the following `terraform-bot-token.yaml`:
+Then, create the following `terraform-bot-token.yaml`, replacing <Var
+name="context-id" /> with your context ID:
 
 ```yaml
 kind: token
@@ -163,7 +164,7 @@ spec:
   bot_name: terraform
   circleci:
     organization_id: <Var name="organization-id" />
-    # allow specifies the rules by which the Auth Server determines if `tbot`
+    # allow specifies the rules by which the Auth Service determines if `tbot`
     # should be allowed to join.
     allow:
     - context_id: <Var name="context-id" />

diff --git a/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/local.mdx b/docs/pages/admin-guides/infrastructure-as-code/terraform-provider/local.mdx
@@ -32,7 +32,7 @@ verify that you can run `tctl` commands using your current credentials.
 For example:
 
 ```code
-$ tsh login --proxy=<Var name="teleport.example.com:443" /> --user=<Var name="email@example.com" />
+$ tsh login --proxy=teleport.example.com --user=email@example.com
 $ tctl status
 # Cluster  (=teleport.url=)
 # Version  (=teleport.version=)

diff --git a/...min-guides/infrastructure-as-code/terraform-provider/long-lived-credentials.mdx b/...min-guides/infrastructure-as-code/terraform-provider/long-lived-credentials.mdx
@@ -119,7 +119,10 @@ To prepare a Terraform configuration file:
 
 1. Create a new file called `main.tf` and open it in an editor.
 
-1. Define an example user and role using Terraform by pasting the following content into the `main.tf` file:
+1. Define an example user and role using Terraform by pasting the following
+   content into the `main.tf` file, replacing 
+   <Var name="teleport.example.com:443" /> with the host and port of the
+   Teleport Proxy Service:
 
    ```hcl
    terraform {

diff --git a/docs/pages/admin-guides/management/admin/labels.mdx b/docs/pages/admin-guides/management/admin/labels.mdx
@@ -311,7 +311,7 @@ should be named `si-<name>`.
 
 To add resource-based labels:
 
-1. Run `tctl get node/<Var name="hostname"/>` to get the name of the node resource to apply labels to.
+1. Run `tctl get node/NODE_NAME` to get the name of the node resource to apply labels to.
    You should get output similar to the following:
 
    ```yaml

diff --git a/docs/pages/admin-guides/management/guides/awsoidc-integration-rds.mdx b/docs/pages/admin-guides/management/guides/awsoidc-integration-rds.mdx
@@ -113,7 +113,8 @@ teleport.dev/origin:       integration_awsoidc
 teleport.dev/integration:  <Var name="my-integration"/>
 ```
 
-You can also search for AWS resources created by the wizard using the `aws` cli:
+You can also search for AWS resources created by the wizard using the `aws` cli.
+Assign <Var name="us-west-1" /> to the name of an AWS region:
 
 ```code
 $ aws resourcegroupstaggingapi get-resources \

diff --git a/docs/pages/admin-guides/management/operations/ca-rotation.mdx b/docs/pages/admin-guides/management/operations/ca-rotation.mdx
@@ -84,7 +84,8 @@ to reflect data held by the Auth Service. This internal data includes the status
 of the `host` CA rotation if one is in progress.
 
 To check the rotation status of an agent or Proxy Service instance, run a
-variation of the following command:
+variation of the following command, assigning <Var name="resource" /> to the
+name of an agent or Proxy Service instance:
 
 ```code
 $ tctl get <Var name="resource" /> --format=json | jq '.[] | {hostname: .spec.hostname, rotation: .spec.rotation.state, phase: .spec.rotation.phase}'

diff --git a/docs/pages/admin-guides/migrate-plans.mdx b/docs/pages/admin-guides/migrate-plans.mdx
@@ -93,15 +93,17 @@ Validate connectivity to both the new Teleport Enterprise cluster and your
 original Teleport Enterprise cluster. You should be able to connect to both
 Teleport clusters and execute `tctl` commands using your current credentials.
 
-1. Log in to the original Teleport cluster:
+1. Log in to the original Teleport cluster, replacing 
+   <Var name="enterprise.example.com" /> with the cluster domain name:
 
    ```code
    # Use the --auth flag instead of --user to log in with Single Sign-On.
    $ tsh login --proxy=<Var name="enterprise.example.com" /> --user=<Var name="myuser" />
    $ tctl status
    ```
 
-1. Log in to the new Teleport Enterprise cluster:
+1. Log in to the new Teleport Enterprise cluster, replacing <Var
+   name="example.teleport.sh" /> with the domain name of your new cluster:
 
    ```code
    # Use the --auth flag instead of --user to log in with Single Sign-On.

diff --git a/docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx b/docs/pages/admin-guides/teleport-policy/integrations/ssh-keys-scan.mdx
@@ -167,7 +167,7 @@ Below are a few example queries demonstrating how the `ssh_keys` view can be use
   ```
 - View insecure access paths and SSH authorized keys for a specific node:
   ```sql
-  SELECT * FROM ssh_keys WHERE resource='<Var name="resource name" />';
+  SELECT * FROM ssh_keys WHERE resource='RESOURCE_NAME';
   ```
 - View insecure access paths and SSH authorized keys for a subset of nodes using labels:
   ```sql

diff --git a/docs/pages/connect-your-client/gui-clients.mdx b/docs/pages/connect-your-client/gui-clients.mdx
@@ -21,7 +21,7 @@ work with Teleport.
 - To check that you can connect to your Teleport cluster, sign in with `tsh login`. For example:
 
   ```code
-  $ tsh login --proxy=<Var name="teleport.example.com" /> --user=<Var name="email@example.com" />
+  $ tsh login --proxy=teleport.example.com --user=myuser@example.com
   ```
 
 - The Teleport Database Service configured to access a database. See one of our

diff --git a/docs/pages/connect-your-client/introduction.mdx b/docs/pages/connect-your-client/introduction.mdx
@@ -18,8 +18,9 @@ your Teleport cluster:
 <Tabs>
 <TabItem label="Local user">
 
-Authenticate to Teleport as a local user with `tsh login` by 
-assigning <Var name="user"/> to your Teleport username:
+Authenticate to Teleport as a local user with `tsh login` by assigning <Var
+name="user"/> to your Teleport username and <Var name="teleport.example.com" />
+to the domain name of your Teleport cluster:
 
 ```code
 $ tsh login --proxy=<Var name="teleport.example.com" description="Your Teleport Proxy Service or Teleport Cloud tenant address"/> --user=<Var name="user" description="Your Teleport username"/>
@@ -39,8 +40,8 @@ Tap any security key
 <TabItem label="Single sign-on user">
 
 Authenticate to Teleport as a single sign-on (SSO) user by running `tsh login`
-and assigning the `auth` flag to the name of your authentication connector, if
-implemented by your administrators:
+and assigning <Var name="your-idp-connector" /> to the name of your
+authentication connector, if implemented by your administrators:
 
 ```code
 $ tsh login --proxy=<Var name="teleport.example.com"/> --auth=<Var name="your-idp-connector" description="Your Identity Provider connection name, if implemented by your administrators"/>

diff --git a/docs/pages/connect-your-client/teleport-connect.mdx b/docs/pages/connect-your-client/teleport-connect.mdx
@@ -405,10 +405,9 @@ locks](../admin-guides/access-controls/guides/locking.mdx) on those nodes.
 
 ```code
 $ tctl nodes ls -v --query='labels["teleport.dev/connect-my-computer/owner"] != ""'
-$ tctl lock --server-id=<Var name="Node UUID" /> --message="Using Connect My Computer is forbidden"
+$ tctl lock --server-id=SERVER_UUID --message="Using Connect My Computer is forbidden"
 ```
 
-
 ## Using tsh outside of Teleport Connect
 
 Teleport Connect ships with its own bundled version of tsh. Teleport Connect will always use this

diff --git a/docs/pages/connect-your-client/vnet.mdx b/docs/pages/connect-your-client/vnet.mdx
@@ -104,7 +104,8 @@ From /var/log/vnet.log:
 INFO  Setting an IP route for the VNet. netmask:100.64.0.0/10 vnet/osconfig_darwin.go:47
 ```
 
-Send a query for a TCP app available in your cluster:
+Send a query for a TCP app available in your cluster, replacing <Var
+name="tcp-app.teleport.example.com" /> with the name of your app:
 
 ```code
 $ dscacheutil -q host -a name <Var name="tcp-app.teleport.example.com" />

diff --git a/docs/pages/enroll-resources/application-access/cloud-apis/aws-console.mdx b/docs/pages/enroll-resources/application-access/cloud-apis/aws-console.mdx
@@ -307,7 +307,8 @@ Service.
    Application Service.
 
 1. Run the following command to associate the new instance profile with your
-   instance:
+   instance, assigning <Var name="INSTANCE_ID" /> to your instance ID and 
+   <Var name="AWS_REGION" /> to your AWS region:
 
    ```code
    $ aws ec2 associate-iam-instance-profile --iam-instance-profile Name="TeleportAWSAccess" \

diff --git a/.../pages/enroll-resources/application-access/cloud-apis/azure-aks-workload-id.mdx b/.../pages/enroll-resources/application-access/cloud-apis/azure-aks-workload-id.mdx
@@ -135,7 +135,7 @@ Next assign the managed identity desired permissions that the Teleport user
 should have. In this example, the "Reader" role is assigned to the managed
 identity:
 ```code
-$ az role assignment create --role "<Var name="Reader" />" --scope "/subscriptions/${SUBSCRIPTION}" --assignee-object-id $(az identity show --name "<Var name="teleport-reader" />" --resource-group "${RESOURCE_GROUP}" --query principalId --output tsv) --assignee-principal-type ServicePrincipal
+$ az role assignment create --role "Reader" --scope "/subscriptions/${SUBSCRIPTION}" --assignee-object-id $(az identity show --name "<Var name="teleport-reader" />" --resource-group "${RESOURCE_GROUP}" --query principalId --output tsv) --assignee-principal-type ServicePrincipal
 ```
 
 ### Associate the managed identity with the Kubernetes service account

diff --git a/docs/pages/enroll-resources/application-access/guides/vnet.mdx b/docs/pages/enroll-resources/application-access/guides/vnet.mdx
@@ -137,7 +137,7 @@ To make a [leaf cluster](../../../admin-guides/management/admin/trustedclusters.
 `public_addr`, you need to follow the same steps while being logged in directly to the leaf cluster.
 
 ```code
-$ tsh login --proxy=<Var name="leaf.example.com" /> --user=<Var name="email@example.com" />
+$ tsh login --proxy=leaf.example.com --user=email@example.com
 ```
 
 ### Accessing web apps through VNet

diff --git a/docs/pages/enroll-resources/application-access/troubleshooting-apps.mdx b/docs/pages/enroll-resources/application-access/troubleshooting-apps.mdx
@@ -169,7 +169,7 @@ manually set the `SSL_CERT_FILE` or `SSL_CERT_DIR` environment variable on the
 command line. For example:
 
 ```code
-sudo SSL_CERT_FILE=<Var name="path-to-rootCA-pem" /> teleport start --config=/etc/teleport.yaml
+sudo SSL_CERT_FILE="path/to/rootCA-pem" teleport start --config=/etc/teleport.yaml
 ```
 
 You should specify the `SSL_CERT_FILE` and `SSL_CERT_DIR` environment variables as command-line

diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes-applications/get-started.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes-applications/get-started.mdx
@@ -57,7 +57,9 @@ by adding the `kube`, `app`, and `discovery` to roles as shown below.
 <TabItem label="Install a new agent">
 
 Deploy a new Teleport Agent running your configured services by installing the
-`teleport-kube-agent` Helm chart:
+`teleport-kube-agent` Helm chart, assigning <Var name="proxy-address" /> to the
+host and port of your Teleport Proxy Service and <Var name="token" /> to the
+join token you created earlier:
 
 ```code
 $ helm install teleport-agent teleport/teleport-kube-agent \

diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/aws.mdx
@@ -297,7 +297,7 @@ teleport:
   join_params:
     token_name: "/tmp/token"
     method: token
-  proxy_server: <Var name="teleport.example.com" />:443
+  proxy_server: "teleport.example.com:443"
 auth_service:
   enabled: off
 proxy_service:

diff --git a/docs/pages/enroll-resources/auto-discovery/kubernetes/azure.mdx b/docs/pages/enroll-resources/auto-discovery/kubernetes/azure.mdx
@@ -234,7 +234,7 @@ teleport:
   join_params:
     token_name: "/tmp/token"
     method: token
-  proxy_server: <Var name="teleport.example.com" />:443    
+  proxy_server: "teleport.example.com:443"
 auth_service:
   enabled: off
 proxy_service:

diff --git a/docs/pages/enroll-resources/auto-discovery/servers/azure-discovery.mdx b/docs/pages/enroll-resources/auto-discovery/servers/azure-discovery.mdx
@@ -243,7 +243,7 @@ teleport:
   join_params:
     token_name: "/tmp/token"
     method: token
-  proxy_server: "<Var name="teleport.example.com" />:443"
+  proxy_server: "teleport.example.com:443"
 auth_service:
   enabled: off
 proxy_service:
@@ -308,4 +308,4 @@ logs can be found on the targeted VM at
 - Read [Joining Nodes via Azure Managed Identity](../../agents/join-services-to-your-cluster/azure.mdx)
   for more information on Azure tokens.
 - Full documentation on Azure discovery configuration can be found through the [
-  config file reference documentation](../../../reference/config.mdx).
+  config file reference documentation](../../../reference/config.mdx).
diff --git a/docs/pages/enroll-resources/auto-discovery/servers/ec2-discovery.mdx b/docs/pages/enroll-resources/auto-discovery/servers/ec2-discovery.mdx
@@ -126,7 +126,7 @@ teleport:
   join_params:
     token_name: "/tmp/token"
     method: token
-  proxy_server: "<Var name="teleport.example.com" />:443"
+  proxy_server: "<Var name="teleport.example.com:443" />"
 auth_service:
   enabled: off
 proxy_service:
@@ -222,7 +222,7 @@ mainSteps:
     sourceType: "HTTP"
     destinationPath: "/tmp/installTeleport.sh"
     sourceInfo:
-      url: "https://teleport.example.com:443/webapi/scripts/installer/{{ scriptName }}"
+      url: "https://<Var name="teleport.example.com:443" />/webapi/scripts/installer/{{ scriptName }}"
 - action: aws:runShellScript
   name: runShellScript
   inputs:
@@ -354,4 +354,4 @@ for more information on IAM Invite Tokens.
 Manager can be found for in the [AWS Cloud Operations & Migrations Blog
 ](https://aws.amazon.com/blogs/mt/applying-managed-instance-policy-best-practices/).
 - Full documentation on EC2 discovery configuration can be found through the [
-config file reference documentation](../../../reference/config.mdx).
+config file reference documentation](../../../reference/config.mdx).
diff --git a/docs/pages/enroll-resources/auto-discovery/servers/gcp-discovery.mdx b/docs/pages/enroll-resources/auto-discovery/servers/gcp-discovery.mdx
@@ -138,8 +138,10 @@ discover instances.
   --role="projects/<Var name="project_id" />/roles/teleport_discovery"
   ```
 
-  If the Discovery Service will run in a GCP compute instance, run the following command to
-  add the service account to the instance:
+  If the Discovery Service will run in a GCP compute instance, run the following
+  command to add the service account to the instance, replacing <Var
+  name="discovery_service_vm_name" /> with the name of the Discovery Service VM:
+
   ```code
   $ gcloud compute instances set-service-account <Var name="discovery_service_vm_name" description="Name of the instance running the Discovery Service" /> \
   --service-account=teleport-discovery@<Var name="project_id" />.iam.gserviceaccount.com \
@@ -292,4 +294,4 @@ for details on alternate methods.
 - Read [Joining Services via GCP](../../../enroll-resources/agents/join-services-to-your-cluster/gcp.mdx)
   for more information on GCP tokens.
 - Full documentation on GCP discovery configuration can be found through the [
-  config file reference documentation](../../../reference/config.mdx).
+  config file reference documentation](../../../reference/config.mdx).
diff --git a/docs/pages/enroll-resources/database-access/enroll-aws-databases/aws-docdb.mdx b/docs/pages/enroll-resources/database-access/enroll-aws-databases/aws-docdb.mdx
@@ -52,13 +52,14 @@ description: How to access Amazon DocumentDB with Teleport database access
 (!docs/pages/includes/install-linux.mdx!)
 
 On the node that is running the Database Service, create a configuration file.
-Use your DocumentDB cluster endpoint and port as the URI:
+Use your DocumentDB cluster endpoint and port as the URI, replacing 
+<Var name="my-docdb.cluster-abcdefghijklm.us-east-1.docdb.amazonaws.com:27017"/>:
 
 ```code
 $ sudo teleport db configure create \
    -o file \
    --name="my-docdb" \
-   --proxy=example.teleport.sh:443 \
+   --proxy=<Var name="example.teleport.sh:443" /> \
    --protocol=mongodb \
    --token=/tmp/token \
    --uri="<Var name="my-docdb.cluster-abcdefghijklm.us-east-1.docdb.amazonaws.com:27017"/>"
@@ -157,7 +158,9 @@ and `Allowed` for the value. Then click **Create Role** to complete the process.
 Log in to your DocumentDB cluster with your master username and password from a
 machine that has network access to the DocumentDB cluster. Create a DocumentDB
 user with the IAM role ARN as username and specify `MONGODB-AWS` in the
-mechanisms for authentication:
+mechanisms for authentication. Replace 
+<Var name="arn:aws:iam::(=aws.aws_account_id=):role/teleport-docdb-user"/> with
+the ARN of your DocumentDB user:
 
 ```code
 use $external;