2017-08-23 23:56:05 +00:00
|
|
|
---
|
|
|
|
layout: api
|
|
|
|
page_title: ACL Policies - HTTP API
|
2020-02-06 23:45:31 +00:00
|
|
|
description: The /acl/policy endpoints are used to configure and manage ACL policies.
|
2017-08-23 23:56:05 +00:00
|
|
|
---
|
|
|
|
|
|
|
|
# ACL Policies HTTP API
|
|
|
|
|
|
|
|
The `/acl/policies` and `/acl/policy/` endpoints are used to manage ACL policies.
|
2023-01-25 17:31:14 +00:00
|
|
|
For more details about ACLs, please see the [ACL Guide](/nomad/tutorials/access-control).
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
## List Policies
|
|
|
|
|
|
|
|
This endpoint lists all ACL policies. This lists the policies that have been replicated
|
|
|
|
to the region, and may lag behind the authoritative region.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | --------------- | ------------------ |
|
|
|
|
| `GET` | `/acl/policies` | `application/json` |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-08-23 23:56:05 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
| ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
|
|
|
|
| `YES` | `all` | `management` for all policies.<br />Output when given a non-management token will be limited to the policies on the token itself |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
2019-10-08 18:05:12 +00:00
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `prefix` `(string: "")` - Specifies a string to filter ACL policies based on
|
2019-10-11 14:28:44 +00:00
|
|
|
a name prefix. This is specified as a query string parameter.
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2017-08-23 23:56:05 +00:00
|
|
|
$ curl \
|
2018-01-29 16:27:52 +00:00
|
|
|
https://localhost:4646/v1/acl/policies
|
2017-08-23 23:56:05 +00:00
|
|
|
```
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2019-10-08 18:05:12 +00:00
|
|
|
$ curl \
|
|
|
|
https://localhost:4646/v1/acl/policies?prefix=prod
|
|
|
|
```
|
|
|
|
|
2017-08-23 23:56:05 +00:00
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
[
|
|
|
|
{
|
|
|
|
"Name": "foo",
|
|
|
|
"Description": "",
|
|
|
|
"CreateIndex": 12,
|
2020-02-06 23:45:31 +00:00
|
|
|
"ModifyIndex": 13
|
2017-08-23 23:56:05 +00:00
|
|
|
}
|
|
|
|
]
|
|
|
|
```
|
|
|
|
|
|
|
|
## Create or Update Policy
|
|
|
|
|
|
|
|
This endpoint creates or updates an ACL Policy. This request is always forwarded to the
|
|
|
|
authoritative region.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | -------------------------- | -------------- |
|
|
|
|
| `POST` | `/acl/policy/:policy_name` | `(empty body)` |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-08-23 23:56:05 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------ |
|
|
|
|
| `NO` | `management` |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `Name` `(string: <required>)` - Specifies the name of the policy.
|
|
|
|
Creates the policy if the name does not exist, otherwise updates the existing policy.
|
|
|
|
|
|
|
|
- `Description` `(string: <optional>)` - Specifies a human readable description.
|
|
|
|
|
|
|
|
- `Rules` `(string: <required>)` - Specifies the Policy rules in HCL or JSON format.
|
|
|
|
|
2023-04-19 15:12:58 +00:00
|
|
|
- `JobACL` `(JobACL: <optional>)` - Associates the policy with a given
|
|
|
|
namespace, job, group, or task. Refer to [Workload Associated ACL
|
|
|
|
Policies][concepts_workload_identity_acl] for more information.
|
|
|
|
|
|
|
|
- `Namespace` `(string: <optional>)` - The namespace to attach the policy.
|
|
|
|
Required if `JobID` is set.
|
|
|
|
|
|
|
|
- `JobID` `(string: <optional>)` - The job to attach to the policy. Required
|
|
|
|
if `Group` is set.
|
|
|
|
|
|
|
|
- `Group` `(string: <optional>)` - The group to attach to the policy.
|
|
|
|
Required if `Task` is set.
|
|
|
|
|
|
|
|
- `Task` `(string: <optional>)` - The task to attach to the policy.
|
|
|
|
|
2017-08-23 23:56:05 +00:00
|
|
|
### Sample Payload
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
2020-02-06 23:45:31 +00:00
|
|
|
"Name": "my-policy",
|
|
|
|
"Description": "This is a great policy",
|
2023-04-19 15:12:58 +00:00
|
|
|
"Rules": "",
|
|
|
|
"JobACL": {
|
|
|
|
"Namespace": "default",
|
|
|
|
"JobID": "example"
|
|
|
|
}
|
2017-08-23 23:56:05 +00:00
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2017-08-23 23:56:05 +00:00
|
|
|
$ curl \
|
|
|
|
--request POST \
|
|
|
|
--data @payload.json \
|
2018-01-29 16:27:52 +00:00
|
|
|
https://localhost:4646/v1/acl/policy/my-policy
|
2017-08-23 23:56:05 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
## Read Policy
|
|
|
|
|
|
|
|
This endpoint reads an ACL policy with the given name. This queries the policy that have been
|
|
|
|
replicated to the region, and may lag behind the authoritative region.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| ------ | -------------------------- | ------------------ |
|
|
|
|
| `GET` | `/acl/policy/:policy_name` | `application/json` |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries), [consistency modes](/nomad/api-docs#consistency-modes) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-08-23 23:56:05 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Blocking Queries | Consistency Modes | ACL Required |
|
|
|
|
| ---------------- | ----------------- | ------------------------------------------- |
|
2017-10-13 18:30:27 +00:00
|
|
|
| `YES` | `all` | `management` or token with access to policy |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2017-08-23 23:56:05 +00:00
|
|
|
$ curl \
|
2018-01-29 16:27:52 +00:00
|
|
|
https://localhost:4646/v1/acl/policy/foo
|
2017-08-23 23:56:05 +00:00
|
|
|
```
|
|
|
|
|
|
|
|
### Sample Response
|
|
|
|
|
|
|
|
```json
|
|
|
|
{
|
|
|
|
"Name": "foo",
|
|
|
|
"Rules": "",
|
|
|
|
"Description": "",
|
|
|
|
"CreateIndex": 12,
|
|
|
|
"ModifyIndex": 13
|
|
|
|
}
|
|
|
|
```
|
|
|
|
|
|
|
|
## Delete Policy
|
|
|
|
|
|
|
|
This endpoint deletes the named ACL policy. This request is always forwarded to the
|
|
|
|
authoritative region.
|
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Method | Path | Produces |
|
|
|
|
| -------- | -------------------------- | -------------- |
|
|
|
|
| `DELETE` | `/acl/policy/:policy_name` | `(empty body)` |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
The table below shows this endpoint's support for
|
2023-01-25 17:31:14 +00:00
|
|
|
[blocking queries](/nomad/api-docs#blocking-queries) and
|
|
|
|
[required ACLs](/nomad/api-docs#acls).
|
2017-08-23 23:56:05 +00:00
|
|
|
|
2020-02-06 23:45:31 +00:00
|
|
|
| Blocking Queries | ACL Required |
|
|
|
|
| ---------------- | ------------ |
|
|
|
|
| `NO` | `management` |
|
2017-08-23 23:56:05 +00:00
|
|
|
|
|
|
|
### Parameters
|
|
|
|
|
|
|
|
- `policy_name` `(string: <required>)` - Specifies the policy name to delete.
|
|
|
|
|
|
|
|
### Sample Request
|
|
|
|
|
2020-05-01 20:02:21 +00:00
|
|
|
```shell-session
|
2017-08-23 23:56:05 +00:00
|
|
|
$ curl \
|
|
|
|
--request DELETE \
|
2018-01-29 16:27:52 +00:00
|
|
|
https://localhost:4646/v1/acl/policy/foo
|
2017-08-23 23:56:05 +00:00
|
|
|
```
|
2023-04-19 15:12:58 +00:00
|
|
|
|
|
|
|
[concepts_workload_identity_acl]: /nomad/docs/concepts/workload-identity#workload-associated-acl-policies
|