gravitational · zmb3 · Feb 14, 2022 · Feb 14, 2022 · Feb 14, 2022 · Feb 14, 2022
diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx
@@ -122,7 +122,7 @@ Save this role as `interns.yaml`:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: interns
 spec:

diff --git a/docs/pages/access-controls/guides/dual-authz.mdx b/docs/pages/access-controls/guides/dual-authz.mdx
@@ -80,7 +80,7 @@ spec:
 version: v2
 ---
 kind: role
-version: v5
+version: v4
 metadata:
   name: access-plugin
 spec:
@@ -162,7 +162,7 @@ Create `dbadmin`, `reviewer` and `devops` roles:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: reviewer
 spec:
@@ -171,7 +171,7 @@ spec:
       roles: ['dbadmin']
 ---
 kind: role
-version: v5
+version: v4
 metadata:
   name: devops
 spec:
@@ -183,7 +183,7 @@ spec:
           deny: 1
 ---
 kind: role
-version: v5
+version: v4
 metadata:
   name: dbadmin
 spec:

diff --git a/docs/pages/access-controls/guides/impersonation.mdx b/docs/pages/access-controls/guides/impersonation.mdx
@@ -32,7 +32,7 @@ Save this file as `jenkins.yaml` to create the user and role:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: jenkins
 spec:
@@ -77,7 +77,7 @@ Save this role definition as `impersonator.yaml`:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: impersonator
 spec:
@@ -179,7 +179,7 @@ allowed the impersonation of any users or roles with the label
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: security-impersonator
 spec:
@@ -214,7 +214,7 @@ Create a user and a role `security-scanner` using the following template:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: security-scanner
   labels:
@@ -256,7 +256,7 @@ as the label on the role and/or user to impersonate:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: security-impersonator
 spec:

diff --git a/docs/pages/access-controls/guides/locking.mdx b/docs/pages/access-controls/guides/locking.mdx
@@ -105,7 +105,7 @@ Create a role `locksmith`:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: locksmith
 spec:
@@ -231,7 +231,7 @@ It is also possible to configure the locking mode for a particular role:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
     name: example-role-with-strict-locking
 spec:

diff --git a/docs/pages/access-controls/guides/moderated-sessions.mdx b/docs/pages/access-controls/guides/moderated-sessions.mdx
@@ -4,6 +4,10 @@ description: Moderated Sessions
 h1: Moderated Sessions
 ---
 
+<Details title="Version Requirements" min="8.3" opened>
+  Moderated Sessions require `version: v5` roles, which are only available in Teleport 8.3.0 and above.
+</Details>
+
 ## Introduction
 
 Moderated Sessions allows Teleport administrators to
@@ -54,6 +58,7 @@ When a user with this require policy starts a session, it will be pending
 until the policy is fulfilled. 
 
 ```yaml
+version: v5
 kind: role
 metadata:
   name: prod-access
@@ -86,6 +91,7 @@ The following allow policy attaches to the role `auditor` and allows one to join
 SSH and Kubernetes sessions started by a user with the role `prod-access` as a moderator or observer.
 
 ```yaml
+version: v5
 kind: role
 metadata:
   name: auditor

diff --git a/docs/pages/access-controls/guides/per-session-mfa.mdx b/docs/pages/access-controls/guides/per-session-mfa.mdx
@@ -87,7 +87,7 @@ Olga defines two Teleport roles: `access-dev` and `access-prod`:
 ```yaml
 # access-dev.yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: access-dev
 spec:
@@ -100,7 +100,7 @@ spec:
 ---
 # access-prod.yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: access-prod
 spec:

diff --git a/docs/pages/access-controls/guides/role-templates.mdx b/docs/pages/access-controls/guides/role-templates.mdx
@@ -36,7 +36,7 @@ We can create two roles, one for each user in file `roles.yaml`:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: alice
 spec:
@@ -49,7 +49,7 @@ spec:
       '*': '*'
 ---
 kind: role
-version: v5
+version: v4
 metadata:
   name: bob
 spec:
@@ -78,7 +78,7 @@ Let's create a role template `devs.yaml`:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: devs
 spec:
@@ -173,7 +173,7 @@ to be set by identity provider. Save this role as `sso-users.yaml`:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: sso-users
 spec:
@@ -255,7 +255,7 @@ Let's see how these variables are used with role template `interpolation`:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: interpolation
 spec:
@@ -288,7 +288,7 @@ behave as the following role:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: interpolation
 spec:

diff --git a/docs/pages/access-controls/reference.mdx b/docs/pages/access-controls/reference.mdx
@@ -41,9 +41,15 @@ $ tctl get roles
 
 A role definition looks like this:
 
+<Details title="Role Versioning" min="8.3" opened>
+  The role example below uses `version: v4` for compatability reasons. Note that
+  the `join_sessions` and `require_session_join` fields are only supported on `version: v5` roles,
+  which are otherwise identical to `version: v4`.
+</Details>
+
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: example
 spec:
@@ -230,12 +236,18 @@ that are more appropriately scoped.
 
 ### Role versions
 
-There are currently two supported role versions: `v3` and `v5`. `v5` roles are
-completely backwards-compatible with `v3`, the only difference lies in the
-default allow labels which will be applied to the role if they are not
+There are currently three supported role versions: `v3`, `v4` and `v5`. `v4` roles are
+completely backwards-compatible with `v3`. The only difference lies in the
+default allow labels, which will be applied to the role if they are not
 explicitly set.
 
-Label              | `v3` Default   | `v5` Default
+`v5` roles are also backwards compatible with `v4`. They add
+the `join_sessions` and `require_session_join` fields related to [Moderated Sessions](./guides/moderated-sessions.mdx).
+
+Upon upgrading to Telport 8.3.0 or later, new roles will be created with `version: v5` and old roles
+will be migrated as they are edited but not automatically.
+
+Label              | `v3` Default   | `v4` Default
 ------------------ | -------------- | ---------------
 `node_labels`       | `[{"*": "*"}]` if the role has any logins, else `[]` | `[]`
 `app_labels`        | `[{"*": "*"}]` | `[]`
@@ -263,7 +275,7 @@ Access to any other nodes will be denied:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: example-role
 spec:
@@ -293,7 +305,7 @@ Below are a few examples for more complex filtering using various regexes.
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: example-role
 spec:
@@ -370,7 +382,7 @@ downgrade they will become invalid.
 Role for restricted access to session recordings:
 
 ```yaml
