Skip to main content

S3

S3 is the AWS-native recording driver. The s3 driver field configures session recordings. It cannot be used for cluster state or audit events.

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

TL;DR​

  1. Enable bucket versioning before you start. AlmaForge depends on it for recording integrity.
  2. Write a StorageConfig with spec.s3 for name: recordings.
  3. Use an IAM role when possible, and use S3 bucket replication if you need cross-region copies.

Prerequisites​

Before you start, make sure you have:

  • An S3 bucket with versioning enabled.
  • An IAM role on the Auth host, or AWS credentials reachable through the standard AWS SDK provider chain.
  • A reachable endpoint URL if you are using an S3-compatible store such as MinIO or Ceph RGW.
  • A plan for server-side encryption and object ownership if you need them.

Bucket versioning must be enabled. AlmaForge reads the oldest version of a recording and relies on versioning so a later overwrite cannot silently replace the original session artifact.

Configuration​

Step 1. Pick the bucket layout​

Use S3 when AlmaForge runs on AWS, or when your on-prem environment exposes an S3-compatible object store such as MinIO or Ceph RGW. Select it explicitly with a recordings StorageConfig or ALMA_RECORDINGS_URI. Without recording storage configuration, recordings stay in local files under $ALMA_DATA_DIR/records, including when the state backend is DynamoDB.

There is exactly one recordings instance per cluster. If you need extra copies, use bucket-side replication rather than multiple AlmaForge recording stores.

Step 2. Write the recordings resource​

Basic S3 configuration:

recordings.yaml:

examples/storage/s3/recordings.yaml
# S3 destination for session recordings.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  s3:
    bucket: almaforge-recordings
    region: us-east-1
    path: records

For a custom S3-compatible endpoint such as MinIO:

recordings-compatible.yaml:

examples/storage/s3/recordings-compatible.yaml
# S3-compatible destination for session recordings.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  s3:
    bucket: almaforge-recordings
    region: us-east-1
    endpoint: minio.internal.example.com
    path: records

For server-side encryption with a customer-managed KMS key:

recordings-kms.yaml:

examples/storage/s3/recordings-kms.yaml
# S3 recording destination encrypted with an AWS KMS key.
apiVersion: almaforge.com/v1
kind: StorageConfig
metadata:
  name: recordings
spec:
  s3:
    bucket: almaforge-recordings
    region: us-east-1
    sseKmsKey: arn:aws:kms:us-east-1:123456789012:key/abcd1234-...
FieldRequiredDefaultNotes
bucketyesnoneS3 bucket name.
regionyesnoneAWS region.
pathnobucket rootPath prefix inside the bucket. Operators usually set this to records.
endpointnoAWS S3 defaultCustom endpoint for S3-compatible object stores.
aclnounsetCanned ACL name, such as bucket-owner-full-control for cross-account uploads.
sseKmsKeynounsetCustomer-managed KMS key ID or ARN for server-side encryption.
disableServerSideEncryptionnofalseDisables the server-side encryption AlmaForge otherwise requests on upload. Use when the bucket enforces its own SSE.
insecurenofalseUses HTTP instead of HTTPS. Do not use this in production.

Step 3. Restart and verify​

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

Terminal
sudo systemctl restart almadalma get storageconfig/recordings -o yaml

Open and end a recorded terminal session, then replay it from the Web UI. Successful replay verifies uploads, object reads, and the permissions needed to retrieve the original recording.

URI form​

Equivalent URI string, suitable for an environment variable or a CLI flag. The URI host is the bucket. The URI path is the optional key prefix. Everything else is a query parameter:

text
s3://almaforge-recordings/sessions?region=us-east-1&sse_kms_key=arn:aws:kms:us-east-1:123:key/abc

Canonical query keys are snake_case (sse_kms_key, acl, insecure). disablesse is the legacy single-word canonical key for the disable-SSE knob. The typed JSON-tag forms (sseKmsKey, disableServerSideEncryption) are accepted as aliases. See Authentication.

Troubleshooting​

Versioning is disabled on the bucket​

Turn it on before using the driver. Versioning is the main integrity safeguard for S3-backed recordings.

Objects land in the wrong account after cross-account uploads​

Set acl: bucket-owner-full-control so the destination bucket owner can read the objects without depending on the uploader's account.

A non-AWS object store is in use​

Set endpoint to the S3-compatible service address. AlmaForge does not require AWS S3 itself.

Operations​

Authentication​

The S3 driver uses the standard AWS SDK credential provider chain. An IAM role on the Auth host is the preferred path.

The role needs S3 read, write, list, and multipart permissions on the configured bucket and prefix, plus s3:GetBucketVersioning and s3:PutBucketVersioning if you let AlmaForge manage versioning.

Encryption​

Set sseKmsKey to a valid KMS key ID or ARN if you want customer-managed encryption. The Auth host's IAM principal needs kms:Encrypt, kms:GenerateDataKey, kms:Decrypt, kms:ReEncrypt*, and kms:DescribeKey on that key.

Replication and fan-out​

There is exactly one recordings instance per cluster. To replicate recordings across regions or accounts, use S3 cross-region replication on the bucket itself.

References​