github.com/Ilhicas/nomad@v1.0.4-0.20210304152020-e86851182bc3/website/content/api-docs/sentinel-policies.mdx (about)

     1  ---
     2  layout: api
     3  page_title: Sentinel Policies - HTTP API
     4  sidebar_title: Sentinel Policies
     5  description: >-
     6    The /sentinel/policy/ endpoints are used to configure and manage Sentinel
     7    policies.
     8  ---
     9  
    10  # Sentinel Policies HTTP API
    11  
    12  The `/sentinel/policies` and `/sentinel/policy/` endpoints are used to manage Sentinel policies.
    13  For more details about Sentinel policies, please see the [Sentinel Policy Guide](https://learn.hashicorp.com/tutorials/nomad/sentinel).
    14  
    15  Sentinel endpoints are only available when ACLs are enabled. For more details about ACLs, please see the [ACL Guide](https://learn.hashicorp.com/collections/nomad/access-control).
    16  
    17  <EnterpriseAlert>
    18  This API endpoint and functionality only exists in
    19  Nomad Enterprise. This is not present in the open source version of Nomad.
    20  </EnterpriseAlert>
    21  
    22  ## List Policies
    23  
    24  This endpoint lists all Sentinel policies. This lists the policies that have been replicated
    25  to the region, and may lag behind the authoritative region.
    26  
    27  | Method | Path                 | Produces           |
    28  | ------ | -------------------- | ------------------ |
    29  | `GET`  | `/sentinel/policies` | `application/json` |
    30  
    31  The table below shows this endpoint's support for
    32  [blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
    33  [required ACLs](/api-docs#acls).
    34  
    35  | Blocking Queries | Consistency Modes | ACL Required |
    36  | ---------------- | ----------------- | ------------ |
    37  | `YES`            | `all`             | `management` |
    38  
    39  ### Sample Request
    40  
    41  ```shell-session
    42  $ curl \
    43      https://localhost:4646/v1/sentinel/policies
    44  ```
    45  
    46  ### Sample Response
    47  
    48  ```json
    49  [
    50    {
    51      "Name": "foo",
    52      "Description": "test policy",
    53      "Scope": "submit-job",
    54      "EnforcementLevel": "advisory",
    55      "Hash": "CIs8aNX5OfFvo4D7ihWcQSexEJpHp+Za+dHSncVx5+8=",
    56      "CreateIndex": 8,
    57      "ModifyIndex": 8
    58    }
    59  ]
    60  ```
    61  
    62  ## Create or Update Policy
    63  
    64  This endpoint creates or updates an Sentinel Policy. This request is always forwarded to the
    65  authoritative region.
    66  
    67  | Method | Path                            | Produces       |
    68  | ------ | ------------------------------- | -------------- |
    69  | `POST` | `/sentinel/policy/:policy_name` | `(empty body)` |
    70  
    71  The table below shows this endpoint's support for
    72  [blocking queries](/api-docs#blocking-queries) and
    73  [required ACLs](/api-docs#acls).
    74  
    75  | Blocking Queries | ACL Required |
    76  | ---------------- | ------------ |
    77  | `NO`             | `management` |
    78  
    79  ### Parameters
    80  
    81  - `Name` `(string: <required>)` - Specifies the name of the policy.
    82    Creates the policy if the name does not exist, otherwise updates the existing policy.
    83  
    84  - `Description` `(string: <optional>)` - Specifies a human readable description.
    85  
    86  - `Scope` `(string: <required>)` - Specifies the scope of when this policy applies. Only `submit-job` is currently supported.
    87  
    88  - `EnforcementLevel` `(string: <required>)` - Specifies the enforcement level of the policy. Can be `advisory` which warns on failure,
    89    `hard-mandatory` which prevents an operation on failure, and `soft-mandatory` which is like `hard-mandatory` but can be overridden.
    90  
    91  - `Policy` `(string: <required>)` - Specifies the Sentinel policy itself.
    92  
    93  ### Sample Payload
    94  
    95  ```json
    96  {
    97    "Name": "my-policy",
    98    "Description": "This is a great policy",
    99    "Scope": "submit-job",
   100    "EnforcementLevel": "advisory",
   101    "Policy": "main = rule { true }"
   102  }
   103  ```
   104  
   105  ### Sample Request
   106  
   107  ```shell-session
   108  $ curl \
   109      --request POST \
   110      --data @payload.json \
   111      https://localhost:4646/v1/sentinel/policy/my-policy
   112  ```
   113  
   114  ## Read Policy
   115  
   116  This endpoint reads a Sentinel policy with the given name. This queries the policy that have been
   117  replicated to the region, and may lag behind the authoritative region.
   118  
   119  | Method | Path                            | Produces           |
   120  | ------ | ------------------------------- | ------------------ |
   121  | `GET`  | `/sentinel/policy/:policy_name` | `application/json` |
   122  
   123  The table below shows this endpoint's support for
   124  [blocking queries](/api-docs#blocking-queries), [consistency modes](/api-docs#consistency-modes) and
   125  [required ACLs](/api-docs#acls).
   126  
   127  | Blocking Queries | Consistency Modes | ACL Required |
   128  | ---------------- | ----------------- | ------------ |
   129  | `YES`            | `all`             | `management` |
   130  
   131  ### Sample Request
   132  
   133  ```shell-session
   134  $ curl \
   135      https://localhost:4646/v1/sentinel/policy/foo
   136  ```
   137  
   138  ### Sample Response
   139  
   140  ```json
   141  {
   142    "Name": "foo",
   143    "Description": "test policy",
   144    "Scope": "submit-job",
   145    "EnforcementLevel": "advisory",
   146    "Policy": "main = rule { true }\n",
   147    "Hash": "CIs8aNX5OfFvo4D7ihWcQSexEJpHp+Za+dHSncVx5+8=",
   148    "CreateIndex": 8,
   149    "ModifyIndex": 8
   150  }
   151  ```
   152  
   153  ## Delete Policy
   154  
   155  This endpoint deletes the named Sentinel policy. This request is always forwarded to the
   156  authoritative region.
   157  
   158  | Method   | Path                            | Produces       |
   159  | -------- | ------------------------------- | -------------- |
   160  | `DELETE` | `/sentinel/policy/:policy_name` | `(empty body)` |
   161  
   162  The table below shows this endpoint's support for
   163  [blocking queries](/api-docs#blocking-queries) and
   164  [required ACLs](/api-docs#acls).
   165  
   166  | Blocking Queries | ACL Required |
   167  | ---------------- | ------------ |
   168  | `NO`             | `management` |
   169  
   170  ### Parameters
   171  
   172  - `policy_name` `(string: <required>)` - Specifies the policy name to delete.
   173  
   174  ### Sample Request
   175  
   176  ```shell-session
   177  $ curl \
   178      --request DELETE \
   179      https://localhost:4646/v1/sentinel/policy/foo
   180  ```