-version: v5
+version: v4
 kind: role
 metadata:
   name: only-own-sessions
@@ -387,7 +399,7 @@ spec:
 Role for restricted access to active sessions:
 
 ```yaml
-version: v5
+version: v4
 kind: role
 metadata:
   name: only-own-ssh-sessions

diff --git a/docs/pages/api/architecture.mdx b/docs/pages/api/architecture.mdx
@@ -36,7 +36,7 @@ spec:
   deny:
     node_labels:
       '*': '*'
-version: v5
+version: v4
 EOF
 # Create role
 tctl create -f api-role.yaml

diff --git a/docs/pages/application-access/controls.mdx b/docs/pages/application-access/controls.mdx
@@ -41,7 +41,7 @@ For example, this role will grant access to all applications from the group
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: dev
 spec:

diff --git a/docs/pages/application-access/guides/aws-console.mdx b/docs/pages/application-access/guides/aws-console.mdx
@@ -142,7 +142,7 @@ role ARNs this particular role permits its users to assume:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: aws-console-access
 spec:

diff --git a/docs/pages/database-access/guides/mysql-self-hosted.mdx b/docs/pages/database-access/guides/mysql-self-hosted.mdx
@@ -74,7 +74,7 @@ database account:
 ```bash
 tctl --config=/path/to/teleport-db-role.yaml create <<EOF
 kind: role
-version: v5
+version: v4
 metadata:
   name: db
 spec:

diff --git a/docs/pages/database-access/guides/postgres-self-hosted.mdx b/docs/pages/database-access/guides/postgres-self-hosted.mdx
@@ -70,7 +70,7 @@ database account:
 ```bash
 tctl --config=/path/to/teleport.yaml create <<EOF
 kind: role
-version: v5
+version: v4
 metadata:
   name: db
 spec:

diff --git a/docs/pages/database-access/rbac.mdx b/docs/pages/database-access/rbac.mdx
@@ -23,7 +23,7 @@ database access:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: developer
 spec:
@@ -55,7 +55,7 @@ production database except for the internal "postgres" database/user:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: developer
 spec:

diff --git a/docs/pages/desktop-access/getting-started.mdx b/docs/pages/desktop-access/getting-started.mdx
@@ -313,7 +313,7 @@ For example, you can create a role that gives its users access to all Windows de
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: windows-desktop-admins
 spec:

diff --git a/docs/pages/desktop-access/reference.mdx b/docs/pages/desktop-access/reference.mdx
@@ -60,7 +60,7 @@ desktop access:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: developer
 spec:

diff --git a/docs/pages/enterprise/sso.mdx b/docs/pages/enterprise/sso.mdx
@@ -126,7 +126,7 @@ connect to Teleport nodes. To support this:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: sso_user
 spec:
@@ -166,7 +166,7 @@ Here's how this looks in a Teleport role:
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: sso_user
 spec:

diff --git a/docs/pages/enterprise/sso/azuread.mdx b/docs/pages/enterprise/sso/azuread.mdx
@@ -146,7 +146,7 @@ obtain admin access to Teleport.
 
 ```yaml
 kind: role
-version: v5
+version: v4
 metadata:
   name: dev
 spec: