[v17] Add dynamic registration for Windows desktops docs (#49151)

* Add dynamic Windows desktops registration docs * lint * lint * review * mentione dynamic desktops in reference docs * Update docs/pages/enroll-resources/desktop-access/dynamic-registration.mdx Co-authored-by: Zac Bergquist <[email protected]> * Update docs/pages/enroll-resources/desktop-access/dynamic-registration.mdx Co-authored-by: Zac Bergquist <[email protected]> * comment * Additional updates --------- Co-authored-by: Przemko Robakowski <[email protected]>
gravitational · Nov 19, 2024 · 003f242 · 003f242
1 parent b31e675
commit 003f242
Show file tree

Hide file tree

Showing 4 changed files with 163 additions and 32 deletions.
diff --git a/docs/pages/enroll-resources/desktop-access/dynamic-registration.mdx b/docs/pages/enroll-resources/desktop-access/dynamic-registration.mdx
@@ -0,0 +1,147 @@
+---
+title: Dynamic Windows Desktop Registration
+description: Register/unregister Windows desktops without restarting Teleport.
+---
+
+Dynamic Windows desktop registration allows Teleport administrators to register
+new Windows desktops (or update/unregister existing ones) without having to
+update the static configuration files read by Teleport Windows Desktop Service
+instances.
+
+Windows Desktop Service instances watch for updates from the Teleport Auth
+Service for `dynamic_windows_desktop` resources, each of which includes the
+information that the Windows Desktop Service needs to connect to a Windows
+desktop.
+
+## Required permissions
+
+In order to interact with dynamically registered Windows desktops, a user must have
+a Teleport role with permissions to manage `dynamic_windows_desktop` resources.
+
+In the following example, a role allows a user to perform all possible
+operations against `dynamic_windows_desktop` resources:
+
+```yaml
+allow:
+  rules:
+    - resources: [dynamic_windows_desktop]
+      verbs: [list, create, read, update, delete]
+```
+
+## Enabling dynamic registration
+
+To enable dynamic registration, include a `resources` section in your Windows Desktop
+Service configuration with a list of resource label selectors you'd like this
+service to monitor for registering:
+
+```yaml
+windows_desktop_service:
+  enabled: "yes"
+  resources:
+  - labels:
+      "*": "*"
+```
+
+You can use a wildcard selector to register all dynamic Windows desktop resources in the cluster
+on the Windows Desktop Service or provide a specific set of labels for a subset:
+
+```yaml
+resources:
+- labels:
+    "env": "prod"
+- labels:
+    "env": "test"
+```
+
+## Creating a dynamic_windows_desktop resource
+
+Configure Teleport to register a Windows desktop dynamically by creating an `dynamic_windows_desktop`
+resource. The following example configures Teleport for connecting to Windows desktop
+called `example` at `host1.example.com:3089`.
+
+```yaml
+kind: dynamic_windows_desktop
+version: v1
+metadata:
+  name: example
+  description: "Example desktop"
+  labels:
+    env: test
+spec:
+  addr: host1.example.com:3089
+  # non_ad should be true for logging with local Windows user and false for Active Directory users
+  non_ad: true
+  # domain specifies domain used for AD-joined machines
+  domain: ""
+
+  # Optional - ensures that all sessions use the same screen size,
+  # no matter what the size of the browser window is.
+  # Leave blank to use the size of the browser window.
+  screen_size:
+    width: 1024
+    height: 768
+```
+
+The user creating the dynamic Windows desktop needs to have a role with access
+to the Windows desktop labels and the `dynamic_windows_desktop` resource. In
+this example role the user can only create and maintain dynamic Windows desktops
+labeled `env: test`.
+
+```yaml
+kind: role
+version: v7
+metadata:
+  name: example
+spec:
+  allow:
+    windows_desktop_labels:
+      env: test
+    rules:
+    - resources: [dynamic_windows_desktop]
+      verbs: [list, create, read, update, delete]
+```
+
+To create a dynamic Windows desktop resource, run:
+
+<Tabs>
+    <TabItem scope={["oss", "enterprise"]} label="Self-Hosted">
+
+        ```code
+        # Log in to your cluster with tsh so you can use tctl from your local machine.
+        # You can also run tctl on your Auth Service host without running "tsh login"
+        # first.
+        $ tsh login --proxy=teleport.example.com --user=myuser
+        $ tctl create dynamic_windows_desktop.yaml
+        ```
+
+    </TabItem>
+    <TabItem scope={["cloud"]} label="Teleport Enterprise (Cloud)">
+
+        ```code
+        # Log in to your Teleport cluster so you can use tctl remotely.
+        $ tsh login --proxy=mytenant.teleport.sh --user=myuser
+        $ tctl create dynamic_windows_desktop.yaml
+        ```
+
+    </TabItem>
+
+</Tabs>
+
+After the resource has been created, it will appear among the list of available
+Windows desktops (in the web UI) as long as at least one Windows Desktop Service
+instance picks it up according to its label selectors.
+
+To update an existing dynamic Windows desktop resource, run:
+
+```code
+$ tctl create -f dynamic_windows_desktop.yaml
+```
+
+If the updated resource's labels no longer match a particular Windows Desktop Service, it
+will unregister and stop routing traffic to it.
+
+To delete a dynamic Windows desktop resource, run:
+
+```code
+$ tctl rm dynamic_windows_desktop/example
+```
diff --git a/docs/pages/enroll-resources/desktop-access/introduction.mdx b/docs/pages/enroll-resources/desktop-access/introduction.mdx
@@ -76,6 +76,7 @@ Windows-specific configuration settings, role-based permissions, and audit event
 - [Role-Based Access Control for Desktops](./rbac.mdx)
 - [Clipboard Sharing](../../reference/agent-services/desktop-access-reference/clipboard.mdx)
 - [Directory Sharing](./directory-sharing.mdx)
+- [Dynamic Registration](./dynamic-registration.mdx)
 - [Session Recording and Playback](../../reference/agent-services/desktop-access-reference/sessions.mdx)
 - [Troubleshooting Desktop Access](./troubleshooting.mdx)
 - [Desktop Access Audit Events Reference](../../reference/agent-services/desktop-access-reference/audit.mdx)

diff --git a/docs/pages/includes/config-reference/desktop-config.yaml b/docs/pages/includes/config-reference/desktop-config.yaml
@@ -109,7 +109,15 @@ windows_desktop_service:
     # The key of the label will be "ldap/" + the value of the attribute.
     label_attributes:
     - location
-  # Rules for applying labels to Windows hosts based on regular expressions
+
+  # (optional) configure a set of label selectors for dynamic registration.
+  # If specified, this service will monitor the cluster for dynamic_windows_desktop
+  # and automatically proxy connections for desktops with matching labels.
+  resources:
+  - labels:
+      "env": "dev"
+
+  # (optional) rules for applying labels to Windows hosts based on regular expressions
   # matched against the host name. If multiple rules match, the desktop will
   # get the union of all matching labels.
   host_labels:

diff --git a/docs/pages/reference/resources.mdx b/docs/pages/reference/resources.mdx
@@ -138,51 +138,26 @@ are required.*/}
 | <pre>kubernetes_groups: <br/>  - "system:masters" <br/>kubernetes_labels: <br/>  env: ["dev"] <br/>kubernetes_resources: <br/>  - kind: "namespace" <br/>    name: "foo"</pre>                                                                                            | ⚠️ not supported                                                                                                  | ⚠️ not supported                                                                                                  | ✅ full access in namespace `foo` <br/>❌ cannot access other namespaces                                                                                                                                |
 
 
