github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/api-docs/variables.mdx (about) 1 --- 2 layout: api 3 page_title: Variables - HTTP API 4 description: The /var endpoints are used to query for and interact with variables. 5 --- 6 7 # Variables HTTP API 8 9 The `/var` and `/vars` endpoints are used to query for and interact with 10 variables. 11 12 See the [Variables] documentation for information how these capabilities are 13 used. For a CLI to perform these operations manually, please see the 14 documentation for the [`nomad var`] commands. 15 16 ## List Variables 17 18 This endpoint lists all variables. Note this API returns only variable metadata 19 without decrypting the variable body. 20 21 | Method | Path | Produces | 22 |--------|------------|--------------------| 23 | `GET` | `/v1/vars` | `application/json` | 24 25 The table below shows this endpoint's support for [blocking queries] and 26 [required ACLs]. 27 28 | Blocking Queries | ACL Required | 29 |------------------|-----------------------------------------------------------------------------------------| 30 | `YES` | `namespace:* variables:list`<br />The list capability on the namespace and path queried | 31 32 ### Parameters 33 34 - `prefix` `(string: "")` - Specifies a string to filter variables on based on 35 an index prefix. This is specified as a query string parameter. 36 37 - `next_token` `(string: "")` - This endpoint supports paging. The `next_token` 38 parameter accepts a string which identifies the next expected job. This value 39 can be obtained from the `X-Nomad-NextToken` header from the previous 40 response. 41 42 - `per_page` `(int: 0)` - Specifies a maximum number of variables to return for 43 this request. If omitted, the response is not paginated. The value of the 44 `X-Nomad-NextToken` header of the last response can be used as the 45 `next_token` of the next request to fetch additional pages. 46 47 - `filter` `(string: "")` - Specifies the [expression](/api-docs#filtering) used 48 to filter the results. Consider using pagination or a query parameter to 49 reduce resources used to serve the request. 50 51 - `namespace` `(string: "default")` - Specifies the target namespace. Specifying 52 `*` will return all variables across all the authorized namespaces. 53 54 ### Sample Request 55 56 ```shell-session 57 $ curl \ 58 https://localhost:4646/v1/vars?namespace=prod&prefix=example 59 ``` 60 61 ### Sample Response 62 63 ```json 64 [ 65 { 66 "Namespace": "prod", 67 "Path": "example/first", 68 "CreateIndex": 1457, 69 "ModifyIndex": 1457, 70 "CreateTime": 1662061225600373000, 71 "ModifyTime": 1662061225600373000 72 }, 73 { 74 "Namespace": "prod", 75 "Path": "example/second", 76 "CreateIndex": 800, 77 "ModifyIndex": 1000, 78 "CreateTime": 1662061717905426000, 79 "ModifyTime": 1662062162982630000 80 } 81 ] 82 ``` 83 84 ## Read Variable 85 86 This endpoint reads a specific variable by path. This API returns the decrypted 87 variable body. 88 89 | Method | Path | Produces | 90 |--------|--------------------|--------------------| 91 | `GET` | `/v1/var/:var_path` | `application/json` | 92 93 The table below shows this endpoint's support for [blocking queries] and 94 [required ACLs]. 95 96 | Blocking Queries | ACL Required | 97 |------------------|--------------------------------------------------------------------------------------------| 98 | `YES` | `namespace:* variables:read`<br />The read capability on the variable's namespace and path | 99 100 ### Parameters 101 102 - `namespace` `(string: "default")` - Specifies the variable's namespace. 103 104 ### Sample Request 105 106 ```shell-session 107 $ curl \ 108 https://localhost:4646/v1/var/example/first?namespace=prod 109 ``` 110 111 ### Sample Response 112 113 ```json 114 { 115 "Namespace": "prod", 116 "Path": "example/first", 117 "CreateIndex": 1457, 118 "ModifyIndex": 1457, 119 "CreateTime": 1662061225600373000, 120 "ModifyTime": 1662061225600373000 121 "Items": { 122 "user": "me", 123 "password": "passw0rd1" 124 } 125 } 126 ``` 127 128 ## Create Variable 129 130 This endpoint creates or updates a variable. 131 132 | Method | Path | Produces | 133 |--------|---------------------|--------------------| 134 | `PUT` | `/v1/var/:var_path` | `application/json` | 135 136 The table below shows this endpoint's support for [blocking queries] and 137 [required ACLs]. 138 139 | Blocking Queries | ACL Required | 140 |------------------|---------------------------------------------------------------------------------------------| 141 | `NO` | `namespace:* variables:write`<br />The read capability on the variable's namespace and path | 142 143 ### Parameters 144 145 - `namespace` `(string: "default")` - Specifies the variable's namespace. If 146 set, this will override the request body. 147 148 - `cas` `(int: <unset>)` - If set, the variable will only be updated if the 149 `cas` value matches the current variables `ModifyIndex`. If the `cas` value is 150 0, the variable is only created if it does not already exist. This paradigm 151 allows check-and-set style updates. 152 153 ## Restrictions 154 155 Variable paths are restricted to [RFC3986][] URL-safe characters that don't 156 conflict with the use of the characters `@` and `.` in template blocks. This 157 includes alphanumeric characters and the special characters `-`, `_`, `~`, and 158 `/`. Paths may be up to 128 bytes long. The following regex matches the allowed 159 paths: `^[a-zA-Z0-9-_~/]{1,128}$` 160 161 Variable items are restricted to 16KiB in size. This limit is calculated by 162 taking the sum of the length in bytes of all of the unencrypted keys and values 163 in the `Items` field. 164 165 ### Sample Request 166 167 ```shell-session 168 $ curl \ 169 -XPUT -d@spec.nsv.json \ 170 https://localhost:4646/v1/var/example/first 171 ``` 172 173 ### Sample Payload 174 175 ```json 176 { 177 "Namespace": "prod", 178 "Path": "example/first", 179 "CreateIndex": 1457, 180 "ModifyIndex": 1457, 181 "CreateTime": 1662061225600373000, 182 "ModifyTime": 1662061225600373000, 183 "Items": { 184 "user": "me", 185 "password": "passw0rd1" 186 } 187 } 188 ``` 189 190 ### Sample Response 191 192 The response body returns the created or updated variable along with metadata 193 created by the server: 194 195 ```json 196 { 197 "Namespace": "prod", 198 "Path": "example/first", 199 "CreateIndex": 1457, 200 "ModifyIndex": 1457, 201 "CreateTime": 1662061225600373000, 202 "ModifyTime": 1662061225600373000, 203 "Items": { 204 "user": "me", 205 "password": "passw0rd1" 206 } 207 } 208 ``` 209 210 ### Sample Response for Conflict 211 212 In the case of a compare-and-set conflict, the API will return HTTP error code 213 409 and a response body showing the conflicting variable. If the provided ACL 214 token does not also have `read` permissions to the variable path, the response 215 will include only metadata and not the `Items` field: 216 217 ```json 218 { 219 "Namespace": "prod", 220 "Path": "example/first", 221 "CreateIndex": 1457, 222 "ModifyIndex": 1457, 223 "CreateTime": 1662061225600373000, 224 "ModifyTime": 1662061225600373000, 225 "Items": { 226 "user": "me", 227 "password": "passw0rd1" 228 } 229 } 230 ``` 231 232 233 ## Delete Variable 234 235 This endpoint deletes a specific variable by path. 236 237 | Method | Path | Produces | 238 |--------|--------------------|--------------------| 239 | `DELETE` | `/v1/var/:var_path` | `application/json` | 240 241 The table below shows this endpoint's support for [blocking queries] and 242 [required ACLs]. 243 244 | Blocking Queries | ACL Required | 245 |------------------|--------------------------------------------------------------------------------------------------| 246 | `NO` | `namespace:* variables:destroy`<br />The destroy capability on the variable's namespace and path | 247 248 ### Parameters 249 250 - `namespace` `(string: "default")` - Specifies the variable's namespace. 251 252 - `cas` `(int: <unset>)` - If set, the variable will only be deleted if the 253 `cas` value matches the current variables `ModifyIndex`. 254 255 ### Sample Request 256 257 ```shell-session 258 $ curl \ 259 -XDELETE \ 260 https://localhost:4646/v1/var/example/first?namespace=prod 261 ``` 262 263 ### Sample Response 264 265 ```json 266 { 267 "Index": 16 268 } 269 ``` 270 271 ### Sample Request With CAS 272 273 ```shell-session 274 $ curl \ 275 -XDELETE \ 276 https://localhost:4646/v1/var/example/first?namespace=prod&cas=1 277 ``` 278 279 ### Sample Response for Conflict 280 281 In the case of a compare-and-set conflict on delete, the API will return HTTP 282 error code 409 and a response body showing the conflicting variable. If the 283 provided ACL token does not also have `read` permissions to the variable path, 284 the response will include only metadata and not the `Items` field: 285 286 ```json 287 { 288 "Namespace": "prod", 289 "Path": "example/first", 290 "CreateIndex": 1457, 291 "ModifyIndex": 1457, 292 "CreateTime": 1662061225600373000, 293 "ModifyTime": 1662061225600373000 294 } 295 ``` 296 297 298 [Variables]: /docs/concepts/variables 299 [`nomad var`]: /docs/commands/var 300 [blocking queries]: /api-docs#blocking-queries 301 [required ACLs]: /api-docs#acls 302 [RFC3986]: https://www.rfc-editor.org/rfc/rfc3986#section-2