Audit some beginner/early-stage Teleport guides #11841
Comments
|
would include: docs/setup/admin/ - no opening info on what these guides are for. The setup section lacks a intro which nearly all others have |
ptgott
added a commit
that referenced
this issue
Apr 13, 2022
See #11841 Make the Adding Nodes guide more usable for Cloud - Add a ca_pin preset - Clarify that tctl must be run on the local machine for Cloud users - Structure the guide as a step-by-step tutorial. The guide already included sequences of sample commands, so all this took was to rename headings according to the "Step n/d." format and move the CA pinning section into the section on starting the Node. - Add environment variables to use for storing a CA pin and invite token to sample commands, plus piped commands to extract these strings from the output of tctl commands. - Use a ScopedBlock to hide the Node Tunneling section for Cloud users - Indicate that the --auth-server flag in "teleport start" requires a port. Add intros to the Admin and Operations menu pages - Clarify the purpose of the Admin Guides and Operations sections by adding an intro paragraph to each page. Since these sections are similar in scope, I added links from one to the other with statements about how the two sections differ. - Replace lists of links with Tiles. GitHub SSO - Move the step to create an OAuth app out of the Prerequisites and into its own step. This makes it easier to give the instructions to use a specific callback URL proper space. - Be more explicit about the rp_ip value. - Add explicit instructions for logging in to the cluster after creating the auth preference, including screenshots of expected results.
ptgott
added a commit
that referenced
this issue
Apr 14, 2022
See #11841 Make the Adding Nodes guide more usable for Cloud - Add a ca_pin preset - Clarify that tctl must be run on the local machine for Cloud users - Structure the guide as a step-by-step tutorial. The guide already included sequences of sample commands, so all this took was to rename headings according to the "Step n/d." format and move the CA pinning section into the section on starting the Node. - Add environment variables to use for storing a CA pin and invite token to sample commands, plus piped commands to extract these strings from the output of tctl commands. - Use a ScopedBlock to hide the Node Tunneling section for Cloud users - Indicate that the --auth-server flag in "teleport start" requires a port. Add intros to the Admin and Operations menu pages - Clarify the purpose of the Admin Guides and Operations sections by adding an intro paragraph to each page. Since these sections are similar in scope, I added links from one to the other with statements about how the two sections differ. - Replace lists of links with Tiles. GitHub SSO - Move the step to create an OAuth app out of the Prerequisites and into its own step. This makes it easier to give the instructions to use a specific callback URL proper space. - Be more explicit about the rp_ip value. - Add explicit instructions for logging in to the cluster after creating the auth preference, including screenshots of expected results.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
See #11841 Make the Adding Nodes guide more usable for Cloud - Add a ca_pin preset - Clarify that tctl must be run on the local machine for Cloud users - Structure the guide as a step-by-step tutorial. The guide already included sequences of sample commands, so all this took was to rename headings according to the "Step n/d." format and move the CA pinning section into the section on starting the Node. - Add environment variables to use for storing a CA pin and invite token to sample commands, plus piped commands to extract these strings from the output of tctl commands. - Use a ScopedBlock to hide the Node Tunneling section for Cloud users - Indicate that the --auth-server flag in "teleport start" requires a port. Add intros to the Admin and Operations menu pages - Clarify the purpose of the Admin Guides and Operations sections by adding an intro paragraph to each page. Since these sections are similar in scope, I added links from one to the other with statements about how the two sections differ. - Replace lists of links with Tiles. GitHub SSO - Move the step to create an OAuth app out of the Prerequisites and into its own step. This makes it easier to give the instructions to use a specific callback URL proper space. - Be more explicit about the rp_ip value. - Add explicit instructions for logging in to the cluster after creating the auth preference, including screenshots of expected results.
ptgott
added a commit
that referenced
this issue
Apr 15, 2022
See #11841 - Define "local users" at the beginning of the guide - Split the "Adding and deleting users" section and move the "Deleting users" section after the "Editing users" section. This way, readers can follow all commands in the guide. Otherwise, the new user is deleted before being edited. - Hide scope-irrelevant details - Remove a "tsh ssh" command that a reader may not necessarily have set up Teleport to run properly.
ptgott
added a commit
that referenced
this issue
Apr 18, 2022
See #11841 This change organizes the Daemon guide into a step-by-step tutorial that users can follow more easily. - Clarify the title a bit more. - Remove the table of commands. This is covered more fully in the CLI reference (which this links to) and isn't strictly relevant to the purpose of this guide, setting up Teleport as a systemd unit. - Add a Prerequisites section. - Organize body sections into steps. - Add installation and "teleport configure" commands, which are necessary for the systemd service to run.
ptgott
added a commit
that referenced
this issue
Apr 18, 2022
See #11841 - Define "local users" at the beginning of the guide - Split the "Adding and deleting users" section and move the "Deleting users" section after the "Editing users" section. This way, readers can follow all commands in the guide. Otherwise, the new user is deleted before being edited. - Hide scope-irrelevant details - Remove a "tsh ssh" command that a reader may not necessarily have set up Teleport to run properly.
ptgott
added a commit
that referenced
this issue
Apr 18, 2022
* Improve the usability of the Local Users guide See #11841 - Define "local users" at the beginning of the guide - Split the "Adding and deleting users" section and move the "Deleting users" section after the "Editing users" section. This way, readers can follow all commands in the guide. Otherwise, the new user is deleted before being edited. - Hide scope-irrelevant details - Remove a "tsh ssh" command that a reader may not necessarily have set up Teleport to run properly. * Respond to PR feedback
ptgott
added a commit
that referenced
this issue
Apr 18, 2022
See #11841 Make the Adding Nodes guide more usable for Cloud - Add a ca_pin preset - Clarify that tctl must be run on the local machine for Cloud users - Structure the guide as a step-by-step tutorial. The guide already included sequences of sample commands, so all this took was to rename headings according to the "Step n/d." format and move the CA pinning section into the section on starting the Node. - Add environment variables to use for storing a CA pin and invite token to sample commands, plus piped commands to extract these strings from the output of tctl commands. - Use a ScopedBlock to hide the Node Tunneling section for Cloud users - Indicate that the --auth-server flag in "teleport start" requires a port. Add intros to the Admin and Operations menu pages - Clarify the purpose of the Admin Guides and Operations sections by adding an intro paragraph to each page. Since these sections are similar in scope, I added links from one to the other with statements about how the two sections differ. - Replace lists of links with Tiles. GitHub SSO - Move the step to create an OAuth app out of the Prerequisites and into its own step. This makes it easier to give the instructions to use a specific callback URL proper space. - Be more explicit about the rp_ip value. - Add explicit instructions for logging in to the cluster after creating the auth preference, including screenshots of expected results.
ptgott
added a commit
that referenced
this issue
Apr 18, 2022
See #11841 The current guide is a conceptual introduction to Teleport's labeling functionality. Since we cover this information in our reference guides, I wanted to make it possible for readers to follow this guide as a tutorial and get started labeling resources quickly. - Introduce labels at the beginning of the guide to set the stage conceptually before the steps begin. - Clarify in the Prerequisites section that the instructions in the guide apply to any Teleport resource, not just Nodes - Require a host for running a Teleport Node in the Prerequisites and include instructions for starting the Node. Previously, we included sample commands/config for applications as well. Requiring a Node and including setup instructions for that Node will ensure that all instructions in the guide can be followed easily. - Add scoped instructions via Tabs and ScopedBlocks. - Reorganize sections into a series of steps. - Add commands to verify that labels have been added.
ptgott
added a commit
that referenced
this issue
Apr 18, 2022
* Clarify two guides and two intro pages See #11841 Make the Adding Nodes guide more usable for Cloud - Add a ca_pin preset - Clarify that tctl must be run on the local machine for Cloud users - Structure the guide as a step-by-step tutorial. The guide already included sequences of sample commands, so all this took was to rename headings according to the "Step n/d." format and move the CA pinning section into the section on starting the Node. - Add environment variables to use for storing a CA pin and invite token to sample commands, plus piped commands to extract these strings from the output of tctl commands. - Use a ScopedBlock to hide the Node Tunneling section for Cloud users - Indicate that the --auth-server flag in "teleport start" requires a port. Add intros to the Admin and Operations menu pages - Clarify the purpose of the Admin Guides and Operations sections by adding an intro paragraph to each page. Since these sections are similar in scope, I added links from one to the other with statements about how the two sections differ. - Replace lists of links with Tiles. GitHub SSO - Move the step to create an OAuth app out of the Prerequisites and into its own step. This makes it easier to give the instructions to use a specific callback URL proper space. - Be more explicit about the rp_ip value. - Add explicit instructions for logging in to the cluster after creating the auth preference, including screenshots of expected results. * Fix wording and linter issues following PR review * Respond to PR feedback Remove a misleading instruction re: CA pinning. Also move some text about CA pinning to a more appropriate location.
ptgott
added a commit
that referenced
this issue
Apr 19, 2022
See #11841 - Make Cloud instructions smoother by using ScopedBlocks (this component was not available during the first round of Cloud-specific edits). - Add a Prerequisites section - Use steps in H2 headers. The idea is that a user would follow each step to collect diagnostic information, then pose a question in the final "Ask for help" section. - Add more detailed examples of debug logs and a goroutine dump, and explain a bit more how you would use this information. - Remove the text about resetting teleport's state by deleting the data directory. This is a general-purpose guide to investigating issues,so it seemed more appropriate to reserve that kind of action for when a user determined what the issue was. - Add instructions for getting your Teleport version in order to ask for help. - Add a further reading section.
ptgott
added a commit
that referenced
this issue
Apr 19, 2022
See #11841 - Define "local users" at the beginning of the guide - Split the "Adding and deleting users" section and move the "Deleting users" section after the "Editing users" section. This way, readers can follow all commands in the guide. Otherwise, the new user is deleted before being edited. - Hide scope-irrelevant details - Remove a "tsh ssh" command that a reader may not necessarily have set up Teleport to run properly.
ptgott
added a commit
that referenced
this issue
Apr 19, 2022
See #11841 - Define "local users" at the beginning of the guide - Split the "Adding and deleting users" section and move the "Deleting users" section after the "Editing users" section. This way, readers can follow all commands in the guide. Otherwise, the new user is deleted before being edited. - Hide scope-irrelevant details - Remove a "tsh ssh" command that a reader may not necessarily have set up Teleport to run properly.
ptgott
added a commit
that referenced
this issue
Apr 19, 2022
See #11841 - Define "local users" at the beginning of the guide - Split the "Adding and deleting users" section and move the "Deleting users" section after the "Editing users" section. This way, readers can follow all commands in the guide. Otherwise, the new user is deleted before being edited. - Hide scope-irrelevant details - Remove a "tsh ssh" command that a reader may not necessarily have set up Teleport to run properly.
ptgott
added a commit
that referenced
this issue
Jun 2, 2022
See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide.
ptgott
added a commit
that referenced
this issue
Jun 2, 2022
See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide.
ptgott
added a commit
that referenced
this issue
Jun 3, 2022
See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide.
ptgott
added a commit
that referenced
this issue
Jun 3, 2022
* Make the Adding Nodes guide more usable See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide. * Respond to PR feedback Also remove some erroneous command output
ptgott
added a commit
that referenced
this issue
Jun 3, 2022
See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide.
ptgott
added a commit
that referenced
this issue
Jun 3, 2022
See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide.
ptgott
added a commit
that referenced
this issue
Jun 3, 2022
* Make the Adding Nodes guide more usable See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide. * Respond to PR feedback Also remove some erroneous command output
ptgott
added a commit
that referenced
this issue
Jun 3, 2022
* Make the Adding Nodes guide more usable See: #11841 This change makes the Adding Nodes guide more usable for self-hosted clusters based on manual testing. - Make it clearer that you can use tctl on your local machine with a self-hosted cluster. For convenience, all instructions in this guide assume you are using tctl from a local machine. - Misc. minor edits for clarity. - Move different methods of using tokens into Details boxes, since following the guide only requires the first "tctl nodes add" command. - Use environment variables to store the CA pin, invite token, and Proxy/Auth address, making it slightly more convenient to copy the "teleport start" command and run it on the Node. - Turn the Node Tunneling section into a Details box below the instruction to assign the Auth/Proxy address to an environment variable, and better integrate the text into the guide. Previously, the Node Tunneling section also advised the reader to create a token, which they would have doe already at this point in the guide. * Respond to PR feedback Also remove some erroneous command output
ptgott
added a commit
that referenced
this issue
Jun 6, 2022
See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
ptgott
added a commit
that referenced
this issue
Jun 6, 2022
…ent scopes) (#10708) * Edit the Trusted Clusters guide for Cloud See #10633 - Misc style/grammar/clarity tweaks - Turn the Teleport Node Tunneling Admonition into a Details box so it can be invisible for Cloud users. In Cloud, Nodes must connect via Node Tunneling. - Use Tabs components to add Cloud versions of CLI commands - Only show the static join token method for self-hosted users via Tabs - Use a Details box to show content relevant only for Enterprise and Cloud users - Remove an Admonition that was duplicated in the Troubleshooting section * Respond to PR feedback * Address PR feedback * Turn the Trusted Clusters guide into a tutorial See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
ptgott
added a commit
that referenced
this issue
Jun 6, 2022
See #11841 - Add a Prerequisites section and divide the instructions into steps via H2 headings. - Use ScopedBlocks to add instructions for Cloud users. - Fill in missing instructions (e.g., adding host_cert permissions for Cloud users and editing the file permission of the host key/cert) - Since all supported versions of Teleport now include "tsh config," remove the manual OpenSSH configuration option. This makes the guide much simpler to follow. - Add a Details box explaining "tsh config" The original OpenSSH guide included some technical details about the proxy subsystem, but without enough context to understand the configuration generated by tsh config. I've moved the technical details into a Details box, and expanded them, so readers interested in how the local SSH config they generate via "tsh config" works. - Indicate that you need to specify the SSH port when connecting to an OpenSSH host via configuration generated by tsh config.
ptgott
added a commit
that referenced
this issue
Jun 6, 2022
* Make the OpenSSH guide more usable See #11841 - Add a Prerequisites section and divide the instructions into steps via H2 headings. - Use ScopedBlocks to add instructions for Cloud users. - Fill in missing instructions (e.g., adding host_cert permissions for Cloud users and editing the file permission of the host key/cert) - Since all supported versions of Teleport now include "tsh config," remove the manual OpenSSH configuration option. This makes the guide much simpler to follow. - Add a Details box explaining "tsh config" The original OpenSSH guide included some technical details about the proxy subsystem, but without enough context to understand the configuration generated by tsh config. I've moved the technical details into a Details box, and expanded them, so readers interested in how the local SSH config they generate via "tsh config" works. - Indicate that you need to specify the SSH port when connecting to an OpenSSH host via configuration generated by tsh config. * Respond to PR feedback
ptgott
added a commit
that referenced
this issue
Jun 6, 2022
Backports #12034 * Make the Labeling guide easier to follow See #11841 The current guide is a conceptual introduction to Teleport's labeling functionality. Since we cover this information in our reference guides, I wanted to make it possible for readers to follow this guide as a tutorial and get started labeling resources quickly. - Introduce labels at the beginning of the guide to set the stage conceptually before the steps begin. - Clarify in the Prerequisites section that the instructions in the guide apply to any Teleport resource, not just Nodes - Require a host for running a Teleport Node in the Prerequisites and include instructions for starting the Node. Previously, we included sample commands/config for applications as well. Requiring a Node and including setup instructions for that Node will ensure that all instructions in the guide can be followed easily. - Add scoped instructions via Tabs and ScopedBlocks. - Reorganize sections into a series of steps. - Add commands to verify that labels have been added. * Respond to PR feedback * Improve the Labeling guide for self-hosted users See: #11841 - Edit tctl.mdx: Users of self-hosted Teleport can run tctl commands from their local machines after logging in to a cluster, just like they can with Teleport Cloud. I have edited tctl.mdx to instruct self- hosted users to use tctl remotely. This way, users won't need to access their Auth Service hosts in order to follow the guides that use tctl.mdx. - Add steps for fixing unexpected "tsh ls" output Also applies PR feedback. - Add provisions for labeling specific resources as a table near the top of the page. - Remove the option to add labels using CLI flags. - Fix command output spacing Also misc. clarity tweaks. * Respond to PR feedback
ptgott
added a commit
that referenced
this issue
Jun 6, 2022
Backports #12034 * Make the Labeling guide easier to follow See #11841 The current guide is a conceptual introduction to Teleport's labeling functionality. Since we cover this information in our reference guides, I wanted to make it possible for readers to follow this guide as a tutorial and get started labeling resources quickly. - Introduce labels at the beginning of the guide to set the stage conceptually before the steps begin. - Clarify in the Prerequisites section that the instructions in the guide apply to any Teleport resource, not just Nodes - Require a host for running a Teleport Node in the Prerequisites and include instructions for starting the Node. Previously, we included sample commands/config for applications as well. Requiring a Node and including setup instructions for that Node will ensure that all instructions in the guide can be followed easily. - Add scoped instructions via Tabs and ScopedBlocks. - Reorganize sections into a series of steps. - Add commands to verify that labels have been added. * Respond to PR feedback * Improve the Labeling guide for self-hosted users See: #11841 - Edit tctl.mdx: Users of self-hosted Teleport can run tctl commands from their local machines after logging in to a cluster, just like they can with Teleport Cloud. I have edited tctl.mdx to instruct self- hosted users to use tctl remotely. This way, users won't need to access their Auth Service hosts in order to follow the guides that use tctl.mdx. - Add steps for fixing unexpected "tsh ls" output Also applies PR feedback. - Add provisions for labeling specific resources as a table near the top of the page. - Remove the option to add labels using CLI flags. - Fix command output spacing Also misc. clarity tweaks. * Respond to PR feedback
ptgott
added a commit
that referenced
this issue
Jun 7, 2022
See #11841 - Add a Prerequisites section and divide the instructions into steps via H2 headings. - Use ScopedBlocks to add instructions for Cloud users. - Fill in missing instructions (e.g., adding host_cert permissions for Cloud users and editing the file permission of the host key/cert) - Since all supported versions of Teleport now include "tsh config," remove the manual OpenSSH configuration option. This makes the guide much simpler to follow. - Add a Details box explaining "tsh config" The original OpenSSH guide included some technical details about the proxy subsystem, but without enough context to understand the configuration generated by tsh config. I've moved the technical details into a Details box, and expanded them, so readers interested in how the local SSH config they generate via "tsh config" works. - Indicate that you need to specify the SSH port when connecting to an OpenSSH host via configuration generated by tsh config.
ptgott
added a commit
that referenced
this issue
Jun 7, 2022
See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
ptgott
added a commit
that referenced
this issue
Jun 7, 2022
Backports #10708 * Edit the Trusted Clusters guide for Cloud See #10633 - Misc style/grammar/clarity tweaks - Turn the Teleport Node Tunneling Admonition into a Details box so it can be invisible for Cloud users. In Cloud, Nodes must connect via Node Tunneling. - Use Tabs components to add Cloud versions of CLI commands - Only show the static join token method for self-hosted users via Tabs - Use a Details box to show content relevant only for Enterprise and Cloud users - Remove an Admonition that was duplicated in the Troubleshooting section * Respond to PR feedback * Address PR feedback * Turn the Trusted Clusters guide into a tutorial See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
ptgott
added a commit
that referenced
this issue
Jun 7, 2022
See #11841 - Add a Prerequisites section and divide the instructions into steps via H2 headings. - Use ScopedBlocks to add instructions for Cloud users. - Fill in missing instructions (e.g., adding host_cert permissions for Cloud users and editing the file permission of the host key/cert) - Since all supported versions of Teleport now include "tsh config," remove the manual OpenSSH configuration option. This makes the guide much simpler to follow. - Add a Details box explaining "tsh config" The original OpenSSH guide included some technical details about the proxy subsystem, but without enough context to understand the configuration generated by tsh config. I've moved the technical details into a Details box, and expanded them, so readers interested in how the local SSH config they generate via "tsh config" works. - Indicate that you need to specify the SSH port when connecting to an OpenSSH host via configuration generated by tsh config.
ptgott
added a commit
that referenced
this issue
Jun 7, 2022
* Make the OpenSSH guide more usable See #11841 - Add a Prerequisites section and divide the instructions into steps via H2 headings. - Use ScopedBlocks to add instructions for Cloud users. - Fill in missing instructions (e.g., adding host_cert permissions for Cloud users and editing the file permission of the host key/cert) - Since all supported versions of Teleport now include "tsh config," remove the manual OpenSSH configuration option. This makes the guide much simpler to follow. - Add a Details box explaining "tsh config" The original OpenSSH guide included some technical details about the proxy subsystem, but without enough context to understand the configuration generated by tsh config. I've moved the technical details into a Details box, and expanded them, so readers interested in how the local SSH config they generate via "tsh config" works. - Indicate that you need to specify the SSH port when connecting to an OpenSSH host via configuration generated by tsh config. * Respond to PR feedback
ptgott
added a commit
that referenced
this issue
Jun 8, 2022
See #11841 - Add a Prerequisites section and divide the instructions into steps via H2 headings. - Use ScopedBlocks to add instructions for Cloud users. - Fill in missing instructions (e.g., adding host_cert permissions for Cloud users and editing the file permission of the host key/cert) - Since all supported versions of Teleport now include "tsh config," remove the manual OpenSSH configuration option. This makes the guide much simpler to follow. - Add a Details box explaining "tsh config" The original OpenSSH guide included some technical details about the proxy subsystem, but without enough context to understand the configuration generated by tsh config. I've moved the technical details into a Details box, and expanded them, so readers interested in how the local SSH config they generate via "tsh config" works. - Indicate that you need to specify the SSH port when connecting to an OpenSSH host via configuration generated by tsh config.
ptgott
added a commit
that referenced
this issue
Jun 8, 2022
* Make the OpenSSH guide more usable See #11841 - Add a Prerequisites section and divide the instructions into steps via H2 headings. - Use ScopedBlocks to add instructions for Cloud users. - Fill in missing instructions (e.g., adding host_cert permissions for Cloud users and editing the file permission of the host key/cert) - Since all supported versions of Teleport now include "tsh config," remove the manual OpenSSH configuration option. This makes the guide much simpler to follow. - Add a Details box explaining "tsh config" The original OpenSSH guide included some technical details about the proxy subsystem, but without enough context to understand the configuration generated by tsh config. I've moved the technical details into a Details box, and expanded them, so readers interested in how the local SSH config they generate via "tsh config" works. - Indicate that you need to specify the SSH port when connecting to an OpenSSH host via configuration generated by tsh config. * Respond to PR feedback
ptgott
added a commit
that referenced
this issue
Jun 22, 2022
Backports #10708 * Edit the Trusted Clusters guide for Cloud See #10633 - Misc style/grammar/clarity tweaks - Turn the Teleport Node Tunneling Admonition into a Details box so it can be invisible for Cloud users. In Cloud, Nodes must connect via Node Tunneling. - Use Tabs components to add Cloud versions of CLI commands - Only show the static join token method for self-hosted users via Tabs - Use a Details box to show content relevant only for Enterprise and Cloud users - Remove an Admonition that was duplicated in the Troubleshooting section * Respond to PR feedback * Address PR feedback * Turn the Trusted Clusters guide into a tutorial See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
ptgott
added a commit
that referenced
this issue
Jun 22, 2022
Convert the Trusted Clusters guide to a tutorial Backports #10708 * Edit the Trusted Clusters guide for Cloud See #10633 - Misc style/grammar/clarity tweaks - Turn the Teleport Node Tunneling Admonition into a Details box so it can be invisible for Cloud users. In Cloud, Nodes must connect via Node Tunneling. - Use Tabs components to add Cloud versions of CLI commands - Only show the static join token method for self-hosted users via Tabs - Use a Details box to show content relevant only for Enterprise and Cloud users - Remove an Admonition that was duplicated in the Troubleshooting section * Respond to PR feedback * Address PR feedback * Turn the Trusted Clusters guide into a tutorial See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
ptgott
added a commit
that referenced
this issue
Jun 22, 2022
See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
ptgott
added a commit
that referenced
this issue
Jun 22, 2022
* Edit the Trusted Clusters guide for Cloud See #10633 - Misc style/grammar/clarity tweaks - Turn the Teleport Node Tunneling Admonition into a Details box so it can be invisible for Cloud users. In Cloud, Nodes must connect via Node Tunneling. - Use Tabs components to add Cloud versions of CLI commands - Only show the static join token method for self-hosted users via Tabs - Use a Details box to show content relevant only for Enterprise and Cloud users - Remove an Admonition that was duplicated in the Troubleshooting section * Respond to PR feedback * Address PR feedback * Turn the Trusted Clusters guide into a tutorial See: #11841 The Trusted Clusters guide is organized as a conceptual introduction, with configuration/command snippets used as illustrations. To make this guide easier to follow, I have structured it as a step-by-step tutorial where a user should be able to copy each command/config snippet on their own environment, establish trust between clusters, and connect to a remote Node. Some more specific changes: - Remove Details box re: Node Tunneling: This isn't strictly relevant to Trusted Clusters, so removing it shortens and simplifies what is quite a long guide. - Make "How Trusted Clusters work" more concise and add the information to the introduction. - Move long explanatory passages into Details boxes. Eventually, it would be great to split this guide into multiple guides that explain different topics in more depth (e.g., a section of the docs devoted to Trusted Clusters). For now, this is the quickest way to organize conceptual information without detracting from the tutorial structure.
|
This is done |
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Details
Ensure that guides for users in the early stages of setting up Teleport are accurate and straightforward to follow.
While we want all of our guides to have these qualities, this issue focuses on some guides that users first getting acquainted with Teleport are expected to read.
Since these guides provide the basis for following other guides, frustration while working through them can hamper a new user's overall adoption of Teleport.
I will set up a demo environment for the Cloud, Open Source, and Enterprise editions of Teleport, and verify each page separately for each.
/docs/getting-started/linux-server/docs/installation/setup/admin/github-sso//setup/admin/adding-nodes//setup/admin/trustedclusters//setup/admin/labels//setup/admin/users//setup/admin/troubleshooting//setup/admin/graceful-restarts//setup/admin/daemon//setup/admin/(add intro paragraph)/docs/server-access/guides/openssh/Category
The text was updated successfully, but these errors were encountered: