github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/acl/policies.mdx (about)

     1  ---
     2  layout: api
     3  page_title: ACL Policies - HTTP API
     4  description: The /acl/policy endpoints are used to configure and manage ACL policies.
     5  ---
     6  
     7  # ACL Policies HTTP API
     8  
     9  The `/acl/policies` and `/acl/policy/` endpoints are used to manage ACL policies.
    10  For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control).
    11  
    12  ## List Policies
    13  
    14  This endpoint lists all ACL policies. This lists the policies that have been replicated
    15  to the region, and may lag behind the authoritative region.
    16  
    17  | Method | Path            | Produces           |
    18  | ------ | --------------- | ------------------ |
    19  | `GET`  | `/acl/policies` | `application/json` |
    20  
    21  The table below shows this endpoint's support for
    22  [blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
    23  [required ACLs](/api-docs#acls).
    24  
    25  | Blocking Queries | Consistency Modes | ACL Required                                                                                                                     |
    26  | ---------------- | ----------------- | -------------------------------------------------------------------------------------------------------------------------------- |
    27  | `YES`            | `all`             | `management` for all policies.<br />Output when given a non-management token will be limited to the policies on the token itself |
    28  
    29  ### Parameters
    30  
    31  - `prefix` `(string: "")` - Specifies a string to filter ACL policies based on
    32    a name prefix. This is specified as a query string parameter.
    33  
    34  ### Sample Request
    35  
    36  ```shell-session
    37  $ curl \
    38      https://localhost:4646/v1/acl/policies
    39  ```
    40  
    41  ```shell-session
    42  $ curl \
    43      https://localhost:4646/v1/acl/policies?prefix=prod
    44  ```
    45  
    46  ### Sample Response
    47  
    48  ```json
    49  [
    50    {
    51      "Name": "foo",
    52      "Description": "",
    53      "CreateIndex": 12,
    54      "ModifyIndex": 13
    55    }
    56  ]
    57  ```
    58  
    59  ## Create or Update Policy
    60  
    61  This endpoint creates or updates an ACL Policy. This request is always forwarded to the
    62  authoritative region.
    63  
    64  | Method | Path                       | Produces       |
    65  | ------ | -------------------------- | -------------- |
    66  | `POST` | `/acl/policy/:policy_name` | `(empty body)` |
    67  
    68  The table below shows this endpoint's support for
    69  [blocking queries](/api-docs#blocking-queries) and
    70  [required ACLs](/api-docs#acls).
    71  
    72  | Blocking Queries | ACL Required |
    73  | ---------------- | ------------ |
    74  | `NO`             | `management` |
    75  
    76  ### Parameters
    77  
    78  - `Name` `(string: <required>)` - Specifies the name of the policy.
    79    Creates the policy if the name does not exist, otherwise updates the existing policy.
    80  
    81  - `Description` `(string: <optional>)` - Specifies a human readable description.
    82  
    83  - `Rules` `(string: <required>)` - Specifies the Policy rules in HCL or JSON format.
    84  
    85  ### Sample Payload
    86  
    87  ```json
    88  {
    89    "Name": "my-policy",
    90    "Description": "This is a great policy",
    91    "Rules": ""
    92  }
    93  ```
    94  
    95  ### Sample Request
    96  
    97  ```shell-session
    98  $ curl \
    99      --request POST \
   100      --data @payload.json \
   101      https://localhost:4646/v1/acl/policy/my-policy
   102  ```
   103  
   104  ## Read Policy
   105  
   106  This endpoint reads an ACL policy with the given name. This queries the policy that have been
   107  replicated to the region, and may lag behind the authoritative region.
   108  
   109  | Method | Path                       | Produces           |
   110  | ------ | -------------------------- | ------------------ |
   111  | `GET`  | `/acl/policy/:policy_name` | `application/json` |
   112  
   113  The table below shows this endpoint's support for
   114  [blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
   115  [required ACLs](/api-docs#acls).
   116  
   117  | Blocking Queries | Consistency Modes | ACL Required                                |
   118  | ---------------- | ----------------- | ------------------------------------------- |
   119  | `YES`            | `all`             | `management` or token with access to policy |
   120  
   121  ### Sample Request
   122  
   123  ```shell-session
   124  $ curl \
   125      https://localhost:4646/v1/acl/policy/foo
   126  ```
   127  
   128  ### Sample Response
   129  
   130  ```json
   131  {
   132    "Name": "foo",
   133    "Rules": "",
   134    "Description": "",
   135    "CreateIndex": 12,
   136    "ModifyIndex": 13
   137  }
   138  ```
   139  
   140  ## Delete Policy
   141  
   142  This endpoint deletes the named ACL policy. This request is always forwarded to the
   143  authoritative region.
   144  
   145  | Method   | Path                       | Produces       |
   146  | -------- | -------------------------- | -------------- |
   147  | `DELETE` | `/acl/policy/:policy_name` | `(empty body)` |
   148  
   149  The table below shows this endpoint's support for
   150  [blocking queries](/api-docs#blocking-queries) and
   151  [required ACLs](/api-docs#acls).
   152  
   153  | Blocking Queries | ACL Required |
   154  | ---------------- | ------------ |
   155  | `NO`             | `management` |
   156  
   157  ### Parameters
   158  
   159  - `policy_name` `(string: <required>)` - Specifies the policy name to delete.
   160  
   161  ### Sample Request
   162  
   163  ```shell-session
   164  $ curl \
   165      --request DELETE \
   166      https://localhost:4646/v1/acl/policy/foo
   167  ```