Add a two-part Terraform starter guide#44834
Merged
Conversation
github-actions
Bot
requested review from
EdwardDowling,
mmcallister,
r0mant,
ryanclark,
xinding33 and
zmb3
Contributor
|
The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with |
1 similar comment
Contributor
|
The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with |
Contributor
|
🤖 Vercel preview here: https://docs-fggtisa8u-goteleport.vercel.app/docs/ver/preview |
ptgott
force-pushed
the
paul.gottschling/2024-07-tf-rbac
branch
from
42593e8 to
61b7270
Compare
Contributor
|
The PR changelog entry failed validation: Changelog entry not found in the PR body. Please add a "no-changelog" label to the PR, or changelog lines starting with |
ptgott
added
the
no-changelog
Contributor
|
🤖 Vercel preview here: https://docs-mwdrvwpie-goteleport.vercel.app/docs/ver/preview |
ptgott
force-pushed
the
paul.gottschling/2024-07-tf-rbac
branch
from
61b7270 to
7e9add5
Compare
Contributor
|
🤖 Vercel preview here: https://docs-915b9z298-goteleport.vercel.app/docs/ver/preview |
ptgott
force-pushed
the
paul.gottschling/2024-07-tf-rbac
branch
from
7e9add5 to
b866fc7
Compare
Contributor
|
🤖 Vercel preview here: https://docs-kvlytfpw1-goteleport.vercel.app/docs/ver/preview |
Contributor
Author
|
@mmcallister Just putting this on your radar for when you have time to take a look. Thanks! |
hugoShaka
reviewed
Aug 2, 2024
Contributor
Author
|
Feedback item TODOs:
For the bottom three bullets, consider editing Part One to only explain how to enroll servers, mentioning the ability to enroll other resource kinds (and limitations for enrolling those resource kinds) in a "Further reading" section. |
ptgott
force-pushed
the
paul.gottschling/2024-07-tf-rbac
branch
from
5099436 to
ec58c89
Compare
public-teleport-github-review-bot
Bot
removed the request for review
from stevenGravy
ptgott
force-pushed
the
paul.gottschling/2024-07-tf-rbac
branch
from
cb35ffb to
30938bb
Compare
Contributor
|
🤖 Vercel preview here: https://docs-ms5r5qqln-goteleport.vercel.app/docs/ver/preview |
Closes #41055 Add a learning series for users who wants to get started with managing Teleport resources using Terraform. The guide takes the user through some fundamental cluster setup tasks: deploying Agents, enrolling resources, adding labels, configuring roles, and setting up SSO. The series includes two guides: - Part One: Enrolling resources - Part Two: Configuring RBAC Part One of the series is based on the "Deploy Agents with Terraform" guide. This change adds instructions to the guide to label infrastructure resources so the user can access those resources with the roles configured in Part Two. Other changes: - Rename `agent-pool-terraform` to `terraform-starter`. - Rename the "Dynamic Resources" guide to be more explicitly about Infrastructure as Code. Organize this section into subsections to make room for the new starter guide. - Edit the Further Reading discussion in Part One. Move the static resource discussion to Further Reading because, otherwise, there is too much explanatory text between instructions. Also mention auto-discovery.
- Fix link syntax. - Set expectations that the child modules downloaded in the two guides are examples. - Remove diagram with outdated logo. - Use purpose-oriented names for TF files instead of `main.tf` - Use `tctl terraform env` to get credentials
Responds to hugoShaka feedback. Resources that are not SSH servers registered via the SSH Service have some complexities that don't make sense to cover in this guide. Instead, for simplicity, the guide has the user deploy SSH Service instances, then includes the possibility of enrolling other kinds of resources in a "Next steps" section. Changes: - Remove the `agent_roles` input in the `terraform-starter/agent-installation` module. - Only deploy a token for the Node role, and configure the Agents deployed by the module to only enable the SSH Service. - Add an agent_labels input to the `agent-installation` module. - Move non-server deployment instructions to "Next steps".
Note that you can skip the SSO step in the RBAC guide. Include links to relevant docs.
ptgott
force-pushed
the
paul.gottschling/2024-07-tf-rbac
branch
from
30938bb to
e2f89e5
Compare
Contributor
|
🤖 Vercel preview here: https://docs-p5157bcil-goteleport.vercel.app/docs/ver/preview |
ptgott
force-pushed
the
paul.gottschling/2024-07-tf-rbac
branch
from
e2f89e5 to
a6888b2
Compare
Contributor
|
🤖 Vercel preview here: https://docs-enh8mjc2h-goteleport.vercel.app/docs/ver/preview |
ptgott
added a commit
that referenced
this pull request
Sep 19, 2025
The Terraform starter guide, added in #44834, was meant to provide new Teleport users with a comprehensive example of deploying agents, configuring SSO, and managing RBAC. However, for a guide aimed at educating a broad audience, it gets very little exposure on the docs site. This change improves the visibility of the Terraform starter guide. - **Condense the two-part guide and its index page into a single guide:** Currently, the index page for the two-part guide has little substantial content and performs poorly in organic search. By condensing all content of the guide into a single page, we can provide a content-rich page that is more visible in search results. - **Move the guide:** Make it the Getting Started page within the `/docs/infrastructure-as-code/terraform-provider` section. This also clarifies the structure of the Infrastructure as Code section, since all Terraform-specific content is in a single subsection. To make this work, rename the sidebar titles of the Terraform section and add a link to the guide within the section index page. - **Minor edits to the Terraform starter guide:** Move the SSO guide links to the prerequisites section to avoid surprising the user with the need to context-switch. Remove an unneeded `tctl.mdx` partial inclusion. Remove prerequisite item re: following a Terraform setup guide, since this guide already shows the local demo method.
ptgott
added a commit
that referenced
this pull request
Sep 19, 2025
The Terraform starter guide, added in #44834, was meant to provide new Teleport users with a comprehensive example of deploying agents, configuring SSO, and managing RBAC. However, for a guide aimed at educating a broad audience, it gets very little exposure on the docs site. This change improves the visibility of the Terraform starter guide. - **Condense the two-part guide and its index page into a single guide:** Currently, the index page for the two-part guide has little substantial content and performs poorly in organic search. By condensing all content of the guide into a single page, we can provide a content-rich page that is more visible in search results. - **Move the guide:** Make it the Getting Started page within the `/docs/infrastructure-as-code/terraform-provider` section. This also clarifies the structure of the Infrastructure as Code section, since all Terraform-specific content is in a single subsection. To make this work, rename the sidebar titles of the Terraform section and add a link to the guide within the section index page. - **Minor edits to the Terraform starter guide:** Move the SSO guide links to the prerequisites section to avoid surprising the user with the need to context-switch. Remove an unneeded `tctl.mdx` partial inclusion. Remove prerequisite item re: following a Terraform setup guide, since this guide already shows the local demo method.
ptgott
added a commit
that referenced
this pull request
Sep 19, 2025
The Terraform starter guide, added in #44834, was meant to provide new Teleport users with a comprehensive example of deploying agents, configuring SSO, and managing RBAC. However, for a guide aimed at educating a broad audience, it gets very little exposure on the docs site. This change improves the visibility of the Terraform starter guide. - **Condense the two-part guide and its index page into a single guide:** Currently, the index page for the two-part guide has little substantial content and performs poorly in organic search. By condensing all content of the guide into a single page, we can provide a content-rich page that is more visible in search results. - **Move the guide:** Make it the Getting Started page within the `/docs/infrastructure-as-code/terraform-provider` section. This also clarifies the structure of the Infrastructure as Code section, since all Terraform-specific content is in a single subsection. To make this work, rename the sidebar titles of the Terraform section and add a link to the guide within the section index page. - **Minor edits to the Terraform starter guide:** Move the SSO guide links to the prerequisites section to avoid surprising the user with the need to context-switch. Remove an unneeded `tctl.mdx` partial inclusion. Remove prerequisite item re: following a Terraform setup guide, since this guide already shows the local demo method.
ptgott
added a commit
that referenced
this pull request
Sep 19, 2025
The Terraform starter guide, added in #44834, was meant to provide new Teleport users with a comprehensive example of deploying agents, configuring SSO, and managing RBAC. However, for a guide aimed at educating a broad audience, it gets very little exposure on the docs site. This change improves the visibility of the Terraform starter guide. - **Condense the two-part guide and its index page into a single guide:** Currently, the index page for the two-part guide has little substantial content and performs poorly in organic search. By condensing all content of the guide into a single page, we can provide a content-rich page that is more visible in search results. - **Move the guide:** Make it the Getting Started page within the `/docs/infrastructure-as-code/terraform-provider` section. This also clarifies the structure of the Infrastructure as Code section, since all Terraform-specific content is in a single subsection. To make this work, rename the sidebar titles of the Terraform section and add a link to the guide within the section index page. - **Minor edits to the Terraform starter guide:** Move the SSO guide links to the prerequisites section to avoid surprising the user with the need to context-switch. Remove an unneeded `tctl.mdx` partial inclusion. Remove prerequisite item re: following a Terraform setup guide, since this guide already shows the local demo method.
ptgott
added a commit
that referenced
this pull request
Sep 19, 2025
The Terraform starter guide, added in #44834, was meant to provide new Teleport users with a comprehensive example of deploying agents, configuring SSO, and managing RBAC. However, for a guide aimed at educating a broad audience, it gets very little exposure on the docs site. This change improves the visibility of the Terraform starter guide. - **Condense the two-part guide and its index page into a single guide:** Currently, the index page for the two-part guide has little substantial content and performs poorly in organic search. By condensing all content of the guide into a single page, we can provide a content-rich page that is more visible in search results. - **Move the guide:** Make it the Getting Started page within the `/docs/infrastructure-as-code/terraform-provider` section. This also clarifies the structure of the Infrastructure as Code section, since all Terraform-specific content is in a single subsection. To make this work, rename the sidebar titles of the Terraform section and add a link to the guide within the section index page. - **Minor edits to the Terraform starter guide:** Move the SSO guide links to the prerequisites section to avoid surprising the user with the need to context-switch. Remove an unneeded `tctl.mdx` partial inclusion. Remove prerequisite item re: following a Terraform setup guide, since this guide already shows the local demo method.
ptgott
added a commit
that referenced
this pull request
Sep 19, 2025
The Terraform starter guide, added in #44834, was meant to provide new Teleport users with a comprehensive example of deploying agents, configuring SSO, and managing RBAC. However, for a guide aimed at educating a broad audience, it gets very little exposure on the docs site. This change improves the visibility of the Terraform starter guide. - **Condense the two-part guide and its index page into a single guide:** Currently, the index page for the two-part guide has little substantial content and performs poorly in organic search. By condensing all content of the guide into a single page, we can provide a content-rich page that is more visible in search results. - **Move the guide:** Make it the Getting Started page within the `/docs/infrastructure-as-code/terraform-provider` section. This also clarifies the structure of the Infrastructure as Code section, since all Terraform-specific content is in a single subsection. To make this work, rename the sidebar titles of the Terraform section and add a link to the guide within the section index page. - **Minor edits to the Terraform starter guide:** Move the SSO guide links to the prerequisites section to avoid surprising the user with the need to context-switch. Remove an unneeded `tctl.mdx` partial inclusion. Remove prerequisite item re: following a Terraform setup guide, since this guide already shows the local demo method.
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
5 participants
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Closes #41055
Add a learning series for users who wants to get started with managing Teleport resources using Terraform. The guide takes the user through some fundamental cluster setup tasks: deploying Agents, enrolling resources, adding labels, configuring roles, and setting up SSO. The series includes two guides:
Part One of the series is based on the "Deploy Agents with Terraform" guide. This change adds instructions to the guide to label infrastructure resources so the user can access those resources with the roles configured in Part Two.
Other changes:
agent-pool-terraformtoterraform-starter.