Promote IAC docs for agents and dynamic resources#27703
Merged
Conversation
Contributor
Author
|
TODO:
|
801269c to
6a513f2
Compare
alexfornuto
reviewed
Jun 23, 2023
xinding33
approved these changes
Jun 27, 2023
5bb0554 to
748ed8c
Compare
alexfornuto
approved these changes
Jun 27, 2023
Contributor
alexfornuto
left a comment
There was a problem hiding this comment.
👍 , though my local render fails on deploy-agents-terraform with a Expected a closing tag for ` error that I couldn't track down the source of.
7cec66b to
f7296b5
Compare
zmb3
approved these changes
Jun 30, 2023
This was referenced Jul 6, 2023
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jul 7, 2023
PR #27703 rearranged some docs pages without adding redirects. This change corrects the missing redirects.
github-actions Bot
pushed a commit
that referenced
this pull request
Jul 7, 2023
PR #27703 rearranged some docs pages without adding redirects. This change corrects the missing redirects.
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jul 7, 2023
PR #27703 rearranged some docs pages without adding redirects. This change corrects the missing redirects.
ravicious
pushed a commit
that referenced
this pull request
Jul 11, 2023
PR #27703 rearranged some docs pages without adding redirects. This change corrects the missing redirects.
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jan 25, 2024
* Add an overview of the Teleport documentation Closes #34038 Help visitors to the Teleport documentation find their way through the docs site by including a description of each docs page in an overview guide. This change is based on adapting the former Teleport index page (prior to #27703). * Minor grammar and language tweaks
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jan 26, 2024
* Add an overview of the Teleport documentation Closes #34038 Help visitors to the Teleport documentation find their way through the docs site by including a description of each docs page in an overview guide. This change is based on adapting the former Teleport index page (prior to #27703). * Minor grammar and language tweaks
github-merge-queue Bot
pushed a commit
that referenced
this pull request
Jan 26, 2024
* Add an overview of the Teleport documentation Closes #34038 Help visitors to the Teleport documentation find their way through the docs site by including a description of each docs page in an overview guide. This change is based on adapting the former Teleport index page (prior to #27703). * Minor grammar and language tweaks
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
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 #27382
Closes #25418
Closes #25442
Two aspects of setting up a Teleport cluster are omnipresent in the docs but have not received dedicated treatment:
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:
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.
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.
Substantial changes in response to feedback:
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:
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.