diff --git a/docs/appendices/0.29.0-migration-guide.md b/docs/appendices/0.29.0-migration-guide.md index 09c3d2eb1ca..368829553ce 100644 --- a/docs/appendices/0.29.0-migration-guide.md +++ b/docs/appendices/0.29.0-migration-guide.md @@ -3,4 +3,8 @@ ## Changes - The output of `run:detached` now uses the container name - eg. `node-js-app.run.1` - vs the container id. -- The ID of `cron` tasks is now base36-encoded instead of base64-encoded. \ No newline at end of file +- The ID of `cron` tasks is now base36-encoded instead of base64-encoded. + +## Removals + +- The `DOKKU_WAIT_TO_RETIRE` environment variable has been migrated to a `checks` property named `wait-to-retire` and will be ignored if set as an environment variable. \ No newline at end of file diff --git a/docs/configuration/environment-variables.md b/docs/configuration/environment-variables.md index bb078ec9393..002cc312036 100644 --- a/docs/configuration/environment-variables.md +++ b/docs/configuration/environment-variables.md @@ -125,4 +125,3 @@ The following config variables have special meanings and can be set in a variety | `DOKKU_START_CMD` | none | `dokku config:set` | Command to run instead of `/start $PROC_TYPE` | | `DOKKU_SYSTEM_GROUP` | `dokku` | `/etc/environment`
`~dokku/.dokkurc`
`~dokku/.dokkurc/*` | System group to chown files as. | | `DOKKU_SYSTEM_USER` | `dokku` | `/etc/environment`
`~dokku/.dokkurc`
`~dokku/.dokkurc/*` | System user to chown files as. | -| `DOKKU_WAIT_TO_RETIRE` | `60` | `dokku config:set` | After a successful deploy, the grace period given to old containers before they are stopped/terminated. This is useful for ensuring completion of long-running http connections. | diff --git a/docs/deployment/zero-downtime-deploys.md b/docs/deployment/zero-downtime-deploys.md index b68734ae268..c4e43779727 100644 --- a/docs/deployment/zero-downtime-deploys.md +++ b/docs/deployment/zero-downtime-deploys.md @@ -3,11 +3,12 @@ > New as of 0.5.0 ``` -checks:disable [process-type(s)] Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments*** -checks:enable [process-type(s)] Enable zero-downtime deployment for all processes (or comma-separated process-type list) -checks:report [] [] Displays a checks report for one or more apps -checks:run [process-type(s)] Runs zero-downtime checks for all processes (or comma-separated process-type list) -checks:skip [process-type(s)] Skip zero-downtime checks for all processes (or comma-separated process-type list) +checks:disable [process-type(s)] Disable zero-downtime deployment for all processes (or comma-separated process-type list) ***WARNING: this will cause downtime during deployments*** +checks:enable [process-type(s)] Enable zero-downtime deployment for all processes (or comma-separated process-type list) +checks:report [] [] Displays a checks report for one or more apps +checks:run [process-type(s)] Runs zero-downtime checks for all processes (or comma-separated process-type list) +checks:set [--global|] Set or clear a logs property for an app +checks:skip [process-type(s)] Skip zero-downtime checks for all processes (or comma-separated process-type list) ``` By default, Dokku will wait `10` seconds after starting each container before assuming it is up and proceeding with the deploy. Once this has occurred for all containers started by an application, traffic will be switched to point to your new containers. Dokku will also wait a further `60` seconds *after* the deploy is complete before terminating old containers in order to give time for long running connections to terminate. In either case, you may have more than one container running for a given application. @@ -22,13 +23,24 @@ You may both create user-defined checks for web processes using a `CHECKS` file, > - Allow checks from all hostnames: Modify your application to accept a dynamically provided hostname. > - Specify the domain within the check: See below for further documentation. +## Configuring checks settings + +### wait-to-retire + +After a successful deploy, the grace period given to old containers before they are stopped/terminated is determined by the value of `wait-to-retire`. This is useful for ensuring completion of long-running HTTP connections. + +```shell +dokku checks:set node-js-app wait-to-retire 30 +``` + +Defaults to `60`. + ## Configuring check settings using the `config` plugin There are certain settings that can be configured via environment variables: - `DOKKU_DEFAULT_CHECKS_WAIT`: (default: `10`) If no user-defined checks are specified - or if the process being checked is not a `web` process - this is the period of time Dokku will wait before checking that a container is still running. - `DOKKU_DOCKER_STOP_TIMEOUT`: (default: `10`) Configurable grace period given to the `docker stop` command. If a container has not stopped by this time, a `kill -9` signal or equivalent is sent in order to force-terminate the container. Both the `ps:stop` and `apps:destroy` commands *also* respect this value. If not specified, the Docker defaults for the [`docker stop` command](https://docs.docker.com/engine/reference/commandline/stop/) will be used. -- `DOKKU_WAIT_TO_RETIRE`: (default: `60`) After a successful deploy, the grace period given to old containers before they are stopped/terminated. This is useful for ensuring completion of long-running HTTP connections. The following settings may also be specified in the `CHECKS` file, though are available as environment variables in order to ease application reuse. @@ -82,13 +94,22 @@ dokku checks:report ``` =====> node-js-app checks information Checks disabled list: none - Checks skipped list: none + Checks skipped list: none + Checks computed wait to retire: 60 + Checks global wait to retire: 60 + Checks wait to retire: =====> python-app checks information Checks disabled list: none - Checks skipped list: none + Checks skipped list: none + Checks computed wait to retire: 60 + Checks global wait to retire: 60 + Checks wait to retire: =====> ruby-app checks information Checks disabled list: _all_ - Checks skipped list: none + Checks skipped list: none + Checks computed wait to retire: 60 + Checks global wait to retire: 60 + Checks wait to retire: ``` You can run the command for a specific app also. @@ -100,7 +121,10 @@ dokku checks:report node-js-app ``` =====> node-js-app checks information Checks disabled list: none - Checks skipped list: none + Checks skipped list: none + Checks computed wait to retire: 60 + Checks global wait to retire: 60 + Checks wait to retire: ``` You can pass flags which will output only the value of the specific information you want. For example: diff --git a/docs/development/plugin-triggers.md b/docs/development/plugin-triggers.md index c8b6edb7d1e..74f5cd255ac 100644 --- a/docs/development/plugin-triggers.md +++ b/docs/development/plugin-triggers.md @@ -262,6 +262,22 @@ if [[ "$DOKKU_DISABLE_DEPLOY" = "true" ]]; then fi ``` +### `checks-get-property` + +- Description: Return the value for an app's checks property +- Invoked by: +- Arguments: `$APP $KEY` +- Example: + +```shell +#!/usr/bin/env bash + +set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x +APP="$1"; PROPERTY="$2" + +# TODO +``` + ### `commands help` and `commands :help` - Description: Your plugin should implement a `help` command in your `commands` file to take advantage of this plugin trigger. `commands help` is used by `dokku help` to aggregate all plugins abbreviated `help` output. Implementing `:help` in your `commands` file gives users looking for help, a more detailed output. 'commands help' must be implemented inside the `commands` plugin file. It's recommended that `PLUGIN_NAME:help` be added to the commands file to ensure consistency among community plugins and give you a new avenue to share rich help content with your user. @@ -869,9 +885,9 @@ fi ### `logs-get-property` -- Description: Fetches a given logs property value +- Description: Return the value for an app's log property - Invoked by: -- Arguments: `$APP` `$PROPERTY` +- Arguments: `$APP $KEY` - Example: ```shell @@ -990,7 +1006,7 @@ set -eo pipefail; [[ $DOKKU_TRACE ]] && set -x ### `network-get-property` -- Description: Return the network value for an app's property +- Description: Return the value for an app's network property - Invoked by: `internally triggered by a deploy` - Arguments: `$APP $KEY` - Example: diff --git a/plugins/checks/checks-get-property b/plugins/checks/checks-get-property new file mode 100755 index 00000000000..f8ce96af7be --- /dev/null +++ b/plugins/checks/checks-get-property @@ -0,0 +1,19 @@ +#!/usr/bin/env bash +set -eo pipefail +source "$PLUGIN_AVAILABLE_PATH/checks/internal-functions" +[[ $DOKKU_TRACE ]] && set -x + +trigger-checks-checks-get-property() { + declare desc="return the value for an app's checks property" + declare trigger="checks-get-property" + declare APP="$1" KEY="$2" + + if [[ "$KEY" == "wait-to-retire" ]]; then + fn-checks-computed-wait-to-retire "$APP" + return + fi + + return 1 +} + +trigger-checks-checks-get-property "$@" diff --git a/plugins/checks/install b/plugins/checks/install index f6321f86b67..7ee6f8b9aca 100755 --- a/plugins/checks/install +++ b/plugins/checks/install @@ -2,8 +2,15 @@ set -eo pipefail [[ $DOKKU_TRACE ]] && set -x source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions" +source "$PLUGIN_CORE_AVAILABLE_PATH/common/property-functions" source "$PLUGIN_AVAILABLE_PATH/config/functions" +migrate_checks_vars_0_29_0() { + declare desc="migrates deprecated DOKKU_WAIT_TO_RETIRE config variables to property counter part introduced in 0.29.x" + + fn-migrate-config-to-property "checks" "wait-to-retire" "DOKKU_WAIT_TO_RETIRE" "DOKKU_WAIT_TO_RETIRE" +} + migrate_checks_vars_0_5_0() { declare desc="migrates deprecated CHECKS config variables to simplified counter part introduced in 0.5.x" local GLOBAL_SKIP_ALL_CHECKS=$(config_get --global DOKKU_SKIP_ALL_CHECKS || true) @@ -54,8 +61,10 @@ trigger-checks-install() { declare desc="installs the checks plugin" declare trigger="install" + fn-plugin-property-setup "checks" migrate_checks_vars_0_5_0 "$@" migrate_checks_vars_0_6_0 "$@" + migrate_checks_vars_0_29_0 "$@" } trigger-checks-install "$@" diff --git a/plugins/checks/internal-functions b/plugins/checks/internal-functions index fe125bf08c0..faf4daeb102 100755 --- a/plugins/checks/internal-functions +++ b/plugins/checks/internal-functions @@ -37,6 +37,9 @@ cmd-checks-report-single() { local flag_map=( "--checks-disabled-list: $(fn-checks-disabled-list "$APP")" "--checks-skipped-list: $(fn-checks-skipped-list "$APP")" + "--checks-computed-wait-to-retire: $(fn-checks-computed-wait-to-retire "$APP")" + "--checks-global-wait-to-retire: $(fn-checks-global-wait-to-retire "$APP")" + "--checks-wait-to-retire: $(fn-checks-wait-to-retire "$APP")" ) if [[ -z "$INFO_FLAG" ]]; then @@ -80,3 +83,26 @@ fn-checks-skipped-list() { DOKKU_CHECKS_SKIPPED="${DOKKU_CHECKS_SKIPPED:-none}" echo "$DOKKU_CHECKS_SKIPPED" } + +fn-checks-computed-wait-to-retire() { + declare APP="$1" + + file="$(fn-checks-wait-to-retire "$APP")" + if [[ "$file" == "" ]]; then + file="$(fn-checks-global-wait-to-retire "$APP")" + fi + + echo "$file" +} + +fn-checks-global-wait-to-retire() { + declare APP="$1" + + fn-plugin-property-get "checks" "--global" "wait-to-retire" "60" +} + +fn-checks-wait-to-retire() { + declare APP="$1" + + fn-plugin-property-get "checks" "$APP" "wait-to-retire" "" +} diff --git a/plugins/checks/subcommands/set b/plugins/checks/subcommands/set new file mode 100755 index 00000000000..e40855da5a9 --- /dev/null +++ b/plugins/checks/subcommands/set @@ -0,0 +1,37 @@ +#!/usr/bin/env bash +source "$PLUGIN_CORE_AVAILABLE_PATH/common/functions" +source "$PLUGIN_CORE_AVAILABLE_PATH/common/property-functions" +set -eo pipefail +[[ $DOKKU_TRACE ]] && set -x + +cmd-checks-set() { + declare desc="set or clear a checks property for an app" + declare cmd="checks:set" + [[ "$1" == "$cmd" ]] && shift 1 + declare APP="$1" KEY="$2" VALUE="$3" + local VALID_KEYS=("wait-to-retire") + [[ "$APP" == "--global" ]] || verify_app_name "$APP" + + [[ -z "$KEY" ]] && dokku_log_fail "No key specified" + + if ! fn-in-array "$KEY" "${VALID_KEYS[@]}"; then + dokku_log_fail "Invalid key specified, valid keys include: wait-to-retire" + fi + + if [[ -n "$VALUE" ]]; then + dokku_log_info2_quiet "Setting ${KEY} to ${VALUE}" + fn-plugin-property-write "checks" "$APP" "$KEY" "$VALUE" + else + dokku_log_info2_quiet "Unsetting ${KEY}" + if [[ "$KEY" == "rev-env-var" ]]; then + fn-plugin-property-write "checks" "$APP" "$KEY" "$VALUE" + else + fn-plugin-property-delete "checks" "$APP" "$KEY" + if [[ "$KEY" == "enabled" ]]; then + fn-plugin-property-destroy "checks" "$APP" + fi + fi + fi +} + +cmd-checks-set "$@" diff --git a/plugins/common/functions b/plugins/common/functions index 1261774a65d..2205274186a 100755 --- a/plugins/common/functions +++ b/plugins/common/functions @@ -1143,3 +1143,35 @@ suppress_output() { } return 0 } + +fn-migrate-config-to-property() { + declare desc="migrates deprecated config variables to property counterpart" + declare PLUGIN="$1" KEY="$2" CONFIG_VAR="$3" GLOBAL_CONFIG_VAR="$4" + + # todo: refactor to remove config_unset usage + if ! declare -f -F config_unset >/dev/null; then + source "$PLUGIN_AVAILABLE_PATH/config/functions" + fi + + if ! declare -f -F fn-plugin-property-write >/dev/null; then + source "$PLUGIN_CORE_AVAILABLE_PATH/common/property-functions" + fi + + if [[ -n "$GLOBAL_CONFIG_VAR" ]]; then + local value=$(plugn trigger config-get-global "$GLOBAL_CONFIG_VAR" || true) + if [[ -n "$value" ]]; then + dokku_log_info1 "Migrating deprecated global $GLOBAL_CONFIG_VAR to $PLUGIN $KEY property." + fn-plugin-property-write "$PLUGIN" --global "$KEY" "$value" + DOKKU_QUIET_OUTPUT=1 config_unset --global "$GLOBAL_CONFIG_VAR" || true + fi + fi + + for app in $(dokku_apps "false"); do + local value=$(plugn trigger config-get "$app" "$CONFIG_VAR" || true) + if [[ -n "$value" ]]; then + dokku_log_info1 "Migrating deprecated $CONFIG_VAR to $PLUGIN $KEY property for $app." + fn-plugin-property-write "$PLUGIN" "$app" "$KEY" "$value" + DOKKU_QUIET_OUTPUT=1 config_unset --no-restart "$app" "$CONFIG_VAR" || true + fi + done +} diff --git a/plugins/scheduler-docker-local/scheduler-deploy b/plugins/scheduler-docker-local/scheduler-deploy index b71f4c81955..b9fbdae7beb 100755 --- a/plugins/scheduler-docker-local/scheduler-deploy +++ b/plugins/scheduler-docker-local/scheduler-deploy @@ -37,13 +37,8 @@ trigger-scheduler-docker-local-scheduler-deploy() { DOKKU_START_CMD="$(config_get "$APP" DOKKU_START_CMD || true)" - if [[ -z "$DOKKU_WAIT_TO_RETIRE" ]]; then - local DOKKU_APP_DOKKU_WAIT_TO_RETIRE=$(config_get "$APP" DOKKU_WAIT_TO_RETIRE || true) - local DOKKU_GLOBAL_DOKKU_WAIT_TO_RETIRE=$(config_get --global DOKKU_WAIT_TO_RETIRE || true) - local DOKKU_WAIT_TO_RETIRE=${DOKKU_APP_DOKKU_WAIT_TO_RETIRE:="$DOKKU_GLOBAL_DOKKU_WAIT_TO_RETIRE"} - fi - - export DOKKU_WAIT_TO_RETIRE="${DOKKU_WAIT_TO_RETIRE:-60}" + local DOKKU_WAIT_TO_RETIRE="$(plugn trigger checks-get-property "$APP" wait-to-retire)" + export DOKKU_WAIT_TO_RETIRE local TMP_FILE=$(mktemp "/tmp/dokku-${DOKKU_PID}-${FUNCNAME[0]}.XXXXXX") trap "rm -rf '$TMP_FILE' >/dev/null" RETURN INT TERM diff --git a/tests/unit/registry.bats b/tests/unit/registry.bats index 67bb6adf370..403e68f9d30 100644 --- a/tests/unit/registry.bats +++ b/tests/unit/registry.bats @@ -5,7 +5,7 @@ load test_helper setup() { global_setup create_app - dokku config:set $TEST_APP DOKKU_WAIT_TO_RETIRE=30 + dokku checks:set $TEST_APP wait-to-retire 30 } teardown() {