From 15a2b7cbce9db8f663f04eb046894f6eff722a99 Mon Sep 17 00:00:00 2001 From: Jose Diaz-Gonzalez Date: Sun, 14 Oct 2018 19:39:24 -0400 Subject: [PATCH] feat: sanitize docker inspect output with ps:inspect Often-times, we will want to have the container inspect output for debugging purposes, but this process is: - error prone, as the user needs to know what their containers are - potentially insecure, as the output must be sanitized of sensitive data Instead of making users wade through this process, we provide a helper `ps:inspect` command, that can be used to diagnose problems associated with containers that may or may not exist for an application. --- ISSUE_TEMPLATE.md | 5 +- docs/deployment/process-management.md | 13 +++++ docs/development/plugin-triggers.md | 19 +++++++ plugins/ps/commands | 1 + plugins/ps/internal-functions | 10 ++++ plugins/ps/subcommands/inspect | 5 ++ .../scheduler-docker-local/scheduler-inspect | 54 +++++++++++++++++++ tests/unit/10_ps-general.bats | 11 ++++ 8 files changed, 116 insertions(+), 2 deletions(-) create mode 100755 plugins/ps/subcommands/inspect create mode 100755 plugins/scheduler-docker-local/scheduler-inspect diff --git a/ISSUE_TEMPLATE.md b/ISSUE_TEMPLATE.md index bc3d753fe..ec2af94d1 100644 --- a/ISSUE_TEMPLATE.md +++ b/ISSUE_TEMPLATE.md @@ -27,8 +27,9 @@ ### Additional information -- `docker inspect CONTAINER_ID` (if applicable): - (BEWARE: `docker inspect` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX): +- Container Inspect Output (if applicable): + - 0.13.0+: `dokku inspect APP_NAME` + - <0.13.0: `docker inspect CONTAINER_ID`: WARNING, `docker inspect` will print environment variables for some commands, be sure you're not exposing any sensitive information when posting issues. You may replace these values with XXXXXXX. - `cat /home/dokku//nginx.conf` (if applicable): - Link to the exact repository being deployed (if possible/applicable): - If a deploy is failing or behaving unexpectedly: diff --git a/docs/deployment/process-management.md b/docs/deployment/process-management.md index b11a919cc..6a62317d0 100644 --- a/docs/deployment/process-management.md +++ b/docs/deployment/process-management.md @@ -4,6 +4,7 @@ ``` ps # List processes running in app container(s) +ps:inspect # Displays a sanitized version of docker inspect for an app ps:rebuild # Rebuild an app from source ps:rebuildall # Rebuild all apps from source ps:report [] [] # Displays a process report for one or more apps @@ -32,6 +33,18 @@ To find out if your application's containers are running the commands you expect dokku ps node-js-app ``` +### Inspecting app containers + +> New as of 0.13.0 + +A common administrative task to perform is calling `docker inspect` on the containers that are running for an application. This can be an error-prone task to perform, and may also reveal sensitive environment variables if not done correctly. Dokku provides a wrapper around this command via the `ps:inspect` subcommand: + +```shell +dokku ps:inspect node-js-app +``` + +This command will gather all the running container IDs for your application and call `docker inspect`, sanitizing the output data so it can be copy-pasted elsewhere safely. + ### Rebuilding applications There are some Dokku commands which will not automatically rebuild an application's environment, or which can be told to skip a rebuild. For instance, you may wish to run multiple `config:set` commands without a restart so as to speed up configuration. In these cases, you can ultimately trigger an application rebuild using `ps:rebuild` diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md index 57e79fbc7..6bf29a48f 100644 --- a/docs/development/plugin-triggers.md +++ b/docs/development/plugin-triggers.md @@ -1213,6 +1213,25 @@ DOKKU_SCHEDULER="$1"; APP="$2"; FORCE_CLEANUP="$3"; # TODO ``` +### `scheduler-inspect` + +> Warning: The scheduler plugin trigger apis are under development and may change +> between minor releases until the 1.0 release. + +- Description: Allows you to run inspect commands for all containers for a given app +- Invoked by: `dokku ps:inspect` +- Arguments: `$DOKKU_SCHEDULER $APP` +- Example: + +```shell +#!/usr/bin/env bash + +set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x +DOKKU_SCHEDULER="$1"; APP="$2"; + +# TODO +``` + ### `scheduler-logs-failed` > Warning: The scheduler plugin trigger apis are under development and may change diff --git a/plugins/ps/commands b/plugins/ps/commands index 9e6389eb9..c623c5d1d 100755 --- a/plugins/ps/commands +++ b/plugins/ps/commands @@ -8,6 +8,7 @@ case "$1" in declare desc="return ps plugin help content" cat<, List processes running in app container(s) + ps:inspect , Displays a sanitized version of docker inspect for an app ps:scale = [=...], Get/Set how many instances of a given process to run ps:start , Start app container(s) ps:startall, Starts all apps via command line diff --git a/plugins/ps/internal-functions b/plugins/ps/internal-functions index dfa8639a0..d4b6dc353 100755 --- a/plugins/ps/internal-functions +++ b/plugins/ps/internal-functions @@ -4,6 +4,16 @@ source "$PLUGIN_AVAILABLE_PATH/docker-options/functions" source "$PLUGIN_AVAILABLE_PATH/ps/functions" set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x +cmd-ps-inspect() { + declare desc="displays a sanitized version of docker inspect for an app" + local cmd="ps:inspect" + local APP="$2" + + verify_app_name "$APP" + local DOKKU_SCHEDULER=$(get_app_scheduler "$APP") + plugn trigger scheduler-inspect "$DOKKU_SCHEDULER" "$APP" +} + cmd-ps-report() { declare desc="displays a ps report for one or more apps" local cmd="ps:report" diff --git a/plugins/ps/subcommands/inspect b/plugins/ps/subcommands/inspect new file mode 100755 index 000000000..96974342e --- /dev/null +++ b/plugins/ps/subcommands/inspect @@ -0,0 +1,5 @@ +#!/usr/bin/env bash +source "$PLUGIN_AVAILABLE_PATH/ps/internal-functions" +set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x + +cmd-ps-inspect "$@" diff --git a/plugins/scheduler-docker-local/scheduler-inspect b/plugins/scheduler-docker-local/scheduler-inspect new file mode 100755 index 000000000..1200314b9 --- /dev/null +++ b/plugins/scheduler-docker-local/scheduler-inspect @@ -0,0 +1,54 @@ +#!/usr/bin/env bash +set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x +source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions" +source "$PLUGIN_AVAILABLE_PATH/config/functions" + +scheduler-docker-local-scheduler-inspect() { + declare desc="scheduler-docker-local scheduler-inspect plugin trigger" + declare trigger="scheduler-docker-local scheduler-inspect" + declare DOKKU_SCHEDULER="$1" APP="$2" + + if [[ "$DOKKU_SCHEDULER" != "docker-local" ]]; then + return + fi + + local TMP_INSPECT_CMD=$(mktemp "/tmp/${FUNCNAME[0]}.XXXX") + trap 'rm -rf "$TMP_INSPECT_CMD" > /dev/null' RETURN INT TERM EXIT + cat > "$TMP_INSPECT_CMD" </dev/null | sort -t . -k 2 -n | xargs)" + local CIDS=() + for CONTAINER_FILE in $CONTAINER_FILES; do + CIDS+="$(< "$DOKKU_ROOT/$APP/$CONTAINER_FILE")" + done + docker inspect "${CIDS[@]}" | python2.7 "$TMP_INSPECT_CMD" + +} + +scheduler-docker-local-scheduler-inspect "$@" diff --git a/tests/unit/10_ps-general.bats b/tests/unit/10_ps-general.bats index 356cc50f4..b5cc00ce1 100644 --- a/tests/unit/10_ps-general.bats +++ b/tests/unit/10_ps-general.bats @@ -12,6 +12,17 @@ teardown() { global_teardown } +@test "(ps) ps:inspect" { + deploy_app dockerfile + + CID=$(< $DOKKU_ROOT/$TEST_APP/CONTAINER.web.1) + run bash -c "dokku ps:inspect $TEST_APP" + echo "output: "$output + echo "status: "$status + assert_success + assert_output_contains "$CID" 6 +} + @test "(ps:scale) procfile commands extraction" { source "$PLUGIN_CORE_AVAILABLE_PATH/ps/functions" cat < "$DOKKU_ROOT/$TEST_APP/DOKKU_PROCFILE"