303 lines
8.6 KiB
Plaintext
303 lines
8.6 KiB
Plaintext
---
|
|
layout: api
|
|
page_title: Variables - HTTP API
|
|
description: The /var endpoints are used to query for and interact with variables.
|
|
---
|
|
|
|
# Variables HTTP API
|
|
|
|
The `/var` and `/vars` endpoints are used to query for and interact with
|
|
variables.
|
|
|
|
See the [Variables] documentation for information how these capabilities are
|
|
used. For a CLI to perform these operations manually, please see the
|
|
documentation for the [`nomad var`] commands.
|
|
|
|
## List Variables
|
|
|
|
This endpoint lists all variables. Note this API returns only variable metadata
|
|
without decrypting the variable body.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|------------|--------------------|
|
|
| `GET` | `/v1/vars` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|-----------------------------------------------------------------------------------------|
|
|
| `YES` | `namespace:* variables:list`<br />The list capability on the namespace and path queried |
|
|
|
|
### Parameters
|
|
|
|
- `prefix` `(string: "")` - Specifies a string to filter variables on based on
|
|
an index prefix. This is specified as a query string parameter.
|
|
|
|
- `next_token` `(string: "")` - This endpoint supports paging. The `next_token`
|
|
parameter accepts a string which identifies the next expected job. This value
|
|
can be obtained from the `X-Nomad-NextToken` header from the previous
|
|
response.
|
|
|
|
- `per_page` `(int: 0)` - Specifies a maximum number of variables to return for
|
|
this request. If omitted, the response is not paginated. The value of the
|
|
`X-Nomad-NextToken` header of the last response can be used as the
|
|
`next_token` of the next request to fetch additional pages.
|
|
|
|
- `filter` `(string: "")` - Specifies the [expression](/api-docs#filtering) used
|
|
to filter the results. Consider using pagination or a query parameter to
|
|
reduce resources used to serve the request.
|
|
|
|
- `namespace` `(string: "default")` - Specifies the target namespace. Specifying
|
|
`*` will return all variables across all the authorized namespaces.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/vars?namespace=prod&prefix=example
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
[
|
|
{
|
|
"Namespace": "prod",
|
|
"Path": "example/first",
|
|
"CreateIndex": 1457,
|
|
"ModifyIndex": 1457,
|
|
"CreateTime": 1662061225600373000,
|
|
"ModifyTime": 1662061225600373000
|
|
},
|
|
{
|
|
"Namespace": "prod",
|
|
"Path": "example/second",
|
|
"CreateIndex": 800,
|
|
"ModifyIndex": 1000,
|
|
"CreateTime": 1662061717905426000,
|
|
"ModifyTime": 1662062162982630000
|
|
}
|
|
]
|
|
```
|
|
|
|
## Read Variable
|
|
|
|
This endpoint reads a specific variable by path. This API returns the decrypted
|
|
variable body.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|--------------------|--------------------|
|
|
| `GET` | `/v1/var/:var_path` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|--------------------------------------------------------------------------------------------|
|
|
| `YES` | `namespace:* variables:read`<br />The read capability on the variable's namespace and path |
|
|
|
|
### Parameters
|
|
|
|
- `namespace` `(string: "default")` - Specifies the variable's namespace.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
https://localhost:4646/v1/var/example/first?namespace=prod
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Namespace": "prod",
|
|
"Path": "example/first",
|
|
"CreateIndex": 1457,
|
|
"ModifyIndex": 1457,
|
|
"CreateTime": 1662061225600373000,
|
|
"ModifyTime": 1662061225600373000
|
|
"Items": {
|
|
"user": "me",
|
|
"password": "passw0rd1"
|
|
}
|
|
}
|
|
```
|
|
|
|
## Create Variable
|
|
|
|
This endpoint creates or updates a variable.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|---------------------|--------------------|
|
|
| `PUT` | `/v1/var/:var_path` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|---------------------------------------------------------------------------------------------|
|
|
| `NO` | `namespace:* variables:write`<br />The read capability on the variable's namespace and path |
|
|
|
|
### Parameters
|
|
|
|
- `namespace` `(string: "default")` - Specifies the variable's namespace. If
|
|
set, this will override the request body.
|
|
|
|
- `cas` `(int: <unset>)` - If set, the variable will only be updated if the
|
|
`cas` value matches the current variables `ModifyIndex`. If the `cas` value is
|
|
0, the variable is only created if it does not already exist. This paradigm
|
|
allows check-and-set style updates.
|
|
|
|
## Restrictions
|
|
|
|
Variable paths are restricted to [RFC3986][] URL-safe characters that don't
|
|
conflict with the use of the characters `@` and `.` in template blocks. This
|
|
includes alphanumeric characters and the special characters `-`, `_`, `~`, and
|
|
`/`. Paths may be up to 128 bytes long. The following regex matches the allowed
|
|
paths: `^[a-zA-Z0-9-_~/]{1,128}$`
|
|
|
|
Variable items are restricted to 16KiB in size. This limit is calculated by
|
|
taking the sum of the length in bytes of all of the unencrypted keys and values
|
|
in the `Items` field.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
-XPUT -d@spec.nsv.json \
|
|
https://localhost:4646/v1/var/example/first
|
|
```
|
|
|
|
### Sample Payload
|
|
|
|
```json
|
|
{
|
|
"Namespace": "prod",
|
|
"Path": "example/first",
|
|
"CreateIndex": 1457,
|
|
"ModifyIndex": 1457,
|
|
"CreateTime": 1662061225600373000,
|
|
"ModifyTime": 1662061225600373000,
|
|
"Items": {
|
|
"user": "me",
|
|
"password": "passw0rd1"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
The response body returns the created or updated variable along with metadata
|
|
created by the server:
|
|
|
|
```json
|
|
{
|
|
"Namespace": "prod",
|
|
"Path": "example/first",
|
|
"CreateIndex": 1457,
|
|
"ModifyIndex": 1457,
|
|
"CreateTime": 1662061225600373000,
|
|
"ModifyTime": 1662061225600373000,
|
|
"Items": {
|
|
"user": "me",
|
|
"password": "passw0rd1"
|
|
}
|
|
}
|
|
```
|
|
|
|
### Sample Response for Conflict
|
|
|
|
In the case of a compare-and-set conflict, the API will return HTTP error code
|
|
409 and a response body showing the conflicting variable. If the provided ACL
|
|
token does not also have `read` permissions to the variable path, the response
|
|
will include only metadata and not the `Items` field:
|
|
|
|
```json
|
|
{
|
|
"Namespace": "prod",
|
|
"Path": "example/first",
|
|
"CreateIndex": 1457,
|
|
"ModifyIndex": 1457,
|
|
"CreateTime": 1662061225600373000,
|
|
"ModifyTime": 1662061225600373000,
|
|
"Items": {
|
|
"user": "me",
|
|
"password": "passw0rd1"
|
|
}
|
|
}
|
|
```
|
|
|
|
|
|
## Delete Variable
|
|
|
|
This endpoint deletes a specific variable by path.
|
|
|
|
| Method | Path | Produces |
|
|
|--------|--------------------|--------------------|
|
|
| `DELETE` | `/v1/var/:var_path` | `application/json` |
|
|
|
|
The table below shows this endpoint's support for [blocking queries] and
|
|
[required ACLs].
|
|
|
|
| Blocking Queries | ACL Required |
|
|
|------------------|--------------------------------------------------------------------------------------------------|
|
|
| `NO` | `namespace:* variables:destroy`<br />The destroy capability on the variable's namespace and path |
|
|
|
|
### Parameters
|
|
|
|
- `namespace` `(string: "default")` - Specifies the variable's namespace.
|
|
|
|
- `cas` `(int: <unset>)` - If set, the variable will only be deleted if the
|
|
`cas` value matches the current variables `ModifyIndex`.
|
|
|
|
### Sample Request
|
|
|
|
```shell-session
|
|
$ curl \
|
|
-XDELETE \
|
|
https://localhost:4646/v1/var/example/first?namespace=prod
|
|
```
|
|
|
|
### Sample Response
|
|
|
|
```json
|
|
{
|
|
"Index": 16
|
|
}
|
|
```
|
|
|
|
### Sample Request With CAS
|
|
|
|
```shell-session
|
|
$ curl \
|
|
-XDELETE \
|
|
https://localhost:4646/v1/var/example/first?namespace=prod&cas=1
|
|
```
|
|
|
|
### Sample Response for Conflict
|
|
|
|
In the case of a compare-and-set conflict on delete, the API will return HTTP
|
|
error code 409 and a response body showing the conflicting variable. If the
|
|
provided ACL token does not also have `read` permissions to the variable path,
|
|
the response will include only metadata and not the `Items` field:
|
|
|
|
```json
|
|
{
|
|
"Namespace": "prod",
|
|
"Path": "example/first",
|
|
"CreateIndex": 1457,
|
|
"ModifyIndex": 1457,
|
|
"CreateTime": 1662061225600373000,
|
|
"ModifyTime": 1662061225600373000
|
|
}
|
|
```
|
|
|
|
|
|
[Variables]: /docs/concepts/variables
|
|
[`nomad var`]: /docs/commands/var
|
|
[blocking queries]: /api-docs#blocking-queries
|
|
[required ACLs]: /api-docs#acls
|
|
[RFC3986]: https://www.rfc-editor.org/rfc/rfc3986#section-2
|