{docs,tailscale}: better document device_subnet_routes (#428)

Add better documentation to the device_subnet_routes resource to clarify
that routes need to be advertised on the device itself, and that all routes
(including those enabled via the admin console / autoApprovers in the ACL)
must be added to the `routes` param when using this resource to avoid
configuration drift.

Updates tailscale/corp#22115

Signed-off-by: Mario Minardi <mario@tailscale.com>

docs/resources/device_subnet_routes.md

@@ -3,12 +3,18 @@
 page_title: "tailscale_device_subnet_routes Resource - terraform-provider-tailscale"
 subcategory: ""
 description: |-
-  The device_subnet_routes resource allows you to configure subnet routes for your Tailscale devices. See https://tailscale.com/kb/1019/subnets for more information.
+  "The device_subnet_routes resource allows you to configure enabled subnet routes for your Tailscale devices. See https://tailscale.com/kb/1019/subnets for more information.
+  Routes must be both advertised and enabled for a device to act as a subnet router or exit node. Routes must be advertised directly from the device and cannot be managed through Terraform. If a device is advertising routes, they are not exposed to traffic until they are enabled. Conversely, if routes are enabled before they are advertised, they are not available for routing until the device in question is advertising them.
+  Note: all routes enabled for the device through the admin console or autoApprovers in the ACL must be explicitly added to the routes attribute of this resource to avoid configuration drift.
 ---
 
 # tailscale_device_subnet_routes (Resource)
 
-The device_subnet_routes resource allows you to configure subnet routes for your Tailscale devices. See https://tailscale.com/kb/1019/subnets for more information.
+"The device_subnet_routes resource allows you to configure enabled subnet routes for your Tailscale devices. See https://tailscale.com/kb/1019/subnets for more information.
+
+Routes must be both advertised and enabled for a device to act as a subnet router or exit node. Routes must be advertised directly from the device and cannot be managed through Terraform. If a device is advertising routes, they are not exposed to traffic until they are enabled. Conversely, if routes are enabled before they are advertised, they are not available for routing until the device in question is advertising them.
+
+Note: all routes enabled for the device through the admin console or autoApprovers in the ACL must be explicitly added to the routes attribute of this resource to avoid configuration drift.
 
 ## Example Usage
 

tailscale/resource_device_subnet_routes.go

@@ -9,9 +9,16 @@ import (
 	tsclient "github.com/tailscale/tailscale-client-go/v2"
 )
 
+const resourceDeviceSubnetRoutesDescription = `"The device_subnet_routes resource allows you to configure enabled subnet routes for your Tailscale devices. See https://tailscale.com/kb/1019/subnets for more information.
+
+Routes must be both advertised and enabled for a device to act as a subnet router or exit node. Routes must be advertised directly from the device and cannot be managed through Terraform. If a device is advertising routes, they are not exposed to traffic until they are enabled. Conversely, if routes are enabled before they are advertised, they are not available for routing until the device in question is advertising them.
+
+Note: all routes enabled for the device through the admin console or autoApprovers in the ACL must be explicitly added to the routes attribute of this resource to avoid configuration drift.
+`
+
 func resourceDeviceSubnetRoutes() *schema.Resource {
 	return &schema.Resource{
-		Description:   "The device_subnet_routes resource allows you to configure subnet routes for your Tailscale devices. See https://tailscale.com/kb/1019/subnets for more information.",
+		Description:   resourceDeviceSubnetRoutesDescription,
 		ReadContext:   resourceDeviceSubnetRoutesRead,
 		CreateContext: resourceDeviceSubnetRoutesCreate,
 		UpdateContext: resourceDeviceSubnetRoutesUpdate,