bindan 0.2.0 → 0.2.1

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
checksums.yaml CHANGED
@@ -1,7 +1,7 @@
1
1
  ---
2
2
  SHA256:
3
- metadata.gz: 3f8436f7249259c3a94776cb3698fe1afe49446e1b21c7e45a8e2930334602fe
4
- data.tar.gz: 1241b3b53ba1633c55dd817d59b0300eda7713baccda8611c4bf89488e29b2ff
3
+ metadata.gz: d8d6bd2055debe3414cc3c1c82802dd55aae38da0e493f8ce0252083bf62cc5f
4
+ data.tar.gz: c6de5a2b13a1aeda060bd5886f973c21293d87cace68641a84119e51ae81e20f
5
5
  SHA512:
6
- metadata.gz: 92f7df51c973455ec67ef6381b0534f5dd123ca8e336ae24a5cb80f1f9c646222a7db582db41bd31289408251fef0fb3bc23c9fc76d23b6f951380ee1bf8d767
7
- data.tar.gz: 31499462bfff33ed2f6341db17d5ba9e0dae3215ff70afd1aa5d1045e8f23026097f3083d1e13badefe078496c317ee3cb08ba2d1dc522631f8d39626057f48e
6
+ metadata.gz: a1e7b8c963cec2bbf37f6324c4a0349c0e890420d7262296427d34e6ba263dc775b1ec87ddbbb2fc5958f287231beb9dbaf77f76afd33287669f2e5ba9973b91
7
+ data.tar.gz: 676a894f98eb6a3e2a29a0a5e071064b8befb1071e50f29d61792a4073fea542618f22bd0c30d37797420e3820b484317696809d94dff9b911ea6faeda9a45c4
data/CHANGELOG.md CHANGED
@@ -1,4 +1,7 @@
1
- ## [Unreleased]
1
+ ## [0.2.1] - 2026-11-15
2
+
3
+ - (feat) Add `Bindan::SecretManagerHelper` and `bindan-secret-update` to add Secret Manager versions from exact file bytes or a known-good numerical version. The helper also retrieves the last created version regardless of its state.
4
+ - (refactor) Make Firestore and Secret Manager emulator controller errors inherit from `Bindan::Error`.
2
5
 
3
6
  ## [0.2.0] - 2026-11-13
4
7
 
