diff --git a/website/content/api-docs/acl/auth-methods.mdx b/website/content/api-docs/acl/auth-methods.mdx
index 7b65bf6903..805a9ee93c 100644
--- a/website/content/api-docs/acl/auth-methods.mdx
+++ b/website/content/api-docs/acl/auth-methods.mdx
@@ -13,8 +13,10 @@ The `/acl/auth-method` endpoints [create](#create-an-auth-method),
[list](#list-auth-methods) and [delete](#delete-an-auth-method)
ACL auth methods in Consul.
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources:
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
## Create an Auth Method
@@ -439,7 +441,7 @@ listing and must be retrieved by the [auth method reading endpoint](#read-an-aut
]
```
-## Methods to Specify Namespace
+## Methods to specify namespace
Auth method create, read, update, and delete endpoints
support several methods for specifying the namespace of the auth method resource.
diff --git a/website/content/api-docs/acl/binding-rules.mdx b/website/content/api-docs/acl/binding-rules.mdx
index 10be5f9d20..9894ce21c7 100644
--- a/website/content/api-docs/acl/binding-rules.mdx
+++ b/website/content/api-docs/acl/binding-rules.mdx
@@ -13,8 +13,10 @@ The `/acl/binding-rule` endpoints [create](#create-a-binding-rule),
[list](#list-binding-rules) and [delete](#delete-a-binding-rule) ACL binding
rules in Consul.
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources:
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
## Create a Binding Rule
@@ -57,9 +59,9 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
```
- `BindType` `(string: )` - Specifies the way the binding rule
- affects a token created at login.
+ affects a token created at login. You can specify one of the following:
- - `BindType=service` - The computed bind name value is used as an
+ - `service` - The computed bind name value is used as an
`ACLServiceIdentity.ServiceName` field in the token that is created.
@@ -78,7 +80,7 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
- - `BindType=node` - The computed bind name value is used as an
+ - `node` - The computed bind name value is used as an
`ACLNodeIdentity.NodeName` field in the token that is created.
@@ -98,7 +100,7 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
- - `BindType=role` - The computed bind name value is used as a `RoleLink.Name`
+ - `role` - The computed bind name value is used as a `RoleLink.Name`
field in the token that is created. This binding rule will only apply if a
role with the given name exists at login-time. If it does not then this
rule is ignored.
@@ -118,6 +120,29 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
```
+
+ - `templated-policy` - The bind name value is used as an
+ `ACLTemplatedPolicy.TemplateName` field in the token that is created. The computed
+ `BindVars` values are used in the `ACLTemplatedPolicy.TemplateVariables` field.
+
+
+
+ ```json
+ {
+ "AccessorID": "",
+ "SecretID": "",
+ "TemplatedPolicies": [
+ {
+ "TemplateName": "",
+ "TemplateVariables": {
+ "Name": ""
+ }
+ }
+ ]
+ }
+ ```
+
+
- `BindName` `(string: )` - The name to bind to a token at
login-time. What it binds to can be adjusted with different values of the
@@ -129,6 +154,20 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
prefixed-${serviceaccount.name}
```
+- `BindVars` `()` - Specifies the templated policy
+ variables when `BindType` field is set to `templated-policy`. Consul populates
+ the `TemplatedPolicies.TemplateVariables` field with the computed `BindVars` values
+ in the token it creates. You can specify either a plain text string or templated
+ string using [HIL syntax](https://github.com/hashicorp/hil).
+ Consul interpolates templated strings with values that are usable by the `Selector` syntax.
+ For example:
+
+ ```
+ "BindVars": {
+ "Name": "prefixed-${serviceaccount.name}"
+ }
+ ```
+
- `Namespace` `(string: "")` - Specifies the namespace of the binding rule you create.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
@@ -270,9 +309,9 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
```
- `BindType` `(string: )` - Specifies the way the binding rule
- affects a token created at login.
+ affects a token created at login. You can specify one of the following:
- - `BindType=service` - The computed bind name value is used as an
+ - `service` - The computed bind name value is used as an
`ACLServiceIdentity.ServiceName` field in the token that is created.
@@ -291,7 +330,7 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
- - `BindType=node` - The computed bind name value is used as an
+ - `node` - The computed bind name value is used as an
`ACLNodeIdentity.NodeName` field in the token that is created.
@@ -311,7 +350,7 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
- - `BindType=role` - The computed bind name value is used as a `RoleLink.Name`
+ - `role` - The computed bind name value is used as a `RoleLink.Name`
field in the token that is created. This binding rule will only apply if a
role with the given name exists at login-time. If it does not then this
rule is ignored.
@@ -331,6 +370,30 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
```
+
+ - `templated-policy` - Consul populates the `TemplatedPolicies.TemplateName` with
+ the value specified in the `BindName` field in the token that is created. Consul
+ also populates the `TemplatedPolicies.TemplateVariables` field with the computed
+ `BindVars` values.
+
+
+
+ ```json
+ {
+ "AccessorID": "",
+ "SecretID": "",
+ "TemplatedPolicies": [
+ {
+ "TemplateName": "",
+ "TemplateVariables": {
+ "Name": ""
+ }
+ }
+ ]
+ }
+ ```
+
+
- `BindName` `(string: )` - The name to bind to a token at
login-time. What it binds to can be adjusted with different values of the
@@ -342,6 +405,20 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
prefixed-${serviceaccount.name}
```
+- `BindVars` `()` - Specifies the templated policy
+ variables when the `BindType` field is set to `templated-policy`. Consul
+ populates the `TemplatedPolicies.TemplateVariables` field with the computed
+ `BindVars` values in the token it creates. You can specify either a plain text
+ string or templated string using [HIL syntax](https://github.com/hashicorp/hil).
+ Consul interpolates templated strings with values that are usable by the `Selector`
+ syntax. For example:
+
+ ```
+ "BindVars": {
+ "Name": "prefixed-${serviceaccount.name}"
+ }
+ ```
+
- `Namespace` `(string: "")` - Specifies the namespace of the binding rule you update.
This field takes precedence over the `ns` query parameter,
one of several [other methods to specify the namespace](#methods-to-specify-namespace).
@@ -486,7 +563,7 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/binding-rules
]
```
-## Methods to Specify Namespace
+## Methods to specify namespace
Binding rule create, read, update, and delete endpoints
support several methods for specifying the namespace of the auth method resource
diff --git a/website/content/api-docs/acl/index.mdx b/website/content/api-docs/acl/index.mdx
index 57a527d99d..c45368370b 100644
--- a/website/content/api-docs/acl/index.mdx
+++ b/website/content/api-docs/acl/index.mdx
@@ -8,8 +8,10 @@ description: The /acl endpoints manage the Consul's ACL system.
The `/acl` endpoints are used to manage ACL tokens and policies in Consul, [bootstrap the ACL system](#bootstrap-acls) and [check ACL replication status](#check-acl-replication). There are additional pages for managing [tokens](/consul/api-docs/acl/tokens) and [policies](/consul/api-docs/acl/policies) with the `/acl` endpoints.
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources:
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
## Bootstrap ACLs
@@ -506,7 +508,7 @@ $ curl \
}
```
-## Methods to Specify Namespace
+## Methods to specify namespace
Some ACL endpoints support several methods for specifying the namespace of the resource
with the following order of precedence:
diff --git a/website/content/api-docs/acl/policies.mdx b/website/content/api-docs/acl/policies.mdx
index d0c8f68163..c41583626b 100644
--- a/website/content/api-docs/acl/policies.mdx
+++ b/website/content/api-docs/acl/policies.mdx
@@ -380,7 +380,7 @@ retrieved by the [policy reading endpoint](#read-a-policy)
]
```
-## Methods to Specify Namespace
+## Methods to specify namespace
ACL policy endpoints
support several methods for specifying the namespace of the ACL policy resources
diff --git a/website/content/api-docs/acl/roles.mdx b/website/content/api-docs/acl/roles.mdx
index 3da27002d4..fbcb8d8b72 100644
--- a/website/content/api-docs/acl/roles.mdx
+++ b/website/content/api-docs/acl/roles.mdx
@@ -11,8 +11,10 @@ description: The /acl/role endpoints manage Consul's ACL Roles.
The `/acl/role` endpoints [create](#create-a-role), [read](#read-a-role),
[update](#update-a-role), [list](#list-roles) and [delete](#delete-a-role) ACL roles in Consul.
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources:
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
## Create a Role
@@ -55,9 +57,17 @@ The corresponding CLI command is [`consul acl role create`](/consul/commands/acl
linking roles internally by IDs, Consul enables policy renaming without
breaking tokens.
+- `TemplatedPolicies` `(list of maps)` - The list of [templated policies](/consul/docs/security/acl#templated-policies)
+ that should be applied to the role.
+
+ - `TemplateName` `(string: )` - The templated policy name.
+
+ - `TemplateVariables` `(map of strings|maps: )` - The templated policy variables. Not all templated policies
+ require variables.
+
- `ServiceIdentities` `(array)` - The list of [service
identities](/consul/docs/security/acl#service-identities) that should be
- applied to the role. Added in Consul 1.5.0.
+ applied to the role.
- `ServiceName` `(string: )` - The name of the service. The name
must be no longer than 256 characters, must start and end with a lowercase
@@ -71,7 +81,7 @@ The corresponding CLI command is [`consul acl role create`](/consul/commands/acl
- `NodeIdentities` `(array)` - The list of [node
identities](/consul/docs/security/acl#node-identities) that should be
- applied to the role. Added in Consul 1.8.1.
+ applied to the role.
- `NodeName` `(string: )` - The name of the node. The name
must be no longer than 256 characters, must start and end with a lowercase
@@ -99,6 +109,17 @@ The corresponding CLI command is [`consul acl role create`](/consul/commands/acl
"Name": "node-read"
}
],
+ "TemplatedPolicies": [
+ {
+ "TemplateName": "builtin/service",
+ "TemplateVariables": {
+ "Name": "api"
+ }
+ },
+ {
+ "TemplateName": "builtin/dns"
+ }
+ ],
"ServiceIdentities": [
{
"ServiceName": "web"
@@ -153,6 +174,19 @@ $ curl --request PUT \
"Datacenter": "dc2"
}
],
+ "TemplatedPolicies": [
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000003",
+ "TemplateName": "builtin/service",
+ "TemplateVariables": {
+ "Name": "api"
+ }
+ },
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000005",
+ "TemplateName": "builtin/dns"
+ }
+ ],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
@@ -223,6 +257,19 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/role/aa770e5b-8b0b-7fcf-e5a1-8
"Datacenter": "dc2"
}
],
+ "TemplatedPolicies": [
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000003",
+ "TemplateName": "builtin/service",
+ "TemplateVariables": {
+ "Name": "api"
+ }
+ },
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000005",
+ "TemplateName": "builtin/dns"
+ }
+ ],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
@@ -293,6 +340,19 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/role/name/example-role
"Datacenter": "dc2"
}
],
+ "TemplatedPolicies": [
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000003",
+ "TemplateName": "builtin/service",
+ "TemplateVariables": {
+ "Name": "api"
+ }
+ },
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000005",
+ "TemplateName": "builtin/dns"
+ }
+ ],
"Hash": "mBWMIeX9zyUTdDMq8vWB0iYod+mKBArJoAhj6oPz3BI=",
"CreateIndex": 57,
"ModifyIndex": 57
@@ -379,6 +439,11 @@ The corresponding CLI command is [`consul acl role update`](/consul/commands/acl
"NodeName": "node-1",
"Datacenter": "dc2"
}
+ ],
+ "TemplatedPolicies": [
+ {
+ "TemplateName": "builtin/dns"
+ }
]
}
```
@@ -414,6 +479,12 @@ $ curl --request PUT \
"Datacenter": "dc2"
}
],
+ "TemplatedPolicies": [
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000005",
+ "TemplateName": "builtin/dns"
+ }
+ ],
"Hash": "OtZUUKhInTLEqTPfNSSOYbRiSBKm3c4vI2p6MxZnGWc=",
"CreateIndex": 14,
"ModifyIndex": 28
@@ -550,7 +621,7 @@ $ curl --request GET http://127.0.0.1:8500/v1/acl/roles
]
```
-## Methods to Specify Namespace
+## Methods to specify namespace
ACL role endpoints
support several methods for specifying the namespace of the ACL role resources
diff --git a/website/content/api-docs/acl/templated-policies.mdx b/website/content/api-docs/acl/templated-policies.mdx
new file mode 100644
index 0000000000..5805449dd5
--- /dev/null
+++ b/website/content/api-docs/acl/templated-policies.mdx
@@ -0,0 +1,189 @@
+---
+layout: api
+page_title: ACL Templated Policies - HTTP API
+description: The /acl/templated-policies endpoints manage Consul's ACL templated policies.
+---
+
+# ACL Templated Policy HTTP API
+
+The `/acl/templated-policy` endpoints [read](#read-a-templated-policy-by-name),
+[preview](#preview-a-templated-policy), and [list](#list-templated-policies) ACL templated policies in Consul.
+
+For more information on how to setup ACLs, refer to the following resources:
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
+
+## Read a templated policy by name
+
+This endpoint reads an ACL policy with the given ID.
+
+| Method | Path | Produces |
+| ------ | ------------------------ | ------------------ |
+| `GET` | `/acl/templated-policy/name/:name` | `application/json` |
+
+The following table shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
+| ---------------- | ----------------- | ------------- | ------------ |
+| `NO` | `none` | `none` | `acl:read` |
+
+The corresponding CLI command is [`consul acl templated-policy read -name=`](/consul/commands/acl/templated-policy/read#name).
+
+### Path parameters
+
+- `name` `(string: )` - Specifies the name of the ACL policy to read.
+
+### Sample request
+
+```shell-session
+$ curl --request GET http://127.0.0.1:8500/v1/acl/templated-policy/name/builtin/service
+```
+
+### Sample response
+
+```json
+{
+ "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}"
+}
+```
+
+## Preview a templated policy
+
+The `preview` endpoint shows the policy created from a templated policy. The endpoint helps you understand what templated variables are required or are missing from your request.
+
+| Method | Path | Produces |
+| ------ | ------------- | ------------------ |
+| `POST` | `/acl/templated-policy/preview/:name` | `application/json` |
+
+The following table shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
+| ---------------- | ----------------- | ------------- | ------------ |
+| `NO` | `none` | `none` | `acl:read` |
+
+The corresponding CLI command is [`consul acl templated-policy preview`](/consul/commands/acl/templated-policy/preview).
+
+### Path parameters
+
+- `name` `(string: )` - Specifies the name of the ACL templated policy to preview.
+
+### Query parameters
+
+- `ns` `(string: "")` - Specifies the namespace that the policy created from the template applies to.
+ You can also [specify the namespace through other methods](#methods-to-specify-namespace).
+
+### JSON request body schema
+
+- `Name` `(string: )` - Specifies the value of the `name` variable in the templated policy variables.
+
+### Sample payload
+
+```json
+{
+ "Name": "api"
+}
+```
+
+### Sample request
+
+```shell-session
+$ curl --request POST \
+ --data @payload.json \
+ http://127.0.0.1:8500/v1/acl-templated/preview/builtin/service
+```
+
+### Sample response
+
+```json
+{
+ "ID": "0a73657276696365202277656222207...",
+ "Name": "synthetic-policy-0a73657276...",
+ "Description": "synthetic policy generated from templated policy: builtin/service",
+ "Rules": "\nservice \"web\" {\n\tpolicy = \"write\"\n}\nservice \"web-sidecar-proxy\" {\n\tpolicy = \"write\"\n}\nservice_prefix \"\" {\n\tpolicy = \"read\"\n}\nnode_prefix \"\" {\n\tpolicy = \"read\"\n}",
+ "Hash": "b04MnvCVtBXZAmGe4uDpGLABJoGo2nNhEJkqaN5E5x4=",
+ "CreateIndex": 0,
+ "ModifyIndex": 0
+}
+```
+
+## List templated policies
+
+Call the `templated-policies` endpoint with a `GET` method to list all templated ACL policies.
+
+| Method | Path | Produces |
+| ------ | ------------------------- | ------------------ |
+| `GET` | `/acl/templated-policies` | `application/json` |
+
+The following table shows this endpoint's support for
+[blocking queries](/consul/api-docs/features/blocking),
+[consistency modes](/consul/api-docs/features/consistency),
+[agent caching](/consul/api-docs/features/caching), and
+[required ACLs](/consul/api-docs/api-structure#authentication).
+
+| Blocking Queries | Consistency Modes | Agent Caching | ACL Required |
+| ---------------- | ----------------- | ------------- | ------------ |
+| `No` | `none` | `none` | `acl:read` |
+
+The corresponding CLI command is [`consul acl templated-policy list`](/consul/commands/acl/templated-policy/list).
+
+### Query parameters
+
+This endpoint does not accept query parameters.
+
+## Sample Request
+
+```shell-session
+$ curl --request GET http://127.0.0.1:8500/v1/acl/templated-policies
+```
+
+### Sample response
+
+```json
+{
+ "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}"
+ },
+ "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}"
+ },
+ "builtin/nomad-server": {
+ "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}"
+ },
+ "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}"
+ },
+ "builtin/workload-identity": {
+ "TemplateName": "builtin/workload-identity",
+ "Schema": "{\n \"type\": \"object\",\n \"properties\": {\n \"name\": { \"type\": \"string\", \"$ref\": \"#/definitions/min-length-one\" }\n },\n \"required\": [\"name\"],\n \"definitions\": {\n \"min-length-one\": {\n \"type\": \"string\",\n \"minLength\": 1\n }\n }\n}",
+ "Template": "identity \"{{.Name}}\" {\n\tpolicy = \"write\"\n}"
+ }
+}
+```
+
+## Methods to specify namespace
+
+You can employ several methods to specify the namespace in calls to templated ACL policy endpoints. Consul applies the following order of precedence to determine the namespace:
+1. `Namespace` field of the JSON request body. This method only applies to [create](#create-a-policy) and [update](#update-a-policy) endpoints
+1. `ns` query parameter.
+1. `X-Consul-Namespace` request header.
+1. Namespace inherited from the namespace of the request's ACL token.
+1. The `default` namespace.
\ No newline at end of file
diff --git a/website/content/api-docs/acl/tokens.mdx b/website/content/api-docs/acl/tokens.mdx
index d1e6d609af..a741ec3a70 100644
--- a/website/content/api-docs/acl/tokens.mdx
+++ b/website/content/api-docs/acl/tokens.mdx
@@ -9,8 +9,10 @@ description: The /acl/token endpoints manage Consul's ACL Tokens.
The `/acl/token` endpoints [create](#create-a-token), [read](#read-a-token),
[update](#update-a-token), [list](#list-tokens), [clone](#clone-a-token) and [delete](#delete-a-token) ACL tokens in Consul.
-For more information on how to setup ACLs, please check
-the [ACL tutorial](/consul/tutorials/security/access-control-setup-production).
+For more information on how to setup ACLs, refer to the following resources:
+
+- [Access control list (ACL) overview](/consul/docs/security/acl)
+- [ACL tutorial](/consul/tutorials/security/access-control-setup-production)
## Create a Token
@@ -64,6 +66,14 @@ The corresponding CLI command is [`consul acl token create`](/consul/commands/ac
resolved to the role ID. With linking tokens internally by IDs, Consul
enables role renaming without breaking tokens. Added in Consul 1.5.0.
+- `TemplatedPolicies` `(list of maps)` - The list of [templated policies](/consul/docs/security/acl#templated-policies)
+ that should be applied to the role.
+
+ - `TemplateName` `(string: )` - The templated policy name.
+
+ - `TemplateVariables` `(map of strings|maps: )` - The templated policy variables. Not all templated policies
+ require variables.
+
- `ServiceIdentities` `(array)` - The list of [service
identities](/consul/docs/security/acl#service-identities) that should be
applied to the token. Added in Consul 1.5.0.
@@ -121,6 +131,14 @@ The corresponding CLI command is [`consul acl token create`](/consul/commands/ac
"Name": "node-read"
}
],
+ "TemplatedPolicies": [
+ {
+ "TemplateName": "builtin/service",
+ "TemplateVariables": {
+ "Name": "api"
+ }
+ }
+ ],
"Local": false
}
```
@@ -150,6 +168,15 @@ $ curl --request PUT \
"Name": "node-read"
}
],
+ "TemplatedPolicies": [
+ {
+ "TemplateID": "00000000-0000-0000-0000-000000000003",
+ "TemplateName": "builtin/service",
+ "TemplateVariables": {
+ "Name": "api"
+ }
+ }
+ ],
"Local": false,
"CreateTime": "2018-10-24T12:25:06.921933-04:00",
"Hash": "UuiRkOQPRCvoRZHRtUxxbrmwZ5crYrOdZ0Z1FTFbTbA=",
@@ -762,7 +789,7 @@ for reading other secrets which given even more permissions.
]
```
-## Methods to Specify Namespace
+## Methods to specify namespace
ACL token endpoints
support several methods for specifying the namespace of the ACL token resources
diff --git a/website/content/api-docs/agent/check.mdx b/website/content/api-docs/agent/check.mdx
index 5faf728629..9418d06684 100644
--- a/website/content/api-docs/agent/check.mdx
+++ b/website/content/api-docs/agent/check.mdx
@@ -523,7 +523,7 @@ $ curl \
http://127.0.0.1:8500/v1/agent/check/update/my-check-id
```
-## Methods to Specify Namespace
+## Methods to specify namespace
Local agent health check endpoints
support several methods for specifying the namespace of the check resources
diff --git a/website/content/api-docs/agent/connect.mdx b/website/content/api-docs/agent/connect.mdx
index c45eae3499..edef8125b3 100644
--- a/website/content/api-docs/agent/connect.mdx
+++ b/website/content/api-docs/agent/connect.mdx
@@ -246,7 +246,7 @@ $ curl \
- `ValidBefore` `(string)` - The time before which the certificate is valid.
Used with `ValidAfter` this can determine the validity period of the certificate.
-## Methods to Specify Namespace
+## Methods to specify namespace
Local agent service mesh endpoints
support several methods for specifying the namespace of resources
diff --git a/website/content/api-docs/agent/service.mdx b/website/content/api-docs/agent/service.mdx
index cf821c9ddf..eee3dd471e 100644
--- a/website/content/api-docs/agent/service.mdx
+++ b/website/content/api-docs/agent/service.mdx
@@ -824,7 +824,7 @@ $ curl \
http://127.0.0.1:8500/v1/agent/service/maintenance/my-service-id?enable=true&reason=For+the+docs
```
-## Methods to Specify Namespace
+## Methods to specify namespace
Local agent service endpoints
support several methods for specifying the namespace of service resources
diff --git a/website/content/api-docs/catalog.mdx b/website/content/api-docs/catalog.mdx
index 91d1fe7f7e..8af4a2f011 100644
--- a/website/content/api-docs/catalog.mdx
+++ b/website/content/api-docs/catalog.mdx
@@ -1132,7 +1132,7 @@ $ curl \
- `FromWildcard` determines whether the service was associated with the gateway by providing a wildcard specifier
in the gateway's configuration entry
-## Methods to Specify Namespace
+## Methods to specify namespace
Catalog endpoints
support several methods for specifying the namespace of resources
diff --git a/website/content/api-docs/config.mdx b/website/content/api-docs/config.mdx
index a79e024fa4..2c550a2526 100644
--- a/website/content/api-docs/config.mdx
+++ b/website/content/api-docs/config.mdx
@@ -325,7 +325,7 @@ $ curl \
http://127.0.0.1:8500/v1/config/service-defaults/web
```
-## Methods to Specify Namespace
+## Methods to specify namespace
Config endpoints
support several methods for specifying the namespace of configuration entry resources
diff --git a/website/content/api-docs/connect/intentions.mdx b/website/content/api-docs/connect/intentions.mdx
index 20a6b5054b..ebe835ac90 100644
--- a/website/content/api-docs/connect/intentions.mdx
+++ b/website/content/api-docs/connect/intentions.mdx
@@ -668,7 +668,7 @@ $ curl \
}
```
-## Methods to Specify Namespace
+## Methods to specify namespace
Intention endpoints
support several methods for specifying the namespace of intention resources
diff --git a/website/content/api-docs/discovery-chain.mdx b/website/content/api-docs/discovery-chain.mdx
index ecde4b3146..d84bd293c4 100644
--- a/website/content/api-docs/discovery-chain.mdx
+++ b/website/content/api-docs/discovery-chain.mdx
@@ -556,7 +556,7 @@ Response:
}
```
-## Methods to Specify Namespace
+## Methods to specify namespace
The discovery chain endpoint
supports several methods for specifying the namespace to use as the basis of discovery chain compilation
diff --git a/website/content/api-docs/health.mdx b/website/content/api-docs/health.mdx
index bd373c91b9..405c97df1f 100644
--- a/website/content/api-docs/health.mdx
+++ b/website/content/api-docs/health.mdx
@@ -545,7 +545,7 @@ the following selectors and filter operations being supported:
| `ServiceTags` | In, Not In, Is Empty, Is Not Empty |
| `Status` | Equal, Not Equal, In, Not In, Matches, Not Matches |
-## Methods to Specify Namespace
+## Methods to specify namespace
The health endpoints
support several methods for specifying the namespace of resources
diff --git a/website/content/api-docs/kv.mdx b/website/content/api-docs/kv.mdx
index 9f449e5d0a..29aa32cbe6 100644
--- a/website/content/api-docs/kv.mdx
+++ b/website/content/api-docs/kv.mdx
@@ -303,7 +303,7 @@ $ curl \
true
```
-## Methods to Specify Namespace
+## Methods to specify namespace
The key-value store endpoints
support several methods for specifying the namespace of resources
diff --git a/website/content/api-docs/session.mdx b/website/content/api-docs/session.mdx
index 8b4884483a..30dd005a1c 100644
--- a/website/content/api-docs/session.mdx
+++ b/website/content/api-docs/session.mdx
@@ -411,7 +411,7 @@ $ curl \
-> **Note:** Consul may return a TTL value higher than the one specified during session creation. This indicates the server is under high load and is requesting clients renew less often.
-## Methods to Specify Namespace
+## Methods to specify namespace
Session endpoints
support several methods for specifying the namespace of session resources
diff --git a/website/content/commands/acl/templated-policy/index.mdx b/website/content/commands/acl/templated-policy/index.mdx
new file mode 100644
index 0000000000..026cbe3866
--- /dev/null
+++ b/website/content/commands/acl/templated-policy/index.mdx
@@ -0,0 +1,72 @@
+---
+layout: commands
+page_title: 'Commands: ACL Templated Policy'
+description: |
+ The `consul acl templated-policy` command interacts with Consul's ACL templated policies. It exposes commands for reading, previewing and listing templated policies.
+---
+
+# Consul ACL Templated Policies
+
+Command: `consul acl templated-policy`
+
+Use the `acl templated-policy` command to manage templated ACL policies.
+It exposes commands for reading, previewing, and listing templated policies.
+
+You can also manage ACL templated policies using the [/`templated-policies` HTTP API endpoint](/consul/api-docs/acl/templated-policies).
+
+All of the example subcommands require a valid Consul token with the appropriate permissions. Either set the `CONSUL_HTTP_TOKEN` environment variable to the token's secret ID or pass the
+secret ID as the value of the `-token` parameter.
+
+## Usage
+
+Usage: `consul acl templated-policy `
+
+For the exact documentation for your Consul version, run `consul acl templated-policy -h` to view the complete list of subcommands.
+
+```text
+Usage: consul acl templated-policy [options] [args]
+
+ ...
+
+ List all templated policies:
+
+ $ consul acl templated-policy list
+
+ Preview the policy rendered by the ACL templated policy:
+
+ $ consul acl templated-policy preview -name "builtin/service" -var "name:api"
+
+ Read a templated policy with name:
+
+ $ consul acl templated-policy read -name "builtin/service"
+
+ For more examples, ask for subcommand help or view the documentation.
+
+Subcommands:
+ list Lists ACL templated policies
+ preview Preview the policy rendered by the ACL templated policy
+ read Read an ACL Templated Policy
+```
+
+For more information, examples, and usage about a subcommand, click on the name
+of the subcommand in the sidebar.
+
+## Basic examples
+
+Read a ACl templated policy:
+
+```shell-session
+$ consul acl templated-policy read -name "builtin/service"
+```
+
+List all templated policies:
+
+```shell-session
+$ consul acl templated-policy list
+```
+
+Preview a templated policy:
+
+```shell-session
+$ consul acl templated-policy preview -name "builtin/service" -var "name:api"
+```
\ No newline at end of file
diff --git a/website/content/commands/acl/templated-policy/list.mdx b/website/content/commands/acl/templated-policy/list.mdx
new file mode 100644
index 0000000000..bc77f4c3f5
--- /dev/null
+++ b/website/content/commands/acl/templated-policy/list.mdx
@@ -0,0 +1,43 @@
+---
+layout: commands
+page_title: 'Commands: ACL Templated Policy List'
+description: |
+ The `consul acl templated-policy list` command lists names for all ACL templated policies in the cluster.
+---
+
+# Consul ACL Templated Policy List
+
+Command: `consul acl templated-policy list`
+
+Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/templated-policies](/consul/api-docs/acl/templated-policies#list-templated-policies)
+
+Use the `acl templated-policy list` command to list all templated policies.
+
+You must provide an ACL token with `acl:read` permissions to use the `consul all templated-policy list` command.
+
+The command does not support [blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching).
+
+## Usage
+
+Usage: `consul acl templated-policy list`
+
+### Command options
+
+- `-format`: Specifies the output format. You can specify either `pretty` or `json`. The default value is `pretty`.
+
+### API options
+
+@include 'http_api_options_client.mdx'
+
+@include 'http_api_options_server.mdx'
+
+## Example
+
+```shell-session
+$ consul acl templated-policy list
+builtin/dns
+builtin/node
+builtin/nomad-server
+builtin/service
+builtin/workload-identity
+```
\ No newline at end of file
diff --git a/website/content/commands/acl/templated-policy/preview.mdx b/website/content/commands/acl/templated-policy/preview.mdx
new file mode 100644
index 0000000000..7e0c38d165
--- /dev/null
+++ b/website/content/commands/acl/templated-policy/preview.mdx
@@ -0,0 +1,130 @@
+---
+layout: commands
+page_title: 'Commands: ACL Templated Policy Preview'
+description: |
+ The `consul acl templated-policy preview` command previews what resulting generated policy from a templated policy.
+---
+
+# Consul ACL Templated Policy Preview
+
+Command: `consul acl templated-policy preview`
+
+Corresponding HTTP API Endpoint: [\[POST\] /v1/acl/templated-policy/preview/:name](/consul/api-docs/acl/templated-policies#preview-a-templated-policy)
+
+Use the `acl templated-policy preview` command to preview the policy generated from a templated policy.
+
+You must provide an ACL token with `acl:read` permissions to use the `consul all templated-policy preview` command.
+
+The command does not support [blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching).
+
+## Usage
+
+Usage: `consul acl templated-policy preview [options] [args]`
+
+### Command Options
+
+- `-name`: String value that specifies the templated policy name. Use `-var` flag to specify variables when
+ required.
+
+- `var`: String value that specifies templated policy variables. Must be used in combination with `-name`
+ flag to specify required variables. You can use the flag multiple times with different
+ variables. Format is `VariableName:Value`
+
+- `-file`: String value that specifies the path to a file containing templated policies and variables.
+
+- `-format`: Specifies the output format. You can specify either `pretty` or `json` The default value is `pretty`.
+
+### Enterprise options
+
+@include 'http_api_partition_options.mdx'
+
+@include 'http_api_namespace_options.mdx'
+
+### API options
+
+@include 'http_api_options_client.mdx'
+
+@include 'http_api_options_server.mdx'
+
+## Examples
+
+The following examples demonstrate common patterns for using the `acl templated-policy preview` command.
+
+### Preview a templated policy with no required variables
+
+```shell-session
+consul acl templated-policy preview -name "builtin/dns"
+ID: 0a6e6f64655f70726566697...
+Name: synthetic-policy-0a6e6f...
+Description: synthetic policy generated from templated policy: builtin/dns
+Datacenters:
+Rules:
+node_prefix "" {
+ policy = "read"
+}
+service_prefix "" {
+ policy = "read"
+}
+query_prefix "" {
+ policy = "read"
+}
+```
+
+### Preview a templated policy with required variables
+
+In the following example, Consul prints a preview of the policy generated from the `builtin/service` templated policy for the service name `api`.
+
+```shell-session
+consul acl templated-policy preview -name "builtin/service" -var "name:api"
+ID: 0a736572766963652022617...
+Name: synthetic-policy-0a7365...
+Description: synthetic policy generated from templated policy: builtin/service
+Datacenters:
+Rules:
+service "api" {
+ policy = "write"
+}
+service "api-sidecar-proxy" {
+ policy = "write"
+}
+service_prefix "" {
+ policy = "read"
+}
+node_prefix "" {
+ policy = "read"
+}
+```
+
+### Preview a templated policy using a file:
+
+The following example shows a payload request to preview of the policy generated from the `builtin/service` templated policy.
+ The payload includes a variable named `web`, which Consul uses as the service name.
+
+#### Sample payload
+
+```hcl
+TemplatedPolicy "builtin/service" {
+ Name = "web"
+}
+```
+
+```shell-session
+$ consul acl templated-policy -file templated-policy.hcl
+ID: 0a736572766963652022776...
+Name: synthetic-policy-0a7365...
+Description: synthetic policy generated from templated policy: builtin/service
+Datacenters:
+Rules:
+service "web" {
+ policy = "write"
+}
+service "web-sidecar-proxy" {
+ policy = "write"
+}
+service_prefix "" {
+ policy = "read"
+}
+node_prefix "" {
+ policy = "read"
+}
+```
diff --git a/website/content/commands/acl/templated-policy/read.mdx b/website/content/commands/acl/templated-policy/read.mdx
new file mode 100644
index 0000000000..94e461e4ea
--- /dev/null
+++ b/website/content/commands/acl/templated-policy/read.mdx
@@ -0,0 +1,46 @@
+---
+layout: commands
+page_title: 'Commands: ACL Templated Policy Read'
+description: |
+ The `consul acl templated-policy read` command outputs details that make up an ACL templated policy of the specified name.
+---
+
+# Consul ACL Templated Policy Read
+
+Command: `consul acl templated-policy read`
+
+Corresponding HTTP API Endpoint: [\[GET\] /v1/acl/templated-policy/name/:name](/consul/api-docs/acl/templated-policies#read-a-templated-policy-by-name)
+
+The `acl templated-policy read` command reads and displays a templated policies details.
+
+You must provide an ACL token with `acl:read` permissions to use the `consul all templated-policy read` command.
+The command does not support [blocking queries](/consul/api-docs/features/blocking) and [agent caching](/consul/api-docs/features/caching).
+
+## Usage
+
+Usage: `consul acl templated-policy read [options] [args]`
+
+### Command options
+
+- `-name`: String value that specifies the name of the templated policy to read.
+
+- `-format`: String value that specifies the output format. You can specify `pretty` or `json`. The default value is `pretty`.
+
+### API options
+
+@include 'http_api_options_client.mdx'
+
+@include 'http_api_options_server.mdx'
+
+## Examples
+
+Get templated policy details by name:
+
+```shell-session
+$ consul acl templated-policy read -name "builtin/service"
+Name: builtin/service
+Input variables:
+ Name: String - Required - The name of the service.
+Example usage:
+ consul acl token create -templated-policy builtin/service -var name:api
+```
diff --git a/website/content/docs/security/acl/index.mdx b/website/content/docs/security/acl/index.mdx
index 4ee0d18743..f3a2065685 100644
--- a/website/content/docs/security/acl/index.mdx
+++ b/website/content/docs/security/acl/index.mdx
@@ -67,11 +67,23 @@ As a result, roles can provide a more convenient authentication infrastructure t
Refer to the [Roles](/consul/docs/security/acl/acl-roles) topic for additional information.
+## Templated Policies
+
+Templated policies are configuration blocks that you can add to token and role configurations. Consul uses them to generate a policy. Consul links the generated policy to the role or token, which provides the required access to a particular resource.
+
+You can use them during the authorization process to automatically generate a policy for common use-cases, rather than creating multiple identical policies or digging through the permission system to understand permissions.
+
+Refer to the following topics for more details about policies:
+
+- [API documentation for templated policies](/consul/api-docs/acl/templated-policies)
+- [API documentation for roles](/consul/api-docs/acl/roles#sample-payload)
+- [API documentation for tokens](/consul/api-docs/acl/tokens#sample-payload)
+
## Service Identities
Service identities are configuration blocks that you can add to role configurations or specify when linking tokens to policies. You can use them during the authorization process to automatically generate a policy for specific services. The policy is linked to the role or token, allowing the services to be discovered and to discover other healthy service instances in a service mesh.
-Service identities enable you to quickly construct policies for services, rather than creating identical polices for each service.
+Service identities enable you to quickly construct policies for services, rather than creating identical policies for each service.
Refer to the following topics for additional information about service identities:
diff --git a/website/content/docs/upgrading/upgrade-specific.mdx b/website/content/docs/upgrading/upgrade-specific.mdx
index 720f8c9814..19b2e2ab14 100644
--- a/website/content/docs/upgrading/upgrade-specific.mdx
+++ b/website/content/docs/upgrading/upgrade-specific.mdx
@@ -27,6 +27,9 @@ This bug is fixed starting in Consul v1.17.0. Now service-defaults configuration
If you are using non-default partitions and namespaces with Consul-k8s, we recommend explicitly defining these fields for all upstreams in addition to ensuring that accurate
service-defaults are configured in each partition and namespace before upgrading. Doing so ensures that no unexpected protocol changes occur during the upgrade.
+#### ACL tokens with templated policies
+[ACL templated policies](/consul/docs/security/acl#templated-policies) were added to 1.17.0 to simplify obtaining the right permissions for ACL tokens. When performing a [rolling upgrade](/consul/tutorials/datacenter-operations/upgrade-federated-environment#server-rolling-upgrade) and a version of Consul prior to 1.17.x is presented with a token created Consul v1.17.x or newer that contains templated policies, the templated policies field is not recognized. As a result, the token might not have the expected permissions on the older version of Consul.
+
## Consul 1.16.x
### Known issues
diff --git a/website/data/api-docs-nav-data.json b/website/data/api-docs-nav-data.json
index 66d8fa9a94..63109eb5e2 100644
--- a/website/data/api-docs-nav-data.json
+++ b/website/data/api-docs-nav-data.json
@@ -47,6 +47,10 @@
"title": "Policies",
"path": "acl/policies"
},
+ {
+ "title": "Templated Policies",
+ "path": "acl/templated-policies"
+ },
{
"title": "Roles",
"path": "acl/roles"
diff --git a/website/data/commands-nav-data.json b/website/data/commands-nav-data.json
index dd38459a90..bdeaebea3d 100644
--- a/website/data/commands-nav-data.json
+++ b/website/data/commands-nav-data.json
@@ -101,6 +101,27 @@
}
]
},
+ {
+ "title": "templated policy",
+ "routes": [
+ {
+ "title": "Overview",
+ "path": "acl/templated-policy"
+ },
+ {
+ "title": "list",
+ "path": "acl/templated-policy/list"
+ },
+ {
+ "title": "preview",
+ "path": "acl/templated-policy/preview"
+ },
+ {
+ "title": "read",
+ "path": "acl/templated-policy/read"
+ }
+ ]
+ },
{
"title": "role",
"routes": [