Use the start-auth-proxy.mdx partial outside Database Access guides #11538
Labels
Comments
|
On the other hand, the "start-auth-proxy.mdx" partial includes instructions to use ACME/Let's Encrypt for self-hosted users, which won't work with everyone's use case (e.g., airgapped networks, private DNS infrastructure, and local demo environments). By leaving "a running Teleport cluster" (or similar) in the Prerequisites, we can abstract away the particularities of a user's Teleport deployment. |
|
After talking to @xinding33, it sounds like the best approach here for making
|
ptgott
added a commit
that referenced
this issue
Apr 5, 2022
While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 7, 2022
While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 12, 2022
While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 12, 2022
While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 14, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 14, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 14, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
Backports #11710 While editing guides in certain sections to accommodate Cloud users (#10631), I introduced some inconsistencies into the way the Prerequisites sections in these guides provide instructions for users of Cloud, Open Source, and Enterprise Teleport. This change adds a partial that provides tabbed instructions to users of different Teleport editions when a guide requires a running Auth and Proxy Service. It then includes this partial where relevant in guides that fall under the scope of #10631. This helps ensure that cross-edition instructions are consistent in our guides, and makes it easier to edit additional guides to accommodate users of different editions. Caveats: - Since this change covers a lot of guides, it aims to be as small as possible. While all of these guides included links in their Prerequisites sections, for example, replacing these links with full instructions was out of the scope of this guide. This change should still make it easier to make further edits, e.g., in response to #11538. - We still need to change other elements of some guides to accommodate Cloud users. The current change only aims to standardize the Prerequisites section.
ptgott
modified the milestones:
Docs sprint: May 9, 2022 – May 20, 2022,
Docs sprint: May 23, 2022 – June 3, 2022
|
I am going to remove this issue from the current milestone and address it after we have done some of the reorganization work in #12787. When we revisit this issue in a later milestone, let's create a child issue per the tracking table above and add that issue to the milestone. This issue itself is too broad to tackle in a single two-week sprint. |
ptgott
added a commit
that referenced
this issue
Jan 17, 2023
Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide.
ptgott
added a commit
that referenced
this issue
Jan 27, 2023
Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide.
ptgott
added a commit
that referenced
this issue
Feb 3, 2023
Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide.
ptgott
added a commit
that referenced
this issue
Feb 3, 2023
* Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
alexfornuto
pushed a commit
that referenced
this issue
Feb 9, 2023
Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide.
ptgott
added a commit
that referenced
this issue
Feb 9, 2023
* Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Paul Gottschling <[email protected]>
ptgott
added a commit
that referenced
this issue
Feb 10, 2023
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
ptgott
added a commit
that referenced
this issue
Feb 10, 2023
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
ptgott
added a commit
that referenced
this issue
Feb 13, 2023
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
ptgott
added a commit
that referenced
this issue
Feb 13, 2023
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
ptgott
added a commit
that referenced
this issue
Feb 13, 2023
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
alexfornuto
pushed a commit
that referenced
this issue
Feb 13, 2023
Backports #20308 * Remove Auth/Proxy instructions from DB guides Closes #11538 A number of our Database Service guides instruct the user to install the Auth Service and the Proxy Service. For users who have already set up these services, these instructions add friction. For users who have _not_ set up these services, Teleport has existing instructions that users can follow instead. This change edits our Database Access guides to require the user to have a running Teleport cluster as a prerequisite, in line with how-to guides in other sections of the docs. Note that, while the issue this change closes is to add Auth/Proxy Service setup instructions to _more_ places in the docs, this change follows our style guide recommendation (#20024) to add steps to the Prerequisites section if we have them documented elsewhere and they don't directly pertain to the goal of a how-to guide. * Respond to PR feedback Change H3s to H2s --------- Co-authored-by: Alex Fornuto <[email protected]>
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Details
Overview
A number of our Database Access guides use the
start-auth-proxy.mdxpartial to include a standard set of instructions for installing/deploying the Teleport Auth Service and Proxy Service. This means that a user doesn't need to follow a Getting Started guide to deploy Teleport before following one of these guides.We can make our other docs guides more self contained by expanding the use of the "start-auth-proxy.mdx" partial outside Database Access guides. For example, a number of our guides include a Prerequisites step calling for a "Teleport installation" or "Running Teleport cluster" (or similar).
We can also think about splitting the "Self-Hosted" tab in the "start-auth-proxy.mdx" partial into "OSS" and "Enterprise" tabs, where the latter includes downloading the Enterprise version of Teleport and adding a license file.
Note that this is especially important because a lot of readers find our guides via organic search, and it's difficult to predict which guide a user will begin their Teleport experience with. If all resource-specific guides include setup instructions from installation onwards, we can prevent users from running into setup issues.
Related issue:
#11328
Tracking
We have a lot of step-by-step guides, so it would be best to divide this issue into child issues according to section of the docs. Since each of Teleport's services has slightly different prerequisites for running, this will also help ensure that we can make any adjustments to the
start-auth-proxypartial—or use a different partial instead—depending on the section.I used this command to generate the table. It looks for all docs pages that include a
Step 1section, indicating a tutorial, but that do not include thestart-auth-proxy.mdxpartial:Note that there are some ongoing efforts to reorganize the docs (e.g., #12654 and #12787). As these issues are resolved, we'll need to run the command above and update the table as needed.
Category
The text was updated successfully, but these errors were encountered: