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.

The table below shows this endpoint's support for blocking queries and required ACLs.

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 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

$ curl \
    https://localhost:4646/v1/vars?namespace=prod&prefix=example

Sample Response

[
  {
    "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.

The table below shows this endpoint's support for blocking queries and required ACLs.

Parameters

• namespace (string: "default") - Specifies the variable's namespace.

Sample Request

$ curl \
    https://localhost:4646/v1/var/example/first?namespace=prod

Sample Response

{
  "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.

The table below shows this endpoint's support for blocking queries and required ACLs.

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

$ curl \
    -XPUT -d@spec.nsv.json \
    https://localhost:4646/v1/var/example/first

Sample Payload

{
  "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:

{
  "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:

{
  "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.

The table below shows this endpoint's support for blocking queries and required ACLs.

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

$ curl \
    -XDELETE \
    https://localhost:4646/v1/var/example/first?namespace=prod

Sample Response

{
  "Index": 16
}

Sample Request With CAS

$ 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:

{
  "Namespace": "prod",
  "Path": "example/first",
  "CreateIndex": 1457,
  "ModifyIndex": 1457,
  "CreateTime": 1662061225600373000,
  "ModifyTime": 1662061225600373000
}