data/README.md CHANGED
@@ -119,8 +119,36 @@ Replace `my-project` with your Google Cloud project ID. Storage joins `project_i
119
119
  Secret Manager also accepts an omitted `project_id:`, using `GOOGLE_CLOUD_PROJECT`
120
120
  or `GCLOUD_PROJECT` from the environment. An explicit `project_id:` takes precedence.
121
121
 
122
- For update and revert precautions and commands, see
123
- [Secret Manager operations](docs/secret-manager-operations.md).
122
+ ### Reflecting configuration changes
123
+
124
+ The current Bindan implementation retains the values resolved by `configure`;
125
+ `config` does not reread the Providers. For now, reflect source changes by replacing
126
+ the application's execution units to acquire the updated values. See the
127
+ [configuration rollout guide](docs/configuration-rollout.md) for App Engine and Cloud Run.
128
+
129
+ ### Updating and reverting Secret Manager values
130
+
131
+ If you need to revert a Secret Manager value, take care: GCP and the emulator
132
+ differ in how `latest` handles disabled versions. `bindan-secret-update` supports
133
+ both updates and reverts by adding a new version without exposing
134
+ the value.
135
+
136
+ Install `google-cloud-secret_manager` alongside `bindan`. Use a file for an update,
137
+ or a known-good numerical version for a revert:
138
+
139
+ ```bash
140
+ bundle exec bindan-secret-update --project my-project --secret api-key \
141
+ --file ./api-key.bin
142
+
143
+ bundle exec bindan-secret-update --project my-project --secret api-key \
144
+ --from-version 1
145
+ ```
146
+
147
+ For the behavior differences and the full workflow, see
148
+ [Secret Manager operations from Cloud Shell](docs/secret-manager-operations.md)
149
+ before performing a revert. Neither command refreshes running applications.
150
+ For direct Ruby use, see the example in
151
+ [`Bindan::SecretManagerHelper`](lib/bindan/secret_manager_helper.rb).
124
152
 
125
153
  ## Development
126
154
 
@@ -0,0 +1,162 @@
1
+ # Reflecting configuration changes in running applications
2
+
3
+ ## Current limitation and rollout approach
4
+
5
+ The current Bindan implementation evaluates the configuration block when
6
+ `configure` runs and retains the resolved values. Subsequent `config` calls return
7
+ that configuration without reading the Providers again. Changing a value at its source does not change
8
+ the configuration already held by a running application.
9
+
10
+ Given this current limitation, this guide reflects changes by completely replacing
11
+ the execution units that hold the old configuration, such as instances or containers.
12
+ The new units run the application's configuration setup and acquire the updated values. Changing
13
+ traffic routing alone does not cause an existing unit to reread configuration.
14
+
15
+ ## Rollout sequence
16
+
17
+ 1. Update the configuration source and verify the values the application will
18
+ read. Follow that source's update and consistency requirements before proceeding;
19
+ source-specific operations are outside this guide.
20
+ 2. Replace every execution unit that can hold the old configuration, keeping
21
+ enough capacity available to serve requests.
22
+ 3. Verify that the new units work with the updated configuration and that old
23
+ units no longer handle requests.
24
+
25
+ New and old configurations can coexist from the moment the source changes:
26
+ the platform may start new units independently of this procedure. Keep the
27
+ application compatible with both configurations during the transition. Coordinate
28
+ the rollout with other configuration changes and application deployments.
29
+
30
+ ## Replace execution units
31
+
32
+ The examples use Cloud Shell and gcloud. Authorize the session when prompted and
33
+ check the account and target project. Instance replacement and revision deployment
34
+ require the hosting service's permissions, separately from source read/write access.
35
+ These operations affect capacity, running requests, and potentially cost. Start
36
+ in a non-production environment and use the application's normal health checks.
37
+
38
+ ```bash
39
+ PROJECT_ID="my-project"
40
+ ```
41
+
42
+ For external-source changes, reuse the deployed application code or image rather
43
+ than rebuilding it. For deployment-supplied values such as environment variables,
44
+ update the deployment definition first; replacing units with the unchanged
45
+ definition would supply the same values. Choose the hosting service below.
46
+
47
+ ### App Engine Standard
48
+
49
+ After the source is updated and ready to read, record the UTC cutoff time. Units
50
+ started before this point may retain the old configuration and must be replaced:
51
+
52
+ ```bash
53
+ REPLACE_BEFORE="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
54
+ ```
55
+
56
+ For each service and version that can receive requests, list instances and
57
+ review their `id` and `startTime` against `REPLACE_BEFORE`:
58
+
59
+ ```bash
60
+ APP_SERVICE="default"
61
+ APP_VERSION="my-version"
62
+ gcloud app instances list --project "$PROJECT_ID" \
63
+ --service "$APP_SERVICE" --version "$APP_VERSION" --format=json
64
+ ```
65
+
66
+ Stop instances started before the cutoff **one at a time**, checking replacement
67
+ capacity and application health between operations. App Engine starts instances
68
+ according to its scaling configuration and demand; stopping one does not promise
69
+ an immediately running replacement. Do not delete all instances at once.
70
+
71
+ ```bash
72
+ INSTANCE_ID="replace-with-reviewed-instance-id"
73
+ gcloud app instances delete "$INSTANCE_ID" --project "$PROJECT_ID" \
74
+ --service "$APP_SERVICE" --version "$APP_VERSION"
75
+ ```
76
+
77
+ List again until no pre-cutoff instances remain for all relevant services and
78
+ versions. Include versions reachable through direct version URLs, not only the
79
+ default traffic allocation. Check errors and successful use of the updated
80
+ configuration without logging sensitive values. Instance age identifies the
81
+ replacement targets; it does not prove which values the application loaded.
82
+
83
+ See [instance deletion](https://cloud.google.com/sdk/gcloud/reference/app/instances/delete)
84
+ and [instance fields](https://cloud.google.com/appengine/docs/admin-api/reference/rest/v1/apps.services.versions.instances#Instance).
85
+
86
+ ### Cloud Run
87
+
88
+ Create a new revision of the same image with a changed, non-sensitive generation
89
+ marker. The marker only forces a fresh revision; Bindan does not interpret it.
90
+ First review the current traffic, serving revision, and its image digest:
91
+
92
+ ```bash
93
+ RUN_SERVICE="my-service"
94
+ REGION="asia-northeast1"
95
+ gcloud run services describe "$RUN_SERVICE" --project "$PROJECT_ID" \
96
+ --region "$REGION" --format='yaml(status.traffic)'
97
+ SERVING_REVISION="replace-with-reviewed-serving-revision"
98
+ gcloud run revisions describe "$SERVING_REVISION" --project "$PROJECT_ID" \
99
+ --region "$REGION" --format='value(status.imageDigest)'
100
+ ```
101
+
102
+ The example below assumes a single-container service, one serving revision, and
103
+ a service template matching that revision's intended configuration. If there are
104
+ pending configuration changes, sidecars, or an existing traffic split, adapt the
105
+ normal deployment procedure instead of overwriting it with this example. Do not
106
+ run concurrently with other deployments. Use the reviewed full image reference
107
+ with `@sha256:...`, not a mutable tag, and keep all other settings unchanged.
108
+
109
+ ```bash
110
+ IMAGE="replace-with-current-image-reference@sha256:..."
111
+ GENERATION="cfg-$(date -u +%Y%m%d%H%M%S)"
112
+ NEW_REVISION="$RUN_SERVICE-$GENERATION"
113
+ gcloud run deploy "$RUN_SERVICE" --project "$PROJECT_ID" --region "$REGION" \
114
+ --image "$IMAGE" --revision-suffix "$GENERATION" \
115
+ --update-env-vars "BINDAN_CONFIG_GENERATION=$GENERATION" \
116
+ --no-traffic --tag "$GENERATION"
117
+ ```
118
+
119
+ Choose a unique generation that keeps the full revision name within Cloud Run's
120
+ length limit. Verify the deployment succeeded and test the new revision through
121
+ its tagged URL using the service's normal authentication. Check that the
122
+ application actually works with the new configuration, not just that it starts.
123
+ Then move a small proportion of traffic and monitor it before completing:
124
+
125
+ ```bash
126
+ gcloud run services update-traffic "$RUN_SERVICE" \
127
+ --project "$PROJECT_ID" --region "$REGION" \
128
+ --to-revisions "$SERVING_REVISION=95,$NEW_REVISION=5"
129
+ # After verifying health, move the remaining traffic.
130
+ gcloud run services update-traffic "$RUN_SERVICE" \
131
+ --project "$PROJECT_ID" --region "$REGION" --to-revisions "$NEW_REVISION=100"
132
+ ```
133
+
134
+ Confirm the resulting traffic allocation and allow in-flight requests to finish.
135
+ Review old tagged URLs and minimum-instance settings too: zero main-service
136
+ traffic does not mean an old revision cannot still run or receive direct requests.
137
+ See [Cloud Run traffic migration and required roles](https://cloud.google.com/run/docs/rollouts-rollbacks-traffic-migration).
138
+
139
+ ## Verify completion
140
+
141
+ Confirm that all request-serving execution units use the updated configuration,
142
+ including units reachable through direct version or tagged URLs. Monitor errors
143
+ and normal application operations that depend on the changed settings; a successful
144
+ restart or deployment alone is not sufficient. Do not log sensitive configuration
145
+ values while checking them.
146
+
147
+ If a new unit loads an unexpected value, check the source and the application's
148
+ read path before replacing more units. Correct the cause and repeat the replacement
149
+ as needed. Retire old values only after confirming that no request-serving units
150
+ still depend on them.
151
+
152
+ ## Revert if needed
153
+
154
+ Restore the known-good values using the source's rollback procedure, verify what
155
+ the application will read, and repeat the execution-unit replacement and completion
156
+ checks. Restoring the source alone does not change values already held by Bindan.
157
+
158
+ For Cloud Run, create another fresh revision with a new generation marker. Merely
159
+ sending traffic to an old revision does not reliably restore externally loaded
160
+ configuration: retained instances may have cached values and newly started ones
161
+ read the current source. Verify application behavior and replacement completion,
162
+ not only that the source update or deployment command succeeded.
@@ -1,76 +1,126 @@
1
- # Secret Manager operations
2
-
3
- ## Update and revert: what matters
4
-
5
- - **Update by adding a new version.** This provider reads `latest`, which selects
6
- the newest created version, not the newest enabled one.
7
- - **Reverting requires another update.** Record the known-good version before
8
- making a change. To restore its value, add that value as a new version.
9
- Disabling or destroying the newest version does not restore the previous one:
10
- GCP's `latest` still selects the newest created version and reading it fails.
11
- The emulator may return an older enabled version instead; GCP does not.
12
- - **Do not expose or accidentally alter the value while updating or reverting.**
13
- Logs and shell history can retain secrets; added or removed newlines can change
14
- their meaning. If an update fails or times out, check whether it created a
15
- version before retrying.
16
-
17
- ## Manual command examples
18
-
19
- These examples use Bash and `gcloud`, including Cloud Shell. They modify an
20
- existing secret; check the account and target before running them, and serialize
21
- updates to the same secret. The operator needs permissions to
22
- access/add versions and read version metadata, separate from the application's
23
- read-only access. Use non-sensitive test data before production use.
1
+ # Secret Manager operations from Cloud Shell
2
+
3
+ ## Update and revert
4
+
5
+ Bindan's Secret Manager Provider reads `latest`. The update sequence is:
6
+
7
+ 1. Add a new version with the CLI and record the returned version name.
8
+ 2. Inspect the last created version without filtering by state or resolving an alias.
9
+ 3. Follow the [configuration rollout guide](configuration-rollout.md) to replace
10
+ the execution units holding Bindan's previous configuration.
11
+
12
+ For credentials, enable the new credential first and revoke the old one only
13
+ after verifying the application rollout. Serialize updates to a secret and
14
+ coordinate them with application deployments.
15
+
16
+ Updating multiple secrets is not a single transaction. If an update fails partway
17
+ through, earlier updates remain in effect; neither the CLI nor the Helper rolls
18
+ them back automatically. An application starting during the updates can also
19
+ load a mixture of old and new values. Plan for these combinations and partial
20
+ failures, recording the known-good version of each secret before making changes.
21
+
22
+ Revert also means adding a version: copy a known-good numerical version into a
23
+ new one, then repeat version checks and application rollout. Disabling or
24
+ destroying the newest version does **not** revert it. GCP's `latest` selects the
25
+ newest created version and fails if it is disabled or destroyed; the emulator
26
+ may return an older enabled version instead.
27
+
28
+ The CLI does not replace instances, move traffic, or guarantee convergence of
29
+ `latest`. Start with a non-sensitive secret in a non-production environment.
30
+
31
+ ## 1. Prepare Cloud Shell
32
+
33
+ Cloud Shell includes Ruby and gcloud, not Bindan or the Secret Manager Ruby SDK.
34
+ Include `bindan` and `google-cloud-secret_manager` in your Gemfile, then install
35
+ the dependencies:
36
+
37
+ ```bash
38
+ bundle install
39
+ bundle exec bindan-secret-update --help
40
+ ```
41
+
42
+ Authorize the session when Cloud Shell prompts. Normally no
43
+ `gcloud auth application-default login` is needed in Cloud Shell; the Ruby SDK
44
+ uses [Application Default Credentials](https://cloud.google.com/docs/authentication/set-up-adc-local-dev-environment#local-user-cred).
45
+ Check for credential overrides such as `GOOGLE_APPLICATION_CREDENTIALS` or a local
46
+ ADC file: the SDK and gcloud can otherwise use different identities. Do not print
47
+ tokens or credential files to diagnose access problems.
48
+
49
+ Updating requires `secretmanager.versions.add`; reverting also requires
50
+ `secretmanager.versions.access` to read the source. Inspecting the last created
51
+ version requires `secretmanager.versions.list`. The application's identity can
52
+ remain read-only for secrets.
24
53
 
25
54
  ```bash
