[NET-6249] Add templated policies description (#19735)

.changelog/19735.txt

@@ -0,0 +1,3 @@
+```release-note:improvement
+acl: add templated policy descriptions
+```

agent/acl_endpoint.go

@@ -1166,6 +1166,7 @@ func (s *HTTPHandlers) ACLTemplatedPoliciesList(resp http.ResponseWriter, req *h
 			TemplateName: tmpBase.TemplateName,
 			Schema:       tmpBase.Schema,
 			Template:     tmpBase.Template,
+			Description:  tmpBase.Description,
 		}
 	}
 
@@ -1211,6 +1212,7 @@ func (s *HTTPHandlers) ACLTemplatedPolicyRead(resp http.ResponseWriter, req *htt
 		TemplateName: baseTemplate.TemplateName,
 		Schema:       baseTemplate.Schema,
 		Template:     baseTemplate.Template,
+		Description:  baseTemplate.Description,
 	}, nil
 }
 

agent/acl_endpoint_test.go

@@ -1413,6 +1413,7 @@ func TestACL_HTTP(t *testing.T) {
 				TemplateName: api.ACLTemplatedPolicyServiceName,
 				Schema:       structs.ACLTemplatedPolicyServiceSchema,
 				Template:     structs.ACLTemplatedPolicyService,
+				Description:  structs.ACLTemplatedPolicyServiceDescription,
 			}, list[api.ACLTemplatedPolicyServiceName])
 		})
 		t.Run("Read", func(t *testing.T) {
@@ -1435,6 +1436,7 @@ func TestACL_HTTP(t *testing.T) {
 				var templatedPolicy api.ACLTemplatedPolicyResponse
 				require.NoError(t, json.NewDecoder(resp.Body).Decode(&templatedPolicy))
 				require.Equal(t, structs.ACLTemplatedPolicyNoRequiredVariablesSchema, templatedPolicy.Schema)
+				require.Equal(t, structs.ACLTemplatedPolicyDNSDescription, templatedPolicy.Description)
 				require.Equal(t, api.ACLTemplatedPolicyDNSName, templatedPolicy.TemplateName)
 				require.Equal(t, structs.ACLTemplatedPolicyDNS, templatedPolicy.Template)
 			})

agent/structs/acl_templated_policy.go

@@ -42,6 +42,13 @@ const (
 	ACLTemplatedPolicyWorkloadIdentityID = "00000000-0000-0000-0000-000000000007"
 	ACLTemplatedPolicyAPIGatewayID       = "00000000-0000-0000-0000-000000000008"
 
+	ACLTemplatedPolicyServiceDescription          = "Gives the token or role permissions to register a service and discover services in the Consul catalog. It also gives the specified service's sidecar proxy the permission to discover and route traffic to other services."
+	ACLTemplatedPolicyNodeDescription             = "Gives the token or role permissions for a register an agent/node into the catalog. A node is typically a consul agent but can also be a physical server, cloud instance or a container."
+	ACLTemplatedPolicyDNSDescription              = "Gives the token or role permissions for the Consul DNS to query services in the network."
+	ACLTemplatedPolicyNomadServerDescription      = "Gives the token or role permissions required for integration with a nomad server."
+	ACLTemplatedPolicyWorkloadIdentityDescription = "Gives the token or role permissions for a specific workload identity."
+	ACLTemplatedPolicyAPIGatewayDescription       = "Gives the token or role permissions for a Consul api gateway"
+
 	ACLTemplatedPolicyNoRequiredVariablesSchema = "" // catch-all schema for all templated policy that don't require a schema
 )
 
@@ -52,6 +59,7 @@ type ACLTemplatedPolicyBase struct {
 	TemplateID   string
 	Schema       string
 	Template     string
+	Description  string
 }
 
 var (
@@ -63,36 +71,42 @@ var (
 			TemplateName: api.ACLTemplatedPolicyServiceName,
 			Schema:       ACLTemplatedPolicyServiceSchema,
 			Template:     ACLTemplatedPolicyService,
+			Description:  ACLTemplatedPolicyServiceDescription,
 		},
 		api.ACLTemplatedPolicyNodeName: {
 			TemplateID:   ACLTemplatedPolicyNodeID,
 			TemplateName: api.ACLTemplatedPolicyNodeName,
 			Schema:       ACLTemplatedPolicyNodeSchema,
 			Template:     ACLTemplatedPolicyNode,
+			Description:  ACLTemplatedPolicyNodeDescription,
 		},
 		api.ACLTemplatedPolicyDNSName: {
 			TemplateID:   ACLTemplatedPolicyDNSID,
 			TemplateName: api.ACLTemplatedPolicyDNSName,
 			Schema:       ACLTemplatedPolicyNoRequiredVariablesSchema,
 			Template:     ACLTemplatedPolicyDNS,
+			Description:  ACLTemplatedPolicyDNSDescription,
 		},
 		api.ACLTemplatedPolicyNomadServerName: {
 			TemplateID:   ACLTemplatedPolicyNomadServerID,
 			TemplateName: api.ACLTemplatedPolicyNomadServerName,
 			Schema:       ACLTemplatedPolicyNoRequiredVariablesSchema,
 			Template:     ACLTemplatedPolicyNomadServer,
+			Description:  ACLTemplatedPolicyNomadServerDescription,
 		},
 		api.ACLTemplatedPolicyWorkloadIdentityName: {
 			TemplateID:   ACLTemplatedPolicyWorkloadIdentityID,
 			TemplateName: api.ACLTemplatedPolicyWorkloadIdentityName,
 			Schema:       ACLTemplatedPolicyWorkloadIdentitySchema,
 			Template:     ACLTemplatedPolicyWorkloadIdentity,
+			Description:  ACLTemplatedPolicyWorkloadIdentityDescription,
 		},
 		api.ACLTemplatedPolicyAPIGatewayName: {
 			TemplateID:   ACLTemplatedPolicyAPIGatewayID,
 			TemplateName: api.ACLTemplatedPolicyAPIGatewayName,
 			Schema:       ACLTemplatedPolicyAPIGatewaySchema,
 			Template:     ACLTemplatedPolicyAPIGateway,
+			Description:  ACLTemplatedPolicyAPIGatewayDescription,
 		},
 	}
 )

