mirror of https://github.com/hashicorp/consul
Ronald Ekambi
1 year ago
parent
809bf1deb8
commit
694d05555e
@ -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.
|
||||
@ -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"
|
||||
```
|
||||
@ -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
|
||||
```
|
||||
@ -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"
|
||||
}
|
||||
```
|
||||
@ -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
|
||||
```
|
||||
Loading…
Reference in new issue