github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/docs/commands/alloc/exec.mdx (about)

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