status-im
/
consul
mirror of https://github.com/status-im/consul.git
2
0
Fork 0
Code Issues Projects Releases Wiki Activity
consul/website/content/api-docs/acl/templated-policies.mdx

191 lines
8.2 KiB
Plaintext
Raw Normal View History

[NET-5327] Templated policies api/cli docs (#19270)
2023-10-23 11:41:24 +00:00
---
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.
DOCS: CE-556 Add partition parameter to API endpoint docs (#21374) * CD-556 rename partition partial that's only used in CLI Update CLI pages for partial rename API: Add partial for partition as body option API: Add partial for partition as query parameter Update API peering and members pages * acl/auth-methods.mdx Update partition partials to be generic * binding-rules.mdx, policies.mdx * roles.mdx, templated-policies.mdx * tokens.mdx, catalog.mdx, config.mdx, intentions.mdx * service.mdx, exported-services.mdx, kv.mdx, namespaces.mdx * Apply suggestions from code review Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> * Add partial to acl/auth-methods.mdx Fix headings indent in a few files. * Update website/content/api-docs/acl/auth-methods.mdx Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com> --------- Co-authored-by: Jeff Boruszak <104028618+boruszak@users.noreply.github.com>
2024-07-18 17:02:45 +00:00
@include 'http-api-body-options-partition.mdx'
[NET-5327] Templated policies api/cli docs (#19270)
2023-10-23 11:41:24 +00:00
### 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.