open-nomad/website/content/api-docs/acl/policies.mdx

Ignoring revisions in .git-blame-ignore-revs. Click here to bypass and see the normal blame view.

168 lines
4.7 KiB
Plaintext
Raw Normal View History

---
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.
---
# ACL Policies HTTP API
The `/acl/policies` and `/acl/policy/` endpoints are used to manage ACL policies.
For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control).
## 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` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
[required ACLs](/api-docs#acls).
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 |
### Parameters
- `prefix` `(string: "")` - Specifies a string to filter ACL policies based on
a name prefix. This is specified as a query string parameter.
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
https://localhost:4646/v1/acl/policies
```
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
https://localhost:4646/v1/acl/policies?prefix=prod
```
### Sample Response
```json
[
{
"Name": "foo",
"Description": "",
"CreateIndex": 12,
2020-02-06 23:45:31 +00:00
"ModifyIndex": 13
}
]
```
## 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)` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### 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.
### Sample Payload
```json
{
2020-02-06 23:45:31 +00:00
"Name": "my-policy",
"Description": "This is a great policy",
"Rules": ""
}
```
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
--request POST \
--data @payload.json \
https://localhost:4646/v1/acl/policy/my-policy
```
## 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` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
[required ACLs](/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | Consistency Modes | ACL Required |
| ---------------- | ----------------- | ------------------------------------------- |
| `YES` | `all` | `management` or token with access to policy |
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
https://localhost:4646/v1/acl/policy/foo
```
### 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)` |
The table below shows this endpoint's support for
[blocking queries](/api-docs#blocking-queries) and
[required ACLs](/api-docs#acls).
2020-02-06 23:45:31 +00:00
| Blocking Queries | ACL Required |
| ---------------- | ------------ |
| `NO` | `management` |
### Parameters
- `policy_name` `(string: <required>)` - Specifies the policy name to delete.
### Sample Request
2020-05-01 20:02:21 +00:00
```shell-session
$ curl \
--request DELETE \
https://localhost:4646/v1/acl/policy/foo
```