135 lines
4.2 KiB
Plaintext
135 lines
4.2 KiB
Plaintext
---
|
|
layout: "docs"
|
|
page_title: "Commands: alloc exec"
|
|
sidebar_current: "docs-commands-alloc-exec"
|
|
description: >
|
|
Runs a command in a container.
|
|
---
|
|
|
|
# Command: alloc exec
|
|
**Alias: `nomad exec`**
|
|
|
|
The `alloc exec` command runs a command in a running allocation.
|
|
|
|
## Usage
|
|
|
|
```
|
|
nomad alloc exec [options] <allocation> <command> [<args>...]
|
|
```
|
|
|
|
|
|
The nomad exec command can be use to run commands inside a running task/allocation.
|
|
|
|
Use cases are for inspecting container state, debugging a failed application
|
|
without needing ssh access into the node that's running the allocation.
|
|
|
|
This command executes the command in the given task in the allocation. If the
|
|
allocation is only running a single task, the task name can be omitted.
|
|
Optionally, the `-job` option may be used in which case a random allocation from
|
|
the given job will be chosen.
|
|
|
|
## General Options
|
|
|
|
<%= partial "docs/commands/_general_options" %>
|
|
|
|
## Exec Options
|
|
|
|
* `-task`: Sets the task to exec command in. Defaults to first task.
|
|
|
|
* `-job`: Use a random allocation from the specified job ID.
|
|
|
|
* `-i`: Pass stdin to the container, defaults to true.
|
|
Pass `-i=false` to disable explicitly.
|
|
|
|
* `-t`: Allocate a pseudo-tty, defaults to true if stdin is detected to be a tty session.
|
|
Pass `-t=false` to disable explicitly.
|
|
|
|
* `-e` <escape_char>: Sets the escape character for sessions with a pty
|
|
(default: '~'). The escape character is only recognized at the beginning of a
|
|
line. The escape character followed by a dot ('.') closes the connection.
|
|
Setting the character to 'none' disables any escapes and makes the session fully
|
|
transparent.
|
|
|
|
|
|
## Examples
|
|
|
|
To start an interactive debugging session in a particular alloc, invoke exec
|
|
command with your desired shell available inside the task:
|
|
|
|
```
|
|
$ nomad alloc exec eb17e557 /bin/bash
|
|
root@eb17e557:/data# # now run any debugging commands inside container
|
|
root@eb17e557:/data# # ps -ef
|
|
```
|
|
|
|
To run a command and stream results without starting an interactive shell, you
|
|
can pass the command and its arguments to exec directly:
|
|
|
|
```
|
|
$ # run commands without starting an interactive session
|
|
$ nomad alloc exec eb17e557 cat /etc/resolv.conf
|
|
```
|
|
|
|
When passing command arguments to be evaluated in task, you may need to ensure
|
|
that your host shell doesn't interpolate values before invoking `exec` command.
|
|
For example, the following command would return the environment variable on
|
|
operator shell rather than task containers:
|
|
|
|
```
|
|
$ nomad alloc exec eb17e557 echo $NOMAD_ALLOC_ID # wrong
|
|
```
|
|
|
|
Here, we must start a shell in task to interpolate `$NOMAD_ALLOC_ID`, and quote
|
|
command or use the [heredoc syntax][heredoc]
|
|
|
|
```
|
|
$ # by quoting argument
|
|
$ nomad alloc exec eb17e557 /bin/sh -c 'echo $NOMAD_ALLOC_ID'
|
|
eb17e557-443e-4c51-c049-5bba7a9850bc
|
|
|
|
$ # by using heredoc and passing command in stdin
|
|
$ nomad alloc exec eb17e557 /bin/sh <<'EOF'
|
|
> echo $NOMAD_ALLOC_ID
|
|
> EOF
|
|
eb17e557-443e-4c51-c049-5bba7a9850bc
|
|
```
|
|
|
|
This technique applies when aiming to run a shell pipeline without streaming
|
|
intermediate command output across the network:
|
|
|
|
```
|
|
$ # e.g. find top appearing lines in some output
|
|
$ nomad alloc exec eb17e557 /bin/sh -c 'cat /output | sort | uniq -c | sort -rn | head -n 5'
|
|
```
|
|
|
|
[heredoc]: http://tldp.org/LDP/abs/html/here-docs.html
|
|
|
|
## Using Job ID instead of Allocation ID
|
|
|
|
Setting the `-job` flag causes a random allocation of the specified job to be
|
|
selected.
|
|
|
|
```
|
|
nomad alloc exec -job <job-id> <command> [<args>...]
|
|
```
|
|
|
|
|
|
Choosing a specific allocation is useful for debugging issues with a specific
|
|
instance of a service. For other operations using the `-job` flag may be more
|
|
convenient than looking up an allocation ID to use.
|
|
|
|
## Disabling remote execution
|
|
|
|
`alloc exec` is enabled by default to aid with debugging. Operators can disable the feature by setting [`disable_remote_exec` client config option][disable_remote_exec_flag] on all clients, or a subset of clients that run sensitive workloads.
|
|
|
|
[disable_remote_exec_flag]: /docs/configuration/client.html#disable_remote_exec
|
|
|
|
## Exec targeting a specific task
|
|
|
|
When trying to `alloc exec` for a job that has more than one task associated with it, you may want to target a specific task.
|
|
|
|
```
|
|
# open a shell session in one of your allocation's tasks
|
|
$ nomad alloc exec -i -t -task mytask a1827f93 /bin/bash
|
|
```
|