github.com/ferranbt/nomad@v0.9.3-0.20190607002617-85c449b7667c/website/source/docs/commands/alloc/exec.html.md.erb (about)

     1  ---
     2  layout: "docs"
     3  page_title: "Commands: alloc exec"
     4  sidebar_current: "docs-commands-alloc-exec"
     5  description: >
     6    Runs a command in a container.
     7  ---
     8  
     9  # Command: alloc exec
    10  **Alias: `nomad exec`**
    11  
    12  The `alloc exec` command runs a command in a running allocation.
    13  
    14  ## Usage
    15  
    16  ```
    17  nomad alloc exec [options] <allocation> <command> [<args>...]
    18  ```
    19  
    20  
    21  The nomad exec command can be use to run commands inside a running task/allocation.
    22  
    23  Use cases are for inspecting container state, debugging a failed application
    24  without needing ssh access into the node that's running the allocation.
    25  
    26  This command executes the command in the given task in the allocation.  If the
    27  allocation is only running a single task, the task name can be omitted.
    28  Optionally, the `-job` option may be used in which case a random allocation from
    29  the given job will be chosen.
    30  
    31  ## General Options
    32  
    33  <%= partial "docs/commands/_general_options" %>
    34  
    35  ## Exec Options
    36  
    37  * `task`: Sets the task to exec command in.  Defaults to first task.
    38  
    39  * `-job`: Use a random allocation from the specified job ID.
    40  
    41  * `-i`: Pass stdin to the container, defaults to true.
    42  Pass `-i=false` to disable explicitly.
    43  
    44  * `-t`: Allocate a pseudo-tty, defaults to true if stdin is detected to be a tty session.
    45  Pass `-t=false` to disable explicitly.
    46  
    47  * `-e` <escape_char>: Sets the escape character for sessions with a pty
    48  (default: '~'). The escape character is only recognized at the beginning of a
    49  line. The escape character followed by a dot ('.') closes the connection.
    50  Setting the character to 'none' disables any escapes and makes the session fully
    51  transparent.
    52  
    53  
    54  ## Examples
    55  
    56  To start an interactive debugging session in a particular alloc, invoke exec
    57  command with your desired shell available inside the task:
    58  
    59  ```
    60  $ nomad alloc exec eb17e557 /bin/bash
    61  root@eb17e557:/data# # now run any debugging commands inside container
    62  root@eb17e557:/data# # ps -ef
    63  ```
    64  
    65  To run a command and stream results without starting an interactive shell, you
    66  can pass the command and its arguments to exec directly:
    67  
    68  ```
    69  $ # run commands without starting an interactive session
    70  $ nomad alloc exec eb17e557 cat /etc/resolv.conf
    71  ```
    72  
    73  When passing command arguments to be evaluated in task, you may need to ensure
    74  that your host shell doesn't interpolate values before invoking `exec` command.
    75  For example, the following command would return the environment variable on
    76  operator shell rather than task containers:
    77  
    78  ```
    79  $ nomad alloc exec eb17e557 echo $NOMAD_ALLOC_ID # wrong
    80  ```
    81  
    82  Here, we must start a shell in task to interpolate `$NOMAD_ALLOC_ID`, and quote
    83  command or use the [heredoc syntax][heredoc]
    84  
    85  ```
    86  $ # by quoting argument
    87  $ nomad alloc exec eb17e557 /bin/sh -c 'echo $NOMAD_ALLOC_ID'
    88  eb17e557-443e-4c51-c049-5bba7a9850bc
    89  
    90  $ # by using heredoc and passing command in stdin
    91  $ nomad alloc exec eb17e557 /bin/sh <<'EOF'
    92  > echo $NOMAD_ALLOC_ID
    93  > EOF
    94  eb17e557-443e-4c51-c049-5bba7a9850bc
    95  ```
    96  
    97  This technique applies when aiming to run a shell pipeline without streaming
    98  intermediate command output across the network:
    99  
   100  ```
   101  $ # e.g. find top appearing lines in some output
   102  $ nomad alloc exec eb17e557 /bin/sh -c 'cat /output | sort | uniq -c | sort -rn | head -n 5'
   103  ```
   104  
   105  [heredoc]: http://tldp.org/LDP/abs/html/here-docs.html
   106  
   107  ## Using Job ID instead of Allocation ID
   108  
   109  Setting the `-job` flag causes a random allocation of the specified job to be
   110  selected.
   111  
   112  ```
   113  nomad alloc exec -job <job-id> <command> [<args>...]
   114  ```
   115  
   116  
   117  Choosing a specific allocation is useful for debugging issues with a specific
   118  instance of a service. For other operations using the `-job` flag may be more
   119  convenient than looking up an allocation ID to use.
   120  
   121  ## Disabling remote execution
   122  
   123  `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.
   124  
   125  [disable_remote_exec_flag]: /docs/configuration/client.html#disable_remote_exec