diff --git a/docs/pages/access-controls/getting-started.mdx b/docs/pages/access-controls/getting-started.mdx
index 41c19b7bc496a..169df79e66d99 100644
--- 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
index cdf8cb008d300..39a1a78f364bc 100644
--- 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
index 38c4117fc9703..6fdacfb46e372 100644
--- 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
index cf998c047d872..2d12b8dbe2bba 100644
--- 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
index fee04919ef893..ef3f9447eb072 100644
--- 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
---
+
+ Moderated Sessions require `version: v5` roles, which are only available in Teleport 8.3.0 and above.
+
+
## 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
index ba345130986ed..e8be4d5063547 100644
--- 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
index 855808ef949e6..90c63b98b9492 100644
--- 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
index 3411ea7370aba..5baa3c5fa8528 100644
--- 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:
+
+ 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`.
+
+
```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
index 2363531aac0d1..11a3bb3306d95 100644
--- 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
index b94f9ab26ff2c..c4956e432ddcf 100644
--- 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
index f6efd76959ecf..0f991c29dd6f9 100644
--- 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
index 9646c7bab41e5..046ea01b2580e 100644
--- 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 <