Refactoring of architecture section. (#13651)

Our architecture section was written almost 5 years ago and was completely obsolete. I refactored all of it to be up to date, added Kuberentes and other resource type references, replaced and created new diagrams.
gravitational · Jun 23, 2022 · 81cc5d2 · 81cc5d2
1 parent f82e062
commit 81cc5d2
Show file tree

Hide file tree

Showing 59 changed files with 1,119 additions and 1,100 deletions.
diff --git a/docs/config.json b/docs/config.json
@@ -896,28 +896,28 @@
       "title": "Architecture",
       "entries": [
         {
-          "title": "Architecture Overview",
+          "title": "Overview",
           "slug": "/architecture/overview/"
         },
         {
-          "title": "Teleport Users",
-          "slug": "/architecture/users/"
-        },
-        {
-          "title": "Teleport Nodes",
-          "slug": "/architecture/nodes/"
+          "title": "Authentication",
+          "slug": "/architecture/authentication/"
         },
         {
-          "title": "Teleport Auth",
-          "slug": "/architecture/authentication/"
+          "title": "Authorization",
+          "slug": "/architecture/authorization/"
         },
         {
           "title": "Teleport Proxy",
           "slug": "/architecture/proxy/"
         },
         {
           "title": "Trusted Clusters",
-          "slug": "/trustedclusters/"
+          "slug": "/architecture/trustedclusters/"
+        },
+        {
+          "title": "Teleport Nodes",
+          "slug": "/architecture/nodes/"
         },
         {
           "title": "TLS Routing",
@@ -1014,6 +1014,11 @@
     }
   },
   "redirects": [
+    {
+      "source": "/architecture/users/",
+      "destination": "/architecture/authorization/",
+      "permanent": true
+    },
     {
       "source": "/user-manual/",
       "destination": "/server-access/guides/tsh/",
@@ -1265,4 +1270,4 @@
       "permanent": true
     }
   ]
-}
+}
diff --git a/docs/img/architecture/auth.png b/docs/img/architecture/auth.png
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/proxy.png b/docs/img/architecture/proxy.png
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/ssh-certs-short-lived.png b/docs/img/architecture/ssh-certs-short-lived.png
diff --git a/docs/img/architecture/ssh-certs-sso.png b/docs/img/architecture/ssh-certs-sso.png
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/tc-role-mapping.svg b/docs/img/architecture/tc-role-mapping.svg
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/architecture/[email protected] b/docs/img/architecture/[email protected]
diff --git a/docs/img/authn_authz.svg b/docs/img/authn_authz.svg
diff --git a/docs/img/cert_invalid.svg b/docs/img/cert_invalid.svg
diff --git a/docs/img/cert_ok.svg b/docs/img/cert_ok.svg
diff --git a/docs/img/cluster_state.svg b/docs/img/cluster_state.svg
diff --git a/docs/img/everything.svg b/docs/img/everything.svg
diff --git a/docs/img/node_cluster_auth.svg b/docs/img/node_cluster_auth.svg
diff --git a/docs/img/node_join.svg b/docs/img/node_join.svg
diff --git a/docs/img/node_lookup.svg b/docs/img/node_lookup.svg
diff --git a/docs/img/overview.svg b/docs/img/overview.svg
diff --git a/docs/img/proxy-ssh-1.svg b/docs/img/proxy-ssh-1.svg
diff --git a/docs/img/proxy-ssh-2.svg b/docs/img/proxy-ssh-2.svg
diff --git a/docs/img/proxy-web.svg b/docs/img/proxy-web.svg
diff --git a/docs/img/proxy_client_connect.svg b/docs/img/proxy_client_connect.svg
diff --git a/docs/img/trusted-clusters/TrustedClusters-MSP.svg b/docs/img/trusted-clusters/TrustedClusters-MSP.svg
diff --git a/docs/img/trusted-clusters/[email protected] b/docs/img/trusted-clusters/[email protected]
diff --git a/docs/img/tunnel.svg b/docs/img/tunnel.svg
diff --git a/docs/img/user_auth.svg b/docs/img/user_auth.svg
diff --git a/docs/img/user_mappings.svg b/docs/img/user_mappings.svg
diff --git a/docs/img/user_node_access.svg b/docs/img/user_node_access.svg
diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx
@@ -56,151 +56,9 @@ $ tctl get roles
 
 (!docs/pages/includes/backup-warning.mdx!)
 
-A role definition looks like this:
+Here is a full role specification:
 
