s3proxy

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

Prerequisites

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

Installation

Install the chart

# 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

Configuration

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

Values

Scroll sideways to see all columns.

Key	Description	Type	Default
affinity	Affinity for pod assignment	object	{}
autoscaling.enabled	Enable HPA	bool	false
autoscaling.maxReplicas	Maximum number of replicas	int	100
autoscaling.minReplicas	Minimum number of replicas	int	1
autoscaling.targetCPUUtilizationPercentage	Target CPU utilization percentage	int	80
config.auth.identity	S3 Access Key ID for client authentication	string	""
config.auth.secret	S3 Secret Access Key for client authentication	string	""
config.auth.type	Authorization type (none, aws-v2, aws-v4, aws-v2-or-v4)	string	"aws-v4"
config.backends.azureblob.account	Storage account name	string	""
config.backends.azureblob.enabled	Enable Azure Blob Storage backend	bool	false
config.backends.azureblob.endpoint	Azure endpoint	string	""
config.backends.azureblob.key	Storage account key	string	""
config.backends.azureblob.provider	Provider type (azureblob or azureblob-sdk)	string	"azureblob"
config.backends.azureblob.sasToken	SAS token	string	""
config.backends.b2.account	B2 account ID	string	""
config.backends.b2.applicationKey	B2 application key	string	""
config.backends.b2.enabled	Enable Backblaze B2 backend	bool	false
config.backends.filesystem.basedir	Base directory for filesystem backend	string	"/data/s3proxy"
config.backends.filesystem.enabled	Enable filesystem backend	bool	true
config.backends.filesystem.nio2	Use NIO2 implementation (filesystem-nio2) instead of standard filesystem	bool	true
config.backends.googleCloudStorage.clientEmail	Service account email or user email (used with both privateKey and jsonCredentials methods)	string	""
config.backends.googleCloudStorage.enabled	Enable Google Cloud Storage backend	bool	false
config.backends.googleCloudStorage.jsonCredentials	JSON credentials configuration	object	{"enabled":false,"existingSecret":"","jsonContent":"","secretKey":"credentials.json"}
config.backends.googleCloudStorage.jsonCredentials.enabled	Use JSON credentials file instead of privateKey	bool	false
config.backends.googleCloudStorage.jsonCredentials.existingSecret	Name of existing secret containing GCP credentials JSON	string	""
config.backends.googleCloudStorage.jsonCredentials.jsonContent	JSON content for creating a new secret (takes precedence over existingSecret)	string	""
config.backends.googleCloudStorage.jsonCredentials.secretKey	Key in the secret containing the JSON credentials (default: credentials.json)	string	"credentials.json"
config.backends.googleCloudStorage.privateKey	Private key (only used when jsonCredentials.enabled is false)	string	""
config.backends.googleCloudStorage.projectID	GCP project ID	string	""
config.backends.openstackSwift.authURL	Authentication URL	string	""
config.backends.openstackSwift.enabled	Enable OpenStack Swift backend	bool	false
config.backends.openstackSwift.password	Password	string	""
config.backends.openstackSwift.region	Region	string	""
config.backends.openstackSwift.tenantName	Tenant name	string	""
config.backends.openstackSwift.userName	Username	string	""
config.backends.rackspaceCloudfiles.apiKey	API key	string	""
config.backends.rackspaceCloudfiles.enabled	Enable Rackspace Cloud Files backend	bool	false
config.backends.rackspaceCloudfiles.region	Region (uk or us)	string	"us"
config.backends.rackspaceCloudfiles.userName	Username	string	""
config.backends.s3.accessKeyID	S3 Access Key ID for backend	string	""
config.backends.s3.aws	Use AWS-specific S3 provider (aws-s3) instead of generic S3 provider	bool	true
config.backends.s3.enabled	Enable S3 backend	bool	false
config.backends.s3.endpoint	S3 endpoint	string	""
config.backends.s3.region	AWS region	string	""
config.backends.s3.secretAccessKey	S3 Secret Access Key for backend	string	""
config.backends.transient.enabled	Enable transient (in-memory) backend	bool	false
config.backends.transient.nio2	Use NIO2 implementation (transient-nio2) instead of standard transient	bool	true
config.buckets.alias	Map virtual bucket names to actual backend buckets	object	{}
config.buckets.locator	Assign specific buckets to different backends (glob patterns supported)	list	[]
config.cors.allowCredential	Allow credentials	bool	false
config.cors.allowHeaders	Allowed headers	list	["Accept","Content-Type"]
config.cors.allowMethods	Allowed methods	list	["GET","PUT","POST","HEAD","DELETE"]
config.cors.allowOrigins	Allowed origins (e.g., ["https://example.com", "https://.+\\.example\\.com"])	list	[]
config.cors.enabled	Enable CORS support	bool	false
config.logLevel	Log level for S3Proxy (DEBUG, INFO, WARN, ERROR)	string	"INFO"
config.middlewares.eventualConsistency	Enable eventual consistency modeling	bool	false
config.middlewares.largeObjectMocking	Enable large object mocking	bool	false
config.middlewares.readOnly	Make backend read-only	bool	false
config.middlewares.shardedBackend	Enable sharded backend containers	bool	false
config.virtualHost	Virtual Host configuration	string	""
configMergeImage.pullPolicy	Config merge container image pull policy	string	"IfNotPresent"
configMergeImage.repository	Config merge container image repository	string	"busybox"
configMergeImage.tag	Config merge container image tag	string	"1.36"
extraEnvVars	Additional environment variables	list	[]
extraVolumeMounts	Additional volume mounts	list	[]
extraVolumes	Additional volumes	list	[]
fullnameOverride	String to fully override s3proxy.fullname template	string	""
image.pullPolicy	Image pull policy	string	"IfNotPresent"
image.repository	S3Proxy image repository	string	"andrewgaul/s3proxy"
image.tag	Overrides the image tag whose default is the chart appVersion	string	""
imagePullSecrets	Image pull secrets	list	[]
ingress.annotations	Ingress annotations	object	{}
ingress.className	Ingress class name	string	""
ingress.enabled	Enable ingress	bool	false
ingress.hosts	Ingress hosts configuration	list	[]
ingress.tls	TLS configuration	list	[]
nameOverride	String to partially override s3proxy.fullname template	string	""
nodeSelector	Node selector for pod assignment	object	{}
persistence.accessMode	PVC Access Mode	string	"ReadWriteOnce"
persistence.annotations	PVC annotations	object	{}
persistence.enabled	Enable persistence using PVC	bool	true
persistence.existingClaim	Use existing PVC	string	""
persistence.size	PVC Storage Request	string	"10Gi"
persistence.storageClass	Storage Class	string	"" (uses default StorageClass)
podAnnotations	Annotations to add to the pod	object	{}
podSecurityContext	Pod security context	object	{}
replicaCount	Number of S3Proxy replicas	int	1
resources	Resource limits and requests	object	{}
securityContext	Container security context	object	{}
service.annotations	Service annotations	object	{}
service.port	Service port	int	9000
service.targetPort	Target port (controls both the container port and S3Proxy bind port)	int	9000
service.type	Kubernetes service type	string	"ClusterIP"
serviceAccount.annotations	Annotations to add to the service account	object	{}
serviceAccount.create	Specifies whether a service account should be created	bool	false
serviceAccount.name	The name of the service account to use. If not set and create is true, a name is generated using the fullname template	string	""
tolerations	Tolerations for pod assignment	list	[]

