feat: migrate to CDK v0.18 database-authoritative configuration #33

Merged

asmo merged 1 commit from feat/cdk-0.18 into main

2026-08-16 17:42:07 +00:00

asmo commented

2026-08-16 17:26:39 +00:00

Owner

Summary

Migrates the operator to the CDK v0.18 configuration model (v0.18.0-rc.0 release notes, migration guide).

CDK v0.18 stores the authoritative mint configuration in the primary database. Normal daemon startup no longer reads config.toml and no longer applies operational CDK_MINTD_* environment overrides — configuration is imported explicitly through cdk-mintd config init / config apply.

How it works

A new config-init init container runs before mintd:

cdk-mintd config validate --file /data/config.toml
if cdk-mintd config show; then cdk-mintd config apply --file /data/config.toml
else cdk-mintd config init --file /data/config.toml; fi

This covers all cases uniformly: new mints (init), existing v0.17 mints upgrading (init imports into the existing database; signer identity is verified against the stored mint pubkey), and configuration changes (apply staged + activated by the config-hash rolling update). Verified against CDK source that validate/init/apply never dial payment backends or read backend files, so localhost gRPC sidecars are safe.

Changes

ConfigMap renders the v0.18 import document: [payment_backend]/backend (was [ln]/ln_backend), tls_dir (was tls_dir_path), explicit allow_insecure = true for plaintext gRPC processor and management RPC, [info.logging] always emitted with stderr output
Secrets are env: references, never literals (CDK rejects literals): postgres URLs, mint mnemonic, LDK RPC password/node mnemonic, Redis connection string. Values are injected from Secrets into the pod environment; the controller no longer resolves urlSecretRef into the ConfigMap
Pod env slimmed to bootstrap settings (work dir, database engine, postgres connection params) plus env:-referenced secrets
LNBits rejected by the webhook — first-class support was removed upstream; mints must front LNBits with an external gRPC payment processor. Sample manifest removed
New spec.ldkNode.bitcoinRpc.user literal field (xor with userSecretRef): the RPC username is a plain field in CDK v0.18 and cannot be an env: reference, so the operator resolves it into the import document
Default image: cashubtc/mintd:0.18.0-rc.0 (bump to 0.18.0 on final release)
Docs: new "Upgrading to CDK v0.18" section in the migration guide (database backup requirement, signer identity, config rollback recovery, LNBits migration path)

Notes for reviewers

Existing mints must back up the database before upgrading — v0.18 runs automatic DB migrations and downgrade requires a restore
Values previously mutated via management RPC outside the CR are overwritten by the spec on first v0.18 start (spec is source of truth)
Follow-ups not in scope: remote signatory ([signatory]) support, Electrum/BDK chain sources

Testing

make test (unit + envtest), make vet, make lint all pass. e2e not run locally (no kind/docker on this machine) — recommend running make test-e2e before merge.

## Summary Migrates the operator to the CDK v0.18 configuration model ([v0.18.0-rc.0 release notes](https://github.com/cashubtc/cdk/releases/tag/v0.18.0-rc.0), [migration guide](https://github.com/cashubtc/cdk/blob/v0.18.0-rc.0/docs/migrations/v0.18.md)). CDK v0.18 stores the authoritative mint configuration in the primary database. Normal daemon startup no longer reads `config.toml` and no longer applies operational `CDK_MINTD_*` environment overrides — configuration is imported explicitly through `cdk-mintd config init` / `config apply`. ## How it works A new **`config-init` init container** runs before `mintd`: ```sh cdk-mintd config validate --file /data/config.toml if cdk-mintd config show; then cdk-mintd config apply --file /data/config.toml else cdk-mintd config init --file /data/config.toml; fi ``` This covers all cases uniformly: new mints (`init`), existing v0.17 mints upgrading (`init` imports into the existing database; signer identity is verified against the stored mint pubkey), and configuration changes (`apply` staged + activated by the config-hash rolling update). Verified against CDK source that validate/init/apply never dial payment backends or read backend files, so localhost gRPC sidecars are safe. ## Changes - **ConfigMap** renders the v0.18 import document: `[payment_backend]`/`backend` (was `[ln]`/`ln_backend`), `tls_dir` (was `tls_dir_path`), explicit `allow_insecure = true` for plaintext gRPC processor and management RPC, `[info.logging]` always emitted with stderr output - **Secrets are `env:` references, never literals** (CDK rejects literals): postgres URLs, mint mnemonic, LDK RPC password/node mnemonic, Redis connection string. Values are injected from Secrets into the pod environment; the controller no longer resolves `urlSecretRef` into the ConfigMap - **Pod env slimmed to bootstrap settings** (work dir, database engine, postgres connection params) plus `env:`-referenced secrets - **LNBits rejected by the webhook** — first-class support was removed upstream; mints must front LNBits with an external gRPC payment processor. Sample manifest removed - **New `spec.ldkNode.bitcoinRpc.user`** literal field (xor with `userSecretRef`): the RPC username is a plain field in CDK v0.18 and cannot be an `env:` reference, so the operator resolves it into the import document - **Default image**: `cashubtc/mintd:0.18.0-rc.0` (bump to `0.18.0` on final release) - **Docs**: new "Upgrading to CDK v0.18" section in the migration guide (database backup requirement, signer identity, `config rollback` recovery, LNBits migration path) ## Notes for reviewers - Existing mints must **back up the database before upgrading** — v0.18 runs automatic DB migrations and downgrade requires a restore - Values previously mutated via management RPC outside the CR are overwritten by the spec on first v0.18 start (spec is source of truth) - Follow-ups not in scope: remote signatory (`[signatory]`) support, Electrum/BDK chain sources ## Testing `make test` (unit + envtest), `make vet`, `make lint` all pass. e2e not run locally (no kind/docker on this machine) — recommend running `make test-e2e` before merge.

asmo added 1 commit

2026-08-16 17:26:39 +00:00

feat: migrate to CDK v0.18 database-authoritative configuration

Docs / Build docs site (pull_request) Successful in 43s

Details

Lint / Run on Ubuntu (pull_request) Successful in 5m0s

Details

Tests / Run on Ubuntu (pull_request) Successful in 3m38s

Details

E2E Tests / Run on Ubuntu (pull_request) Successful in 9m15s

Details

2dae58f29e

CDK v0.18 stores the authoritative mint configuration in the primary
database; normal startup no longer reads config.toml or applies
operational CDK_MINTD_* env overrides.

- Add a config-init init container that runs config validate followed by
  config init (first start) or config apply (subsequent starts), which
  also covers one-time imports for existing v0.17 databases
- Render the v0.18 TOML document: [payment_backend]/backend instead of
  [ln]/ln_backend, tls_dir instead of tls_dir_path, and explicit
  allow_insecure for plaintext gRPC processor and management RPC
- Render secrets as env: references (postgres URLs, mint mnemonic, LDK
  RPC password and node mnemonic, Redis connection string) and inject
  the values from Secrets in the pod environment; literal credentials
  never enter the ConfigMap
- Slim pod env vars down to bootstrap settings (work dir, database
  engine, postgres connection) and env:-referenced secrets
- Reject spec.paymentBackend.lnbits in the webhook (removed upstream);
  LNBits mints must move to an external gRPC payment processor
- Add spec.ldkNode.bitcoinRpc.user as a literal alternative to
  userSecretRef (the username is a plain field in CDK and cannot be an
  env: reference); the controller resolves userSecretRef into the
  import document
- Default image: cashubtc/mintd:0.18.0-rc.0
- Docs: v0.18 upgrade guide (backup, signer identity, rollback) and
  LNBits removal notes

asmo merged commit 72dabaa9b3 into main

2026-08-16 17:42:07 +00:00

asmo referenced this pull request from a commit

2026-08-16 17:42:09 +00:00

feat: migrate to CDK v0.18 database-authoritative configuration (#33)