[Tracker issue] Make infrastructure as code a first-class citizen of the docs

[ptgott]

Applies To

Determining the correct pages is part of the project.

How will we know this is resolved?

The following tracking table is complete. See below for a description of each learning track.

Track	Issue	Pull Request
toy/terraform/self-hosted	#27382
toy/terraform/cloud	#27382
production/terraform/self-hosted
production/helm/self-hosted
production/terraform/cloud	#27382
production/helm/cloud

Related Issues

25423 overlaps with this work. Since that PR focuses on a particular implementation detail, let's address #27379 first, since it is focused on use cases and audiences.

Details

The problem

Currently, our instructions for using infrastructure-as-code tools with Teleport are confined to a couple guides that are buried within subsections of the docs, and it's not clear to users that Teleport deeply integrates with these tools.

Conceptualizing setting up Teleport via IAC

Tools

Teleport has good support for two infrastructure as code tools:

• Helm: deploying the Auth/Proxy Service and agents. Limited support for applying configuration resources via the Kubernetes operator.
• Terraform: Can apply all available configuration resources. Support for deploying agents and the Auth/Proxy Service depends on our bre-built AMIs and any Terraform config a user is able to put together to run Teleport on their infrastructure of choice.

Categorizing IAC flows

An infrastructure-as-code approach to Teleport depends on the following attributes of a prospective user:

• Maturity: Is the cluster a toy cluster or a production cluster? Early users need to spend as little time as possible discovering Teleport's value. Later users need Teleport to integrate with the particulars of their organization's infrastructure, and can spend more time setting this up.
• Edition: Is the user setting up a self-hosted cluster or Teleport Cloud (i.e., starting with Team or scaling to Enterprise Cloud)? This dictates whether the user needs to set up the Auth/Proxy Services via IAC.
• IAC tool: Is the user using Terraform or Helm?

For the purpose of infrastructure-as-code instructions, we can condense our guidance for Teleport Community Edition and Teleport Enterprise Self-Hosted. Architecturally, deploying the two editions via Helm and Terraform are the same, as are the methods you would use for applying resources and deploying agents. The only difference from the perspective of deploying is how to make the license file available to an Enterprise deployment.

Each combination of qualities determines a user's track through the docs and use of IAC with Teleport.

Here are all the permutations:

• toy/terraform/self-hosted
• toy/helm/self-hosted
• toy/terraform/cloud
• toy/helm/cloud
• production/terraform/self-hosted
• production/helm/self-hosted
• production/terraform/cloud
• production/helm/cloud

Possible Steps

Users can achieve several Teleport tasks using IAC solutions. Here are some broad categories:

• Deploy the Auth/Proxy Service
• Deploy a pool of agents: In a departure from the current docs, this is a separate step from enrolling infrastructure resources to make IAC more straightforward. Once users have a pool of agents, they can apply dynamic configuration resources to enroll infrastructure resources.
• Manage access (RBAC)
• Enroll infrastructure resources

For now, we'll ignore the steps in the "Manage your Cluster" section of the docs to focus on the steps above.

Tracks

Each combination of the user attributes listed above influences the procedure for setting up Teleport using IAC.

toy/terraform/self-hosted

• Deploy the Auth/Proxy Service: Single Linux server (i.e., the Linux Server Guide), using the AWS Terraform AMI with an "aws_instance" resource or a Digital Ocean droplet with the "digitalocean_droplet" resource and a startup script.

• Deploy a pool of agents: Linux server for each agent using an "aws_instance" or "digitalocean_droplet". Create a token resource for each agent and use that token within a startup script that runs on each node.

• Manage access (RBAC): How to use the Terraform provider to create roles, users, CAPs, and SSO connectors.

• Enroll resources: How to use the Terraform provider to enroll infrastructure resources via dynamic configuration resources.

toy/helm/self-hosted

We don\'t support this track, as Kubernetes doesn\'t lend itself to small-scale toy clusters and a minikube-hosted Teleport cluster would make it difficult to add resources.

toy/terraform/cloud

• Deploy a pool of agents: Linux server for each agent using an \"aws_instance\" or \"digitalocean_droplet\". Create a token resource for each agent and use that token within a startup script that runs on each agent node.
• Manage access (RBAC): Use the Terraform provider to create roles, users, CAPs, and SSO connectors.
• Enroll resources: Use the Terraform provider to enroll infrastructure resources via dynamic configuration resources.

toy/helm/cloud

We don\'t support this track, as we imagine that users of toy clusters want to add actual infrastructure resources to their cluster, and Kubernetes doesn\'t lend itself to small toy clusters. If a user wants to play with minikube, for example, we would need to show examples of enrolling local demo resources in a Teleport cluster.

production/terraform/self-hosted

• Deploy the Auth/Proxy Service: Follow best practices with a pre-written Terraform module for deploying an HA Teleport cluster on AWS. We have an existing guide for this that we can update.
• Deploy a pool of agents: Extend the Terraform module above to include a pool of agents.
• Manage access (RBAC): Use the Terraform provider to create roles, users, CAPs, and SSO connectors.
• Enroll resources: Use the Terraform provider to enroll infrastructure resources via dynamic configuration resources.

production/helm/self-hosted

• Deploy the Auth/Proxy Service: We have an existing guide to running an HA Teleport cluster using AWS, EKS and Helm. We can see if we can make this more IAC-focused and change the information architecture of viewing the guide.
• Deploy a pool of agents: Use the teleport-kube-agent chart to deploy a pool of agents. The Teleport Kubernetes Operator can create provision tokens for these. Note that the Kubernetes Operator does not yet allow you to apply dynamic infrastructure resources, so we will need to use a static configuration file for each agent.
• Manage access (RBAC): Use the Kubernetes Operator to create roles, users, and SSO connectors. (CAPs are not yet supported. Here are the resources the Operator supports.)

production/terraform/cloud

• Deploy a pool of agents: Linux server for each agent using an \"aws_instance\" or \"digitalocean_droplet\". Create a token resource for each agent and use that token within a startup script that runs on each node.
• Manage access (RBAC): Use the Terraform provider to create roles, users, CAPs, and SSO connectors.
• Enroll resources: Use the Terraform provider to enroll infrastructure resources via dynamic configuration resources.

production/helm/cloud

• Deploy a pool of agents: Use the teleport-kube-agent chart to deploy a pool of agents. The Teleport Kubernetes Operator can create provision tokens for these. Note that the Kubernetes Operator does not yet allow you to apply dynamic resources, so we will need to use a static configuration file for each agent.
• Manage access (RBAC): Use the Kubernetes Operator to create roles, users, and SSO connectors.

[ptgott]

Closing as complete:

• There is now a second-level section on infrastructure as code, moving all IaC-related admin guides into one location: https://github.com/gravitational/teleport/tree/master/docs/pages/admin-guides/infrastructure-as-code
• There are references for Kubernetes operator resources as well as Terraform resources.
• The learning tracks described as missing in this issue are actually present: there are Terraform modules for a self-hosted cluster as well as the teleport-cluster chart, all of which are described in the deploy-a-cluster section of the docs.

If there are more specific issues that make IaC less prominent than it can be in the docs, we should track these as separate GitHub issues, as this issue is very broadly defined.