Armada KVArmada KV
/vmain
Documentation
Edit on GitHub

Tables

Armada organises all key-value data into tables. Each table is an independent keyspace with its own Raft consensus group, its own storage, and its own replication stream. All API consistency guarantees (e.g. compare-and-swap, linearisable reads) are scoped to a single table — there is no cross-table atomicity.

Managing Tables

Tables are managed through the regatta.v1.Tables gRPC API. The easiest way to manage them is with the arctl control-plane CLI, which talks to that API for you. You can also call the API directly with grpcurl or the official client libraries.

Creating and deleting tables is only possible on a leader cluster; followers replicate table changes automatically. Listing tables works on both leader and follower clusters.

Using arctl

The Tables API (and the Maintenance API) is served by the API server on the API address (--api.address, default port 8443). Point arctl at that address; the scheme selects the transport (http/unix for plaintext, https/unixs for TLS):

# Create a table
arctl --address=http://127.0.0.1:8443 tables create my-table

# List all tables
arctl --address=http://127.0.0.1:8443 tables list

# Delete a table
arctl --address=http://127.0.0.1:8443 tables delete my-table

arctl also honours the global --ca, --cert, --key, and --token flags (see the CLI reference). Use an https/unixs address when the Tables API is protected by a token — tokens are only sent over secure connections — or when the API port requires mutual TLS (pass --cert/--key). Pass --format=json to arctl tables list for machine-readable output.

Using grpcurl

Create a Table

grpcurl -plaintext \
  -d '{"name": "my-table"}' \
  127.0.0.1:8443 regatta.v1.Tables/Create

List Tables

grpcurl -plaintext 127.0.0.1:8443 regatta.v1.Tables/List

Delete a Table

grpcurl -plaintext \
  -d '{"name": "my-table"}' \
  127.0.0.1:8443 regatta.v1.Tables/Delete

Warning: Deleting a table is permanent. All data stored in the table will be lost. In a leader–follower deployment, deleting a table on the leader will also cause followers to gracefully delete their local copy.

Securing the Tables API

The Tables API can be protected with a static token. Set --tables.token when starting Armada:

armada leader --tables.token=my-secret-token ...

Clients must then include the token as a gRPC metadata header:

grpcurl -plaintext \
  -H 'authorization: Bearer my-secret-token' \
  -d '{"name": "my-table"}' \
  127.0.0.1:8443 regatta.v1.Tables/Create

With arctl, pass the token via the --token flag over a TLS (https) address:

arctl --address=https://127.0.0.1:8443 --token=my-secret-token tables create my-table

If --tables.token is not set, no authentication is required for the Tables API.

The Tables API can be disabled entirely with --tables.enabled=false.

How Tables Map to Raft Groups

Each table is backed by its own Raft consensus group. This means:

  • Writes to one table do not block writes to another table.
  • A Raft leader election in one table does not affect other tables.
  • Snapshots and log compaction happen independently per table.
  • In a multi-node cluster, different tables may have different Raft leaders.

The metadata table (cluster ID 1000) is a special internal Raft group that tracks the set of known tables and is not directly accessible through the KV API.

Consistency Guarantees

  • Within a single table: reads and writes are linearisable. Compare-and-swap (Txn) and multi-key atomic operations are supported within a single table.
  • Across tables: there are no cross-table consistency guarantees. Two writes to different tables may be observed in any order.

Read-Only Tables on Followers

In a follower cluster, tables are read-only. Write requests (Put, DeleteRange, Txn) received by a follower are forwarded to the leader and the follower waits until its local replica has applied the returned revision before replying to the client. This provides a read-after-write guarantee even when the client sends requests to a follower.

Static Cluster Membership

Armada currently requires a static set of cluster members. The number of nodes in a cluster must be specified at cluster creation time and cannot be changed while the cluster is running. See the Helm Chart for how to set the replica count before deploying.

← PreviousSecurityNext →RFC Template