Helm chart to deploy a single-node Garage
(S3-compatible object storage) to Kubernetes. It runs one node with
replication_factor=1 (no clustering/node discovery), keeps upstream security
hardening and optional Prometheus monitoring, and can optionally bootstrap a
bucket + access key on first boot.
The default configuration for this Helm chart is defined in the values.yaml file. For detailed descriptions of all the configurable parameters, refer to the provided values.reference.yaml file. This file serves as the reference for all available settings and their default values. Do not use this for deployment.
A fresh Garage node serves no S3 traffic until it has a cluster layout. By default (garage.singleNode: true) the chart starts Garage with --single-node, and Garage creates the layout itself on first boot. In this mode Garage refuses to start once the layout version is higher than 1, so nothing else may change the layout.
To let the AboutBits Garage Operator manage the layout with a GarageCluster, set garage.singleNode: false. Garage then starts without a layout until the operator applies one. The probes do not use the admin API's /health for this reason: it answers 503 until there is a layout, so a probe on it would keep the Pod out of the Service the operator connects through. They check that Garage answers, not that the cluster can serve requests. bootstrap.enabled needs single-node mode, because Garage accepts --default-bucket only there; create the bucket and the key with the operator's Bucket and AccessKey instead.
The chart takes no secrets as values, because values are stored in places such as the Terraform state of a helm_release and the Helm release Secret. Instead, it reads them from an existing Secret created by a secret manager such as the 1Password operator:
| Secret | Existing Secret | Default key(s) | Without it |
|---|---|---|---|
| RPC secret | garage.existingRpcSecret |
GARAGE_RPC_SECRET |
generated by the chart |
| Admin token | admin.existingSecret |
GARAGE_ADMIN_TOKEN |
no static admin token |
| Bootstrap access key | bootstrap.existingSecret |
GARAGE_DEFAULT_ACCESS_KEY, GARAGE_DEFAULT_SECRET_KEY |
required when bootstrap.enabled |
The default keys are the names of the environment variables Garage reads them from, and Garage never gets them through garage.toml, which the chart renders into a ConfigMap. With the AboutBits Garage Operator, point the adminSecretRef of the GarageCluster and the GarageClusterConnection at the Secret of admin.existingSecret.
To read the RPC secret or the admin token from a mounted file instead, set GARAGE_RPC_SECRET_FILE or GARAGE_ADMIN_TOKEN_FILE in environment and mount the file with extraVolumes and extraVolumeMounts. See environment in the values.reference.yaml file. The bootstrap keys have no file variant. Never change the bootstrap keys in their Secret: Garage checks them at every start and refuses to start when they differ.
Garage reads secrets only at startup: after changing an existing Secret, restart the Pod.
You can pull and install the Helm chart directly from the OCI registry.
helm install <release-name> oci://ghcr.io/aboutbits/helm-garage/garage --version <chart-version> --values values-<env>.yaml --namespace <namespace>
To build and publish the chart, visit the GitHub Actions page of the repository and trigger the workflow "Release Package" manually.
About Bits is a company based in South Tyrol, Italy. You can find more information about us on our website.
For support, please contact info@aboutbits.it.
The MIT License (MIT). Please see the license file for more information.