Usage Examples

Example 1: Filesystem Backend with Authentication

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

persistence:
  enabled: true
  size: 20Gi

Install:

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

Example 2: AWS S3 Backend

# values-aws-s3.yaml
config:
  auth:
    type: "aws-v4"
    identity: "proxy-access-key"  # For clients connecting to s3proxy
    secret: "proxy-secret-key"
  backend:
    provider: "aws-s3"
    awsS3:
      region: "us-west-2"
      accessKeyID: "aws-access-key-id"  # For s3proxy to connect to AWS
      secretAccessKey: "aws-secret-access-key"

persistence:
  enabled: false  # Not needed for S3 backend

Install:

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

Example 3: Azure Blob Storage Backend

# values-azure.yaml
config:
  auth:
    type: "aws-v4"
    identity: "myaccesskey"
    secret: "mysecretkey"
  backend:
    provider: "azureblob"
    azureblob:
      account: "mystorageaccount"
      key: "storageaccountkey"

persistence:
  enabled: false  # Not needed for Azure backend

Install:

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

Example 4: Google Cloud Storage Backend

# values-gcs.yaml
config:
  auth:
    type: "aws-v4"
    identity: "myaccesskey"
    secret: "mysecretkey"
  backend:
    provider: "google-cloud-storage"
    googleCloudStorage:
      projectID: "my-project"
      clientEmail: "[email protected]"
      privateKey: |
        -----BEGIN RSA PRIVATE KEY-----
        ...
        -----END RSA PRIVATE KEY-----

persistence:
  enabled: false  # Not needed for GCS backend

Example 5: Anonymous Access (No Authentication)

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

persistence:
  enabled: false

Testing the Installation

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/

CORS Configuration

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

Middleware Configuration

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

Bucket Configuration

Bucket Aliasing

Map virtual bucket names to actual backend buckets:

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

Bucket Locator

Assign specific buckets to different backends:

config:
  buckets:
    locator:
      - "bucket1"
      - "bucket2"
      - "*.test"  # Glob patterns supported

Monitoring

Check S3Proxy logs:

kubectl logs deployment/my-s3proxy

Upgrading

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

Uninstalling

helm uninstall my-s3proxy

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

Troubleshooting

Common Issues

1. Authentication failures: Ensure config.auth.identity and config.auth.secret are set correctly 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.

References

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

License

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