api/acl.go

@@ -173,6 +173,7 @@ type ACLTemplatedPolicyResponse struct {
 	TemplateName string
 	Schema       string
 	Template     string
+	Description  string
 }
 
 type ACLTemplatedPolicyVariables struct {

command/acl/templatedpolicy/formatter.go

@@ -65,6 +65,7 @@ func (f *prettyFormatter) FormatTemplatedPolicy(templatedPolicy api.ACLTemplated
 	var buffer bytes.Buffer
 
 	buffer.WriteString(fmt.Sprintf("Name:            %s\n", templatedPolicy.TemplateName))
+	buffer.WriteString(fmt.Sprintf("Description:     %s\n", templatedPolicy.Description))
 
 	buffer.WriteString("Input variables:")
 	switch templatedPolicy.TemplateName {

command/acl/templatedpolicy/formatter_test.go

@@ -37,6 +37,7 @@ func testFormatTemplatedPolicy(t *testing.T, dirPath string) {
 				TemplateName: api.ACLTemplatedPolicyNodeName,
 				Schema:       structs.ACLTemplatedPolicyNodeSchema,
 				Template:     structs.ACLTemplatedPolicyNode,
+				Description:  structs.ACLTemplatedPolicyNodeDescription,
 			},
 		},
 		"dns-templated-policy": {
@@ -44,6 +45,7 @@ func testFormatTemplatedPolicy(t *testing.T, dirPath string) {
 				TemplateName: api.ACLTemplatedPolicyDNSName,
 				Schema:       structs.ACLTemplatedPolicyNoRequiredVariablesSchema,
 				Template:     structs.ACLTemplatedPolicyDNS,
+				Description:  structs.ACLTemplatedPolicyDNSDescription,
 			},
 		},
 		"service-templated-policy": {
@@ -51,6 +53,7 @@ func testFormatTemplatedPolicy(t *testing.T, dirPath string) {
 				TemplateName: api.ACLTemplatedPolicyServiceName,
 				Schema:       structs.ACLTemplatedPolicyServiceSchema,
 				Template:     structs.ACLTemplatedPolicyService,
+				Description:  structs.ACLTemplatedPolicyServiceDescription,
 			},
 		},
 		"nomad-server-templated-policy": {
@@ -58,6 +61,7 @@ func testFormatTemplatedPolicy(t *testing.T, dirPath string) {
 				TemplateName: api.ACLTemplatedPolicyNomadServerName,
 				Schema:       structs.ACLTemplatedPolicyNoRequiredVariablesSchema,
 				Template:     structs.ACLTemplatedPolicyNomadServer,
+				Description:  structs.ACLTemplatedPolicyNomadServerDescription,
 			},
 		},
 	}
@@ -98,16 +102,19 @@ func testFormatTemplatedPolicyList(t *testing.T, dirPath string) {
 			TemplateName: api.ACLTemplatedPolicyNodeName,
 			Schema:       structs.ACLTemplatedPolicyNodeSchema,
 			Template:     structs.ACLTemplatedPolicyNode,
+			Description:  structs.ACLTemplatedPolicyNodeDescription,
 		},
 		"builtin/dns": {
 			TemplateName: api.ACLTemplatedPolicyDNSName,
 			Schema:       structs.ACLTemplatedPolicyNoRequiredVariablesSchema,
 			Template:     structs.ACLTemplatedPolicyDNS,
+			Description:  structs.ACLTemplatedPolicyDNSDescription,
 		},
 		"builtin/service": {
 			TemplateName: api.ACLTemplatedPolicyServiceName,
 			Schema:       structs.ACLTemplatedPolicyServiceSchema,
 			Template:     structs.ACLTemplatedPolicyService,
+			Description:  structs.ACLTemplatedPolicyServiceDescription,
 		},
 	}
 

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/dns-templated-policy.json.golden

