Add labels to container

Author: francoiscampbell

README.md

@@ -293,6 +293,12 @@ Specify the IPC mode to use. See the [docker run options documentation](https://
 
 Example: `host`
 
+### `run-labels` (optional, boolean)
+
+If set to true, adds useful Docker labels to the container. See [Container Labels](#container-labels) for more info.
+
+The default is `true`.
+
 ### `shell` (optional, array or boolean)
 
 Set the shell to use for the command. Set it to `false` to pass the command directly to the `docker run` command. The default is `["/bin/sh", "-e", "-c"]` unless you have provided an `entrypoint` or `command`.
@@ -426,6 +432,26 @@ can be found in https://docs.docker.com/config/containers/resource_constraints/#
 
 Example: `0`
 
+## Container Labels
+
+When running a command, the plugin will automatically add the following Docker labels to the container:
+- `com.buildkite.pipeline_name=${BUILDKITE_PIPELINE_NAME}`
+- `com.buildkite.pipeline_slug=${BUILDKITE_PIPELINE_SLUG}`
+- `com.buildkite.build_number=${BUILDKITE_BUILD_NUMBER}`
+- `com.buildkite.job_id=${BUILDKITE_JOB_ID}`
+- `com.buildkite.job_label=${BUILDKITE_LABEL}`
+- `com.buildkite.step_key=${BUILDKITE_STEP_KEY}`
+- `com.buildkite.agent_name=${BUILDKITE_AGENT_NAME}`
+- `com.buildkite.agent_id=${BUILDKITE_AGENT_ID}`
+
+These labels can make it easier to query containers on hosts using `docker ps` for example:
+
+```bash
+docker ps --filter "label=com.buildkite.job_label=Run tests"
+```
+
+This behaviour can be disabled with the `run-labels: false` option.
+
 ## Developing
 
 To run testing, shellchecks and plugin linting use use `bk run` with the [Buildkite CLI](https://github.com/buildkite/cli).

hooks/command

@@ -503,7 +503,21 @@ elif plugin_read_list_into_result BUILDKITE_PLUGIN_DOCKER_SHELL ; then
 fi
 
 # Add the job id as meta-data for reference in pre-exit
-args+=("--label" "com.buildkite.job-id=${BUILDKITE_JOB_ID}")
+args+=("--label" "com.buildkite.job-id=${BUILDKITE_JOB_ID}")  # Keep the kebab-case one for backwards compat
+
+# Add useful labels to run container
+if [[ "${BUILDKITE_PLUGIN_DOCKER_RUN_LABELS:-true}" =~ ^(true|on|1)$ ]] ; then
+  args+=(
+    "--label" "com.buildkite.pipeline_name=${BUILDKITE_PIPELINE_NAME}"
+    "--label" "com.buildkite.pipeline_slug=${BUILDKITE_PIPELINE_SLUG}"
+    "--label" "com.buildkite.build_number=${BUILDKITE_BUILD_NUMBER}"
+    "--label" "com.buildkite.job_id=${BUILDKITE_JOB_ID}"
+    "--label" "com.buildkite.job_label=${BUILDKITE_LABEL}"
+    "--label" "com.buildkite.step_key=${BUILDKITE_STEP_KEY}"
+    "--label" "com.buildkite.agent_name=${BUILDKITE_AGENT_NAME}"
+    "--label" "com.buildkite.agent_id=${BUILDKITE_AGENT_ID}"
+  )
+fi
 
 # Add the image in before the shell and command
 args+=("${image}")

plugin.yml

@@ -53,6 +53,8 @@ configuration:
       type: string
     runtime:
       type: string
+    run-labels:
+      type: boolean
     shell:
       type: [boolean, array]
     shm-size:

tests/command.bats

@@ -11,6 +11,7 @@ setup() {
   export BUILDKITE_PLUGIN_DOCKER_CLEANUP=false
   export BUILDKITE_PLUGIN_DOCKER_MOUNT_BUILDKITE_AGENT=false
   export BUILDKITE_COMMAND="pwd"
+  export BUILDKITE_PLUGIN_DOCKER_RUN_LABELS="false"
 }
 
 @test "Run with BUILDKITE_COMMAND" {
@@ -723,6 +724,41 @@ EOF
   unstub docker
 }
 
+@test "Runs BUILDKITE_COMMAND with run-labels" {
+  export BUILDKITE_PLUGIN_DOCKER_RUN_LABELS="true"
+  export BUILDKITE_COMMAND="echo hello world"
+
+  # Pipeline vars
+  export BUILDKITE_AGENT_ID="1234"
+  export BUILDKITE_AGENT_NAME="agent"
+  export BUILDKITE_BUILD_NUMBER=1
+  export BUILDKITE_JOB_ID=1111
+  export BUILDKITE_LABEL="Testjob"
+  export BUILDKITE_PIPELINE_NAME="label-test"
+  export BUILDKITE_PIPELINE_SLUG=test
+  export BUILDKITE_STEP_KEY="test-job"
+
+  stub docker \
+    "run -t -i --rm --init --volume $PWD:/workdir --workdir /workdir \
+      --label com.buildkite.job-id=${BUILDKITE_JOB_ID} \
+      --label com.buildkite.pipeline_name=${BUILDKITE_PIPELINE_NAME} \
+      --label com.buildkite.pipeline_slug=${BUILDKITE_PIPELINE_SLUG} \
+      --label com.buildkite.build_number=${BUILDKITE_BUILD_NUMBER} \
+      --label com.buildkite.job_id=${BUILDKITE_JOB_ID} \
+      --label com.buildkite.job_label=${BUILDKITE_LABEL} \
+      --label com.buildkite.step_key=${BUILDKITE_STEP_KEY} \
+      --label com.buildkite.agent_name=${BUILDKITE_AGENT_NAME} \
+      --label com.buildkite.agent_id=${BUILDKITE_AGENT_ID} \
+      image:tag /bin/sh -e -c 'echo hello world' : echo ran command in docker"
+
+  run $PWD/hooks/command
+
+  assert_success
+  assert_output --partial "ran command in docker"
+
+  unstub docker
+}
+
 @test "Runs with a command as a string" {
   export BUILDKITE_PLUGIN_DOCKER_COMMAND="echo hello world"
   export BUILDKITE_COMMAND=
@@ -1241,7 +1277,7 @@ EOF
 @test "Use ssh agent (true)" {
   skip 'Can not create a socket for testing :('
   export BUILDKITE_PLUGIN_DOCKER_MOUNT_SSH_AGENT=true
-  export SSH_AUTH_SOCK="/tmp/sock" 
+  export SSH_AUTH_SOCK="/tmp/sock"
   touch /tmp/sock # does not work as the hook checks that this is a socket
 
   stub docker \
@@ -1258,7 +1294,7 @@ EOF
 @test "Use ssh agent (with path)" {
   skip 'Can not create a socket for testing :('
   export BUILDKITE_PLUGIN_DOCKER_MOUNT_SSH_AGENT=/test/path
-  export SSH_AUTH_SOCK="/tmp/sock" 
+  export SSH_AUTH_SOCK="/tmp/sock"
   touch /tmp/sock # does not work as the hook checks that this is a socket
 
   stub docker \

tests/windows.bats

@@ -9,6 +9,7 @@ setup() {
   export BUILDKITE_PLUGIN_DOCKER_MOUNT_BUILDKITE_AGENT=false
   export BUILDKITE_COMMAND="pwd"
   export OSTYPE="win" # important to define these test as windows
+  export BUILDKITE_PLUGIN_DOCKER_RUN_LABELS="false"
 }
 
 @test "Run with BUILDKITE_COMMAND" {
@@ -29,4 +30,4 @@ setup() {
 
   unstub docker
   unstub cmd.exe
-}
+}