mirror of
https://github.com/kemko/nomad.git
synced 2026-01-08 11:25:41 +03:00
23fd87d9c9
* sectionless files plus acl section * alloc section * config, deployment sections * job section * licence, namespace * node, node-pool * operator * plugin, quota, recommendation * scaling, sentinel, server, service, system, var, volume * Add "ENT" label to left nav for enterprise commands * job tag break into separate folder and files; update options header
102 lines
4.1 KiB
Plaintext
102 lines
4.1 KiB
Plaintext
---
|
|
layout: docs
|
|
page_title: nomad var lock reference
|
|
description: |-
|
|
The `nomad var lock` command locks a variable, only allowing the lock owner to modify it.
|
|
---
|
|
|
|
# `nomad var lock` command reference
|
|
|
|
The `var lock` command holds a lock on a [variable][].
|
|
|
|
## Usage
|
|
|
|
```plaintext
|
|
nomad var lock [options] <lock spec file reference> child...
|
|
nomad var lock [options] <path to store variable> [<variable spec file reference>] child
|
|
```
|
|
|
|
The lock command provides a mechanism for simple distributed locking. A lock
|
|
is created in the given variable, and only when held, is a child process invoked.
|
|
|
|
The lock command can be called on an existing variable or an entire new variable
|
|
specification can be provided to the command from a file by using an
|
|
@-prefixed path to a variable specification file. Items to be stored in the
|
|
variable can be supplied using the specification file as well.
|
|
|
|
Nomad lock launches its children in a shell. By default, Nomad will use the
|
|
shell defined in the environment variable SHELL. If SHELL is not defined,
|
|
it will default to /bin/sh. It should be noted that not all shells terminate
|
|
child processes when they receive SIGTERM. Under Ubuntu, /bin/sh is linked
|
|
to dash, which does not terminate its children. In order to ensure that
|
|
child processes are killed when the lock is lost, be sure to set the SHELL
|
|
environment variable appropriately, or run without a shell by setting -shell=false.
|
|
|
|
If [ACLs][] are enabled, this command requires the 'variables:write' capability
|
|
for the destination namespace and path.
|
|
|
|
## 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}$`
|
|
|
|
The keys for the items in a variable may contain any character, but keys
|
|
containing characters outside the set of Unicode letters, Unicode digits, and
|
|
the underscore (`_`) can not be read directly using dotted references in Nomad's
|
|
template engine. Instead, they require the use of the `index` template function
|
|
to directly access their values. This does not impact cases where the keys and
|
|
values are read using the `range` function.
|
|
|
|
Variable items are restricted to 64KiB in size. This limit is calculated by
|
|
taking the sum of the length in bytes of all of the unencrypted keys and values.
|
|
|
|
## Options
|
|
|
|
- `-verbose`: Provides additional information via standard error to preserve
|
|
standard output (stdout) for redirected output.
|
|
|
|
- `ttl`: Optional, TTL for the lock, time the variable will be locked. Defaults to 15s.
|
|
|
|
- `delay`: Optional, time the variable is blocked from locking when a lease is not renewed.
|
|
Defaults to 15s.
|
|
|
|
- `max-retry`:Optional, max-retry up to this number of times if Nomad returns a 500 error
|
|
while monitoring the lock. This allows riding out brief periods of
|
|
unavailability without causing leader elections, but increases the amount of
|
|
time required to detect a lost lock in some cases. Defaults to 5. Set to 0 to
|
|
disable.
|
|
|
|
- `shell`: Optional, use a shell to run the command (can set a custom shell via
|
|
the SHELL environment variable). The default value is true.
|
|
|
|
## Examples
|
|
|
|
Attempts to acquire a lock over the variable at path "secret/creds" for a time of
|
|
15s and executes `nomad job run webapp.nomad.hcl` if it succeeds:
|
|
|
|
```shell-session
|
|
$ nomad var lock -ttl=15s secret/creds "nomad job run webapp.nomad.hcl"
|
|
```
|
|
|
|
The data can also be consumed from a file on disk by prefixing with the "@"
|
|
symbol. For example, you can store a variable using a specification created with
|
|
the `nomad var init` command.
|
|
|
|
```shell-session
|
|
$ nomad var lock secret/foo @spec.nv.json `nomad job run webapp.nomad.hcl`
|
|
```
|
|
|
|
## General options
|
|
|
|
@include 'general_options.mdx'
|
|
|
|
[variable]: /nomad/docs/concepts/variables
|
|
[varspec]: /nomad/docs/other-specifications/variables
|
|
[ACL Policy]: /nomad/docs/other-specifications/acl-policy#variables
|
|
[RFC3986]: https://www.rfc-editor.org/rfc/rfc3986#section-2
|
|
[ACL]: /nomad/docs/other-specifications/acl-policy#variables
|
|
|