[v13] Promote IAC docs for agents and dynamic resources

docs/cspell.json

@@ -710,6 +710,7 @@
     "teleportyaml",
     "tenantname",
     "testuser",
+    "tfvars",
     "thisisunsafe",
     "thred",
     "timechart",
@@ -738,6 +739,7 @@
     "updaterversionserver",
     "uqcje",
     "urandom",
+    "userdata",
     "userdel",
     "usermod",
     "usernameclaim",

docs/pages/access-controls/compliance-frameworks/soc2.mdx

@@ -56,7 +56,7 @@ Each principle has many “Points of Focus” which will apply differently to di
 | CC6.1 - Manages Points of Access | Points of access by outside entities and the types of data that flow through the points of access are identified, inventoried, and managed. The types of individuals and systems using each point of access are identified, documented, and managed. | [Label Nodes to inventory and create rules](../../management/admin/labels.mdx) <br/><br/> [Create Labels from AWS Tags](../../management/guides/ec2-tags.mdx) <br/><br/>Teleport maintains a live list of all nodes within a cluster. This node list can be queried by users (who see a subset they have access to) and administrators any time. |
 | CC6.1 - Restricts Access to Information Assets | Combinations of data classification, separate data structures, port restrictions, access protocol restrictions, user identification, and digital certificates are used to establish access-control rules for information assets. | [Teleport uses Certificates to grant access and create access control rules](../../core-concepts.mdx) | 
 | CC6.1 - Manages Identification and Authentication | Identification and authentication requirements are established, documented, and managed for individuals and systems accessing entity information, infrastructure, and software. | Teleport makes setting policies for SSH requirements easy since it works in the cloud and on premise with the same authentication security standards. | 
-| CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../../management/join-services-to-your-cluster/join-token.mdx) | 
+| CC6.1 - Manages Credentials for Infrastructure and Software | New internal and external infrastructure and software are registered, authorized, and documented prior to being granted access credentials and implemented on the network or access point. Credentials are removed and access is disabled when access is no longer required or the infrastructure and software are no longer in use. | [Invite nodes to your cluster with short lived tokens](../../agents/join-services-to-your-cluster/join-token.mdx) | 
 | CC6.1 - Uses Encryption to Protect Data | The entity uses encryption to supplement other measures used to protect data at rest, when such protections are deemed appropriate based on assessed risk. | Teleport Audit logs can use DynamoDB encryption at rest. | 
 | CC6.1 - Protects Encryption Keys | Processes are in place to protect encryption keys during generation, storage, use, and destruction. | Teleport acts as a Certificate Authority to issue SSH and x509 user certificates that are signed by the CA and are (by default) short-lived. SSH host certificates are also signed by the CA and rotated automatically  | 
 | CC6.2 - Controls Access Credentials to Protected Assets | Information asset access credentials are created based on an authorization from the system&#39;s asset owner or authorized custodian. | [Request Approval from the command line](../../reference/cli.mdx#tctl-request-approve) <br/><br/> [Build Approval Workflows with Access Requests](../../access-controls/access-requests.mdx) <br/><br/> [Use Plugins to send approvals to tools like Slack or Jira](../../access-controls/access-requests.mdx) |

docs/pages/access-controls/login-rules/kubernetes.mdx

@@ -44,7 +44,7 @@ This guide is applicable if you self-host Teleport in Kubernetes using the
   </Admonition>
 
 - Follow Step 1 of the
