s3proxy

A Helm chart for deploying S3Proxy - Access other storage backends via the S3 API

• Kubernetes 1.19+
• Helm 3.2.0+
• PV provisioner support in the underlying infrastructure (if using filesystem backend with persistence)

Chart 1.x targets S3Proxy 4.x (appVersion currently 4.1.1; override with image.tag). Minimum supported version is 4.0.0.

S3Proxy 4.0.0 removed Apache jclouds and, with it, the Atmos and B2 backends and the -sdk / -nio2 provider-name variants. Each backend now has a single native/SDK implementation selected by its plain name — filesystem, transient, aws-s3, azureblob, google-cloud-storage, openstack-swift — so the chart no longer exposes the aws: / nio2: / azureblob.provider toggles.

• filesystem / transient — the NIO2 implementations (no toggle).
• s3 — the aws-s3 AWS SDK provider; serves AWS or any S3-compatible endpoint (set endpoint). Supports keyless auth: leave accessKeyID/secretAccessKey empty and set s3.keyless: true to use the AWS default credential chain (IRSA / EKS Pod Identity / EC2 instance profile).
• azureblob — the Azure SDK; supports Managed/Workload Identity via azureblob.managedIdentity: true (no static key) — see "Example 3b".
• googleCloudStorage — the Google SDK; a static service-account JSON key is required (serviceAccountKey.value / .existingSecret). Keyless GCS (Workload Identity/ADC) is not supported by S3Proxy 4.x — an empty credential selects an unauthenticated (emulator-only) client, not ADC.
• openstackSwift — the openstack4j SDK (Keystone v3); set projectName and, if non-default, projectDomainName / userDomainName.

Removed in chart 1.x: the b2 and rackspaceCloudfiles backends (jclouds-only, dropped upstream). Rackspace Cloud Files is OpenStack-Swift-compatible — configure it via the openstackSwift backend.

• Guardrail: the chart hard-fails at render time if the effective S3Proxy version (image.tag, else appVersion) parses as semver and is older than 4.0.0, so it cannot render a 4.x-only config against a 3.x image. Use chart 0.x for S3Proxy 3.x.

# Install with default values (filesystem backend)
helm install my-s3proxy oci://ghcr.io/comet-ml/s3proxy

# Install with custom values
helm install my-s3proxy oci://ghcr.io/comet-ml/s3proxy -f override-values.yaml

The following section lists the configurable parameters of the s3proxy chart and their default values.

Scroll sideways to see all columns.

# values-filesystem.yaml
config:
  auth:
    type: "aws-v4"
    identity: "myaccesskey"
    secret: "mysecretkey"
  backends:
    filesystem:
      enabled: true
      basedir: "/data/s3proxy"

persistence:
  enabled: true
  size: 20Gi

Install:

helm install s3proxy-fs ./s3proxy -f values-filesystem.yaml

# values-aws-s3.yaml
config:
  auth:
    type: "aws-v4"
    identity: "proxy-access-key"  # For clients connecting to s3proxy
    secret: "proxy-secret-key"
  backends:
    filesystem:
      enabled: false
    s3:
      enabled: true
      region: "us-west-2"
      accessKeyID: "aws-access-key-id"       # For s3proxy to connect to AWS
      secretAccessKey:
        value: "aws-secret-access-key"

persistence:
  enabled: false  # Not needed for S3 backend

For keyless auth on EKS (IRSA / Pod Identity) or EC2, drop the keys and set keyless:

config:
  backends:
    filesystem:
      enabled: false
    s3:
      enabled: true
      region: "us-west-2"
      keyless: true

Install:

helm install s3proxy-s3 ./s3proxy -f values-aws-s3.yaml

# values-azure.yaml
config:
  auth:
    type: "aws-v4"
    identity: "myaccesskey"
    secret: "mysecretkey"
  backends:
    filesystem:
      enabled: false
    azureblob:
      enabled: true
      account: "mystorageaccount"
      key:
        value: "storageaccountkey"

persistence:
  enabled: false  # Not needed for Azure backend

Install:

helm install s3proxy-azure ./s3proxy -f values-azure.yaml