@@ -1,5 +1,6 @@
 {
     "TemplateName": "builtin/dns",
     "Schema": "",
-    "Template": "\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nquery_prefix \"\" {\n\tpolicy = \"read\"\n}"
+    "Template": "\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nquery_prefix \"\" {\n\tpolicy = \"read\"\n}",
+    "Description": "Gives the token or role permissions for the Consul DNS to query services in the network."
 }

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/dns-templated-policy.pretty-meta.golden

@@ -1,4 +1,5 @@
 Name:            builtin/dns
+Description:     Gives the token or role permissions for the Consul DNS to query services in the network.
 Input variables: None
 Example usage:
 	consul acl token create -templated-policy builtin/dns

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/dns-templated-policy.pretty.golden

@@ -1,4 +1,5 @@
 Name:            builtin/dns
+Description:     Gives the token or role permissions for the Consul DNS to query services in the network.
 Input variables: None
 Example usage:
 	consul acl token create -templated-policy builtin/dns

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/node-templated-policy.json.golden

@@ -1,5 +1,6 @@
 {
     "TemplateName": "builtin/node",
     "Schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n\t},\n\t\"required\": [\"name\"],\n\t\"definitions\": {\n\t\t\"min-length-one\": {\n\t\t\t\t\"type\": \"string\",\n\t\t\t\t\"minLength\": 1\n\t\t}\n\t}\n}",
-    "Template": "\nnode \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}"
+    "Template": "\nnode \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}",
+    "Description": "Gives the token or role permissions for a register an agent/node into the catalog. A node is typically a consul agent but can also be a physical server, cloud instance or a container."
 }

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/node-templated-policy.pretty-meta.golden

@@ -1,4 +1,5 @@
 Name:            builtin/node
+Description:     Gives the token or role permissions for a register an agent/node into the catalog. A node is typically a consul agent but can also be a physical server, cloud instance or a container.
 Input variables:
 	Name: String - Required - The node name.
 Example usage:

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/node-templated-policy.pretty.golden

@@ -1,4 +1,5 @@
 Name:            builtin/node
+Description:     Gives the token or role permissions for a register an agent/node into the catalog. A node is typically a consul agent but can also be a physical server, cloud instance or a container.
 Input variables:
 	Name: String - Required - The node name.
 Example usage:

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/nomad-server-templated-policy.json.golden

@@ -1,5 +1,6 @@
 {
     "TemplateName": "builtin/nomad-server",
     "Schema": "",
-    "Template": "\nacl = \"write\"\nagent_prefix \"\" {\n  policy = \"read\"\n}\nnode_prefix \"\" {\n  policy = \"read\"\n}\nservice_prefix \"\" {\n  policy = \"write\"\n}"
+    "Template": "\nacl = \"write\"\nagent_prefix \"\" {\n  policy = \"read\"\n}\nnode_prefix \"\" {\n  policy = \"read\"\n}\nservice_prefix \"\" {\n  policy = \"write\"\n}",
+    "Description": "Gives the token or role permissions required for integration with a nomad server."
 }

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/nomad-server-templated-policy.pretty-meta.golden

