Create "Configuring your Cluster" docs subsection#25442
Closed
Create "Configuring your Cluster" docs subsection#25442
Conversation
zmb3
reviewed
May 2, 2023
Collaborator
There was a problem hiding this comment.
This could fail depending on what order find produces and what resources depend on others, right?
Is it worth mentioning some strategy or file naming convention to ensure that dependent resources come later?
Contributor
Author
There was a problem hiding this comment.
Ah, good point. I've removed the example command, kept the instructions vague, and added a link to the tctl reference for more information.
Collaborator
There was a problem hiding this comment.
Given this title, I'd expect to see a mention of teleport.yaml here.
This page is more about dynamic configuration - I would include that in the title, and probably also add some notes about how conflicts are resolved between static file config and dynamic configuration resources.
Contributor
Author
There was a problem hiding this comment.
👍 That makes sense—I'll make time to add this section to the page later this week.
Contributor
Author
|
TODO
|
ptgott
force-pushed
the
paul.gottschling/25418-iac-section
branch
from
c4d3790 to
a0bd7b6
Compare
This comment was marked as outdated.
This comment was marked as outdated.
ptgott
force-pushed
the
paul.gottschling/25418-iac-section
branch
from
3e4fd20 to
a408a84
Compare
ptgott
force-pushed
the
paul.gottschling/25418-iac-section
branch
3 times, most recently
from
6ab4575 to
8b88f46
Compare
stevenGravy
reviewed
May 15, 2023
ptgott
force-pushed
the
paul.gottschling/25418-iac-section
branch
from
38d031b to
38a0519
Compare
Contributor
Author
|
@alexfornuto Do you have any thoughts on this? Thanks! |
Contributor
Author
|
@zmb3 Following up on this one. Thanks! |
zmb3
reviewed
May 20, 2023
alexfornuto
reviewed
May 22, 2023
Contributor
Author
TODO:
|
ptgott
force-pushed
the
paul.gottschling/25418-iac-section
branch
from
9037c65 to
1002ea5
Compare
Contributor
Author
|
I'm going to put this in draft for a bit to make this closer to the proposal in #27382, which is one of our commitments for Q2. |
Closes #25418 Help make infrastructure-as-code approaches more prominent in the Teleport docs by separating the Operator and Terraform guides into a "Configuring your Cluster" subsection of the "Management" section. This also adds an introductory page that explains the three major tools we expose for interacting with a Teleport cluster (not counting the API). This subsection also gives us a place to put other guides to using Terraform and the Operator, e.g., if we add guides to using these tools with popular GitOps platforms.
Respond to zmb3 comments - List dynamic fields that overlap static ones - Explain how the Auth Service handles interactions between static and dynamic fields - Since there's some overlap between this and the Configuration Resource Reference, move the conceptual discussions within the reference to this guide.
ptgott
force-pushed
the
paul.gottschling/25418-iac-section
branch
from
1002ea5 to
6caf763
Compare
ptgott
added a commit
that referenced
this pull request
Jun 9, 2023
Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page.
ptgott
added a commit
that referenced
this pull request
Jun 21, 2023
Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page.
ptgott
added a commit
that referenced
this pull request
Jun 28, 2023
Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page.
Contributor
Author
|
Closing in favor of #27703 |
ptgott
added a commit
that referenced
this pull request
Jun 30, 2023
Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page.
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jun 30, 2023
* Promote IAC docs for agents and dynamic resources Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page. * Move the "Dynamic Configuration" section Make this a subsection of "Manage your Cluster" since it's not self-evidently clear as a top-level docs section. Users will probably need an introduction via the "Manage your Cluster" section intro page. This also reverts some of the more drastic sidebar changes introduced by the previous commit. Responds to xinding33 feedback. * Make IAC learning tracks prominent/hard to avoid Closes #27751 Responds to xinding33 feedback The motivation is to be more opinionated about the course that users take through the docs. We currently recommend two tracks for self-service users, i.e., the users expected to make use of the landing page: - Setting up a toy self-hosted Teleport cluster - Setting up a Teleport Team/Enterprise Cloud cluster that can eventually become production ready By moving the "Get Started" guide to the landing page, we direct users immediately on to the first track. This change then gives new users a way to enter the second track from the docs landing page with a prominent link to the Teleport Team docs. This change also edits The landing page to direct users who have completed the getting started experience to instructions for setting up a pool of agents on Terraform, helping to make infrastructure-as-code a first-class citizen of the docs. This change also removes the menu of links that used to confront users on the landing page. Since all sidebar sections include introduction pages, users interested in the content of a sidebar section can visit the section. By removing links, we make it clearer for users how to proceed through the docs. * Fix linter errors * Incorporate Trivy recommendations * Respond to alexfornuto feedback * Restore list of dynamic resources to the reference * Fix linter warnings * Remove the ".sh" extension from userdata script The Terraform module that reads this file does not need the extension, which was causing trouble for our shellcheck linter.
ptgott
added a commit
that referenced
this pull request
Jun 30, 2023
Backports #27703 * Promote IAC docs for agents and dynamic resources Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page. * Move the "Dynamic Configuration" section Make this a subsection of "Manage your Cluster" since it's not self-evidently clear as a top-level docs section. Users will probably need an introduction via the "Manage your Cluster" section intro page. This also reverts some of the more drastic sidebar changes introduced by the previous commit. Responds to xinding33 feedback. * Make IAC learning tracks prominent/hard to avoid Closes #27751 Responds to xinding33 feedback The motivation is to be more opinionated about the course that users take through the docs. We currently recommend two tracks for self-service users, i.e., the users expected to make use of the landing page: - Setting up a toy self-hosted Teleport cluster - Setting up a Teleport Team/Enterprise Cloud cluster that can eventually become production ready By moving the "Get Started" guide to the landing page, we direct users immediately on to the first track. This change then gives new users a way to enter the second track from the docs landing page with a prominent link to the Teleport Team docs. This change also edits The landing page to direct users who have completed the getting started experience to instructions for setting up a pool of agents on Terraform, helping to make infrastructure-as-code a first-class citizen of the docs. This change also removes the menu of links that used to confront users on the landing page. Since all sidebar sections include introduction pages, users interested in the content of a sidebar section can visit the section. By removing links, we make it clearer for users how to proceed through the docs. * Fix linter errors * Incorporate Trivy recommendations * Respond to alexfornuto feedback * Restore list of dynamic resources to the reference * Fix linter warnings * Remove the ".sh" extension from userdata script The Terraform module that reads this file does not need the extension, which was causing trouble for our shellcheck linter.
ptgott
added a commit
that referenced
this pull request
Jun 30, 2023
Backports #27703 * Promote IAC docs for agents and dynamic resources Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page. * Move the "Dynamic Configuration" section Make this a subsection of "Manage your Cluster" since it's not self-evidently clear as a top-level docs section. Users will probably need an introduction via the "Manage your Cluster" section intro page. This also reverts some of the more drastic sidebar changes introduced by the previous commit. Responds to xinding33 feedback. * Make IAC learning tracks prominent/hard to avoid Closes #27751 Responds to xinding33 feedback The motivation is to be more opinionated about the course that users take through the docs. We currently recommend two tracks for self-service users, i.e., the users expected to make use of the landing page: - Setting up a toy self-hosted Teleport cluster - Setting up a Teleport Team/Enterprise Cloud cluster that can eventually become production ready By moving the "Get Started" guide to the landing page, we direct users immediately on to the first track. This change then gives new users a way to enter the second track from the docs landing page with a prominent link to the Teleport Team docs. This change also edits The landing page to direct users who have completed the getting started experience to instructions for setting up a pool of agents on Terraform, helping to make infrastructure-as-code a first-class citizen of the docs. This change also removes the menu of links that used to confront users on the landing page. Since all sidebar sections include introduction pages, users interested in the content of a sidebar section can visit the section. By removing links, we make it clearer for users how to proceed through the docs. * Fix linter errors * Incorporate Trivy recommendations * Respond to alexfornuto feedback * Restore list of dynamic resources to the reference * Fix linter warnings * Remove the ".sh" extension from userdata script The Terraform module that reads this file does not need the extension, which was causing trouble for our shellcheck linter.
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jun 30, 2023
Backports #27703 * Promote IAC docs for agents and dynamic resources Closes #27382 Closes #25418 Closes #25442 Two aspects of setting up a Teleport cluster are omnipresent in the docs but never get dedicated treatment: - Running agents - Applying dynamic resources As a result, it is difficult to include discussions about those topics that are separate from a specific workflow or how-to guide. One glaring absence has been prominent guidance on using infrastructure-as-code tools to achieve these tasks. This change improves the visibility of Teleport's support for infrastructure-as-code tools by: - Creating top-level docs sections for running agents and applying dynamic resources - Making IAC instructions prominent within these sections The intention is for readers to become familiar with different methods of applying dynamic resources and running agents, including how to do this with IAC, so they can apply this knowledge when reading other parts of the docs. As a result, in the docs sidebar, the "Dynamic Resources" section comes before the section on RBAC, and the "Teleport Agents" section comes before the sections related to individual Teleport services ("Application Access", "Server Access", etc.). The new section on dynamic resources also gives us a place to put other guides to using the Terraform provider and Kubernetes Operator, e.g., if we add guides to using these tools with popular GitOps platforms. Likewise, the section on agents gives us a place to put other agent-wide information, e.g., how to enable an additional Teleport service on an instance that is already running. To allow for these changes, I have also made the following, more tangentially related sidebar changes: - **Renamed sidebar sections to be noun phrases instead of verb phrases:** Currently, one half of the sidebar is made of imperative phrases like "Manage Access" and "Manage your Cluster". This doesn't really work for the sections on agents and dynamic resources, so I have renamed these sections for consistency. - **Moved the "Manage your Cluster" and "Deploy a Cluster" sections**: I have arranged the sidebar so more basic topics (i.e., those that new users and experienced users alike will need to be familiar with) are on the top and more advanced ones are on the bottom. The other sections that are currently in the first half of the sidebar are topics that all Teleport users will need to get familiar with, while day two operations and self-hosted production deployments are more advanced topics. - **Edited the landing page:** I have edited the landing page of the docs to reflect the new sidebar organization. This also makes the page shorter, simpler, and more opinionated. It spells out a high-level sequence for setting up Teleport, then provides a list of advanced topics for further reading. Links correspond to sidebar sections--as before, I wanted to describe the topic of each sidebar section so users would know this information without having to navigate away from the landing page. * Move the "Dynamic Configuration" section Make this a subsection of "Manage your Cluster" since it's not self-evidently clear as a top-level docs section. Users will probably need an introduction via the "Manage your Cluster" section intro page. This also reverts some of the more drastic sidebar changes introduced by the previous commit. Responds to xinding33 feedback. * Make IAC learning tracks prominent/hard to avoid Closes #27751 Responds to xinding33 feedback The motivation is to be more opinionated about the course that users take through the docs. We currently recommend two tracks for self-service users, i.e., the users expected to make use of the landing page: - Setting up a toy self-hosted Teleport cluster - Setting up a Teleport Team/Enterprise Cloud cluster that can eventually become production ready By moving the "Get Started" guide to the landing page, we direct users immediately on to the first track. This change then gives new users a way to enter the second track from the docs landing page with a prominent link to the Teleport Team docs. This change also edits The landing page to direct users who have completed the getting started experience to instructions for setting up a pool of agents on Terraform, helping to make infrastructure-as-code a first-class citizen of the docs. This change also removes the menu of links that used to confront users on the landing page. Since all sidebar sections include introduction pages, users interested in the content of a sidebar section can visit the section. By removing links, we make it clearer for users how to proceed through the docs. * Fix linter errors * Incorporate Trivy recommendations * Respond to alexfornuto feedback * Restore list of dynamic resources to the reference * Fix linter warnings * Remove the ".sh" extension from userdata script The Terraform module that reads this file does not need the extension, which was causing trouble for our shellcheck linter.
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
4 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 #25418
Help make infrastructure-as-code approaches more prominent in the Teleport docs by separating the Operator and Terraform guides into a "Configuring your Cluster" subsection of the "Management" section. This also adds an introductory page that explains the three major tools we expose for interacting with a Teleport cluster (not counting the API).
This subsection also gives us a place to put other guides to using Terraform and the Operator, e.g., if we add guides to using these tools with popular GitOps platforms.