Sign inSign up

extenddb/extenddb-cassandra

By extenddb

•Updated about 5 hours ago

DynamoDB-compatible API adapter backed by your own Apache Cassandra 4.1+ cluster

Image
0

509

extenddb/extenddb-cassandra repository overview

⁠ExtendDB with Cassandra

ExtendDB is a DynamoDB-compatible API server backed by your Apache Cassandra cluster. This image contains ExtendDB only; Cassandra is a separate service that you operate.

The Cassandra backend is experimental. Validate it against your workload before you rely on it; the setup guide below lists its known limitations.

⁠Quick start

The Cassandra backend requires Apache Cassandra 4.1 or newer with PasswordAuthenticator enabled. Read the Cassandra setup guide⁠ first: it explains these requirements and the backend's known limitations. Run CassandraAuthorizer, under which init grants the application role only the permissions ExtendDB needs. Under AllowAllAuthorizer, the default, that role can read, drop and alter everything in the cluster, so use such a cluster for ExtendDB alone.

Pull the image:

docker pull docker.io/extenddb/extenddb-cassandra:latest

Initialize the state volume against your cluster. init connects as a Cassandra superuser, creates its keyspaces and an application role, and writes the configuration. The contact point must be resolvable and reachable from the container. Pass the passwords through the environment. Always set EXTENDDB_APP_PASSWORD (ASCII letters, digits, space and -_.,!@#$%^&*()+=~` only): without it the application role gets a fixed, publicly known password. Docker creates the named volume extenddb-state owned by the image's unprivileged user; a host directory would have to be owned by UID 10001 first.

export EXTENDDB_CASSANDRA_PASSWORD='<superuser password>'
export EXTENDDB_APP_PASSWORD='<password for the application role>'
export EXTENDDB_ADMIN_PASSWORD='<first ExtendDB administrator password>'

docker run --rm \
  -v extenddb-state:/var/lib/extenddb \
  -e EXTENDDB_CASSANDRA_PASSWORD -e EXTENDDB_APP_PASSWORD \
  -e EXTENDDB_ADMIN_USER=admin -e EXTENDDB_ADMIN_PASSWORD \
  docker.io/extenddb/extenddb-cassandra:latest \
  init --backend cassandra \
  --config /var/lib/extenddb/extenddb.toml \
  --cassandra-contact-points cassandra.example.com:9042 \
  --cassandra-user <superuser> \
  --replication-factor <1 for one node, 3 for three or more nodes> \
  --datacenter <datacenter name from nodetool status> \
  --bind-addr 0.0.0.0 \
  --tls-san localhost \
  --tls-san 127.0.0.1

init creates its keyspaces with --replication-factor replicas in the --datacenter datacenter, and writes both to the configuration. Use a replication factor of 3 on a cluster of at least three nodes, and 1 on a single node. Use the datacenter name that nodetool status prints for your nodes. The defaults are replication factor 1 and datacenter1. To change the replication later, follow "Keyspace replication" in the setup guide.

Start the server using the generated configuration:

docker run --rm --name extenddb-cassandra \
  -p 127.0.0.1:18443:18443 \
  -v extenddb-state:/var/lib/extenddb \
  --read-only \
  --tmpfs /tmp:rw,noexec,nosuid,size=16m \
  --cap-drop=ALL \
  --security-opt=no-new-privileges:true \
  docker.io/extenddb/extenddb-cassandra:latest

The server listens on https://127.0.0.1:18443. Initialization creates a self-signed certificate; clients need /var/lib/extenddb/.extenddb/tls/cert.pem from the volume. Run one serving container per catalog.

⁠Configuration and security

The ExtendDB container runs as an unprivileged user and is designed to run with a read-only root filesystem. The serving container needs only the generated configuration and TLS files, not the Cassandra superuser password.

ExtendDB connects to Cassandra over plain TCP; the driver is built without TLS. Run ExtendDB and Cassandra on a private network.

For a complete deployment guide, upgrades, and an optional local reference stack, see docker/README-cassandra.md⁠.

⁠Tags and verification

Pin X.Y.Z or a digest for production; a version tag is never overwritten. latest tracks the highest release and only moves forward. Tags of the form sha-<commit> are unpromoted build candidates, not releases. Both linux/amd64 and linux/arm64 ship as one multi-architecture index.

Every published image is signed keyless with Sigstore cosign, with a Rekor transparency-log entry: the certificate names the GitHub Actions workflow and ref that signed the image, and no public key is needed. Verify an image before deploying it:

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-cassandra:X.Y.Z

The signer identity separates tiers: routine backend releases are signed by release-image.yml and routine dev releases by release-dev-image.yml, so this pattern rejects a routinely-signed dev image. The break-glass signer sign-image.yml can sign any tier, so it is the one identity both patterns share; drop it to pin verification to the routine per-tier path. The same images and their signatures are mirrored by digest to ghcr.io/extenddb/extenddb-cassandra and public.ecr.aws/extenddb/extenddb-cassandra.

⁠Note

ExtendDB is an open source project maintained by AWS. It is not Amazon DynamoDB and does not contain any DynamoDB source code. It is not an AWS service. "DynamoDB" is a trademark of Amazon.com, Inc. or its affiliates. ExtendDB is a clean-room implementation that speaks the DynamoDB wire protocol; behavioral differences from the service are documented in Differences from DynamoDB⁠.

More at extenddb.org⁠ and github.com/ExtendDB/extenddb⁠. Licensed under Apache-2.0. Apache Cassandra, Cassandra and Apache are trademarks of The Apache Software Foundation.

Tag summary

Content type

Image

Digest

sha256:05b767fc1…

Size

56.6 MB

Last updated

about 5 hours ago

docker pull extenddb/extenddb-cassandra