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 +4 -4
- data/CHANGELOG.md +4 -1
- data/README.md +30 -2
- data/docs/configuration-rollout.md +162 -0
- data/docs/secret-manager-operations.md +105 -55
- data/exe/bindan-secret-update +6 -0
- data/lib/bindan/emulators/firestore_controller.rb +1 -1
- data/lib/bindan/emulators/secret_manager_controller.rb +2 -1
- data/lib/bindan/secret_manager_helper.rb +92 -0
- data/lib/bindan/secret_update_command.rb +94 -0
- data/lib/bindan/version.rb +1 -1
- data/sig/bindan/emulators/firestore_controller.rbs +1 -1
- data/sig/bindan/emulators/secret_manager_controller.rbs +1 -1
- data/sig/bindan/secret_manager_helper.rbs +12 -0
- data/sig/bindan/secret_update_command.rbs +8 -0
- metadata +10 -3
checksums.yaml
CHANGED
|
@@ -1,7 +1,7 @@
|
|
|
1
1
|
---
|
|
2
2
|
SHA256:
|
|
3
|
-
metadata.gz:
|
|
4
|
-
data.tar.gz:
|
|
3
|
+
metadata.gz: d8d6bd2055debe3414cc3c1c82802dd55aae38da0e493f8ce0252083bf62cc5f
|
|
4
|
+
data.tar.gz: c6de5a2b13a1aeda060bd5886f973c21293d87cace68641a84119e51ae81e20f
|
|
5
5
|
SHA512:
|
|
6
|
-
metadata.gz:
|
|
7
|
-
data.tar.gz:
|
|
6
|
+
metadata.gz: a1e7b8c963cec2bbf37f6324c4a0349c0e890420d7262296427d34e6ba263dc775b1ec87ddbbb2fc5958f287231beb9dbaf77f76afd33287669f2e5ba9973b91
|
|
7
|
+
data.tar.gz: 676a894f98eb6a3e2a29a0a5e071064b8befb1071e50f29d61792a4073fea542618f22bd0c30d37797420e3820b484317696809d94dff9b911ea6faeda9a45c4
|
data/CHANGELOG.md
CHANGED
|
@@ -1,4 +1,7 @@
|
|
|
1
|
-
## [
|
|
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
|
-
|
|
123
|
-
|
|
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
|
|
4
|
-
|
|
5
|
-
|
|
6
|
-
|
|
7
|
-
|
|
8
|
-
|
|
9
|
-
|
|
10
|
-
|
|
11
|
-
|
|
12
|
-
|
|
13
|
-
|
|
14
|
-
|
|
15
|
-
|
|
16
|
-
|
|
17
|
-
|
|
18
|
-
|
|
19
|
-
|
|
20
|
-
|
|
21
|
-
|
|
22
|
-
|
|
23
|
-
|
|
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
|
-
|
|
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
|
|
36
|
-
|
|
37
|
-
|
|
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
|
-
|
|
41
|
-
--
|
|
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
|
-
|
|
84
|
+
For a revert, use the same command with a source version instead of a file:
|
|
45
85
|
|
|
46
|
-
|
|
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
|
-
|
|
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
|
-
|
|
69
|
-
|
|
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
|
-
|
|
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
|
-
|
|
76
|
-
and
|
|
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.
|
|
@@ -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 <
|
|
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
|
data/lib/bindan/version.rb
CHANGED
|
@@ -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
|
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.
|
|
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-
|
|
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: []
|