@@ -1,4 +1,5 @@
 Name:            builtin/nomad-server
+Description:     Gives the token or role permissions required for integration with a nomad server.
 Input variables: None
 Example usage:
 	consul acl token create -templated-policy builtin/nomad-server

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/nomad-server-templated-policy.pretty.golden

@@ -1,4 +1,5 @@
 Name:            builtin/nomad-server
+Description:     Gives the token or role permissions required for integration with a nomad server.
 Input variables: None
 Example usage:
 	consul acl token create -templated-policy builtin/nomad-server

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/service-templated-policy.json.golden

@@ -1,5 +1,6 @@
 {
     "TemplateName": "builtin/service",
     "Schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n\t},\n\t\"required\": [\"name\"],\n\t\"definitions\": {\n\t\t\"min-length-one\": {\n\t\t\t\t\"type\": \"string\",\n\t\t\t\t\"minLength\": 1\n\t\t}\n\t}\n}",
-    "Template": "\nservice \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice \"{{.Name}}-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}"
+    "Template": "\nservice \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice \"{{.Name}}-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}",
+    "Description": "Gives the token or role permissions to register a service and discover services in the Consul catalog. It also gives the specified service's sidecar proxy the permission to discover and route traffic to other services."
 }

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/service-templated-policy.pretty-meta.golden

@@ -1,4 +1,5 @@
 Name:            builtin/service
+Description:     Gives the token or role permissions to register a service and discover services in the Consul catalog. It also gives the specified service's sidecar proxy the permission to discover and route traffic to other services.
 Input variables:
 	Name: String - Required - The name of the service.
 Example usage:

command/acl/templatedpolicy/testdata/FormatTemplatedPolicy/ce/service-templated-policy.pretty.golden

@@ -1,4 +1,5 @@
 Name:            builtin/service
+Description:     Gives the token or role permissions to register a service and discover services in the Consul catalog. It also gives the specified service's sidecar proxy the permission to discover and route traffic to other services.
 Input variables:
 	Name: String - Required - The name of the service.
 Example usage:

command/acl/templatedpolicy/testdata/FormatTemplatedPolicyList/ce/list.json.golden

@@ -2,16 +2,19 @@
     "builtin/dns": {
         "TemplateName": "builtin/dns",
         "Schema": "",
-        "Template": "\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nquery_prefix \"\" {\n\tpolicy = \"read\"\n}"
+        "Template": "\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nquery_prefix \"\" {\n\tpolicy = \"read\"\n}",
+        "Description": "Gives the token or role permissions for the Consul DNS to query services in the network."
     },
     "builtin/node": {
         "TemplateName": "builtin/node",
         "Schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n\t},\n\t\"required\": [\"name\"],\n\t\"definitions\": {\n\t\t\"min-length-one\": {\n\t\t\t\t\"type\": \"string\",\n\t\t\t\t\"minLength\": 1\n\t\t}\n\t}\n}",
-        "Template": "\nnode \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}"
+        "Template": "\nnode \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}",
+        "Description": "Gives the token or role permissions for a register an agent/node into the catalog. A node is typically a consul agent but can also be a physical server, cloud instance or a container."
     },
     "builtin/service": {
         "TemplateName": "builtin/service",
         "Schema": "{\n\t\"type\": \"object\",\n\t\"properties\": {\n\t\t\"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n\t},\n\t\"required\": [\"name\"],\n\t\"definitions\": {\n\t\t\"min-length-one\": {\n\t\t\t\t\"type\": \"string\",\n\t\t\t\t\"minLength\": 1\n\t\t}\n\t}\n}",
-        "Template": "\nservice \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice \"{{.Name}}-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}"
+        "Template": "\nservice \"{{.Name}}\" {\n\tpolicy = \"write\"\n}\nservice \"{{.Name}}-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}",
+        "Description": "Gives the token or role permissions to register a service and discover services in the Consul catalog. It also gives the specified service's sidecar proxy the permission to discover and route traffic to other services."
     }
 }