Object storage
An S3-compatible object store that lives in your private network. You manage buckets and access keys; the machines underneath are managed for you.
What runs underneath
Section titled “What runs underneath”| Layer | Technology |
|---|---|
| Storage engine | Garage — an S3-compatible, self-hosted object store designed for small clusters |
| Base | Ubuntu 24.04, locked — no SSH daemon, no shell, no accounts |
| Node agent | A Go daemon that owns the node’s configuration, cluster layout, buckets, keys and permissions |
| Configuration | Pulled from the panel; the node reports the version it applied |
| API port | Garage’s S3 API, reached privately or through a load balancer |
Garage speaks plain HTTP. It does not terminate TLS itself. That is why a public endpoint is published through a load balancer that terminates TLS — see below.
Stores, buckets and keys
Section titled “Stores, buckets and keys”A store is a Garage cluster: one node or three.
| Nodes | Behaviour |
|---|---|
| 1 | No redundancy. Losing the machine loses the data. Fine for development, caches, artefacts you can rebuild |
| 3 | Data is replicated across three machines; the store survives losing one |
Within a store you create buckets and access keys, and grant each key read, write or owner permission per bucket.
An access key’s secret is shown once, at creation. The panel does not store it. This is the same discipline as server passwords and kubeconfigs.
Creating a store
Section titled “Creating a store”Nesne Depolama → Depo Oluştur (Object storage → Create store). You choose a name, a node count, a plan, a data disk size, and a subnet.
Preconditions
Section titled “Preconditions”| Requirement | Why |
|---|---|
| A subnet with a gateway attached | The nodes fetch their own configuration from the panel. Without egress they would install and hang forever |
A data tier subnet will be refused | data subnets can never have egress |
| For a published endpoint: a load balancer in the same private network | The endpoint is a listener on it |
The gateway requirement is checked at creation and refused with an explanation, rather than allowing a store that would never become ready.
While a store is coming up
Section titled “While a store is coming up”A three-node store does not become ready instantly: the nodes have to find each other and the cluster layout has to be applied. During that window each node reports what it is waiting for — “layout not yet applied”, “nodes still announcing themselves (2/3)” — rather than an error.
This distinction is deliberate. An earlier version reported those conditions as apply failures, which turned an entirely normal three-node installation red and prompted people to intervene in something that was working correctly.
Reaching the store
Section titled “Reaching the store”Privately. Anything in the same private network can use the store’s private endpoint immediately.
Published. Attach the store to a load balancer and give it
a hostname. The listener becomes https, TLS terminates at the load balancer, and traffic
to the storage nodes is plain HTTP inside your private network.
The endpoint URL the panel shows reflects reality: it becomes https://… only when the
certificate is actually ready. Having typed a hostname is not enough — promising HTTPS
while the certificate is still being issued would make the very first copy-pasted aws
command fail with a TLS error.
An internal load balancer works here too: no public address, TLS still valid, endpoint reachable only from your network or through a Zero Trust gateway.
Using it
Section titled “Using it”aws --endpoint-url https://s3.example.com \ s3 ls s3://my-bucket/Any S3 client works: the AWS CLI, rclone, mc, the SDKs. Garage implements the parts of
the S3 API that matter for object storage; it is not a complete reimplementation of every
AWS feature.
Limits
Section titled “Limits”- One or three nodes; no other count.
- Garage implements a practical subset of S3 — no object lock, no versioning, no lifecycle policies, no cross-region replication.
- Access key secrets are stored in the control plane database without application-level encryption today. See Known gaps.
- Growing a store from one node to three after creation is not a panel operation yet.