Merge pull request #60 from shizunge/readme

[gantry] Do not add --with-registry-auth to rollback cmd.
shizunge · Sep 28, 2024 · e8ee9dd · e8ee9dd
2 parents 657a0e3 + ad6a2a0
commit e8ee9dd
Show file tree

Hide file tree

Showing 4 changed files with 36 additions and 34 deletions.
diff --git a/docs/migration.md b/docs/migration.md
@@ -3,7 +3,7 @@
 *Gantry* started to fix the following problems I found in [*shepherd*](https://github.com/containrrr/shepherd), then it became refactored and totally rewritten, with [abundant tests](../tests/README.md).
 
 * `docker manifest` CLI failed to get the image meta data for some registries.
-* High usage of docker hub rate. Getting manifest and then pulling the image double the usage.
+* High usage of Docker Hub rate. Getting manifest and then pulling the image double the usage.
 * Running `docker service update` command when there is no new image slows down the overall process.
 * Removing images related
     * Failure of removing old images will exit and block subsequent updating.
@@ -40,34 +40,36 @@ The label on the services to select config to enable authentication is renamed t
 | *Shepherd* Env | Workaround |
 |----------------|------------|
 | VERBOSE                | Use `GANTRY_LOG_LEVEL` |
-| WITH_REGISTRY_AUTH     | Manually add `--with-registry-auth` to `GANTRY_UPDATE_OPTIONS` and `GANTRY_ROLLBACK_OPTIONS`. |
-| WITH_INSECURE_REGISTRY | Manually add `--insecure` to `GANTRY_MANIFEST_OPTIONS`, `GANTRY_UPDATE_OPTIONS` and `GANTRY_ROLLBACK_OPTIONS`. |
-| WITH_NO_RESOLVE_IMAGE  | Manually add `--no-resolve-image` to `GANTRY_UPDATE_OPTIONS` and `GANTRY_ROLLBACK_OPTIONS`. |
-| IMAGE_AUTOCLEAN_LIMIT  | Use `GANTRY_CLEANUP_IMAGES`. *Gantry* will only clean up the updated images. |
+| WITH_REGISTRY_AUTH     | *Gantry* automatically adds `--with-registry-auth` to the `docker service update` command for a sevice, when it finds the label `gantry.auth.config=<config-name>` on the service. Or manually add `--with-registry-auth` to `GANTRY_UPDATE_OPTIONS`. |
+| WITH_INSECURE_REGISTRY | Manually add `--insecure` to `GANTRY_MANIFEST_OPTIONS` and set `GANTRY_MANIFEST_CMD` to `manifest`. |
+| WITH_NO_RESOLVE_IMAGE  | Manually add `--no-resolve-image` to `GANTRY_UPDATE_OPTIONS`. |
+| IMAGE_AUTOCLEAN_LIMIT  | Use `GANTRY_CLEANUP_IMAGES`. *Gantry* only cleans up the images being updated, thus we no longer need a limit. |
 | RUN_ONCE_AND_EXIT      | Set `GANTRY_SLEEP_SECONDS` to 0. |
 
 ### New configurations
 
-| *Gantry* Env  |
-|---------------|
-| GANTRY_CLEANUP_IMAGES            |
-| GANTRY_LOG_LEVEL                 |
-| GANTRY_MANIFEST_CMD              |
-| GANTRY_MANIFEST_NUM_WORKERS      |
-| GANTRY_MANIFEST_OPTIONS          |
-| GANTRY_NOTIFICATION_CONDITION    |
-| GANTRY_NOTIFICATION_TITLE        |
-| GANTRY_POST_RUN_CMD              |
-| GANTRY_PRE_RUN_CMD               |
-| GANTRY_REGISTRY_CONFIG           |
-| GANTRY_REGISTRY_CONFIG_FILE      |
-| GANTRY_REGISTRY_HOST_FILE        |
-| GANTRY_REGISTRY_PASSWORD_FILE    |
-| GANTRY_REGISTRY_USER_FILE        |
-| GANTRY_SERVICES_EXCLUDED_FILTERS |
-| GANTRY_SERVICES_SELF             |
-| GANTRY_UPDATE_JOBS               |
-| GANTRY_UPDATE_NUM_WORKERS        |
+| *Gantry* Env  | Purpose |
+|---------------|----------------------|
+| GANTRY_CLEANUP_IMAGES            | To control whether *Gantry* cleans up images on all hosts. *Gantry* only cleans up the images being updated. |
+| GANTRY_LOG_LEVEL                 | To introduce more granularity on log levels. *Gantry* can go total slience by setting `GANTRY_LOG_LEVEL` to `NONE`. |
+| GANTRY_MANIFEST_CMD              | To retrieve image metadata correctly and to reduce the Docker Hub rate usage. |
+| GANTRY_MANIFEST_NUM_WORKERS      | To run multiple manifest commands in parallel to accelerate the updating process. |
+| GANTRY_MANIFEST_OPTIONS          | To customize `GANTRY_MANIFEST_CMD`. |
+| GANTRY_NOTIFICATION_CONDITION    | To control notification. *Gantry* only send a summary of updating at the end of each iteration, which includes lists of updated services and errors. |
+| GANTRY_NOTIFICATION_TITLE        | To customize notification. *Gantry* only send a summary of updating at the end of each iteration, which includes lists of updated services and errors. |
+| GANTRY_POST_RUN_CMD              | To run customized tasks together with *Gantry*. See the [example](../examples/prune-and-watchtower). |
+| GANTRY_PRE_RUN_CMD               | To run customized tasks together with *Gantry*. See the [example](../examples/prune-and-watchtower). |
+| GANTRY_REGISTRY_CONFIG           | To apply authentication to only selected services. To use simple authentication configurations together with `GANTRY_REGISTRY_CONFIGS_FILE`. |
+| GANTRY_REGISTRY_CONFIG_FILE      | To pass sensitive information via [docker secret](https://docs.docker.com/engine/swarm/secrets/). |
+| GANTRY_REGISTRY_HOST_FILE        | To pass sensitive information via [docker secret](https://docs.docker.com/engine/swarm/secrets/). |
+| GANTRY_REGISTRY_PASSWORD_FILE    | To pass sensitive information via [docker secret](https://docs.docker.com/engine/swarm/secrets/). |
+| GANTRY_REGISTRY_USER_FILE        | To pass sensitive information via [docker secret](https://docs.docker.com/engine/swarm/secrets/). |
+| GANTRY_SERVICES_EXCLUDED_FILTERS | To provide an alternative method to exclude services from being updated. |
+| GANTRY_SERVICES_SELF             | To avoid an infinity loop of updating itself. You don't need to set this, because *Gantry* should find the value automatically. |
+| GANTRY_UPDATE_JOBS               | *Gantry* can distinguish `replicated-job` and `global-job` from other services. *Gantry* automatically adds more options to [update services with no running tasks](faq.md#how-to-update-services-with-no-running-tasks) to avoid hanging. |
+| GANTRY_UPDATE_NUM_WORKERS        | To run multiple update commands in parallel to accelerate the updating process. |
+
+Besides the global configurations via environment variables, you can apply a different value to a particular service via [labels](../README.md#labels).
 
 ### License
 

diff --git a/examples/webhook/README.md b/examples/webhook/README.md
@@ -18,7 +18,7 @@ Use the following command to deploy the Docker Compose stack that includes the w
 docker stack deploy --detach=true --prune --with-registry-auth --compose-file ./docker-compose.yml webhook
 ```
 
-Use curl to send a POST request to the webhook endpoint. This request tells the *Gantry* to only update the service named "webhook_webhook".
+Use `curl` to send a `POST` request to the webhook endpoint. This request tells the *Gantry* to only update the service named *webhook_webhook*.
 
 ```
 curl -X POST localhost:9000/hooks/run-gantry -H "Content-Type: application/json"  -d '{"GANTRY_SERVICES_FILTERS":"name=webhook_webhook"}'

diff --git a/src/lib-gantry.sh b/src/lib-gantry.sh
@@ -821,10 +821,8 @@ _get_service_rollback_additional_options() {
   local SERVICE_NAME="${1}"
   local DOCKER_CONFIG="${2}"
   local OPTIONS=
-  # Add `--with-registry-auth` if needed.
-  local WITH_REGISTRY_AUTH=
-  WITH_REGISTRY_AUTH="$(_get_with_registry_auth "${DOCKER_CONFIG}")"
-  [ -n "${WITH_REGISTRY_AUTH}" ] && OPTIONS="${OPTIONS} ${WITH_REGISTRY_AUTH}"
+  # Place holder function. Nothing to do here yet.
+  # --with-registry-auth cannot be combined with --rollback.
   echo "${OPTIONS}"
 }
 

diff --git a/tests/gantry_rollback_spec.sh b/tests/gantry_rollback_spec.sh
@@ -76,7 +76,8 @@ Describe 'rollback'
       # Assume service update won't be done within TIMEOUT second.
       export GANTRY_UPDATE_TIMEOUT_SECONDS="${TIMEOUT}"
       # Rollback would fail due to the incorrect option.
-      export GANTRY_ROLLBACK_OPTIONS="--incorrect-option"
+      # --with-registry-auth cannot be combined with --rollback.
+      export GANTRY_ROLLBACK_OPTIONS="--with-registry-auth"
       run_gantry "${TEST_NAME}"
     }
     BeforeEach "common_setup_timeout ${TEST_NAME} ${IMAGE_WITH_TAG} ${SERVICE_NAME} ${TIMEOUT}"
@@ -94,7 +95,7 @@ Describe 'rollback'
       The stderr should satisfy spec_expect_message    "${NUM_SERVICES_UPDATING}"
       The stderr should satisfy spec_expect_no_message "${UPDATED}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_no_message "${NO_UPDATES}.*${SERVICE_NAME}"
-      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS}.*--incorrect-option.*${SERVICE_NAME}"
+      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS}.*--with-registry-auth.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_message    "${ROLLING_BACK}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_message    "${FAILED_TO_ROLLBACK}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_no_message "${ROLLED_BACK}.*${SERVICE_NAME}"
@@ -218,7 +219,8 @@ Describe 'rollback'
       local LABEL_AND_VALUE="gantry.update.timeout_seconds=${TIMEOUT}"
       docker service update --quiet --label-add "${LABEL_AND_VALUE}" "${SERVICE_NAME}"
       # Rollback would fail due to the incorrect option.
-      LABEL_AND_VALUE="gantry.rollback.options=--incorrect-option"
+      # --with-registry-auth cannot be combined with --rollback.
+      LABEL_AND_VALUE="gantry.rollback.options=--with-registry-auth"
       docker service update --quiet --label-add "${LABEL_AND_VALUE}" "${SERVICE_NAME}"
       run_gantry "${TEST_NAME}"
     }
@@ -237,7 +239,7 @@ Describe 'rollback'
       The stderr should satisfy spec_expect_message    "${NUM_SERVICES_UPDATING}"
       The stderr should satisfy spec_expect_no_message "${UPDATED}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_no_message "${NO_UPDATES}.*${SERVICE_NAME}"
-      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS}.*--incorrect-option.*${SERVICE_NAME}"
+      The stderr should satisfy spec_expect_message    "${ADDING_OPTIONS}.*--with-registry-auth.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_message    "${ROLLING_BACK}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_message    "${FAILED_TO_ROLLBACK}.*${SERVICE_NAME}"
       The stderr should satisfy spec_expect_no_message "${ROLLED_BACK}.*${SERVICE_NAME}"