-  [Teleport operator guide](../../management/guides/teleport-operator.mdx#step-13-install-teleport-cluster-helm-chart-with-the-operator)
+  [Teleport operator guide](../../management/dynamic-resources/teleport-operator.mdx#step-13-install-teleport-cluster-helm-chart-with-the-operator)
   to install the Teleport Operator in your Kubernetes cluster.
   Make sure to follow the Enterprise instructions.
 
@@ -250,7 +250,7 @@ logins:
 
 ## Next Steps
 
-- Read the [Teleport Operator Guide](../../management/guides/teleport-operator.mdx) to
+- Read the [Teleport Operator Guide](../../management/dynamic-resources/teleport-operator.mdx) to
   learn more about the Teleport Operator.
 - Read the [Login Rules reference](./reference.mdx) to learn mode about the
   Login Rule expression syntax.

docs/pages/access-controls/login-rules/terraform.mdx

@@ -31,7 +31,7 @@ For simplicity, this guide will configure the Terraform provider to use your
 current logged-in user's Teleport credentials obtained from `tsh login`.
 
 <Admonition type="note">
-The [Terraform provider guide](../../management/guides/terraform-provider.mdx)
+The [Terraform provider guide](../../management/dynamic-resources/terraform-provider.mdx)
 includes instructions for configuring a dedicated `terraform` user and role,
 which is a better option when running Terraform in a non-interactive
 environment.
@@ -156,7 +156,7 @@ logins:
 
 ## Next Steps
 
-- Read the [Terraform Guide](../../management/guides/terraform-provider.mdx) to
+- Read the [Terraform Guide](../../management/dynamic-resources/terraform-provider.mdx) to
   learn more about configuring the Terraform provider.
 - Read the [Login Rules reference](./reference.mdx) to learn mode about the
   Login Rule expression syntax.

docs/pages/agents/deploy-agents-terraform.mdx

@@ -0,0 +1,308 @@
+---
+title: "Deploy Teleport Agents with Terraform"
+description: "In this guide, we will show you how to deploy a pool of Teleport agents so you can apply dynamic resources to enroll your infrastructure with Teleport."
+---
+
+An agent is a Teleport instance configured to run one or more Teleport services
+in order to proxy infrastructure resources. For a brief architectural overview
+of how agents run in a Teleport cluster, read the [Introduction to Teleport
+Agents](introduction.mdx).
+
+This guide shows you how to deploy a pool of Teleport agents by declaring it as
+code using Terraform.
+
+There are several methods you can use to join a Teleport agent to your cluster,
+which we discuss in the [Joining Services to your
+Cluster](join-services-to-your-cluster.mdx) guide. In this guide, we will use
+the **join token** method, where the operator stores a secure token on the Auth
+Service, and an agent presents the token in order to join a cluster.
+
+No matter which join method you use, it will involve the following Terraform
+resources:
+
+- Compute instances to run Teleport services
+- A join token for each compute instance in the agent pool
+
+```mermaid
+flowchart TB
+subgraph agent1["Teleport agent"]
+  service1["Teleport service"]
+  service2["Teleport service"]
+  join1["Join token"]
+end
+
+subgraph agent2["Teleport agent"]
+  join2["Join token"]
+  service3["Teleport service"]
+  service4["Teleport service"]
+end
+
+subgraph auth["Auth Service"]
+  join3["Join token"]
+  join4["Join token"]
+end
+
+join1<-.Matches.->join3
+join2<-.Matches.->join4
+```
+
+## Prerequisites
+
+(!docs/pages/includes/edition-prereqs-tabs.mdx!)
+
+<Admonition type="tip">
+
+We recommend following this guide on a fresh Teleport demo cluster so you can
+see how an agent pool works. After you are familiar with the setup, apply the
+lessons from this guide to protect your infrastructure. You can get started with
+a demo cluster using:
+- A demo deployment on a [Linux server](../index.mdx)
+- A [Teleport Team trial](https://goteleport.com/signup)
+
+</Admonition>
+
+- An AWS account with permissions to create EC2 instances.
+- Terraform v(=terraform.version=).
+- An identity file for the Teleport Terraform provider. Make sure you are
+  familiar with [how to set up the Teleport Terraform
+  provider](../management/dynamic-resources/terraform-provider.mdx) before following this
+  guide.
+- (!docs/pages/includes/tctl.mdx!)
+
+## Step 1/3. Fetch the example Terraform configuration
+
+Fetch the Teleport code repository and copy the example Terraform configuration
+for this project into your current working directory:
+
+```code
+$ git clone --depth=1 https://github.com/gravitational/teleport
+$ cp -R teleport/examples/agent-pool-terraform .
+$ rm -rf teleport
+```
+
+Move the identity file for the Teleport Terraform provider into your project
+directory so the Terraform provider an access it. Name the file
+`terraform-identity`.
+
+<Notice type="warning">
+
+If you don't have an identify file available, make sure you have followed the
+[prerequisites for this guide](#prerequisites).
+
+</Notice>
+
+## Step 2/3. Prepare your Terraform configuration
+
+After you have copied the example Terraform configuration, you will assign input
+variables and apply your new resources. First, we will explain the Terraform
+resource configuration you copied so you can understand how to deploy an agent
+pool in your infrastructure.
+
+### Instances and tokens
+
+The file `agent-pool.tf` configures EC2 instances and Teleport join tokens:
+
+```text
+(!examples/agent-pool-terraform/agent-pool.tf!)
+```
+
+In this minimal example, we deploy one EC2 instance for each Teleport agent.
+Each agent joins the cluster using a token. We create each token using the
+`teleport_provision_token` Terraform resource, specifying the token's value with
+a `random_string` resource.
+
+When we apply the `teleport_provision_token` resources, the Teleport Terraform
+provider creates them on the Teleport Auth Service backend. Each EC2 instance
+presents the token in order to establish trust with the cluster. 
+
+The Auth Service associates the join token with one or more roles, identifying
+the Teleport service that is allowed to use the token. The configuration above
+generates tokens for the following Teleport services:
+
+- Teleport SSH Service (`Node`)
+- Teleport Application Service (`App`)
+- Teleport Database Service (`Db`)
+- Teleport Kubernetes Service (`Kube`)
+
+### Startup script
+
+Each EC2 instance runs a script on startup, which we configured above using the
+`user_data` field within the `aws_instance.teleport_agent` resource
+(`examples/agent-pool-terraform/userdata`):
+
+```text
+(!examples/agent-pool-terraform/userdata!)
+```
+
+This script installs Teleport Community Edition on the host, then writes a
+configuration file to the default location, `/etc/teleport.yaml`. The
+configuration file enables each Teleport service we associated with our token.
+
+The configuration also adds the `role: agent-pool` label to the Teleport SSH
+Service on each instance. This will make it easier to access hosts in the agent
+pool later.
+
+Finally, the script restarts Teleport on the host to apply the new
+configuration.
+
+### Input variables
+
+The Terraform configuration we show in this guide relies on the following inputs
+(`examples/agent-pool-terraform/inputs.tf`):
+
+```text
+(!examples/agent-pool-terraform/inputs.tf!)
+```
+
+In your `agent-pool-terraform` project directory, create a file called
+`main.auto.tfvars` with the following content:
+
+```text
+agent_count=2
+proxy_service_address="mytenant.teleport.sh"
+aws_region=""
+teleport_version=(=teleport.version=)
+subnet_id=""
+```
+
+Assign `agent_count` to `2` for high availability. As you scale your Teleport
+usage, you can increase this count to ease the load on each agent. You can
+consider adding your agents to an Auto Scaling group as well.
+
+Assign `proxy_service_address` to the host and HTTPS port of your Teleport Proxy
+Service, e.g., `mytenant.teleport.sh:443`.
+
+<Notice type="tip">
+
+Make sure to include the port.
+
+</Notice>
+
+Assign `aws_region` to your AWS region, e.g., `us-east-1`.
+
+For `subnet_id`, include the ID of the AWS subnet where you will deploy Teleport
+agents.
+
+Finally, make sure you are using the latest supported version of the Teleport
+Terraform provider. The `required_providers` block for the Teleport provider
+includes a placeholder value:
+
+```text
+(!examples/agent-pool-terraform/provider.tf!)
+```
+
+Replace the placeholder value with the latest version:
+
+```code
+$ sed -i "" "s/TELEPORT_VERSION/(=teleport.plugin.version=)/" provider.tf
+```
+
+## Step 3/3. Verify the deployment
+
+Make sure your AWS credentials are available to Terraform using the standard
+approach for your organization.
+
+Apply the Terraform configuration:
+
+```code
+$ terraform apply
+```
+
+Once the `apply` command completes, run the following command to verify that the
+two agents have deployed successfully:
+
+```code
+$ tsh ls role=agent-pool
+Node Name                  Address    Labels
+-------------------------- ---------- ---------------
+ip-10-1-1-187.ec2.internal ⟵ Tunnel   role=agent-pool
+ip-10-1-1-24.ec2.internal  ⟵ Tunnel   role=agent-pool
+```
+
+## Next step: Enroll infrastructure resources
+
+There are two ways to configure your agent pool to protect infrastructure
+resources with Teleport, which we describe below.
+
+### Define dynamic resources in Terraform 
+
+You can declare Terraform resources that enroll your infrastructure with
+Teleport. The Teleport Terraform provider currently supports the following:
+
+|Infrastructure Resource|Terraform Resource|
+|---|---|
+|Application|`teleport_app`|
+|Database|`teleport_database`|
+
+To declare a dynamic resource with Terraform, add a configuration block similar
+to the ones below to a `*.tf` file in your `agent-pool-terraform` project
+directory. 
+
+The Teleport Terraform provider creates these on the Auth Service backend, and
+the relevant Teleport services query them in order to proxy user traffic. For a
+full list of supported resources and fields, see the [Terraform provider
+reference](../reference/terraform-provider.mdx).
+
+<Tabs>
+<TabItem label="Application">
+
+```text
+resource "teleport_app" "example" {
+  metadata = {
+    name        = "example"
+    description = "Test app"
+    labels = {
+      // Teleport adds this label by default, so add it here to
+      // ensure a consistent state.
+      "teleport.dev/origin" = "dynamic"
+    }
+  }
+
+  spec = {
+    uri = "localhost:3000"
+  }
+}
+```
+
+</TabItem>
+<TabItem label="Database">
+
+```text
+resource "teleport_database" "example" {
+  metadata = {
+    name        = "example"
+    description = "Test database"
+    labels = {
+      // Teleport adds this label by default, so add it here to
+      // ensure a consistent state.
+      "teleport.dev/origin" = "dynamic"
+    }
+  }
+
+  spec = {
+    protocol = "postgres"
+    uri      = "localhost"
+  }
+}
+```
+
+</TabItem>
+</Tabs>
+
+### Configure Teleport services in the agent pool
+
+Each Teleport service reads its local configuration file (`/etc/teleport.yaml`
+by default) to determine which infrastructure resources to proxy. You can edit
+this configuration file to enroll resources with Teleport.
+
+In the setup we explored in this guide, you can edit the user data script for
+each instance to add configuration settings to, for example, the
+`database_service` or `kubernetes_service` sections.
+
+To see how to configure each service, read its section of the documentation:
+
+- [SSH Service](../server-access/introduction.mdx)
+- [Database Service](../database-access/introduction.mdx)
+- [Kubernetes Service](../kubernetes-access/introduction.mdx)
+- [Windows Desktop Service](../desktop-access/introduction.mdx)
+- [Application Service](../application-access/introduction.mdx)