github
/
consul
mirror of https://github.com/hashicorp/consul
1
0
Fork 0
Code Issues Projects Releases Wiki Activity

[NET-5327] Templated policies api/cli docs

pull/19270/head
Ronald Ekambi 2023-10-16 15:50:54 -04:00
parent 809bf1deb8
commit 694d05555e
25 changed files with 736 additions and 37 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

8
website/content/api-docs/acl/auth-methods.mdx
View File

@ -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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Auth method create, read, update, and delete endpoints
support several methods for specifying the namespace of the auth method resource.

99
website/content/api-docs/acl/binding-rules.mdx
View File

@ -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: <required>)` - 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.
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@ -78,7 +80,7 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@ -98,7 +100,7 @@ The corresponding CLI command is [`consul acl binding-rule create`](/consul/comm
</CodeBlockConfig>
- `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
```
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
```json
{
"AccessorID": "<token accessor ID>",
"SecretID": "<token secret ID>",
"TemplatedPolicies": [
{
"TemplateName": "<template name>",
"TemplateVariables": {
"Name": "<name>"
}
}
]
}
```
</CodeBlockConfig>
- `BindName` `(string: <required>)` - 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` `(<ACLTemplatedPolicyVariables>)` - 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: "")` <EnterpriseAlert inline /> - 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: <required>)` - 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.
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@ -291,7 +330,7 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
@ -311,7 +350,7 @@ The corresponding CLI command is [`consul acl binding-rule update`](/consul/comm
</CodeBlockConfig>
- `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
```
</CodeBlockConfig>
- `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.
<CodeBlockConfig heading="Equivalent payload for Consul token API endpoint">
```json
{
"AccessorID": "<token accessor ID>",
"SecretID": "<token secret ID>",
"TemplatedPolicies": [
{
"TemplateName": "<template name>",
"TemplateVariables": {
"Name": "<name>"
}
}
]
}
```
</CodeBlockConfig>
- `BindName` `(string: <required>)` - 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` `(<ACLTemplatedPolicyVariables>)` - 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: "")` <EnterpriseAlert inline /> - 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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Binding rule create, read, update, and delete endpoints
support several methods for specifying the namespace of the auth method resource

8
website/content/api-docs/acl/index.mdx
View File

@ -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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Some ACL endpoints support several methods for specifying the namespace of the resource
with the following order of precedence:

2
website/content/api-docs/acl/policies.mdx
View File

@ -380,7 +380,7 @@ retrieved by the [policy reading endpoint](#read-a-policy)
]
```
## Methods to Specify Namespace <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
ACL policy endpoints
support several methods for specifying the namespace of the ACL policy resources

81
website/content/api-docs/acl/roles.mdx
View File

@ -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: <required>)` - The templated policy name.
- `TemplateVariables` `(map of strings|maps: <optional>)` - The templated policy variables. Not all templated policies
require variables.
- `ServiceIdentities` `(array<ServiceIdentity>)` - 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: <required>)` - 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<NodeIdentity>)` - 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: <required>)` - 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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
ACL role endpoints
support several methods for specifying the namespace of the ACL role resources

189
website/content/api-docs/acl/templated-policies.mdx Normal file
View File

@ -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=<string>`](/consul/commands/acl/templated-policy/read#name).
### Path parameters
- `name` `(string: <required>)` - 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: <required>)` - Specifies the name of the ACL templated policy to preview.
### Query parameters
- `ns` `(string: "")` <EnterpriseAlert inline /> - 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: <optional>)` - 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 <EnterpriseAlert inline />
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.

33
website/content/api-docs/acl/tokens.mdx
View File

@ -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: <required>)` - The templated policy name.
- `TemplateVariables` `(map of strings|maps: <optional>)` - The templated policy variables. Not all templated policies
require variables.
- `ServiceIdentities` `(array<ServiceIdentity>)` - 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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
ACL token endpoints
support several methods for specifying the namespace of the ACL token resources

2
website/content/api-docs/agent/check.mdx
View File

@ -523,7 +523,7 @@ $ curl \
http://127.0.0.1:8500/v1/agent/check/update/my-check-id
```
## Methods to Specify Namespace <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Local agent health check endpoints
support several methods for specifying the namespace of the check resources

2
website/content/api-docs/agent/connect.mdx
View File

@ -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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Local agent service mesh endpoints
support several methods for specifying the namespace of resources

2
website/content/api-docs/agent/service.mdx
View File

@ -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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Local agent service endpoints
support several methods for specifying the namespace of service resources

2
website/content/api-docs/catalog.mdx
View File

@ -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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Catalog endpoints
support several methods for specifying the namespace of resources

2
website/content/api-docs/config.mdx
View File

@ -325,7 +325,7 @@ $ curl \
http://127.0.0.1:8500/v1/config/service-defaults/web
```
## Methods to Specify Namespace <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Config endpoints
support several methods for specifying the namespace of configuration entry resources

2
website/content/api-docs/connect/intentions.mdx
View File

@ -668,7 +668,7 @@ $ curl \
}
```
## Methods to Specify Namespace <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Intention endpoints
support several methods for specifying the namespace of intention resources

2
website/content/api-docs/discovery-chain.mdx
View File

@ -556,7 +556,7 @@ Response:
}
```
## Methods to Specify Namespace <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
The discovery chain endpoint
supports several methods for specifying the namespace to use as the basis of discovery chain compilation

2
website/content/api-docs/health.mdx
View File

@ -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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
The health endpoints
support several methods for specifying the namespace of resources

2
website/content/api-docs/kv.mdx
View File

@ -303,7 +303,7 @@ $ curl \
true
```
## Methods to Specify Namespace <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
The key-value store endpoints
support several methods for specifying the namespace of resources

2
website/content/api-docs/session.mdx
View File

@ -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 <EnterpriseAlert inline />
## Methods to specify namespace <EnterpriseAlert inline />
Session endpoints
support several methods for specifying the namespace of session resources

72
website/content/commands/acl/templated-policy/index.mdx Normal file
View File

@ -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 <subcommand>`
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 <subcommand> [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"
```

43
website/content/commands/acl/templated-policy/list.mdx Normal file
View File

@ -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
```

130
website/content/commands/acl/templated-policy/preview.mdx Normal file
View File

@ -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"
}
```

46
website/content/commands/acl/templated-policy/read.mdx Normal file
View File

@ -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
```

14
website/content/docs/security/acl/index.mdx
View File

@ -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:

3
website/content/docs/upgrading/upgrade-specific.mdx
View File

@ -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

4
website/data/api-docs-nav-data.json
View File

@ -47,6 +47,10 @@
"title": "Policies",
"path": "acl/policies"
},
{
"title": "Templated Policies",
"path": "acl/templated-policies"
},
{
"title": "Roles",
"path": "acl/roles"

21
website/data/commands-nav-data.json
View File

@ -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": [