cp

Why it exists?

I really needed to copy files from Nomad allocation to my PC for debugging.

How to use it?

Firstly, cp has bash completion. It autocompletes what you type.

# nomadtools cp <TAB>
job1:  job2:
# nomadtools cp job1:<TAB>
index.js       node_modules/  package.json   settings.js    views/         yarn.lock  
# nomadtools cp :<TAB>
15b0812a-6893-5d16-86c5-9c6855596386:  a36347b1-3d11-94bb-e7f8-fac0b1d244cc:  
389dd991-6d0c-4878-c743-2dbdb844d25d:  a726de75-69be-a1d5-2d64-e0533e7570a7:  
# nomadtools cp ./<TAB>

The syntax to specify the location tries to be rsync-ish. To specify an allocation to from or two you can use:

 :ALLOCATION[:TASK]:[PATH]
 JOB[:[GROUP][:TASK]]:[PATH]

If an allocation has one task, there is no need to specify the task. Similarly, if a job has one group, and that group has one task, there is no need to specify them.

The : character in job name or task name has to be escaped with \.

Then there is an experimental URL-ish form

task://JOB[@NAMESPACE]/PATH[?group=GROUP][&alloc=ALLOC][&task=TASK][&hostname=HOSTNAME][&node=NODE]

The idea was, for system jobs to find the task with specifically using the hostname or node name. Bash completion for this is junky.

How it works?

The tool follows the same rules as docker cp laid out in https://docs.docker.com/reference/cli/docker/container/cp/ .

Assuming a path separator of /, a first argument of SRC_PATH and second argument of DEST_PATH, the behavior is as follows:

• SRC_PATH specifies a file
  • DEST_PATH does not exist
    • the file is saved to a file created at DEST_PATH
  • DEST_PATH does not exist and ends with /
    • Error condition: the destination directory must exist.
  • DEST_PATH exists and is a file
    • the destination is overwritten with the source file's contents DEST_PATH exists and is a directory
    • the file is copied into this directory using the basename from SRC_PATH
• SRC_PATH specifies a directory
  • DEST_PATH does not exist
    • DEST_PATH is created as a directory and the contents of the source directory are copied into this directory
  • DEST_PATH exists and is a file
    • Error condition: cannot copy a directory to a file
  • DEST_PATH exists and is a directory
    • SRC_PATH does not end with /. (that is: slash followed by dot)
      • the source directory is copied into this directory
    • SRC_PATH does end with /. (that is: slash followed by dot)
      • the content of the source directory is copied into this directory

The tools work as follows:

• First we need to determine if SRC_PATH and DEST_PATH is a directory, file, symbolic link or does not exist.
  • For that, nomad alloc exec is used
  • sh shell script is executed inside the allocation
  • The shell script, which uses only POSIX [ test command to determine the type of the location.
• After determining the type of SRC_PATH and DEST_PATH
  • a set of tar commands with different options are chosen.
• Then another nomad alloc exec is executes which executes tar command with proper options which stream or receive the data.