Object storage

Overview

The trace bucket holds raw uploads and canonical trace objects in your cloud account, and PostgreSQL stores their references and processing state. Use this guide before you deploy the analyzer to prepare private trace storage and scope the analyzer’s access to it. It also covers retention that keeps traces recoverable. Return to it before you change the storage location of an active deployment.

Configure exactly one object-storage backend for each deployment.

Choose a native backend

Each platform’s native storage authenticates the analyzer through workload identity:

Platform	Storage	Workload authentication
AWS	Amazon S3 bucket and prefix.	An IAM role bound to the analyzer’s Kubernetes ServiceAccount.
Azure	Blob Storage account, private container, and prefix.	Microsoft Entra Workload ID bound to the analyzer’s ServiceAccount.
Google Cloud	Cloud Storage bucket and prefix.	Workload Identity Federation for GKE.

The Terraform guides configure native storage in the same cloud as the cluster. Your analysis model is a separate choice; see Model providers.

Configure the location

Create private storage with public access disabled, encryption at rest, and HTTPS in transit.
Bind the storage data-access identity to the analyzer’s ServiceAccount, pig-analyzer in namespace pig. Keep storage credentials out of distributed host plugins.

Add one storage block under spec.storage, alongside postgres:

s3:
  region: us-west-2
  bucket: acme-pig-traces
  prefix: acme/traces

azureBlob:
  accountURL: https://acmepig.blob.core.windows.net
  container: traces
  prefix: acme/traces

gcs:
  bucket: acme-pig-traces
  prefix: acme/traces

Scope data access

The analyzer writes trace objects and reads them back. Scope its permissions to the deployment’s bucket or container and prefix where the provider supports it. Include the bucket metadata or listing permissions and the encryption-key access that your configuration requires.

The cloud modules define the provider-specific grants; review them with the Terraform plan. Azure’s built-in Storage Blob Data Contributor role includes deletion. If your policy requires narrower access, use a custom role. See Azure’s Blob data roles.

Let the workload identity refresh its credentials, and don’t copy temporary tokens into Kubernetes Secrets. Application data access needs no permission to create buckets, resize databases, or change IAM.

Set retention and recovery

Set object retention, version recovery, and backup policies together with your PostgreSQL recovery policy. Retain an object while live rows, retained database backups, or a pending background write still reference it. An archive tier that requires restoration can prevent analysis from reading a trace.

Changing the configured bucket, container, or prefix leaves existing objects where they are. Before you change it for an active deployment, plan a storage migration with Promptless. Preserve the raw and canonical objects that recovery and analysis need.

During deployment verification, check one session’s recorded object location and confirm the object is readable. A successful upload request doesn’t prove durable storage.

How the analyzer writes canonical objects

The analyzer writes each canonical trace object under the configured prefix, at a content-addressed key derived from the object’s contents. Newer content gets a new key, so a delayed upload never overwrites a newer canonical version. The analyzer records an uploaded object as the trace’s location only while it still matches the trace’s current content. Objects written by earlier releases stay readable at their original keys.

The analyzer retries an interrupted or failed canonical write in the background, with a persisted backoff between attempts. A trace that stays pending or failed doesn’t hold back writes for other traces. Because keys depend on content, read the recorded object location during verification. Don’t derive a key from the session ID.

To check storage access, the analyzer writes one small diagnostic object under checks/ in the configured prefix at startup. Each later readiness check reads that object back.