Skip to content

Promote IAC docs for agents and dynamic resources#27703

Merged
ptgott merged 9 commits intomasterfrom
paul.gottschling/27382-iac
Jun 30, 2023
Merged

Promote IAC docs for agents and dynamic resources#27703
ptgott merged 9 commits intomasterfrom
paul.gottschling/27382-iac

Conversation

@ptgott
Copy link
Copy Markdown
Contributor

@ptgott ptgott commented Jun 9, 2023

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:

  • 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 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.

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:

  • 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.

@ptgott
Copy link
Copy Markdown
Contributor Author

ptgott commented Jun 9, 2023

TODO:

  • Make sure I have added redirects

Comment thread examples/agent-pool-terraform/agent-pool.tf Fixed
Comment thread examples/agent-pool-terraform/agent-pool.tf Fixed
Comment thread docs/pages/agents/introduction.mdx
Comment thread docs/pages/agents/introduction.mdx
Comment thread examples/agent-pool-terraform/userdata.sh
Comment thread docs/pages/agents/deploy-agents-terraform.mdx Outdated
Comment thread docs/pages/agents/deploy-agents-terraform.mdx
Comment thread docs/pages/management/introduction.mdx Outdated
Comment thread docs/pages/index.mdx
Comment thread docs/pages/index.mdx Outdated
Comment thread docs/pages/index.mdx
Comment thread docs/pages/index.mdx
@ptgott ptgott requested a review from alexfornuto June 27, 2023 13:55
@ptgott ptgott force-pushed the paul.gottschling/27382-iac branch from 5bb0554 to 748ed8c Compare June 27, 2023 14:15
Copy link
Copy Markdown
Contributor

@alexfornuto alexfornuto left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

👍 , 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.

@ptgott ptgott force-pushed the paul.gottschling/27382-iac branch 3 times, most recently from 7cec66b to f7296b5 Compare June 28, 2023 14:44
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.
ptgott added a commit that referenced this pull request Nov 10, 2023
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).
ptgott added a commit that referenced this pull request Nov 16, 2023
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).
ptgott added a commit that referenced this pull request Nov 30, 2023
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).
ptgott added a commit that referenced this pull request Dec 12, 2023
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).
ptgott added a commit that referenced this pull request Dec 19, 2023
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).
ptgott added a commit that referenced this pull request Jan 2, 2024
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).
ptgott added a commit that referenced this pull request Jan 24, 2024
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).
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-actions Bot pushed a commit that referenced this pull request Jan 25, 2024
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).
github-actions Bot pushed a commit that referenced this pull request Jan 25, 2024
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).
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
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Projects

None yet

5 participants