github.com/smintz/nomad@v0.8.3/website/source/api/acl-policies.html.md (about)

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