tailscale · mpminardi · Oct 14, 2025
diff --git a/docs/data-sources/acl.md b/docs/data-sources/acl.md
@@ -1,16 +1,15 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "tailscale_acl Data Source - terraform-provider-tailscale"
 subcategory: ""
 description: |-
-  The acl data source gets the Tailscale ACL for a tailnet
+  The acl data source gets the Tailscale policy file for a tailnet
 ---
 
 # tailscale_acl (Data Source)
 
-The acl data source gets the Tailscale ACL for a tailnet
-
+The acl data source gets the Tailscale policy file for a tailnet
 
+~> **Note:** The naming of this data source predates Tailscale's usage of the term "policy file" to refer to the centralized configuration file for a tailnet. This data source fetches a tailnet's entire policy file and not just the ACLs section within it.
 
 <!-- schema generated by tfplugindocs -->
 ## Schema

diff --git a/docs/resources/acl.md b/docs/resources/acl.md
@@ -1,29 +1,30 @@
 ---
-# generated by https://github.com/hashicorp/terraform-plugin-docs
 page_title: "tailscale_acl Resource - terraform-provider-tailscale"
 subcategory: ""
 description: |-
-  The acl resource allows you to configure a Tailscale ACL. See https://tailscale.com/kb/1018/acls for more information. Note that this resource will completely overwrite existing ACL contents for a given tailnet.
-  If tests are defined in the ACL (the top-level "tests" section), ACL validation will occur before creation and update operations are applied.
+  The acl resource allows you to configure a Tailscale policy file. See https://tailscale.com/kb/1395/tailnet-policy-file for more information. Note that this resource will completely overwrite existing policy file contents for a given tailnet.
+  If tests are defined in the policy file (the top-level "tests" section), policy file validation will occur before creation and update operations are applied.
 ---
 
 # tailscale_acl (Resource)
 
-The acl resource allows you to configure a Tailscale ACL. See https://tailscale.com/kb/1018/acls for more information. Note that this resource will completely overwrite existing ACL contents for a given tailnet.
+The acl resource allows you to configure a Tailscale policy file. See https://tailscale.com/kb/1395/tailnet-policy-file for more information. Note that this resource will completely overwrite existing policy file contents for a given tailnet.
 
-If tests are defined in the ACL (the top-level "tests" section), ACL validation will occur before creation and update operations are applied.
+If tests are defined in the policy file (the top-level "tests" section), policy file validation will occur before creation and update operations are applied.
+
+~> **Note:** The naming of this resource predates Tailscale's usage of the term "policy file" to refer to the centralized configuration file for a tailnet. This resource controls a tailnet's entire policy file and not just the ACLs section within it.
 
 ## Example Usage
 
 ```terraform
 resource "tailscale_acl" "as_json" {
   acl = jsonencode({
-    acls : [
+    grants : [
       {
         // Allow all users access to all ports.
-        action = "accept",
-        users  = ["*"],
-        ports  = ["*:*"],
+        src = ["*"],
+        dst = ["*"],
+        ip  = ["*"],
       },
     ],
   })
@@ -33,12 +34,12 @@ resource "tailscale_acl" "as_hujson" {
   acl = <<EOF
   {
     // Comments in HuJSON policy are preserved when the policy is applied.
-    "acls": [
+    "grants": [
       {
         // Allow all users access to all ports.
-        action = "accept",
-        users  = ["*"],
-        ports  = ["*:*"],
+        "src" = ["*"],
+        "dst" = ["*"],
+        "ip"  = ["*"],
       },
     ],
   }
@@ -55,8 +56,8 @@ resource "tailscale_acl" "as_hujson" {
 
 ### Optional
 
-- `overwrite_existing_content` (Boolean) If true, will skip requirement to import acl before allowing changes. Be careful, can cause ACL to be overwritten
-- `reset_acl_on_destroy` (Boolean) If true, will reset the ACL for the Tailnet to the default when this resource is destroyed
+- `overwrite_existing_content` (Boolean) If true, will skip requirement to import acl before allowing changes. Be careful, can cause the policy file to be overwritten
+- `reset_acl_on_destroy` (Boolean) If true, will reset the policy file for the Tailnet to the default when this resource is destroyed
 
 ### Read-Only
 
@@ -66,8 +67,6 @@ resource "tailscale_acl" "as_hujson" {
 
 Import is supported using the following syntax:
 
-The [`terraform import` command](https://developer.hashicorp.com/terraform/cli/commands/import) can be used, for example:
-
 ```shell
 # ID doesn't matter.
 terraform import tailscale_acl.sample_acl acl