26
55
  set +x
56
+ umask 077
27
57
  export CLOUDSDK_CORE_LOG_HTTP=false CLOUDSDK_CORE_VERBOSITY=error
28
58
  PROJECT_ID="my-project"
29
59
  SECRET_ID="api-key"
30
60
  gcloud auth list --filter=status:ACTIVE --format='value(account)'
61
+ gcloud config get-value project
31
62
  ```
32
63
 
33
- ### Update
64
+ Use explicit project flags below to avoid depending on gcloud's active project.
65
+ Without `--project`, Bindan uses `GOOGLE_CLOUD_PROJECT`, then `GCLOUD_PROJECT`.
66
+ Cloud Shell initially sets `GOOGLE_CLOUD_PROJECT` from the console's active
67
+ project, but changing gcloud's configuration does not set Bindan's environment.
34
68
 
35
- Prepare a protected file with the exact desired bytes, then add a version.
36
- Avoid `echo` or embedding secrets in shell commands/history. Record the returned
37
- version name and the previous known-good version number.
69
+ Prepare a protected file outside the checkout containing the exact new bytes.
70
+ Do not embed the value in a shell command, history, source control, or build
71
+ configuration. Avoid `echo`, which can change newlines. Cloud Shell's home
72
+ directory persists between sessions; remove plaintext files when no longer
73
+ needed, or use an appropriate ephemeral location. Removal is not secure erasure.
74
+
75
+ ## 2. Update or revert
76
+
77
+ Record the known-good **numerical** version before making a change. For an update:
38
78
 
39
79
  ```bash
