News HashiCorp to join IBM to accelerate multi-cloud automation. Read the blog →
Consul
Consul Home

ACL Templated Policy HTTP API

The /acl/templated-policy endpoints read, preview, and list ACL templated policies in Consul.

For more information on how to setup ACLs, refer to the following resources:

Read a templated policy by name

This endpoint reads an ACL policy with the given ID.

MethodPathProduces
GET/acl/templated-policy/name/:nameapplication/json

The following table shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneacl:read

The corresponding CLI command is consul acl templated-policy read -name=<string>.

Path parameters

  • name (string: <required>) - Specifies the name of the ACL policy to read.

Sample request

$ curl --request GET http://127.0.0.1:8500/v1/acl/templated-policy/name/builtin/service

Sample response

{
  "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.

MethodPathProduces
POST/acl/templated-policy/preview/:nameapplication/json

The following table shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
NOnonenoneacl:read

The corresponding CLI command is consul acl templated-policy preview.

Path parameters

  • name (string: <required>) - Specifies the name of the ACL templated policy to preview.

Query parameters

JSON request body schema

  • Name (string: <optional>) - Specifies the value of the name variable in the templated policy variables.

Sample payload

{
  "Name": "api"
}

Sample request

$ curl --request POST \
    --data @payload.json \
    http://127.0.0.1:8500/v1/acl-templated/preview/builtin/service

Sample response

{
    "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.

MethodPathProduces
GET/acl/templated-policiesapplication/json

The following table shows this endpoint's support for blocking queries, consistency modes, agent caching, and required ACLs.

Blocking QueriesConsistency ModesAgent CachingACL Required
Nononenoneacl:read

The corresponding CLI command is consul acl templated-policy list.

Query parameters

This endpoint does not accept query parameters.

Sample Request

$ curl --request GET http://127.0.0.1:8500/v1/acl/templated-policies

Sample response

{
  "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 Enterprise

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 and update endpoints
  2. ns query parameter.
  3. X-Consul-Namespace request header.
  4. Namespace inherited from the namespace of the request's ACL token.
  5. The default namespace.
Edit this page on GitHub