mirror of https://github.com/hashicorp/consul
191 lines
8.2 KiB
Markdown
191 lines
8.2 KiB
Markdown
---
|
|
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.
|
|
|
|
@include 'http-api-body-options-partition.mdx'
|
|
|
|
### 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. |