40
- gcloud secrets versions add "$SECRET_ID" --project="$PROJECT_ID" \
41
- --data-file="./api-key.bin" --format='value(name)'
80
+ created="$(bundle exec bindan-secret-update \
81
+ --project "$PROJECT_ID" --secret "$SECRET_ID" --file /path/to/api-key.bin)"
42
82
  ```
43
83
 
44
- ### Revert
84
+ For a revert, use the same command with a source version instead of a file:
45
85
 
46
- Copy a known-good numeric version into a new version, then verify its bytes.
86
+ ```bash
87
+ SOURCE_VERSION="1" # Replace with the recorded known-good version.
88
+ created="$(bundle exec bindan-secret-update \
89
+ --project "$PROJECT_ID" --secret "$SECRET_ID" --from-version "$SOURCE_VERSION")"
90
+ ```
91
+
92
+ Run only the chosen form and check its exit status before continuing. Both
93
+ preserve the input bytes, suppress SDK payload logging, and print only the
94
+ created version name on success. Exit status is `0` for success, `2` for argument
95
+ errors, and `1` for operational failures. Writes are not automatically retried.
96
+ **A failed command may still have created a version.** Check the target and
97
+ whether the intended value was added before retrying; do not blindly rerun it.
98
+
99
+ ## 3. Inspect the last created version
100
+
101
+ The CLI succeeds when the SDK returns the newly created version. It does not
102
+ read back and compare secret contents. To inspect the last created version,
103
+ list all versions in creation order without filtering by state:
47
104
 
48
105
  ```bash
