Add context to "tsh ls" in docs (#12583)

* Add context to "tsh ls" in docs Fixes #7051 - Create a partial for how the Teleport Auth Service filters Nodes based on user roles/logins in response to queries. - Add the partial to provide context for example commands that include "tsh ls". - Make our existing text on Teleport's authorization checks clearer by enumerating the checks in the order they are executed in services.RoleSet.CheckAccess. Note that this does not change guides that instruct the user to create a new user and role, since a user following these guides will see the correct "tsh ls" output. * Respond to PR feedback
gravitational · Jun 23, 2022 · 8c2ced7 · 8c2ced7
1 parent e2e5bd9
commit 8c2ced7
Show file tree

Hide file tree

Showing 9 changed files with 58 additions and 22 deletions.
diff --git a/docs/pages/cloud/getting-started.mdx b/docs/pages/cloud/getting-started.mdx
@@ -60,6 +60,12 @@ $ tsh ls
 $ tsh ssh root@myserver
 ```
 
+<Details title="Not seeing Nodes?" opened={false}>
+
+(!docs/pages/includes/node-logins.mdx!)
+
+</Details>
+
 Type exit to end this session.  Happy Teleporting!
 
 ## Next Steps

diff --git a/docs/pages/enterprise/getting-started.mdx b/docs/pages/enterprise/getting-started.mdx
@@ -325,16 +325,22 @@ store it in `~/.tsh/keys/<proxy>` directory.
 With a certificate in place, Joe can now interact with the Teleport cluster:
 
 ```code
-# SSH into any host behind the proxy (Unix user 'joe' should already exist on the node):
-$ tsh ssh [email protected]
-
 # See what hosts are available behind the proxy:
 $ tsh ls
 
+# SSH into any host behind the proxy (Unix user 'joe' should already exist on the node):
+$ tsh ssh [email protected]
+
 # Log out (this will remove the user certificate from ~/.tsh)
 $ tsh logout
 ```
 
+<Details title="tsh not showing Nodes?" opened={false}>
+
+(!docs/pages/includes/node-logins.mdx!)
+
+</Details>
+
 ## Configuring SSO
 
 The local account is good for administrative purposes but regular users of

diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx
@@ -382,22 +382,13 @@ Example of a user being denied because the role `clusteradmin` wasn't set up:
 
 ### Teleport does not show the expected Nodes
 
-When Teleport's Auth Service receives a request to list Teleport Nodes,
-it only returns the Nodes that a user is authorized to access.
-
-A user's Teleport roles must grant the user explicit access to Nodes with a particular label
- before the user can view those Nodes. The Auth Service compares the user's
-`traits.logins` with the `allow` and `deny` rules defined in each of the user's roles.
-If the user's logins match a role's `allow` and `deny` rules, and a Node's labels match
-the keys and values listed within a role's `node_labels` field, then the Auth Service will
-list the Node in response to the user's request.
+(!docs/pages/includes/node-logins.mdx!)
 
 When configuring SSO, ensure that the identity provider is populating each user's
 traits correctly. For a user to see a Node in Teleport, the result of populating a
  template variable in a role's `allow.logins` must match at least one of a user's
  `traits.logins`.
 
-
 In this example a user will have usernames `ubuntu`, `debian` and usernames from the SSO trait `logins` for Nodes that have a `env: dev` label.  If the SSO trait username is `bob` then the usernames would include `ubuntu`, `debian`, and `bob`.
 
 ```yaml

diff --git a/docs/pages/includes/node-logins.mdx b/docs/pages/includes/node-logins.mdx
@@ -0,0 +1,17 @@
+When Teleport's Auth Service receives a request to list Teleport Nodes (e.g., to
+display Nodes in the Web UI or via `tsh ls`), it only returns the Nodes that the
+current user is authorized to view.
+
+For each Node in the user's Teleport cluster, the Auth Service applies the
+following checks in order and, if one check fails, hides the Node from the user:
+
+- None of the user's roles contain a `deny` rule that matches the Node's labels.
+- None of the user's roles contain a `deny` rule that matches the user's login.
+- At least one of the user's roles contains an `allow` rule that matches the
+  Node's labels.
+- At least one of the user's roles contains an `allow` rule that matches the
+  user's login.
+
+If you are not seeing Nodes when expected, make sure that your user's roles
+include the appropriate `allow` and `deny` rules as documented in the
+[Teleport Access Controls Reference](../access-controls/reference.mdx).
diff --git a/docs/pages/includes/sso/loginerrortroubleshooting.mdx b/docs/pages/includes/sso/loginerrortroubleshooting.mdx
@@ -37,15 +37,7 @@ Example of a user being denied because the role `clusteradmin` wasn't set up:
 
 ### Teleport does not show the expected Nodes
 
-When Teleport's Auth Service receives a request to list Teleport Nodes,
-it only returns the Nodes that a user is authorized to access. 
-
-A user's Teleport roles must grant the user explicit access to Nodes with a particular label
- before the user can view those Nodes. The Auth Service compares the user's 
-`traits.logins` with the `allow` and `deny` rules defined in each of the user's roles. 
-If the user's logins match a role's `allow` and `deny` rules, and a Node's labels match 
-the keys and values listed within a role's `node_labels` field, then the Auth Service will
-list the Node in response to the user's request.
+(!docs/pages/includes/node-logins.mdx!)
 
 When configuring SSO, ensure that the identity provider is populating each user's 
 traits correctly. For a user to see a Node in Teleport, the result of populating a

diff --git a/docs/pages/machine-id/getting-started.mdx b/docs/pages/machine-id/getting-started.mdx
@@ -274,6 +274,12 @@ Node Name Address        Labels
 node-name  127.0.0.1:3022 arch=x86_64,group=api-servers
 ```
 
+<Details title="Not seeing Nodes?" opened={false}>
+
+(!docs/pages/includes/node-logins.mdx!)
+
+</Details>
+
 To use Machine ID with the OpenSSH integration, run the following command to
 connect to `node-name` within cluster `example.com`.
 

diff --git a/docs/pages/machine-id/guides/ansible.mdx b/docs/pages/machine-id/guides/ansible.mdx
@@ -76,6 +76,12 @@ $ # Replace ".example.com" below with the name of your cluster.
 $ tsh ls --format=json | jq -r '.[].spec.hostname + ".example.com"' > hosts
 ```
 
+<Details title="Not seeing Nodes?" opened={false}>
+
+(!docs/pages/includes/node-logins.mdx!)
+
+</Details>
+
 ## Step 2/2. Run a playbook
 
 Finally, let's create a simple Ansible playbook, `playbook.yaml`.

diff --git a/docs/pages/server-access/guides/tsh.mdx b/docs/pages/server-access/guides/tsh.mdx
@@ -414,6 +414,12 @@ $ tsh ls os=osx
 
 [CLI Docs -tsh ls](../../setup/reference/cli.mdx#tsh-ls)
 
+<Details title="Not seeing Nodes?" opened={false}>
+
+(!docs/pages/includes/node-logins.mdx!)
+
+</Details>
+
 ## Interactive shell
 
 To launch an interactive shell on a remote Node or to execute a command, use

diff --git a/docs/pages/setup/reference/cli.mdx b/docs/pages/setup/reference/cli.mdx
@@ -405,6 +405,12 @@ List cluster nodes:
 $ tsh ls [<flags>] [<label>]
 ```
 
+<Details title="Not seeing Nodes?" opened={false}>
+
+(!docs/pages/includes/node-logins.mdx!)
+
+</Details>
+
 {/* TODO: label? or labels? seems like it only supports one label at a time */}
 
 #### Arguments