Skip to content

v1.0.0

Latest

Choose a tag to compare

@LeeroyHannigan LeeroyHannigan released this 18 Nov 21:57
c2e9a32

What's Changed

Full Changelog: v0.1.15...v1.0.0


ExtendDB 1.0

1.0.0 is the first release under the compatibility rules of docs/versioning.md. Within 1.x, these stay:

  • the DynamoDB operations, request members and response members that a release implements
  • the keys of extenddb.toml, their EXTENDDB__ environment variables and the runtime settings, with their names and meanings
  • the subcommands, flags and exit codes of the extenddb CLI
  • the management API, and the options and return values of start() in @extenddb/dev
  • the HTTP status code of a /health response and its status field
  • the catalog and the on-disk formats, under the catalog upgrade rules of the policy
  • support for each database version, until after its upstream end of life

A minor release can add operations, configuration keys, CLI flags and catalog migrations. It can also carry a breaking catalog migration, and its release notes then say so. A patch release fixes bugs and security issues. A change that makes ExtendDB answer a request as DynamoDB answers it ships in a minor release. It ships in a patch release only when it closes a security issue. The policy does not cover the APIs of the Rust crates, preview settings, the fields of a /metrics response or the experimental Cassandra backend. The 0.1.x releases get no more fixes.

Upgrading from 0.1.15