49
- (
50
- set -euo pipefail
51
- umask 077
52
- SOURCE_VERSION="1" # Replace with the known-good version number.
53
- workdir="$(mktemp -d)"
54
- trap 'rm -rf -- "$workdir"' EXIT
55
-
56
- gcloud secrets versions access "$SOURCE_VERSION" \
57
- --secret="$SECRET_ID" --project="$PROJECT_ID" --out-file="$workdir/payload"
58
- created="$(gcloud secrets versions add "$SECRET_ID" \
59
- --project="$PROJECT_ID" --data-file="$workdir/payload" --format='value(name)')"
60
- [[ "$created" =~ /versions/[0-9]+$ ]] || exit 1
61
- gcloud secrets versions access "${created##*/}" \
62
- --secret="$SECRET_ID" --project="$PROJECT_ID" --out-file="$workdir/check"
63
- cmp -s "$workdir/payload" "$workdir/check"
64
- printf 'Created and verified: %s\n' "$created"
65
- )
106
+ gcloud secrets versions list "$SECRET_ID" --project "$PROJECT_ID" \
107
+ --sort-by='~createTime' --limit=1 --format='value(name)'
66
108
  ```
67
109
 
68
- `--out-file` preserves raw bytes, including trailing newlines. Temporary files
69
- contain plaintext; use a protected environment. Cleanup is not secure erasure.
110
+ Compare this name with the recorded `created` name. Disabled and destroyed versions
111
+ are included: the last created version is not necessarily an enabled or known-good
112
+ version. Do not use `latest` as a substitute for this lookup, because its behavior
113
+ differs between GCP and the emulator when versions are disabled or destroyed.
114
+
115
+ Listing is [eventually consistent](https://cloud.google.com/secret-manager/docs/access-secret-version#resource_consistency).
116
+ If the new version is not visible yet, wait and repeat the lookup, not the update.
117
+ The update's result identifies the version it created even while listing lags.
118
+ A match does not guarantee that all application reads have converged; allow for
119
+ propagation and check application health during rollout.
70
120
 
71
- If the command fails or verification reports a mismatch, check which version was
72
- created and whether its bytes match the intended value before retrying. Do not
73
- assume a failed command means no version was added.
121
+ ## Next: reflect the value into the application
74
122
 
75
- See [version access](https://cloud.google.com/sdk/gcloud/reference/secrets/versions/access)
76
- and [version addition](https://cloud.google.com/sdk/gcloud/reference/secrets/versions/add).
123
+ Continue with [Reflecting configuration changes in running applications](configuration-rollout.md)
124
+ to replace execution units and let Bindan acquire the updated values.
125
+ Keep the `latest` lookup unchanged; do not pin a numerical version in the application
126
+ to make this change. Follow the same version checks and rollout steps after a revert.
@@ -0,0 +1,6 @@
1
+ #!/usr/bin/env ruby
2
+ # frozen_string_literal: true
3
+
4
+ require "bindan/secret_update_command"
5
+
6
+ exit Bindan::SecretUpdateCommand.new.run(ARGV)
@@ -13,7 +13,7 @@ module Bindan
13
13
  INITIAL_BACKOFF_KEY_SEC = 0.1 # seconds
14
14
  BACKOFF_MULTIPLIER = 1.5
15
15
 
16
- class Error < StandardError; end
16
+ class Error < Bindan::Error; end
17
17
 
18
18
  attr_reader :project_id
19
19
 
@@ -1,6 +1,7 @@
1
1
  require "google/cloud/secret_manager/v1"
2
2
  require "grpc"
3
3
  require "logger"
4
+ require_relative "../error"
4
5
 
5
6
  module Bindan
6
7
  module Emulator
@@ -10,7 +11,7 @@ module Bindan
10
11
  class SecretManagerController
11
12
  WAIT_TIMEOUT = 60 # seconds
12
13
 
13
- class Error < StandardError; end
14
+ class Error < Bindan::Error; end
14
15
 
15
16
  attr_reader :project_id, :client
16
17
 
@@ -0,0 +1,92 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "logger"
4
+ require "google/cloud/secret_manager/v1"
5
+
6
+ module Bindan
7
+ #
8
+ # Add versions separately from the read-only Secret Manager Provider.
9
+ # SDK errors propagate; avoid logging exception details that may contain secrets.
10
+ # A failed operation may have created a version; check before retrying.
11
+ #
12
+ # @example Use the helper directly without the CLI
13
+ # require "bindan/secret_manager_helper"
14
+ #
15
+ # helper = Bindan::SecretManagerHelper.new(project_id: "my-project")
16
+ # previous = helper.last_version("api-key")
17
+ # created = helper.update("api-key", data: File.binread("./api-key.bin"))
18
+ # previous&.name # Last created version before the update, if any.
19
+ # created.name # The newly created version.
20
+ # restored = helper.revert("api-key", version: 1)
21
+ #
22
+ class SecretManagerHelper
23
+ #
24
+ # Create a helper for adding versions of existing global secrets.
25
+ # Suppress SDK request/response logging and automatic write retries.
26
+ #
27
+ # @param [String, nil] project_id project ID or number; defaults to
28
+ # GOOGLE_CLOUD_PROJECT, then GCLOUD_PROJECT
29
+ # @param [Object] sdk client factory yielding configuration
30
+ # @param [Hash] kwargs SDK client settings (logger and retry policies are overridden)
31
+ #
32
+ def initialize(project_id: nil, sdk: ::Google::Cloud::SecretManager::V1::SecretManagerService::Client, **kwargs)
33
+ @project_id = project_id || ENV["GOOGLE_CLOUD_PROJECT"] || ENV["GCLOUD_PROJECT"]
34
+ @_secret_manager = sdk.new do |config|
35
+ kwargs.each { |key, value| config.public_send(:"#{key}=", value) }
36
+ config.logger = Logger.new(nil)
37
+ # GAPIC applies client-wide defaults after RPC defaults. Clear both so
38
+ # a caller-supplied retry policy cannot retry a version-creating write.
39
+ config.retry_policy = nil
40
+ config.rpcs.add_secret_version.retry_policy = nil
41
+ end
42
+ end
43
+ # @return [String, nil] explicit or environment project ID or number
44
+ attr_reader :project_id
45
+
46
+ #
47
+ # Read metadata for the last created version, regardless of its state.
48
+ # This does not resolve the latest alias. Listing is eventually consistent.
49
+ #
50
+ # @param [String] secret_id ID of an existing secret
51
+ # @return [Google::Cloud::SecretManager::V1::SecretVersion, nil] last created version, or nil if none
52
+ # @raise [Google::Cloud::Error] when the SDK reports a service error
53
+ #
54
+ def last_version(secret_id)
55
+ parent = "projects/#{@project_id}/secrets/#{secret_id}"
56
+ @_secret_manager.list_secret_versions(parent: parent).first
57
+ end
58
+
59
+ #
60
+ # Add the exact bytes as a new version and return the SDK's creation result.
61
+ # SDK failures propagate unchanged; no operation is retried here.
62
+ #
63
+ # @param [String] secret_id ID of an existing secret
64
+ # @param [String] data secret payload bytes
65
+ # @return [Google::Cloud::SecretManager::V1::SecretVersion] created version metadata
66
+ # @raise [Google::Cloud::Error] when the SDK reports a service error
67
+ #
68
+ def update(secret_id, data:)
69
+ parent = "projects/#{@project_id}/secrets/#{secret_id}"
70
+ @_secret_manager.add_secret_version(parent: parent, payload: {data: data.b})
71
+ end
72
+
73
+ #
74
+ # Copy an existing numerical version into a new version.
75
+ #
76
+ # @param [String] secret_id ID of an existing secret
77
+ # @param [String, Integer] version known-good positive numerical version, not an alias
78
+ # @return [Google::Cloud::SecretManager::V1::SecretVersion] created version metadata
79
+ # @raise [ArgumentError] when version is not a positive numerical version
80
+ # @raise [Google::Cloud::Error] when the SDK reports a service error
81
+ #
82
+ def revert(secret_id, version:)
83
+ unless /\A[1-9][0-9]*\z/.match?(version.to_s)
84
+ raise ArgumentError, "Secret version must be a positive numerical version"
85
+ end
86
+
87
+ name = "projects/#{@project_id}/secrets/#{secret_id}/versions/#{version}"
88
+ data = @_secret_manager.access_secret_version(name: name).payload.data
89
+ update(secret_id, data: data)
90
+ end
91
+ end
92
+ end
@@ -0,0 +1,94 @@
1
+ # frozen_string_literal: true
2
+
3
+ require "optparse"
4
+
5
+ module Bindan
6
+ class SecretUpdateCommand
7
+ USAGE = <<~TEXT
8
+ Usage: bindan-secret-update --secret SECRET_ID [--project PROJECT] (--file PATH | --from-version NUMBER)
9
+
10
+ Add a new version of an existing global Secret Manager secret.
11
+ --file preserves all bytes, including trailing newlines. Values are never printed.
12
+ --from-version copies a known-good numeric version into a new version.
13
+ Project defaults to GOOGLE_CLOUD_PROJECT, then GCLOUD_PROJECT.
14
+ Success prints the created version name; failure exits nonzero without retrying.
15
+ TEXT
16
+
17
+ #
18
+ # @param [Proc, nil] helper_factory factory accepting project_id:; defaults to SecretManagerHelper
19
+ # @param [IO] stdout destination for help and created version names
20
+ # @param [IO] stderr destination for errors without secret values
21
+ #
22
+ def initialize(helper_factory: nil, stdout: $stdout, stderr: $stderr)
23
+ @helper_factory = helper_factory || ->(**options) {
24
+ require_relative "secret_manager_helper"
25
+ SecretManagerHelper.new(**options)
26
+ }
27
+ @stdout = stdout
28
+ @stderr = stderr
29
+ end
30
+
31
+ #
32
+ # Parse arguments without performing I/O or modifying argv.
33
+ #
34
+ # @param [Array<String>] argv command-line arguments
35
+ # @return [Hash{Symbol => String, true}] parsed options, including :help when requested
36
+ # @raise [OptionParser::ParseError] when arguments are invalid or required options are missing
37
+ #
38
+ def self.parse(argv)
39
+ # @type var options: Hash[Symbol, untyped]
40
+ options = {}
41
+ parser = OptionParser.new do |opts|
42
+ opts.banner = USAGE
43
+ opts.on("--secret SECRET_ID") { |value| options[:secret] = value }
44
+ opts.on("--project PROJECT") { |value| options[:project_id] = value }
45
+ opts.on("--file PATH") { |value| options[:file] = value }
46
+ opts.on("--from-version NUMBER") { |value| options[:version] = value }
47
+ opts.on("-h", "--help") { options[:help] = true }
48
+ end
49
+ remaining = parser.parse(argv.dup)
50
+ return options if options[:help]
51
+
52
+ unless remaining.empty? && options[:secret] && (!!options[:file] != !!options[:version])
53
+ raise OptionParser::InvalidArgument, "Specify a secret and either a file or a source version"
54
+ end
55
+ options
56
+ end
57
+
58
+ #
59
+ # Add a version from file bytes or an existing numerical version.
60
+ # Error messages from files, credentials and SDKs may contain sensitive data.
61
+ # Keep those details out of the command's output, including backtraces.
62
+ #
63
+ # @param [Array<String>] argv command-line arguments
64
+ # @return [Integer] exit status: 0 for success/help, 2 for argument errors, 1 for operational failures
65
+ #
66
+ def run(argv)
67
+ options = self.class.parse(argv)
68
+ if options[:help]
69
+ @stdout.puts USAGE
70
+ return 0
71
+ end
72
+
73
+ # Read the entire file before creating a client or attempting a write.
74
+ data = File.binread(options[:file]) if options[:file]
75
+ helper = @helper_factory.call(project_id: options[:project_id])
76
+ version = if options[:file]
77
+ helper.update(options[:secret], data: data)
78
+ else
79
+ helper.revert(options[:secret], version: options[:version])
80
+ end
81
+ @stdout.puts version.name
82
+ 0
83
+ rescue OptionParser::ParseError
84
+ @stderr.puts USAGE
85
+ 2
86
+ rescue LoadError
87
+ @stderr.puts "Secret Manager SDK unavailable. Install google-cloud-secret_manager."
88
+ 1
89
+ rescue
90
+ @stderr.puts "Secret update failed. A version may have been created; check the target before retrying."
91
+ 1
92
+ end
93
+ end
94
+ end
@@ -1,5 +1,5 @@
1
1
  # frozen_string_literal: true
2
2
 
3
3
  module Bindan
4
- VERSION = "0.2.0"
4
+ VERSION = "0.2.1"
5
5
  end
@@ -11,7 +11,7 @@ module Bindan
11
11
 
12
12
  BACKOFF_MULTIPLIER: ::Float
13
13
 
14
- class Error < StandardError
14
+ class Error < Bindan::Error
15
15
  end
16
16
 
17
17
  @project_id: String
@@ -25,7 +25,7 @@ module Bindan
25
25
  class SecretManagerController
26
26
  WAIT_TIMEOUT: 60
27
27
 
28
- class Error < StandardError
28
+ class Error < Bindan::Error
29
29
  end
30
30
 
31
31
  @project_id: String
@@ -0,0 +1,12 @@
1
+ module Bindan
2
+ class SecretManagerHelper
3
+ @project_id: String?
4
+ @_secret_manager: untyped
5
+
6
+ def initialize: (?project_id: String?, ?sdk: untyped, **untyped kwargs) -> void
7
+ attr_reader project_id: String?
8
+ def last_version: (String secret_id) -> untyped
9
+ def update: (String secret_id, data: String) -> untyped
10
+ def revert: (String secret_id, version: String | Integer) -> untyped
11
+ end
12
+ end
@@ -0,0 +1,8 @@
1
+ module Bindan
2
+ class SecretUpdateCommand
3
+ USAGE: String
4
+ def self.parse: (Array[String] argv) -> Hash[Symbol, untyped]
5
+ def initialize: (?helper_factory: untyped, ?stdout: untyped, ?stderr: untyped) -> void
6
+ def run: (Array[String] argv) -> Integer
7
+ end
8
+ end
metadata CHANGED
@@ -1,14 +1,14 @@
1
1
  --- !ruby/object:Gem::Specification
2
2
  name: bindan
3
3
  version: !ruby/object:Gem::Version
4
- version: 0.2.0
4
+ version: 0.2.1
5
5
  platform: ruby
6
6
  authors:
7
7
  - wtnabe
8
8
  autorequire:
9
9
  bindir: exe
10
10
  cert_chain: []
11
- date: 2026-11-14 00:00:00.000000000 Z
11
+ date: 2026-11-15 00:00:00.000000000 Z
12
12
  dependencies: []
13
13
  description: Bindan is a Ruby gem for building a single configuration object from
14
14
  various sources with providers (including bundled Google Cloud Storage, Firestore,
@@ -17,7 +17,8 @@ description: Bindan is a Ruby gem for building a single configuration object fro
17
17
  (using emulators) and production (eg. actual GCP services) environments.
18
18
  email:
19
19
  - 18510+wtnabe@users.noreply.github.com
20
- executables: []
20
+ executables:
21
+ - bindan-secret-update
21
22
  extensions: []
22
23
  extra_rdoc_files: []
23
24
  files:
@@ -30,7 +31,9 @@ files:
30
31
  - Rakefile
31
32
  - Steepfile
32
33
  - compose.yml
34
+ - docs/configuration-rollout.md
33
35
  - docs/secret-manager-operations.md
36
+ - exe/bindan-secret-update
34
37
  - lib/bindan.rb
35
38
  - lib/bindan/emulators/firestore_controller.rb
36
39
  - lib/bindan/emulators/gcs_server_controller.rb
@@ -41,6 +44,8 @@ files:
41
44
  - lib/bindan/providers/firestore.rb
42
45
  - lib/bindan/providers/secret_manager.rb
43
46
  - lib/bindan/providers/storage.rb
47
+ - lib/bindan/secret_manager_helper.rb
48
+ - lib/bindan/secret_update_command.rb
44
49
  - lib/bindan/version.rb
45
50
  - rbs_collection.lock.yaml
46
51
  - rbs_collection.yaml
@@ -53,6 +58,8 @@ files:
53
58
  - sig/bindan/providers/firestore.rbs
54
59
  - sig/bindan/providers/secret_manager.rbs
55
60
  - sig/bindan/providers/storage.rbs
61
+ - sig/bindan/secret_manager_helper.rbs
62
+ - sig/bindan/secret_update_command.rbs
56
63
  - sig/bindan/version.rbs
57
64
  homepage: https://github.com/wtnabe/bindan
58
65
  licenses: []