On AKS with Workload Identity, set managedIdentity: true instead of an account key or SAS token. The chart then renders both jclouds.identity and jclouds.credential empty, which makes the azureblob-sdk provider fall back to Azure's DefaultAzureCredential — it reads the federated token AKS injects (AZURE_CLIENT_ID / AZURE_TENANT_ID / AZURE_FEDERATED_TOKEN_FILE). The storage account name goes in the endpoint, never in the identity.

# values-azure-mi.yaml
config:
  backends:
    filesystem:
      enabled: false
    azureblob:
      enabled: true
      managedIdentity: true
      account: "mystorageaccount" # used for the endpoint; NOT emitted as jclouds.identity
      # endpoint: "https://mystorageaccount.blob.core.windows.net"  # or set explicitly

# Bind the pod to the AKS user-assigned identity:
serviceAccount:
  create: true
  annotations:
    azure.workload.identity/client-id: "<managed-identity-client-id>"
podLabels:
  azure.workload.identity/use: "true"

persistence:
  enabled: false

The GCS SDK reads the credential as a full service-account JSON key. A static key is required — S3Proxy 4.x does not support keyless GCS (Workload Identity/ADC).

# values-gcs.yaml
config:
  auth:
    type: "aws-v4"
    identity: "myaccesskey"
    secret: "mysecretkey"
  backends:
    filesystem:
      enabled: false
    googleCloudStorage:
      enabled: true
      projectID: "my-project"
      serviceAccountKey:
        # The full service-account JSON key (or use existingSecret / secretKey).
        value: |
          {
            "type": "service_account",
            "project_id": "my-project",
            "private_key": "-----BEGIN PRIVATE KEY-----\n...\n-----END PRIVATE KEY-----\n",
            "client_email": "service-account@my-project.iam.gserviceaccount.com"
          }

persistence:
  enabled: false  # Not needed for GCS backend

# values-anonymous.yaml
config:
  auth:
    type: "none"
  backends:
    transient:
      enabled: true  # In-memory storage

persistence:
  enabled: false

config.auth.identity / config.auth.secret are the S3 Access Key ID and Secret Access Key that clients present to S3Proxy.

Point config.auth.existingSecret at a Secret you manage yourself, so the credentials never appear in the values file (e.g. in GitOps). It takes precedence over inline identity/secret; both credentials are read from it:

config:
  auth:
    type: "aws-v4"
    existingSecret: my-s3proxy-auth
    identityKey: accessKeyId        # default; key holding the Access Key ID
    secretKey: secretAccessKey      # default; key holding the Secret Access Key

kubectl create secret generic my-s3proxy-auth \
  --from-literal=accessKeyId='myaccesskey' \
  --from-literal=secretAccessKey='mysecretkey'

Rotating the Secret does not restart the pod — roll the Deployment yourself, since the credentials are read once at startup.

Set config.auth.identity / config.auth.secret directly, as in Example 1. Convenient for testing; both values are stored in plaintext in the chart's own Secret.

Once deployed, you can test S3Proxy using the AWS CLI:

# Get the service endpoint
kubectl get svc

# Port-forward for local testing
kubectl port-forward svc/my-s3proxy 8080:8080

# Configure AWS CLI (if authentication is enabled)
export AWS_ACCESS_KEY_ID=myaccesskey
export AWS_SECRET_ACCESS_KEY=mysecretkey

# Test S3 operations
aws --endpoint-url http://localhost:8080 s3 ls
aws --endpoint-url http://localhost:8080 s3 mb s3://test-bucket
aws --endpoint-url http://localhost:8080 s3 cp test.txt s3://test-bucket/
aws --endpoint-url http://localhost:8080 s3 ls s3://test-bucket/