1.0.0 carries the same catalog migrations as 0.1.15, 1 to 12, so the upgrade has no migrate step. On a 0.1.15 catalog, extenddb migrate prints Up to date and exits 0.

  1. Check the catalog key. If signed requests to the 0.1.15 server succeed, the key passes. On PostgreSQL, this query in the catalog database prints t:

    SELECT value ~ '^[A-Za-z0-9+/]{42}[AEIMQUYcgkosw048]=$' FROM settings WHERE key = 'encryption_key';

    1.0.0 refuses to start on a key that is not 32 bytes in base64. The key that extenddb init writes passes. A key that fails was changed after init. Restore its original value before you start 1.0.0, because every stored secret is encrypted under it.

  2. On Cassandra, give the catalog keyspace and every account keyspace a replication factor of 3 on at least three nodes, and set replication_factor in [storage.cassandra] to match. 1.0.0 reads and writes at LOCAL_QUORUM (#945).

  3. Stop every server, and then start 1.0.0.

To roll back, first delete any [auth.encryption] section and any EXTENDDB__AUTH__ENCRYPTION__KEY_FILE override from the configuration, because 0.1.15 refuses both. Then stop the 1.0.0 server and start the 0.1.15 binary on the same catalog. After extenddb encryption-key switch, 0.1.15 refuses the catalog: see The switch to a KEK file: rollback.

Upgrading from 0.1.14 or an earlier release

Take a backup of the catalog, stop every server, run extenddb migrate --yes with the 1.0.0 binary, and then start 1.0.0. Do the two checks above before the upgrade too. The upgrade manual and the 0.1.15 release notes describe the migrations and the rollback, which restores the catalog backup.

Highlights

The catalog key (#1003)

With no configuration change, 1.0.0 keeps the stored format and the catalog key. It now refuses to start on a catalog key that is not base64 or does not decode to 32 bytes. 0.1.15 started on such a key and failed every signed request.

1.0.0 keeps the catalog key and the cached SigV4 signing keys in a locked key store: memfd_secret where the kernel has it, otherwise pages locked with mlock. At the default [auth.cache] max_entries of 10,000, the store needs about 640 KB of locked memory. When the server cannot lock it, the server logs a warning that names the limit it needs. It then starts with the keys in ordinary memory. The startup line ends with key_store=memfd_secret, key_store=locked pages or key_store=none.

A new and optional setting, [auth.encryption] key_file, names a key-encryption key (KEK) file outside the catalog. The extenddb encryption-key commands (status, switch, rewrap, rotate, reset and set-data-connection) move the stored secrets under it and manage its keys. The admin guide's Encryption Key section gives the procedure.

Cassandra consistency levels (#945, #1010)

The Cassandra backend runs its reads and writes at LOCAL_QUORUM, and its lightweight transactions run Paxos at LOCAL_SERIAL. No setting changes these levels. A request fails while fewer than a quorum of a keyspace's replicas in the datacenter are up. At a replication factor of 2, that means one replica down. The admin user delete and password change are now lightweight transactions, as the admin user insert already was (#1010).

npm packages

Package Version
@extenddb/dev 1.0.0 (latest)
@extenddb/linux-x64, @extenddb/linux-arm64, @extenddb/darwin-x64, @extenddb/darwin-arm64, @extenddb/win32-x64 1.0.0 (latest)

All six packages carry npm provenance attestations from OIDC trusted publishing. Verify them with npm audit signatures.

crates.io

The 14 workspace crates are on crates.io at 1.0.0, for building ExtendDB from source. The versioning policy does not cover their APIs.

Container images

All four images ship at 1.0.0 for linux/amd64 and linux/arm64, on Docker Hub, ECR Public and GHCR. The release workflows signed each one. Each image also has a latest tag. Pin the version tag or the digest in production.

extenddb-postgres

The production image.

Registry Reference
Docker Hub docker.io/extenddb/extenddb-postgres:1.0.0
ECR Public public.ecr.aws/extenddb/extenddb-postgres:1.0.0 (gallery)
GHCR ghcr.io/extenddb/extenddb-postgres:1.0.0

Index digest:

sha256:b26d28659f92062b62a5ac10cbf8dfbd3cb87cd75f88e74b710add76f9f691be

extenddb-mongodb

The same API, backed by an external MongoDB 7 or later replica set. The image does not include MongoDB.

Registry Reference
Docker Hub docker.io/extenddb/extenddb-mongodb:1.0.0
ECR Public public.ecr.aws/extenddb/extenddb-mongodb:1.0.0 (gallery)
GHCR ghcr.io/extenddb/extenddb-mongodb:1.0.0

Index digest:

sha256:bf3db072fd9c48d15a6ff7208c99c876ee325e2a1202e9e3cb10c1b3bc193eae

extenddb-cassandra

The same API, backed by an external Cassandra 4.1 or later cluster. The image does not include Cassandra. The Cassandra backend is experimental.

Registry Reference
Docker Hub docker.io/extenddb/extenddb-cassandra:1.0.0
ECR Public public.ecr.aws/extenddb/extenddb-cassandra:1.0.0 (gallery)
GHCR ghcr.io/extenddb/extenddb-cassandra:1.0.0

Index digest:

sha256:05b767fc1eeb6634467349959f431f41aa3061eb3c8ac5bf7afd520be2aadaa6

extenddb-dev

One container serves the DynamoDB API over SQLite and plain HTTP, with no init step. It is for local development and CI. Do not run it in production. It is on the same three registries as extenddb/extenddb-dev.

Index digest:

sha256:f5f2ef92c8fe89da8ed87e0ae5e8c277d861acda27fd1503e6c3eac3bb308059

Verifying signatures

The GitHub Actions workflow that released each image signed it keyless through Sigstore, and the public Sigstore transparency log records each signature. With cosign, verify a backend image:

cosign verify \
  --certificate-identity-regexp '^https://github\.com/ExtendDB/extenddb/\.github/workflows/(release-image|sign-image)\.yml@refs/heads/main$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  docker.io/extenddb/extenddb-postgres:1.0.0

The signer of the development image is release-dev-image.yml:

cosign verify \
  --certificate-identity-regexp '^https://github\.com/ExtendDB/extenddb/\.github/workflows/(release-dev-image|sign-image)\.yml@refs/heads/main$' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  docker.io/extenddb/extenddb-dev:1.0.0

The same commands work on all three registries. The signed claims include org.extenddb.release: v1.0.0.

The first pattern rejects the development image. So a policy that uses it does not admit the plain-HTTP development image in place of a backend image. Both patterns accept sign-image.yml, the break-glass signer. To accept only the release workflows, delete it from the pattern.