-```yaml
-kind: role
-version: v5
-metadata:
-  name: example
-spec:
-  # Options used for user sessions with default values:
-  options:
-    # max_session_ttl defines the TTL (time to live) of SSH certificates
-    # issued to the users with this role.
-    max_session_ttl: 8h
-    # forward_agent controls whether SSH agent forwarding is allowed
-    forward_agent: true
-    # port_forwarding controls whether TCP port forwarding is allowed
-    port_forwarding: true
-    # client_idle_timeout determines if SSH sessions to cluster nodes are forcefully
-    # terminated after no activity from a client (idle client). it overrides the
-    # global cluster setting. examples: "30m", "1h" or "1h30m"
-    client_idle_timeout: never
-    # Determines if the clients will be forcefully disconnected when their
-    # certificates expire in the middle of an active SSH session.
-    # It overrides the global cluster setting.
-    disconnect_expired_cert: no
-    # Optional: max_connections Per-user limit of concurrent sessions within a
-    # cluster.
-    max_connections: 2
-    # Optional: max_sessions total number of session channels that can be established
-    # across a single connection. 10 will match OpenSSH default behavior.
-    max_sessions: 10
-    # permit_x11_forwarding allows users to use X11 forwarding with openssh clients and servers through the proxy
-    permit_x11_forwarding: true
-    # Specify whether or not to record the user's desktop sessions.
-    # Desktop session recording is enabled if one or more of the user's
-    # roles has enabled recording. Defaults to true if unspecified.
-    # Desktop sessions will never be recorded if auth_service.session_recording
-    # is set to 'off' in teleport.yaml or if the cluster's session_recording_config
-    # resource has set 'mode: off'.
-    record_sessions:
-      desktop: true
-    # Specify whether clipboard sharing should be allowed with the
-    # remote desktop (requires a supported browser). Defaults to true
-    # if unspecified. If one or more of the user's roles has disabled
-    # the clipboard, then it will be disabled.
-    desktop_clipboard: true
-    # Specify a list of names and associated values to be included in user SSH keys.
-    # The key type can only be "ssh" and the mode can only be "extension".
-    # The name and value fields can be arbitrary strings and the value field
-    # supports variable interpolation.
-    cert_extensions:
-     - type: ssh
-       mode: extension
-       name: [email protected]
-       value: "{{ external.github_login }}"
-  # The allow section declares a list of resource/verb combinations that are
-  # allowed for the users of this role. By default, nothing is allowed.
-  allow:
-    # The logins array defines the OS/UNIX logins a user is allowed to use.
-    # a few special variables are supported here (see below)
-    logins: [root, '{{internal.logins}}']
-    # Windows logins a user is allowed to use for desktop sessions.
-    windows_desktop_logins: [Administrator, '{{internal.logins}}']
-    # If the Kubernetes integration is enabled, this setting configures which
-    # kubernetes groups the users of this role will be assigned to.
-    # Note that you can refer to a SAML/OIDC trait via the "external" property bag.
-    # This allows you to specify Kubernetes group membership in an identity manager:
-    kubernetes_groups: ["system:masters", "{{external.trait_name}}"]]
-
-    # List of node labels a user will be allowed to connect to:
-    node_labels:
-      # A user can only connect to a node marked with 'test' label:
-      'environment': 'test'
-      # The wildcard ('*') means "any node"
-      '*': '*'
-      # Labels can be specified as a list:
-      'environment': ['test', 'staging']
-      # Regular expressions are also supported, for example, the equivalent
-      # of the list example above can be expressed as:
-      'environment': '^test|staging$'
-
-    kubernetes_labels:
-      # A user can only access prod environments
-      'env': 'prod'
-      # User can access any region in us-west, e.g us-west-1, us-west-2
-      'region': 'us-west-*'
-      'cluster_name': '^us.*\.example\.com$'
-
-    # Defines roles that this user can request.
-    # Needed for teleport's access request workflow
-    # https://goteleport.com/teleport/docs/enterprise/workflow/
-    request:
-      roles:
-      - dba
-
-    # List of allow-rules. See below for more information.
-    rules:
-    - resources: [role]
-      verbs: [list, create, read, update, delete]
-    - resources: [auth_connector]
-      verbs: [list, create, read, update, delete]
-    - resources: [session]
-      verbs: [list, read]
-    - resources: [trusted_cluster]
-      verbs: [list, create, read, update, delete]
-    - resources: [event]
-      verbs: [list, read]
-    - resources: [user]
-      verbs: [list,create,read,update,delete]
-    - resources: [token]
-      verbs: [list,create,read,update,delete]
-
-    # Moderated Sessions policy that dictates requirements for starting a session.
-    require_session_join:
-      # Defines the name of the policy. The name serves only as an
-      # identifier in logs and for organisation/categorisation.
-      - name: Auditor oversight
-        # Specifies an RBAC predicate that is used to define
-        # which users count against the required user count of the policy.
-        filter: 'contains(user.roles, "auditor")'
-        # The different session kinds this policy applies to.
-        kinds: ['k8s', 'ssh']
-        # A list of session participant modes that a participant must have
-        # one of in order to count against the policy.
-        modes: ['moderator']
-        # The minimum amount of users that need to match the filter expression
-        # in order to satisfy the policy.
-        count: 1
-
-    # Moderated Sessions policy that dictates the ability to join sessions
-    join_sessions:
-      # Defines the name of the policy. The name serves only as an
-      # identifier in logs and for organisation/categorisation.
-      - name: Auditor oversight
-        # Allows one to join sessions created by other users with these roles
-        roles : ['prod-access']
-        # The different session kinds this policy applies to.
-        kinds: ['k8s', 'ssh']
-        # The list of session participant modes the role may join the session as.
-        modes: ['moderator', 'observer']
-
-  # The deny section uses the identical format as the 'allow' section.
-  # The deny rules always override allow rules.
-  deny: {}
-```
+(!docs/pages/includes/role-spec.mdx!)
 
 The following variables can be used with `logins` and `windows_desktop_logins` fields:
 
@@ -413,7 +271,7 @@ allow:
 
 It is possible to further limit access to
 [shared sessions](../server-access/guides/tsh.mdx#sharing-sessions) and
-[session recordings](../architecture/nodes.mdx#session-recording).
+[session recordings](../architecture/nodes.mdx#ssh-session-recording).
 The examples below illustrate how to restrict session access only for the user
 who created the session.