By default S3Proxy binds plain HTTP and TLS is expected to be terminated at the ingress. Set config.tls.enabled=true to have S3Proxy itself terminate HTTPS in the pod (S3Proxy's secure-endpoint). When enabled:

• S3Proxy serves HTTPS only on service.targetPort (the plaintext endpoint is not bound). The container/Service port is named https.
• The health probes are tcpSocket, which only check the TCP accept (no TLS handshake), so they keep working unchanged against the TLS port.
• A PKCS12 keystore is expected (Jetty's default keystore type; JKS also works if supplied). S3Proxy exposes only the keystore path and password, so the chart does not set a keystore type.
• The keystore password is never written to the ConfigMap; it is merged into the backend properties from the Secret by the config-merge initContainer.

Reference a Secret that already holds the keystore file and the password. This is also how a cert-manager Certificate with spec.keystores.pkcs12 delivers a keystore (point keystore.existingSecret at that Secret, and keystorePassword.existingSecret at the password Secret it references):

config:
  tls:
    enabled: true
    keystore:
      existingSecret: my-tls        # holds the PKCS12 archive
      secretKey: keystore.p12
    keystorePassword:
      existingSecret: my-tls        # holds the password (may be the same Secret)
      secretKey: keystore-password

Provide the base64-encoded keystore and the password inline; both are stored in the chart's own Secret. Convenient for testing; prefer Option A in production.

config:
  tls:
    enabled: true
    keystore:
      value: "<base64-encoded PKCS12 keystore>"
    keystorePassword:
      value: "changeit"

Create a PKCS12 keystore, for example:

# From an existing cert + key:
openssl pkcs12 -export -inkey tls.key -in tls.crt \
  -out keystore.p12 -passout pass:changeit
# Inline value:
base64 -w0 keystore.p12
# Or as an existing Secret (Option A):
kubectl create secret generic my-tls \
  --from-file=keystore.p12=keystore.p12 \
  --from-literal=keystore-password=changeit

Testing over HTTPS (the CI keystore above is self-signed, so skip verification):

aws --endpoint-url https://localhost:9000 --no-verify-ssl s3 ls

To enable CORS support:

config:
  cors:
    enabled: true
    allowOrigins:
      - "https://example.com"
      - "https://.+\\.example\\.com"
    allowMethods:
      - "GET"
      - "PUT"
      - "POST"
      - "HEAD"
      - "DELETE"
    allowHeaders:
      - "Accept"
      - "Content-Type"
    allowCredential: true

S3Proxy supports various middlewares:

config:
  middlewares:
    readOnly: false           # Make backend read-only
    eventualConsistency: true # Enable eventual consistency modeling
    shardedBackend: true      # Enable sharded backend containers
    largeObjectMocking: false # Enable large object mocking

Map virtual bucket names to actual backend buckets:

config:
  buckets:
    alias:
      virtual-bucket: "real-backend-bucket"
      another-bucket: "actual-bucket-name"

When more than one backend is enabled, assign buckets to a specific backend with that backend's own bucketLocators list. S3Proxy reads bucket-locators per backend, so each list is emitted only into that backend's properties file. Glob patterns are supported. A bucket that matches no backend's list falls through to the first-enabled backend (the default).

config:
  backends:
    s3:
      enabled: true
      # ... credentials ...
      bucketLocators:
        - "prod-*"
        - "customer-data"
    filesystem:
      enabled: true
      bucketLocators:
        - "scratch-*"   # everything else also lands here (first-enabled default)

Check S3Proxy logs:

kubectl logs deployment/my-s3proxy

helm upgrade my-s3proxy ./s3proxy -f my-values.yaml

helm uninstall my-s3proxy

This will remove all resources created by the chart. If using persistence, the PVC will be retained by default.

1. Authentication failures: Ensure config.auth.identity and config.auth.secret are set correctly (or, with config.auth.existingSecret, that the Secret exists and its identityKey/secretKey entries are present) for client authentication.

2. Backend connection issues: Verify backend credentials are correctly configured in the appropriate section (e.g., config.backend.awsS3.*).

3. Persistence issues: Check that your cluster has a default StorageClass or specify one explicitly.

4. Port conflicts: If port 8080 is already in use, change service.port and service.targetPort.

• S3Proxy GitHub Repository
• S3Proxy Docker Hub
• Storage Backend Examples

This Helm chart is provided as-is. S3Proxy itself is licensed under the Apache License 2.0.

Autogenerated from chart metadata using helm-docs v1.14.2