github.com/iqoqo/nomad@v0.11.3-0.20200911112621-d7021c74d101/website/pages/api-docs/acl-policies.mdx (about)

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