diff --git a/examples/resources/tailscale_acl/resource.tf b/examples/resources/tailscale_acl/resource.tf
@@ -1,11 +1,11 @@
 resource "tailscale_acl" "as_json" {
   acl = jsonencode({
-    acls : [
+    grants : [
       {
         // Allow all users access to all ports.
-        action = "accept",
-        users  = ["*"],
-        ports  = ["*:*"],
+        src = ["*"],
+        dst = ["*"],
+        ip  = ["*"],
       },
     ],
   })
@@ -15,12 +15,12 @@ resource "tailscale_acl" "as_hujson" {
   acl = <<EOF
   {
     // Comments in HuJSON policy are preserved when the policy is applied.
-    "acls": [
+    "grants": [
       {
         // Allow all users access to all ports.
-        action = "accept",
-        users  = ["*"],
-        ports  = ["*:*"],
+        "src" = ["*"],
+        "dst" = ["*"],
+        "ip"  = ["*"],
       },
     ],
   }

diff --git a/tailscale/data_source_acl.go b/tailscale/data_source_acl.go
@@ -16,7 +16,7 @@ import (
 
 func dataSourceACL() *schema.Resource {
 	return &schema.Resource{
-		Description: "The acl data source gets the Tailscale ACL for a tailnet",
+		Description: "The acl data source gets the Tailscale policy file for a tailnet",
 		ReadContext: dataSourceACLRead,
 		Schema: map[string]*schema.Schema{
 			"json": {

diff --git a/tailscale/resource_acl.go b/tailscale/resource_acl.go
@@ -17,9 +17,9 @@ import (
 	"github.com/tailscale/hujson"
 )
 
-const resourceACLDescription = `The acl resource allows you to configure a Tailscale ACL. See https://tailscale.com/kb/1018/acls for more information. Note that this resource will completely overwrite existing ACL contents for a given tailnet.
+const resourceACLDescription = `The acl resource allows you to configure a Tailscale policy file. See https://tailscale.com/kb/1395/tailnet-policy-file for more information. Note that this resource will completely overwrite existing policy file contents for a given tailnet.
 
-If tests are defined in the ACL (the top-level "tests" section), ACL validation will occur before creation and update operations are applied.`
+If tests are defined in the policy file (the top-level "tests" section), policy file validation will occur before creation and update operations are applied.`
 
 // From https://github.com/hashicorp/terraform-plugin-sdk/blob/34d8a9ebca6bed68fddb983123d6fda72481752c/internal/configs/hcl2shim/values.go#L19
 // TODO: use an exported variable when https://github.com/hashicorp/terraform-plugin-sdk/issues/803 has been addressed.
@@ -91,12 +91,12 @@ func resourceACL() *schema.Resource {
 			"overwrite_existing_content": {
 				Type:        schema.TypeBool,
 				Optional:    true,
-				Description: "If true, will skip requirement to import acl before allowing changes. Be careful, can cause ACL to be overwritten",
+				Description: "If true, will skip requirement to import acl before allowing changes. Be careful, can cause the policy file to be overwritten",
 			},
 			"reset_acl_on_destroy": {
 				Type:        schema.TypeBool,
 				Optional:    true,
-				Description: "If true, will reset the ACL for the Tailnet to the default when this resource is destroyed",
+				Description: "If true, will reset the policy file for the Tailnet to the default when this resource is destroyed",
 			},
 		},
 	}
@@ -106,7 +106,7 @@ func resourceACLRead(ctx context.Context, d *schema.ResourceData, m interface{})
 	client := m.(*tailscale.Client)
 	acl, err := client.PolicyFile().Raw(ctx)
 	if err != nil {
-		return diagnosticsError(err, "Failed to fetch ACL")
+		return diagnosticsError(err, "Failed to fetch policy file")
 	}
 
 	if err := d.Set("acl", acl.HuJSON); err != nil {
@@ -129,12 +129,12 @@ func resourceACLCreate(ctx context.Context, d *schema.ResourceData, m interface{
 	if err := client.PolicyFile().Set(ctx, acl, etag); err != nil {
 		if strings.HasSuffix(err.Error(), "(412)") {
 			err = fmt.Errorf(
-				"! You seem to be trying to overwrite a non-default ACL with a tailscale_acl resource.\n"+
-					"Before doing this, please import your existing ACL into Terraform state using:\n"+
+				"! You seem to be trying to overwrite a non-default policy file with a tailscale_acl resource.\n"+
+					"Before doing this, please import your existing policy file into Terraform state using:\n"+
 					" terraform import $(this_resource) acl\n"+
 					"(got error %q)", err)
 		}
-		return diagnosticsError(err, "Failed to set ACL")
+		return diagnosticsError(err, "Failed to set policy file")
 	}
 
 	d.SetId(createUUID())
@@ -149,7 +149,7 @@ func resourceACLUpdate(ctx context.Context, d *schema.ResourceData, m interface{
 	}
 
 	if err := client.PolicyFile().Set(ctx, d.Get("acl").(string), ""); err != nil {
-		return diagnosticsError(err, "Failed to set ACL")
+		return diagnosticsError(err, "Failed to set policy file")
 	}
 
 	return resourceACLRead(ctx, d, m)
@@ -165,7 +165,7 @@ func resourceACLDelete(ctx context.Context, d *schema.ResourceData, m interface{
 	client := m.(*tailscale.Client)
 	// Setting the ACL to an empty string resets its value to the default.
 	if err := client.PolicyFile().Set(ctx, "", ""); err != nil {
-		return diagnosticsError(err, "Failed to reset ACL")
+		return diagnosticsError(err, "Failed to reset policy file")
 	}
 
 	return nil

diff --git a/templates/data-sources/acl.md.tmpl b/templates/data-sources/acl.md.tmpl
@@ -0,0 +1,14 @@
+---
+page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{ .Description | trimspace }}
+
+~> **Note:** The naming of this data source predates Tailscale's usage of the term "policy file" to refer to the centralized configuration file for a tailnet. This data source fetches a tailnet's entire policy file and not just the ACLs section within it.
+
+{{ .SchemaMarkdown | trimspace }}
diff --git a/templates/resources/acl.md.tmpl b/templates/resources/acl.md.tmpl
@@ -0,0 +1,24 @@
+---
+page_title: "{{.Name}} {{.Type}} - {{.ProviderName}}"
+subcategory: ""
+description: |-
+{{ .Description | plainmarkdown | trimspace | prefixlines "  " }}
+---
+
+# {{.Name}} ({{.Type}})
+
+{{ .Description | trimspace }}
+
+~> **Note:** The naming of this resource predates Tailscale's usage of the term "policy file" to refer to the centralized configuration file for a tailnet. This resource controls a tailnet's entire policy file and not just the ACLs section within it.
+
+## Example Usage
+
+{{ tffile (printf "examples/resources/%s/resource.tf" .Name)}}
+
+{{ .SchemaMarkdown | trimspace }}
+
+## Import
+
+Import is supported using the following syntax:
+
+{{ codefile "shell" (printf "examples/resources/%s/import.sh" .Name)}}