DynamoDB

DynamoDB is the AWS-native shared driver. The same dynamo driver field works for cluster state and audit events. It is the natural fit when the Auth Service runs on AWS and you want a managed control-plane store without running PostgreSQL or etcd yourself.

Storage concern	Supported
Cluster state (name: state)	yes
Audit events (name: audit-*)	yes
Session recordings (name: recordings)	no

TL;DR

1. Pick DynamoDB when the cluster already lives on AWS and you want AWS-managed durability, point-in-time recovery, and IAM-based access control.
2. Write one spec.dynamo StorageConfig for name: state and separate audit-* resources for each audit-events table.
3. Pair DynamoDB with S3 for session recordings.

Prerequisites

Before you start, make sure you have:

• An AWS region reachable from every Auth Service host.
• An IAM role attached to each Auth host, or static AWS keys if you must use them.
• Permission to create DynamoDB tables, or pre-created tables for state and audit with the AlmaForge schema applied.
• A design that stays within DynamoDB Streams limits. A single DynamoDB state backend supports at most two Auth Service instances.

Configuration

Step 1. Pick the table layout

Use DynamoDB when the cluster already lives on AWS and you want AWS-managed durability, point-in-time recovery, and IAM-based access control. It is the cleanest match for EC2, EKS, and other AWS-native deployments.

Use a different table for cluster state and audit events. The schemas differ, and reusing the state table breaks the driver.

Step 2. Write the state backend resource

Every Auth Service instance points at the same state table:

state.yaml:

examples/storage/dynamodb/state.yaml

# DynamoDB cluster-state backend with on-demand billing and backups.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: state
spec:
  dynamo:
    region: us-east-1
    tableName: cluster-state
    billingMode: PAY_PER_REQUEST
    continuousBackups: true

Field	Required	Default	Notes
region	yes	none	AWS region of the DynamoDB table.
tableName	yes	none	DynamoDB table used for cluster state. AlmaForge will create it if it does not exist.
accessKey	no	none	Static AWS access key. Prefer an IAM role instead.
secretKey	no	none	Static AWS secret key. Prefer an IAM role instead.
billingMode	no	PAY_PER_REQUEST	PAY_PER_REQUEST or PROVISIONED.
readCapacityUnits	no	10	Used when billingMode: PROVISIONED.
writeCapacityUnits	no	10	Used when billingMode: PROVISIONED.
continuousBackups	no	false	Enables DynamoDB point-in-time recovery.
autoScaling	no	false	Enables DynamoDB auto-scaling policy management.
readMinCapacity	when autoScaling: true	none	Auto-scaling lower bound for reads.
readMaxCapacity	when autoScaling: true	none	Auto-scaling upper bound for reads.
readTargetValue	when autoScaling: true	none	Auto-scaling target ratio for reads.
writeMinCapacity	when autoScaling: true	none	Auto-scaling lower bound for writes.
writeMaxCapacity	when autoScaling: true	none	Auto-scaling upper bound for writes.
writeTargetValue	when autoScaling: true	none	Auto-scaling target ratio for writes.
bufferSize	no	1024	Event watcher buffer capacity.
pollStreamPeriod	no	1s	Poll interval for the change-feed stream.
retryPeriod	no	10s	Retry interval for backend failures.

Step 3. Write any audit-events resources

The same dynamo driver field works for audit-events instances:

audit.yaml:

examples/storage/dynamodb/audit.yaml

# DynamoDB destination for audit events.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-primary
spec:
  dynamo:
    region: us-east-1
    tableName: cluster-audit

You can fan out across multiple regions or accounts by adding more audit-* instances:

audit-fanout.yaml:

examples/storage/dynamodb/audit-fanout.yaml

# Two DynamoDB destinations that each receive every audit event.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-primary
spec:
  dynamo:
    region: us-east-1
    tableName: cluster-audit
---
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: audit-failover
spec:
  dynamo:
    region: us-west-2
    tableName: cluster-audit

Most production audit configs only set region and tableName. The autoscaling and capacity knobs apply primarily when the state instance runs in PROVISIONED mode.

Retention lives on the driver block as auditRetentionPeriod. DynamoDB honors it via per-item TTL.

Step 4. Restart and verify

Restart the Auth Service after updating the bootstrap file, then verify the active resources:

Terminal

sudo systemctl restart almadalma get storageconfig/state -o yamlalma get storageconfig/audit-primary -o yaml

The configuration is loaded when the output names the intended state and audit tables. Sign in again and confirm that the login event appears in the audit log to check the write path.

URI form

Equivalent URI strings, suitable for an environment variable or a CLI flag. The URI host is the table name. Everything else is a query parameter.

State backend:

text

dynamodb://cluster-state?region=us-east-1&billing_mode=pay_per_request&continuous_backups=true

Audit backend with provisioned capacity and retention:

text

dynamodb://cluster-events?region=us-east-1&read_capacity_units=10&write_capacity_units=20&audit_retention_period=720h

Canonical query keys are snake_case. The typed JSON-tag form (billingMode, readCapacityUnits, etc.) is accepted as an alias. See Authentication.

Troubleshooting

A third Auth Service instance is lagging or getting throttled

That is the DynamoDB Streams reader limit. AWS caps a single stream shard at two simultaneous readers before it starts throttling. If you need more than two Auth instances, move the state backend to PostgreSQL.

State and audit share one table

Split them. The schemas differ, and audit writes fail against the state table.

Autoscaling settings do nothing

autoScaling and the capacity targets are ignored when billingMode: PAY_PER_REQUEST. Switch to PROVISIONED if you want the autoscaling knobs to take effect.

Operations

Authentication

Use an IAM role on the Auth host whenever possible. That keeps credentials out of the bootstrap file and follows normal AWS operational practice.

Static AWS keys via accessKey and secretKey are supported but should be the exception. The driver also honors the standard AWS SDK credential provider chain: environment variables, instance profile, and ~/.aws/credentials.

The IAM role attached to the Auth host needs DynamoDB read, write, and admin permissions on the configured tables, DynamoDB Streams permissions, and application-autoscaling permissions if autoScaling: true.

Durability and limits

Set continuousBackups: true if you want DynamoDB point-in-time recovery.

DynamoDB item size is capped at 400 KB. Oversized audit events exceed the driver limit and cannot be stored as a single item.

Session recordings do not live in DynamoDB. Pair this driver with S3 for the recordings instance.

References

• Storage backends overview.
• High availability, including the two-Auth-instance limit for DynamoDB state.
• Break-glass access.
• S3.
• AWS DynamoDB Streams documentation.