[gantry] Do not change replicas after updating.

Author: shizunge

README.md

@@ -92,7 +92,7 @@ You can configure the most behaviors of *Gantry* via environment variables.
 | GANTRY_ROLLBACK_OPTIONS       |       | [Options](https://docs.docker.com/engine/reference/commandline/service_update/#options) added to the `docker service update --rollback` command for all services. You can apply a different value to a particular service via [labels](#labels). |
 | GANTRY_UPDATE_JOBS            | false | Set to `true` to update `replicated-job` or `global-job`. Set to `false` to disable updating jobs. *Gantry* adds additional options to `docker service update` when there is [no running tasks](docs/faq.md#how-to-update-services-with-no-running-tasks). You can apply a different value to a particular service via [labels](#labels). |
 | GANTRY_UPDATE_NUM_WORKERS     | 1     | The maximum number of updates that can run in parallel. |
-| GANTRY_UPDATE_OPTIONS         |       | [Options](https://docs.docker.com/engine/reference/commandline/service_update/#options) added to the `docker service update` command for all services. You can apply a different value to a particular service via [labels](#labels). |
+| GANTRY_UPDATE_OPTIONS         |       | [Options](https://docs.docker.com/engine/reference/commandline/service_update/#options) added to the `docker service update` command for all services. This also overrides any automatically added options. You can apply a different value to a particular service via [labels](#labels). |
 | GANTRY_UPDATE_TIMEOUT_SECONDS | 0     | Error out if updating of a single service takes longer than the given time. Set to `0` to disable timeout. You can apply a different value to a particular service via [labels](#labels). |
 
 ### After updating

docs/faq.md

@@ -26,9 +26,11 @@ You can start *Gantry* as a docker swarm service and use [`swarm-cronjob`](https
 
 ## How to update services with no running tasks?
 
-As discussed in [docker/cli/issues/627](https://github.com/docker/cli/issues/627), the CLI will hang when running `docker service update` on a service with no running tasks. We must add `--detach=true` option to the `docker service update`.
+As discussed in [docker/cli/issues/627](https://github.com/docker/cli/issues/627), the Docker CLI hangs when `docker service update` is running on a service with no running tasks, requiring the option `--detach=true` to be added.
 
-*Gantry* will check whether there are running tasks in a service. If there is no running task, *Gantry* automatically adds the option `--detach=true`. In addition to the detach option, *Gantry* also adds `--replicas=0` for services in replicated mode. You don't need to add these options manually.
+*Gantry* checks whether a service has running tasks. When none are found, it automatically adds the option `--detach=true`.
+
+To keep replicas at zero after an update, which prevents tasks from starting, add the [label](../README.md#labels) `gantry.update.options=--replicas=0` to the service. Note that `--replicas=0` only applies to services in replicated mode, it causes errors in global mode. See the [example](../examples/cronjob).
 
 ## Which `GANTRY_MANIFEST_CMD` to use?
 

examples/cronjob/README.md

@@ -2,6 +2,6 @@
 
 Use [*swarm-cronjob*](https://github.com/crazy-max/swarm-cronjob) to launch [*Gantry*](https://github.com/shizunge/gantry) at a specific time.
 
-In this example, we only want to run *Gantry* at the specific time, therefore we set `replicas` to `0` on the *Gantry* service to avoid running it as soon as the service is deployed. We also need to set `restart_policy.condition` to `none` to prevent *Gantry* from restarting automatically after a cronjob.
+In this example, we only want to run *Gantry* at the specific time, therefore we set `replicas` to `0` on the *Gantry* service to avoid running it as soon as the service is deployed. We also need to set `restart_policy.condition` to `none` to prevent *Gantry* from restarting automatically after a cronjob. Refer to the [*swarm-cronjob* document](https://crazymax.dev/swarm-cronjob/) for more information.
 
-Refer to the [*swarm-cronjob* document](https://crazymax.dev/swarm-cronjob/) for more information.
+*service_to_be_updated* is another service managed by the *swarm-cronjob* and updated by *Gantry*. The label `gantry.update.options=--replicas=0` is set on the service so that only *swarm-cronjob* starts it. Updating the image does not start the service.

examples/cronjob/docker-compose.yml

@@ -16,9 +16,9 @@ services:
       restart_policy:
         condition: none
       labels:
-        - swarm.cronjob.enable=true
-        - swarm.cronjob.schedule=45 23 0 * * *
-        - swarm.cronjob.skip-running=true
+        - "swarm.cronjob.enable=true"
+        - "swarm.cronjob.schedule=45 23 0 * * *"
+        - "swarm.cronjob.skip-running=true"
 
   cronjob:
     image: crazymax/swarm-cronjob:latest
@@ -28,3 +28,25 @@ services:
       placement:
         constraints:
           - node.role==manager
+
+  # Another service to be updated.
+  service_to_be_updated:
+    image: docker
+    command: ["docker", "system", "prune", "-f"]
+    volumes:
+      - "/var/run/docker.sock:/var/run/docker.sock"
+    deploy:
+      replicas: 0
+      placement:
+        constraints:
+          - node.role==manager
+      restart_policy:
+        condition: none
+      labels:
+        - "swarm.cronjob.enable=true"
+        - "swarm.cronjob.schedule=0 */5 * * * *"
+        - "swarm.cronjob.skip-running=false"
+        # Add "gantry.update.options=--replicas=0" to prevent tasks from starting after the update.
+        # Start the tasks via cronjob only.
+        # "--replicas=0" only applies to services in replicated mode, it cannot be used with services in global mode.
+        - "gantry.update.options=--replicas=0"

src/lib-gantry.sh

@@ -1013,22 +1013,20 @@ _get_service_update_additional_options() {
   local SERVICE_NAME="${1}"
   local IMAGE_UPDATE_TO="${2}"
   local AUTH_CONFIG="${3}"
-  local NUM_RUNS=
-  NUM_RUNS=$(_get_number_of_running_tasks "${SERVICE_NAME}")
-  ! is_number "${NUM_RUNS}" && log WARN "NUM_RUNS \"${NUM_RUNS}\" is not a number." && return 1
+  local RETURN_VALUE=0
   local OPTIONS=
   local SPACE=
-  if [ "${NUM_RUNS}" = "0" ]; then
-    # Add "--detach=true" when there is no running tasks.
-    # https://github.com/docker/cli/issues/627
-    OPTIONS="${OPTIONS}${SPACE}--detach=true"
-    SPACE=" "
-    local MODE=
-    # Do not start a new task. Only works for replicated, not global.
-    if MODE=$(_service_is_replicated "${SERVICE_NAME}"); then
-      OPTIONS="${OPTIONS}${SPACE}--replicas=0"
+  local NUM_RUNS=
+  NUM_RUNS=$(_get_number_of_running_tasks "${SERVICE_NAME}")
+  if is_number "${NUM_RUNS}"; then
+    if [ "${NUM_RUNS}" = "0" ]; then
+      # Add "--detach=true" when there is no running tasks.
+      # https://github.com/docker/cli/issues/627
+      OPTIONS="${OPTIONS}${SPACE}--detach=true"
       SPACE=" "
     fi
+  else
+    log WARN "NUM_RUNS \"${NUM_RUNS}\" is not a number." && RETURN_VALUE=1
   fi
   # Add `--with-registry-auth` if needed.
   local WITH_REGISTRY_AUTH=
@@ -1048,6 +1046,31 @@ _get_service_update_additional_options() {
     SPACE=" "
   fi
   echo "${OPTIONS}"
+  return "${RETURN_VALUE}"
+}
+
+_warn_no_running_task() {
+  local SERVICE_NAME="${1}"
+  local OPTIONS="${2}"
+  local NUM_RUNS=
+  NUM_RUNS=$(_get_number_of_running_tasks "${SERVICE_NAME}")
+  ! is_number "${NUM_RUNS}" && log WARN "NUM_RUNS \"${NUM_RUNS}\" is not a number." && return 1
+  if [ "${NUM_RUNS}" != "0" ]; then
+    return 0
+  fi
+  # Warning for replicated, not global, as "--replicas" only works on replicated, not global.
+  local MODE=
+  if MODE=$(! _service_is_replicated "${SERVICE_NAME}"); then
+    return 0
+  fi
+  # Now, the number of running task is 0, the mode is replicated.
+  # If "--replicas=" is already part of the option, no warning.
+  if [ -n "${OPTIONS}" ] && echo "${OPTIONS}" | grep_q "--replicas="; then
+    return 0
+  fi
+  local MSG="Service ${SERVICE_NAME} is in ${MODE} mode and has no running task before updating."
+  MSG="${MSG} Adding label \"gantry.update.options=--replicas=0\" to the service to prevent tasks from starting after the update."
+  log WARN "${MSG}"
 }
 
 _get_service_rollback_additional_options() {
@@ -1132,6 +1155,7 @@ _update_single_service() {
   [ -n "${AUTH_CONFIG}" ] && log INFO "Adding options \"${AUTH_CONFIG}\" to the command ${CMD_STRING} for ${SERVICE_NAME}."
   [ -n "${AUTOMATIC_OPTIONS}" ] && log INFO "Adding options \"${AUTOMATIC_OPTIONS}\" automatically to the command ${CMD_STRING} for ${SERVICE_NAME}."
   [ -n "${UPDATE_OPTIONS}" ] && log INFO "Adding options \"${UPDATE_OPTIONS}\" specified by user to the command ${CMD_STRING} for ${SERVICE_NAME}."
+  _warn_no_running_task "${SERVICE_NAME}" "${AUTOMATIC_OPTIONS} ${UPDATE_OPTIONS}"
   local TIMEOUT_COMMAND=
   TIMEOUT_COMMAND=$(_get_timeout_command "${SERVICE_NAME}") || return 1
   local SPACE_T=

tests/gantry_login_spec.sh

@@ -79,8 +79,8 @@ Describe 'login'
       The stderr should satisfy spec_expect_message    "${NUM_SERVICES_UPDATING}"
       The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS}.*--config ${AUTH_CONFIG}.*${SERVICE_NAME}"
       # 2 "--with-registry-auth" for SERVICE_NAME. One is automatically added. The other is from user.
-      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS_WITH_REGISTRY_AUTH}.*automatically.*${SERVICE_NAME}"
-      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS_WITH_REGISTRY_AUTH}.*specified by user.*${SERVICE_NAME}"
+      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS_WITH_REGISTRY_AUTH}.*${AUTOMATICALLY}.*${SERVICE_NAME}"
+      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS_WITH_REGISTRY_AUTH}.*${SPECIFIED_BY_USER}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_no_message "${FROM_DOCKER_IMAGE_DIGEST_WARNING}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_no_message "${DOES_NOT_HAVE_A_DIGEST}"
       The stderr should satisfy spec_expect_message    "${UPDATED}.*${SERVICE_NAME}"