Storage servers and their settings

What an account consists of

The S3 module records each storage account and writes an S3StorageAccount resource (platform.stackship.se/v1); the Stackship operator builds the rest in the resource group's namespace:

Object	Name	Notes
Deployment	s3sa-<account>	One replica; replaced with the Recreate strategy, because the volume can be attached to one pod at a time
PersistentVolumeClaim	s3sa-<account>-<suffix>	Size = the account's quota; the cluster's default storage class. Created once and never resized
Service and Ingress	s3sa-<account>	The Ingress serves the account's hostname, with a certificate from the installation's issuer unless the account names its own Secret
Secret	s3sa-<account>-module-creds	The client credentials of the account's own managed identity
ServiceAccount	stackship-s3-server	Shared by the S3 server pods of the namespace

Each server calls back to the S3 module on its gRPC port 8081 to check credentials, register buckets, report usage and send audit entries. The boundary's Object storage control network grant allows that — see Network rules.

Installation settings

Setting	Where	Holds
S3__HostnameSuffix	ConfigMap module-s3-config	The parent domain of account hostnames, s3.example.com, derived from the API domain
S3__ServerImage	ConfigMap stackship-operator-config	The S3 server image, <registry host>/public/s3-server:<version>, pinned by the platform release
S3__ControlPlaneGrpcUrl	ConfigMap stackship-operator-config	Where servers reach the S3 module: http://module-s3.stackship-system:8081
S3__PortalOrigins	ConfigMap stackship-operator-config	The portal's origin, which every server allows for CORS
DataProtection__DEK	Secret stackship-data-protection, key dek	The key that protects the stored secrets of access keys and temporary credentials

Both ConfigMaps are in stackship-system. The operator's ConfigMap is rendered again when the platform is upgraded, so changes made to it by hand do not survive an upgrade.

Account hostnames are <account>.s3.example.com unless an account sets its own, so s3.example.com needs a wildcard DNS record that points at the ingress controller.

The S3 module refuses to start unless DataProtection__DEK decodes to exactly 32 bytes. Replacing the key makes every stored access key and temporary credential unusable.

Server versions

A platform upgrade can bring a new S3__ServerImage. New accounts start on it; an existing account keeps the image its server was started with until its configuration changes — a change to its hostname, TLS settings, CORS origins or Allow S3 API bucket lifecycle starts its server on the current image. A change to HTTP only or Retain data on delete does not. A change to S3__PortalOrigins restarts the server of every account, on the current image.

Kept volumes

When an account with Retain data on delete is deleted, its PersistentVolumeClaim stays in the namespace, detached. A new account never reuses it: volume names carry the account's unique ID. To recover the data, mount the claim in a pod of your own and copy it off — objects are stored as files, in one directory per bucket — and delete the claim when you are done. Claims are deleted with their namespace, that is, when the resource group is deleted.

The operator deletes claims but never PersistentVolumes. For Retain data on delete off to free the disk, the storage class must have the reclaim policy Delete.

Audit data

The S3 module keeps audit entries in the schema s3_audit of the platform database and deletes entries older than 90 days once a day.