Edit two guides for Cloud users #11470

ptgott · 2022-03-25T19:41:11Z

(1) Server Access Getting Started

While this guide mentions Teleport Cloud throughout, I wanted to make
sure that users of one edition wouldn't see scope-irrelevant details.

Add scoped Tabs to the Prerequisites section
Add the scoped "tctl.mdx" Details box
Add ScopedBlocks for minor scope-relevant details like the address
of the Proxy Service
Edit the tctl.mdx partial to mention when you would use sudo to run
tctl on a local machine, a detail that was added to this guide but
could be included in any guide that uses the tctl.mdx partial.

Also makes misc. style, grammar, and clarity edits.

(2) Edit the OpenSSH guide and spin off a PRM guide

The Recording Proxy Mode instructions don't apply to Cloud users.
I didn't want to use a ScopedBlock to hide the relevant H2s, since
these still appear within a page's table of contents. Instead, I
separated the Recording Proxy Mode instructions into their own guide,
and added an edition warning for Cloud users at the top of the guide.

I also did some restructuring of the OpenSSH guide to clean it up after
separating the Recording Proxy Mode instructions.
Used ScopedBlocks to ensure that only scope-relevant information is
shown in the OpenSSH guide.
Misc grammar/style/clarity tweaks

r0mant · 2022-03-29T23:41:55Z

docs/pages/includes/tctl.mdx

+If you have installed `tctl` as your local user, you will not need to run `tctl`
+commands via `sudo`.


Not sure I fully understand what "installed as your local user" means. Maybe remove this sentence?

r0mant · 2022-03-29T23:44:24Z

docs/pages/server-access/getting-started.mdx

+<Tabs>
+<TabItem scope={["oss"]} label="Self-Hosted">
+
+- A running Teleport cluster, version >= 7.0.0. For details on how to set this up,


Why >= 7.0.0?

I'm not sure how this got in here. My best guess is that I copied these tabs from another guide where this was hardcoded and didn't inspect the text carefully enough. I've replaced it with the version variable.

r0mant · 2022-03-29T23:44:52Z

docs/pages/server-access/getting-started.mdx

+  Server](../getting-started/linux-server.mdx).
+
+- One host running your favorite Linux environment (such as Ubuntu 20.04, CentOS
+  8.0-1905, or Debian 10). This will serve as a Teleport Server Access Node.


Should it be as specific as 8.0-1905? Maybe just say CentOS 8?

r0mant · 2022-03-29T23:45:20Z

docs/pages/server-access/getting-started.mdx

+
+- One host running your favorite Linux environment (such as Ubuntu 20.04, CentOS
+  8.0-1905, or Debian 10). This will serve as a Teleport Server Access Node.
+
 - Teleport (=teleport.version=) installed locally.


Is this referring to client tools like tsh, tctl? Otherwise it seems similar to bullet point number 1.

r0mant · 2022-03-29T23:46:07Z

docs/pages/server-access/getting-started.mdx


-## Step 1/4. Install Teleport 
+- A running Teleport cluster, version >= 7.0.0. For details on setting this up, see


Same comments here as above.

r0mant · 2022-03-29T23:47:14Z

docs/pages/server-access/getting-started.mdx

 ```

-If you have installed `tctl` as your local user, you will not need to run `tctl` commands via `sudo`.
-</Details>
+Each Teleport Node can be configured to run as an enhanced SSH server.


What does "enhanced SSH server" mean?

I just realized this wording was already used here before, but I think it's confusing. I think that the next sentence "--type=node specifies that ...." already explain what's happening well, maybe remove this one?

r0mant · 2022-03-29T23:53:39Z

docs/pages/server-access/getting-started.mdx

+<ScopedBlock scope={["oss", "enterprise"]}>
+
+```txt
+Profile URL:        https://tele.example.com:443


Feels like indentation is a bit off here (same below)

Suggested change

Profile URL: https://tele.example.com:443

> Profile URL: https://tele.example.com:443

r0mant · 2022-03-30T00:01:01Z

docs/pages/server-access/guides/recording-proxy-mode.mdx

+- It grants additional privileges to the Teleport Proxy Service. In the default Node Recording mode, the Proxy Service stores no secrets and cannot "see" the decrypted data. This makes a Proxy Server less critical to the security of the overall cluster. But if an attacker gains physical access to a Proxy Server running in Proxy Recording mode, they will be able to see the decrypted traffic and client keys stored in the Proxy Server's process memory.
+- Recording Proxy Mode requires the use of SSH agent forwarding. Agent forwarding is required because without it, a Proxy Server will not be able to establish a second connection to the destination node.
+
+Teleport proxy should be available to clients and be set up with TLS.


Suggested change

Teleport proxy should be available to clients and be set up with TLS.

Teleport Proxy should be available to clients and be set up with TLS.

ulysseskan · 2022-03-30T21:02:56Z

docs/pages/server-access/getting-started.mdx

+This will generate an initial login link where you can create a password and set up two-factor authentication for `tele-admin`.
+
+<Admonition type="note" title="Note">
+   We've only given `tele-admin` the roles `editor` and `access` according to the *Principle of Least Privilege* (POLP).


I would leave out the POLP acronym here and just have it as "Principle of Least Privilege".

ulysseskan · 2022-03-30T21:09:33Z

docs/pages/server-access/guides/openssh.mdx

+<ScopedBlock scope={["cloud"]}>
+
+Once configured, log in to any Node in the `mytenant.teleport.sh` cluster as any
+principal listed in your Teleport profile:


