buildkite-agent lock
The Buildkite Agent's lock subcommands provide the ability to coordinate multiple concurrent builds on the same host that access shared resources.
The agent-api experiment must be enabled to use the lock command. To enable the agent-api experiment, include the --experiment=agent-api flag when starting the agent.
With the lock command, processes can acquire and release a lock using the acquire and release subcommands. For the special case of performing setup once for the life of the agent (and waiting until it is complete), there are the do and done subcommands. These provide an alternative to using flock or OS-dependent locking mechanisms.
Inspecting the state of a lock
Usage
buildkite-agent lock get [key]
Description
Retrieves the value of a lock key. Any key not in use returns an empty string.
Note that this subcommand is only available when an agent has been started
with the agent-api experiment enabled.
lock get is generally only useful for inspecting lock state, as the value
can change concurrently. To acquire or release a lock, use lock acquire and
lock release.
Examples
$ buildkite-agent lock get llama
Kuzco
Options
--no-color #
|
Don't show colors in logging |
|---|---|
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
--lock-scope value #
|
The scope for locks used in this operation. Currently only 'machine' scope is supported (default: "machine") |
--sockets-path value #
|
Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets") |
Acquiring a lock
Usage
buildkite-agent lock acquire [key]
Description
Acquires the lock for the given key. lock acquire will wait (potentially
forever) until it can acquire the lock, if the lock is already held by
another process. If multiple processes are waiting for the same lock, there
is no ordering guarantee of which one will be given the lock next.
To prevent separate processes unlocking each other, the output from lock
acquire should be stored, and passed to lock release.
Note that this subcommand is only available when an agent has been started
with the agent-api experiment enabled.
Examples
#!/bin/bash
token=$(buildkite-agent lock acquire llama)
# your critical section here...
buildkite-agent lock release llama "${token}"
Options
--lock-wait-timeout value #
|
Sets a maximum duration to wait for a lock before giving up (default: 0s) |
|---|---|
--lock-scope value #
|
The scope for locks used in this operation. Currently only 'machine' scope is supported (default: "machine") |
--sockets-path value #
|
Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets") |
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
Releasing a previously-acquired lock
Usage
buildkite-agent lock release [key] [token]
Description
Releases the lock for the given key. This should only be called by the
process that acquired the lock. To help prevent different processes unlocking
each other unintentionally, the output from lock acquire is required as the
second argument, namely, the token in the Usage section above.
Note that this subcommand is only available when an agent has been started
with the agent-api experiment enabled.
Examples
#!/bin/bash
token=$(buildkite-agent lock acquire llama)
# your critical section here...
buildkite-agent lock release llama "${token}"
Options
--no-color #
|
Don't show colors in logging |
|---|---|
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
--lock-scope value #
|
The scope for locks used in this operation. Currently only 'machine' scope is supported (default: "machine") |
--sockets-path value #
|
Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets") |
Starting a do-once section
Usage
buildkite-agent lock do [key]
Description
Begins a do-once lock. Do-once can be used by multiple processes to wait for completion of some shared work, where only one process should do the work.
Note that this subcommand is only available when an agent has been started
with the agent-api experiment enabled.
lock do will do one of two things:
- Print 'do'. The calling process should proceed to do the work and then
call
lock done. - Wait until the work is marked as done (with
lock done) and print 'done'.
If lock do prints 'done' immediately, the work was already done.
Examples
#!/bin/bash
if [[ $(buildkite-agent lock do llama) == 'do' ]]; then
# your critical section here...
buildkite-agent lock done llama
fi
Options
--lock-wait-timeout value #
|
Sets a maximum duration to wait for a lock before giving up (default: 0s) |
|---|---|
--lock-scope value #
|
The scope for locks used in this operation. Currently only 'machine' scope is supported (default: "machine") |
--sockets-path value #
|
Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets") |
--no-color #
|
Don't show colors in logging |
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
Completing a do-once section
Usage
buildkite-agent lock done [key]
Description
Completes a do-once lock. This should only be used by the process performing the work.
Note that this subcommand is only available when an agent has been started
with the agent-api experiment enabled.
Examples
#!/bin/bash
if [[ $(buildkite-agent lock do llama) == 'do' ]]; then
# your critical section here...
buildkite-agent lock done llama
fi
Options
--no-color #
|
Don't show colors in logging |
|---|---|
--debug #
|
Enable debug mode. Synonym for `--log-level debug`. Takes precedence over `--log-level` |
--log-level value #
|
Set the log level for the agent, making logging more or less verbose. Defaults to notice. Allowed values are: debug, info, error, warn, fatal (default: "notice") |
--experiment value #
|
Enable experimental features within the buildkite-agent |
--profile value #
|
Enable a profiling mode, either cpu, memory, mutex or block |
--lock-scope value #
|
The scope for locks used in this operation. Currently only 'machine' scope is supported (default: "machine") |
--sockets-path value #
|
Directory where the agent will place sockets (default: "$HOME/.buildkite-agent/sockets") |