Deploying SelectZero

Requirements

1. External PostgreSQL as the application database (SQLite is not supported in S3 mode)

2. DQM_ENCRYPTION_KEY must be provided from your secrets manager - the application refuses to start in S3 mode without it, because a locally generated key would not survive a pod restart and would make the encrypted files in the bucket unreadable

3. An S3 bucket and IAM permissions: s3:ListBucket on the bucket, s3:GetObject, s3:PutObject, s3:DeleteObject on the bucket contents

At startup in S3 mode the application lists the bucket once to verify the configuration. If the bucket cannot be reached - wrong name or region, missing s3:ListBucket, or credentials that do not resolve - the application refuses to start and logs the reason, rather than running with file storage that would fail later during a scheduled job.

Configuration

Reading a credential failure

When credentials cannot be resolved, the AWS SDK reports every provider it tried. Only the provider matching your setup matters; the others always fail and can be ignored:

• Running with an IAM role (IRSA or EKS Pod Identity), the messages about AWS_ACCESS_KEY_ID are expected. A role never produces an access key.

• Profile file contained no credentials for profile 'default' refers to an AWS credentials profile (~/.aws/credentials), not to a Kubernetes service account. The container has no such file, so this line is normal and unrelated to which service account the pod runs under.

• With IRSA, the line to check is the web identity one. The pod's service account must carry the eks.amazonaws.com/role-arn annotation, which makes EKS inject AWS_ROLE_ARN and AWS_WEB_IDENTITY_TOKEN_FILE into the container. Verify with kubectl exec <pod> -- env | grep AWS_; the service account itself is selected by spec.serviceAccountName in the pod spec, never by application configuration.

Security model with file encryption disabled

When DQM_FILE_ENCRYPTION=false, encryption at rest is provided by the infrastructure instead of the application. Verify and configure the following:

1. Bucket encryption. Check what the bucket applies with aws s3api get-bucket-encryption --bucket <bucket>. Every S3 bucket encrypts objects at rest by default (SSE-S3/AES256). For customer-controlled key rotation, configure the bucket with SSE-KMS and a customer-managed KMS key, and enable S3 Bucket Keys to reduce KMS request costs (SelectZero writes many small objects). Rotating the KMS key never requires re-encrypting stored objects.

2. Per-object proof. aws s3api head-object --bucket <bucket> --key "reports/results/<file>" returns a ServerSideEncryption field (AES256 or aws:kms with the key id) - evidence that a specific object is encrypted at rest.

3. IAM. With SSE-KMS the application's role additionally needs kms:GenerateDataKey and kms:Decrypt on the key, on top of the S3 permissions listed under Requirements.

4. Bucket policies. The application sends no explicit encryption headers - bucket default encryption applies to its uploads. A bucket policy that denies PutObject requests lacking an explicit x-amz-server-side-encryption header will therefore reject all uploads; rely on bucket default encryption instead of such deny policies.

5. Local working copies. The pod's ephemeral volume holds plaintext working copies of uploaded files and cached results while the pod runs (with file encryption enabled it holds plaintext temporary data during query execution as well - only the durable copies differ). At-rest protection for the node comes from volume encryption (e.g. encrypted EBS), which is the same posture as any database workload. For the strictest setup, back the working directories with emptyDir: {medium: Memory} sized for the full uploaded-file set plus cache - plaintext then never touches a disk.

Secrets stored in database columns (connection passwords, certificates, tokens) are encrypted with DQM_ENCRYPTION_KEY in every mode - the flag only affects files.

Kubernetes example

The deployment differs from the persistent volume variant in three ways: no PersistentVolumeClaim (all volumes are emptyDir), the Recreate update strategy (avoids two pods overlapping on the same working files), and the storage/encryption environment variables.

Startup hydration

On every pod start in S3 mode, SelectZero restores its working directories (uploaded data source files, drivers, logo) from the bucket before the application becomes ready. Progress is visible in the system log:

Startup time grows with the amount of uploaded data (downloads run in parallel; roughly 1-3 minutes for 15GB of uploaded files in-region). Configure the pod's startupProbe with enough headroom for your data volume so Kubernetes does not restart the pod mid-hydration.