Perhaps user, hostname, or user@hostname would be a better word than principal here?

ulysseskan

Looks good to me. I made a couple of suggestions above and also agree with Roman's comments.

(1) Server Access Getting Started While this guide mentions Teleport Cloud throughout, I wanted to make sure that users of one edition wouldn't see scope-irrelevant details. - Add scoped Tabs to the Prerequisites section - Add the scoped "tctl.mdx" Details box - Add ScopedBlocks for minor scope-relevant details like the address of the Proxy Service - Edit the tctl.mdx partial to mention when you would use sudo to run tctl on a local machine, a detail that was added to this guide but could be included in any guide that uses the tctl.mdx partial. Also makes misc. style, grammar, and clarity edits. (2) Edit the OpenSSH guide and spin off a PRM guide - The Recording Proxy Mode instructions don't apply to Cloud users. I didn't want to use a ScopedBlock to hide the relevant H2s, since these still appear within a page's table of contents. Instead, I separated the Recording Proxy Mode instructions into their own guide, and added an edition warning for Cloud users at the top of the guide. I also did some restructuring of the OpenSSH guide to clean it up after separating the Recording Proxy Mode instructions. - Used ScopedBlocks to ensure that only scope-relevant information is shown in the OpenSSH guide. - Misc grammar/style/clarity tweaks

Backports #11470 * Edit two guides for Cloud users (1) Server Access Getting Started While this guide mentions Teleport Cloud throughout, I wanted to make sure that users of one edition wouldn't see scope-irrelevant details. - Add scoped Tabs to the Prerequisites section - Add the scoped "tctl.mdx" Details box - Add ScopedBlocks for minor scope-relevant details like the address of the Proxy Service - Edit the tctl.mdx partial to mention when you would use sudo to run tctl on a local machine, a detail that was added to this guide but could be included in any guide that uses the tctl.mdx partial. Also makes misc. style, grammar, and clarity edits. (2) Edit the OpenSSH guide and spin off a PRM guide - The Recording Proxy Mode instructions don't apply to Cloud users. I didn't want to use a ScopedBlock to hide the relevant H2s, since these still appear within a page's table of contents. Instead, I separated the Recording Proxy Mode instructions into their own guide, and added an edition warning for Cloud users at the top of the guide. I also did some restructuring of the OpenSSH guide to clean it up after separating the Recording Proxy Mode instructions. - Used ScopedBlocks to ensure that only scope-relevant information is shown in the OpenSSH guide. - Misc grammar/style/clarity tweaks * Respond to PR feedback

ptgott added documentation cloud-docs labels Mar 25, 2022

ptgott mentioned this pull request Mar 25, 2022

Prepare docs guides in the Server Access section for the Cloud #10634

Closed

github-actions bot requested review from r0mant, xinding33 and zmb3 March 25, 2022 19:41

ptgott force-pushed the paul.gottschling/10634-3 branch from ab411ff to 8782e6a Compare March 28, 2022 19:56

r0mant approved these changes Mar 30, 2022

View reviewed changes

ulysseskan reviewed Mar 30, 2022

View reviewed changes

ulysseskan approved these changes Mar 30, 2022

View reviewed changes

zmb3 approved these changes Mar 31, 2022

View reviewed changes

ptgott force-pushed the paul.gottschling/10634-3 branch from 8782e6a to 852a25b Compare March 31, 2022 21:21

ptgott enabled auto-merge (squash) March 31, 2022 21:22

Respond to PR feedback

ab5a4d8

ptgott force-pushed the paul.gottschling/10634-3 branch from 852a25b to ab5a4d8 Compare March 31, 2022 21:30

ptgott merged commit 6b5e2e7 into master Mar 31, 2022

ptgott deleted the paul.gottschling/10634-3 branch March 31, 2022 21:35

ptgott mentioned this pull request Mar 31, 2022

[v9 backport] Edit two guides for Cloud users #11642

Merged

ptgott mentioned this pull request Mar 31, 2022

[v8 backport] Edit two guides for Cloud users #11643

Merged

ptgott mentioned this pull request Mar 31, 2022

[v7 backport] Edit two guides for Cloud users #11645

Merged

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Edit two guides for Cloud users #11470

Edit two guides for Cloud users #11470

ptgott commented Mar 25, 2022

r0mant Mar 29, 2022

r0mant Mar 29, 2022

ptgott Mar 31, 2022

r0mant Mar 29, 2022

r0mant Mar 29, 2022

r0mant Mar 29, 2022

r0mant Mar 29, 2022

r0mant Mar 29, 2022

r0mant Mar 29, 2022

r0mant Mar 30, 2022

ulysseskan Mar 30, 2022

ulysseskan Mar 30, 2022 •

edited

Loading

ulysseskan left a comment

		If you have installed `tctl` as your local user, you will not need to run `tctl`
		commands via `sudo`.


		## Step 1/4. Install Teleport
		- A running Teleport cluster, version >= 7.0.0. For details on setting this up, see

	Profile URL: https://tele.example.com:443
	> Profile URL: https://tele.example.com:443

	Teleport proxy should be available to clients and be set up with TLS.
	Teleport Proxy should be available to clients and be set up with TLS.

Edit two guides for Cloud users #11470

Edit two guides for Cloud users #11470

Conversation

ptgott commented Mar 25, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ulysseskan Mar 30, 2022 • edited Loading

Choose a reason for hiding this comment

ulysseskan left a comment

Choose a reason for hiding this comment

ulysseskan Mar 30, 2022 •

edited

Loading