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

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