-## Windows desktop
+## Windows desktops
 
 In most cases, Teleport will register `windows_desktop` resources automatically
 based on static hosts in your configuration file or via LDAP-based discovery.
 
-However, you can also manage `windows_desktop` resources manually with `tctl`.
-This can be useful for managing inventories of hosts that are not joined to
-an Active Directory domain.
+You can also use [dynamic
+registration](../enroll-resources/desktop-access/dynamic-registration.mdx) using
+`dynamic_windows_desktop` resources. This can be useful for managing inventories
+of hosts that are not joined to an Active Directory domain.
 
 There are a few important considerations to keep in mind when registering
 desktops this way:
 
 1. The desktop's `addr` can be a hostname or IP address, and should include
    the RDP port (typically 3389).
-1. The desktop's `host_id` should be set to the name of a
-   `windows_desktop_service` that is capable of proxying remote desktop
-   connections to the host. If you have multiple such services, you can create
-   multiple `windows_desktop` resources with different `host_id` values.
 1. If you intend to log in to the desktop with local Windows users you must set
    `non_ad: true`. If you intend to log in with Active Directory users, leave
    `non_ad` unset (or false), and specify the Active Directory domain in the
    `domain` field.
 
-```yaml
-kind: windows_desktop
-metadata:
-  name: desktop-without-ad
-  labels:
-    foo: bar
-    baz: quux
-spec:
-  host_id: 307e091b-7f6b-42e0-b78d-3362ad10b55d
-  addr: 192.168.1.153:3389
-  domain: ""
-  non_ad: true
-
-  # Optional - ensures that all sessions use the same screen size,
-  # no matter what the size of the browser window is.
-  # Leave blank to use the size of the browser window.
-  screen_size:
-    width: 1024
-    height: 768
-version: v3
-```
-
 ## Login Rules
 
 Login rules contain logic to transform SSO user traits during login.
@@ -191,7 +166,7 @@ Login rules contain logic to transform SSO user traits during login.
 
 ## Database object import rule
 
-Database object import rule define the labels to be applied to database objects imported into Teleport. 
+Database object import rule define the labels to be applied to database objects imported into Teleport.
 
 See [Database Access Controls](../enroll-resources/database-access/rbac.mdx) for more details.