Merge pull request #25 from grapl-security/cm/always-pull

Add an `always-pull` option

Author: christophermaier

.buildkite/pipeline.verify.yml

@@ -40,3 +40,12 @@ steps:
       - "grapl-security/vault-login#${BUILDKITE_COMMIT}":
       - improbable-eng/metahook#v0.4.1:
           pre-exit: .buildkite/scripts/pre-exit-hook-validation.sh
+
+  - label: ":buildkite::vault: Validate Plugin Behavior with pull"
+    command:
+      - .buildkite/scripts/environment-hook-validation.sh
+    plugins:
+      - "grapl-security/vault-login#${BUILDKITE_COMMIT}":
+          always-pull: true
+      - improbable-eng/metahook#v0.4.1:
+          pre-exit: .buildkite/scripts/pre-exit-hook-validation.sh

README.md

@@ -82,38 +82,29 @@ Setting `attempt_count` to `1` effectively disables the retry logic.
 
 ## Configuration
 
-### `address` (optional, string)
+### `vault` Flags
+
+#### `address` (optional, string)
 
 The address of the Vault server to access. If not set, falls back to
 `VAULT_ADDR` in the environment. If `VAULT_ADDR` is not set either,
 the plugin fails with an error.
 
-### `auth_role` (optional, string)
+#### `auth_role` (optional, string)
 
 The name of the Vault AWS role to authenticate as. If not specified,
 uses (Grapl-specific) logic to generate the role name from the
 Buildkite agent queue name.
 
-### `image` (optional, string)
-
-The container image with the `vault` binary that the plugin uses. Any
-container used should have the `vault` binary as its entrypoint.
-
-Defaults to `hashicorp/vault`.
-
-### `namespace` (optional, string)
+#### `namespace` (optional, string)
 
 The Vault namespace to access. If not set, falls back to
 `VAULT_NAMESPACE` in the environment. If `VAULT_NAMESPACE` is not set
 either, the plugin fails with an error.
 
-### `tag` (optional, string)
+### Retry Configuration
 
-The container image tag the plugin uses.
-
-Defaults to `latest`.
-
-### `attempt_count` (optional, integer)
+#### `attempt_count` (optional, integer)
 
 The number of times to attempt to login to Vault before giving
 up.
@@ -122,12 +113,35 @@ Defaults to `3`.
 
 You can disable retries by setting this to `1`.
 
-### `attempt_wait_seconds` (optional, integer)
+#### `attempt_wait_seconds` (optional, integer)
 
 The number of seconds to wait between each retry attempt.
 
 Defaults to `5`.
 
+### Container Image Configuration
+
+#### `image` (optional, string)
+
+The container image with the `vault` binary that the plugin uses. Any
+container used should have the `vault` binary as its entrypoint.
+
+Defaults to `hashicorp/vault`.
+
+#### `tag` (optional, string)
+
+The container image tag the plugin uses.
+
+Defaults to `latest`.
+
+#### `always_pull` (optional, boolean)
+
+Whether or not to perform an explicit `docker pull` of the configured
+image before running. Useful when using the `latest` tag to ensure you
+are always using the _actual_ latest image.
+
+Defaults to `false`.
+
 ## Building
 
 Requires `make`, `docker`, and Docker Compose v2.

hooks/environment

@@ -65,6 +65,8 @@ if (("${attempt_wait_seconds}" < 1)); then
     raise_error "Must provide a positive value for attempt_wait_seconds!"
 fi
 
+maybe_pull_image
+
 echo "--- :vault: Login to ${VAULT_ADDR}"
 echo "Using Docker image: ${image}"
 echo "VAULT_ADDR=${VAULT_ADDR}"

lib/vault.sh

@@ -2,12 +2,26 @@
 
 set -euo pipefail
 
+# shellcheck source-path=SCRIPTDIR
+source "$(dirname "${BASH_SOURCE[0]}")/log.sh"
+
 readonly default_image="hashicorp/vault"
 readonly default_tag="latest"
 # TODO: add a "debug" mode where we spit out the specific image and
 # commands being used
 readonly image="${BUILDKITE_PLUGIN_VAULT_LOGIN_IMAGE:-${default_image}}:${BUILDKITE_PLUGIN_VAULT_LOGIN_TAG:-${default_tag}}"
 
