adding note about terraform mappings for create_host_user_mode to hos…

…t user creation guide

api/proto/teleport/legacy/types/types.proto

@@ -2939,7 +2939,7 @@ message RoleOptions {
     (gogoproto.customtype) = "BoolOption"
   ];
 
-  // CreateHostUser allows users to be automatically created on a host
+  // Deprecated: Should use CreateHostUserMode instead.
   BoolValue CreateHostUser = 20 [
     (gogoproto.nullable) = true,
     (gogoproto.jsontag) = "create_host_user,omitempty",

docs/cspell.json

@@ -848,6 +848,7 @@
     "snowsql",
     "spacectl",
     "spacelift",
+    "specoptions",
     "spfile",
     "spiffe",
     "splunkd",

docs/pages/enroll-resources/server-access/guides/host-user-creation.mdx

@@ -108,6 +108,20 @@ permission to restart the Nginx service as root. In Teleport 16.4.0 and later,
 the default shell for a created user can be configured with `create_host_user_default_shell`. 
 Otherwise the host's default shell will be used.
 
+<Admonition type="note">
+
+When using the terraform provider, the values for `create_host_user_mode` are represented numerically
+as reflected in the
+[role reference](/reference/terraform-provider/resources/role/#nested-schema-for-specoptions).
+
+Possible values are:
+- `0` is `unspecified`.
+- `1` is `off`.
+- `2` is `keep`.
+- `4` is `insecure-drop`.
+
+</Admonition>
+
 {/*TODO (ptgott): We should move the information below into a reference guide*/}
 <Details title="Customizing host user creation">
 

docs/pages/reference/operator-resources/resources.teleport.dev_roles.mdx

@@ -340,7 +340,7 @@ resource, which you can apply after installing the Teleport Kubernetes operator.
 |create_db_user|boolean|CreateDatabaseUser enabled automatic database user creation.|
 |create_db_user_mode|string or integer|CreateDatabaseUserMode allows users to be automatically created on a database when not set to off. 0 is "unspecified", 1 is "off", 2 is "keep", 3 is "best_effort_drop". Can be either the string or the integer representation of each option.|
 |create_desktop_user|boolean|CreateDesktopUser allows users to be automatically created on a Windows desktop|
-|create_host_user|boolean|CreateHostUser allows users to be automatically created on a host|
+|create_host_user|boolean|Deprecated: Should use CreateHostUserMode instead.|
 |create_host_user_default_shell|string|CreateHostUserDefaultShell is used to configure the default shell for newly provisioned host users.|
 |create_host_user_mode|string or integer|CreateHostUserMode allows users to be automatically created on a host when not set to off. 0 is "unspecified"; 1 is "off"; 2 is "drop" (removed for v15 and above), 3 is "keep"; 4 is "insecure-drop". Can be either the string or the integer representation of each option.|
 |desktop_clipboard|boolean|DesktopClipboard indicates whether clipboard sharing is allowed between the user's workstation and the remote desktop. It defaults to true unless explicitly set to false.|
@@ -723,7 +723,7 @@ resource, which you can apply after installing the Teleport Kubernetes operator.
 |create_db_user|boolean|CreateDatabaseUser enabled automatic database user creation.|
 |create_db_user_mode|string or integer|CreateDatabaseUserMode allows users to be automatically created on a database when not set to off. 0 is "unspecified", 1 is "off", 2 is "keep", 3 is "best_effort_drop". Can be either the string or the integer representation of each option.|
 |create_desktop_user|boolean|CreateDesktopUser allows users to be automatically created on a Windows desktop|
-|create_host_user|boolean|CreateHostUser allows users to be automatically created on a host|
+|create_host_user|boolean|Deprecated: Should use CreateHostUserMode instead.|
 |create_host_user_default_shell|string|CreateHostUserDefaultShell is used to configure the default shell for newly provisioned host users.|
 |create_host_user_mode|string or integer|CreateHostUserMode allows users to be automatically created on a host when not set to off. 0 is "unspecified"; 1 is "off"; 2 is "drop" (removed for v15 and above), 3 is "keep"; 4 is "insecure-drop". Can be either the string or the integer representation of each option.|
 |desktop_clipboard|boolean|DesktopClipboard indicates whether clipboard sharing is allowed between the user's workstation and the remote desktop. It defaults to true unless explicitly set to false.|

docs/pages/reference/operator-resources/resources.teleport.dev_rolesv6.mdx

@@ -340,7 +340,7 @@ resource, which you can apply after installing the Teleport Kubernetes operator.
 |create_db_user|boolean|CreateDatabaseUser enabled automatic database user creation.|
 |create_db_user_mode|string or integer|CreateDatabaseUserMode allows users to be automatically created on a database when not set to off. 0 is "unspecified", 1 is "off", 2 is "keep", 3 is "best_effort_drop". Can be either the string or the integer representation of each option.|
 |create_desktop_user|boolean|CreateDesktopUser allows users to be automatically created on a Windows desktop|
-|create_host_user|boolean|CreateHostUser allows users to be automatically created on a host|
+|create_host_user|boolean|Deprecated: Should use CreateHostUserMode instead.|
 |create_host_user_default_shell|string|CreateHostUserDefaultShell is used to configure the default shell for newly provisioned host users.|
 |create_host_user_mode|string or integer|CreateHostUserMode allows users to be automatically created on a host when not set to off. 0 is "unspecified"; 1 is "off"; 2 is "drop" (removed for v15 and above), 3 is "keep"; 4 is "insecure-drop". Can be either the string or the integer representation of each option.|
 |desktop_clipboard|boolean|DesktopClipboard indicates whether clipboard sharing is allowed between the user's workstation and the remote desktop. It defaults to true unless explicitly set to false.|

docs/pages/reference/operator-resources/resources.teleport.dev_rolesv7.mdx

@@ -340,7 +340,7 @@ resource, which you can apply after installing the Teleport Kubernetes operator.
 |create_db_user|boolean|CreateDatabaseUser enabled automatic database user creation.|
 |create_db_user_mode|string or integer|CreateDatabaseUserMode allows users to be automatically created on a database when not set to off. 0 is "unspecified", 1 is "off", 2 is "keep", 3 is "best_effort_drop". Can be either the string or the integer representation of each option.|
 |create_desktop_user|boolean|CreateDesktopUser allows users to be automatically created on a Windows desktop|
-|create_host_user|boolean|CreateHostUser allows users to be automatically created on a host|
+|create_host_user|boolean|Deprecated: Should use CreateHostUserMode instead.|
 |create_host_user_default_shell|string|CreateHostUserDefaultShell is used to configure the default shell for newly provisioned host users.|
 |create_host_user_mode|string or integer|CreateHostUserMode allows users to be automatically created on a host when not set to off. 0 is "unspecified"; 1 is "off"; 2 is "drop" (removed for v15 and above), 3 is "keep"; 4 is "insecure-drop". Can be either the string or the integer representation of each option.|
 |desktop_clipboard|boolean|DesktopClipboard indicates whether clipboard sharing is allowed between the user's workstation and the remote desktop. It defaults to true unless explicitly set to false.|

examples/chart/teleport-cluster/charts/teleport-operator/operator-crds/resources.teleport.dev_roles.yaml

@@ -1133,8 +1133,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the
@@ -2465,8 +2464,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the

examples/chart/teleport-cluster/charts/teleport-operator/operator-crds/resources.teleport.dev_rolesv6.yaml

@@ -1136,8 +1136,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the

examples/chart/teleport-cluster/charts/teleport-operator/operator-crds/resources.teleport.dev_rolesv7.yaml

@@ -1136,8 +1136,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the

integrations/operator/config/crd/bases/resources.teleport.dev_roles.yaml

@@ -1133,8 +1133,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the
@@ -2465,8 +2464,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the

integrations/operator/config/crd/bases/resources.teleport.dev_rolesv6.yaml

@@ -1136,8 +1136,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the

integrations/operator/config/crd/bases/resources.teleport.dev_rolesv7.yaml

@@ -1136,8 +1136,7 @@ spec:
                       created on a Windows desktop
                     type: boolean
                   create_host_user:
-                    description: CreateHostUser allows users to be automatically created
-                      on a host
+                    description: 'Deprecated: Should use CreateHostUserMode instead.'
                     type: boolean
                   create_host_user_default_shell:
                     description: CreateHostUserDefaultShell is used to configure the

lib/services/access_checker.go

@@ -1035,6 +1035,7 @@ func (a *accessChecker) HostUsers(s types.Server) (*HostUsersInfo, error) {
 		}
 
 		createHostUserMode := role.GetOptions().CreateHostUserMode
+		//nolint:staticcheck // this field is preserved for existing deployments, but shouldn't be used going forward
 		createHostUser := role.GetOptions().CreateHostUser
 		if createHostUserMode == types.CreateHostUserMode_HOST_USER_MODE_UNSPECIFIED {
 			createHostUserMode = types.CreateHostUserMode_HOST_USER_MODE_OFF

lib/srv/regular/sshserver_test.go

@@ -2848,6 +2848,7 @@ func newUpack(testSvr *auth.TestServer, username string, allowedLogins []string,
 	role.SetRules(types.Allow, rules)
 	opts := role.GetOptions()
 	opts.PermitX11Forwarding = types.NewBool(true)
+	//nolint:staticcheck // this field is preserved for existing deployments, but shouldn't be used going forward
 	opts.CreateHostUser = types.NewBoolOption(true)
 	role.SetOptions(opts)
 	role.SetLogins(types.Allow, allowedLogins)