+maybe_pull_image() {
+    # We match against the value true / on / 1, rather than simply
+    # checking whether it is set or not, to make it possible to set a
+    # value globally via the environment, but still allow for
+    # job-specific overrides.
+    if [[ "${BUILDKITE_PLUGIN_VAULT_LOGIN_ALWAYS_PULL:-false}" =~ ^(true|on|1)$ ]]; then
+        echo ":docker: Explicitly pulling '${image}' image"
+        log_and_run docker pull "${image}"
+    fi
+}
+
 # Wrap up the invocation of a Vault container image to alleviate the
 # need to have a Vault binary installed on the Buildkite agent machine
 # already. Scripts can just source this file and then call `vault`

lib/vault_test.sh

@@ -36,3 +36,25 @@ test_vault_stdout_contains_no_ANSI_codes() {
         "${output}" \
         "${expanded_output}"
 }
+
+test_explicit_pull() {
+    output="$(BUILDKITE_PLUGIN_VAULT_LOGIN_ALWAYS_PULL=1 maybe_pull_image)"
+    assertContains "${output}" "latest: Pulling from hashicorp/vault"
+}
+
+test_no_explicit_pull() {
+    output="$(
+        unset BUILDKITE_PLUGIN_VAULT_LOGIN_ALWAYS_PULL
+        maybe_pull_image
+    )"
+    assertEquals "" "${output}"
+}
+
+test_synonyms_for_always_pull_activation() {
+    for value in "true" "on" "1"; do
+        output="$(BUILDKITE_PLUGIN_VAULT_LOGIN_ALWAYS_PULL=${value} maybe_pull_image)"
+        assertContains "Expected '${value}' to enable 'always-pull' option" \
+            "${output}" \
+            "latest: Pulling from hashicorp/vault"
+    done
+}

plugin.yml

@@ -2,7 +2,8 @@
 name: Vault Login
 description: Log into a Hashicorp Vault server
 author: https://github.com/grapl-security
-requirements: ["docker"]
+requirements:
+  - "docker"
 configuration:
   properties:
     auth_role:
@@ -19,6 +20,15 @@ configuration:
       description: |
         The `vault` image tag to use; defaults to `latest`.
       type: string
+    always-pull:
+      description: |
+        Explicitly pull the image before running. Useful if using the
+        `latest` tag. Defaults to `false`.
+
+        Note that "true", "on", and "1" are all acceptable values to
+        enable this option. Any other value is considered synonymous
+        with `false`.
+      type: boolean
     address:
       description: |
         The address of the Vault server to interact with. Should

tests/environment.bats

@@ -20,6 +20,7 @@ setup() {
 teardown() {
     unset BUILDKITE_AGENT_META_DATA_QUEUE
     unset BUILDKITE_PLUGIN_VAULT_LOGIN_ADDRESS
+    unset BUILDKITE_PLUGIN_VAULT_LOGIN_ALWAYS_PULL
     unset BUILDKITE_PLUGIN_VAULT_LOGIN_AUTH_ROLE
     unset BUILDKITE_PLUGIN_VAULT_LOGIN_IMAGE
     unset BUILDKITE_PLUGIN_VAULT_LOGIN_NAMESPACE
@@ -245,3 +246,16 @@ teardown() {
 
     assert_output --partial "Must provide a positive value for attempt_wait_seconds!"
 }
+
+@test "always-pull will pull an image before running" {
+    export BUILDKITE_PLUGIN_VAULT_LOGIN_ALWAYS_PULL=1
+
+    stub docker \
+         "pull ${DEFAULT_IMAGE}:${DEFAULT_TAG} : echo 'pulling image'" \
+         "run --init --rm --env=SKIP_SETCAP=true --env=VAULT_ADDR=${VAULT_ADDR} --env=VAULT_NAMESPACE=${VAULT_NAMESPACE} -- ${DEFAULT_IMAGE}:${DEFAULT_TAG} login -method=aws -token-only role=default : echo 'THIS_IS_YOUR_VAULT_TOKEN'"
+
+    run "${PWD}/hooks/environment"
+    assert_success
+
+    unstub docker
+}