MinIO

Overview

MinIO is a high-performance, S3-compatible object storage server. This template deploys it in distributed mode: replicas nodes form one erasure-coded pool, every object is striped with parity across all of them, and the pool keeps serving reads and writes while some nodes are down. It is the usual in-org S3 target for other catalog templates that back up to MinIO. The root credentials — the S3 access key and secret key every client uses — come from a dictionary secret you create before installing. Nothing sensitive passes through Helm values, and the template creates no credential secret of its own.

This template does not create a GVC. You must deploy it into an existing GVC.

What Gets Created

Resource	Name	Purpose	Optional
Workload	`RELEASE_NAME-minio`	Distributed MinIO cluster (stateful, `replicas` nodes); S3 API on port `9000`, web console on port `9001`	—
Volume set	`RELEASE_NAME-minio-vs`	One `ext4` general-purpose SSD volume per replica, mounted at `/data`; a final snapshot is kept for 7 days when the volume set is deleted	—
Secret	`RELEASE_NAME-minio-startup`	Opaque secret holding the boot script each node runs to assemble its peer list; holds no credentials	—
Identity	`RELEASE_NAME-minio-identity`	Identity bound to the workload	—
Policy	`RELEASE_NAME-minio-policy`	Grants the identity `reveal` on exactly two secrets: the startup script and your credentials secret	—

Prerequisites

One secret must exist before you install. Secrets are org-level, so no GVC flag is involved.

Create the root credentials secret

A dictionary secret holding exactly two keys, username and password. These become MINIO_ROOT_USER and MINIO_ROOT_PASSWORD — the S3 access key and secret key every client and every other template will use. MinIO requires a username of at least 3 characters and a password of at least 8:

cpln secret create-dictionary --name SECRET_NAME \
  --entry username=minioadmin \
  --entry password="$(openssl rand -hex 24)"

Set admin.credentialsSecretName to this name.

Check the replica quota

The template defaults to replicas: 6, which is above the default replicas-per-workload quota of 5. Either request a quota increase before installing, or install with --set replicas=4 (the minimum). Your org’s current limit is shown by:

cpln quota get

Create the secret before installing. The chart refuses to render when admin.credentialsSecretName is blank, but a name pointing at a secret that does not exist installs “successfully” and then wedges: every resource is created, the workload never becomes ready, and cpln logs returns zero lines because no container ever starts. The only diagnostic is status.versions[].message:

cpln workload get-deployments RELEASE_NAME-minio --gvc GVC_NAME -o yaml

It names the missing secret:

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Note the command is get-deployments — plain cpln workload get has no versions key. Once the secret exists the workload recovers on its own after several minutes, or right away if you force a redeployment:

cpln workload force-redeployment RELEASE_NAME-minio --gvc GVC_NAME

Installation

Install against an existing GVC, naming the credentials secret you created:

cpln helm install RELEASE_NAME oci://ghcr.io/controlplane-com/templates/minio \
  --version 1.3.1 --gvc GVC_NAME \
  --set admin.credentialsSecretName=SECRET_NAME

To install, follow the instructions for your preferred method:

UI

Browse, install, and manage templates visually

CLI

Manage templates from your terminal

Terraform

Declare templates in your Terraform configurations

Pulumi

Declare templates in your Pulumi programs

Configuration

Image and Replicas

image: quay.io/minio/minio:RELEASE.2025-09-07T16-13-09Z # quay.io: MinIO withdrew minio/minio from Docker Hub (2025); quay is its public registry. Same release tag.

replicas: 6 # Must be at least 4 and an even number

replicas is fixed at install time — see Scaling and Availability.

Root Credentials

admin:
  # REQUIRED PREREQUISITE SECRET — CREATE IT BEFORE YOU INSTALL.
  # A `dictionary` secret holding exactly two keys: `username` and `password`.
  # These are the MinIO root credentials, i.e. the S3 access key and secret key
  # every client and every other template will use. If the secret does not exist
  # at install time the deployment WEDGES silently — `cpln logs` returns nothing
  # at all. See Prerequisites in the README for the exact
  # `cpln secret create-dictionary` command.
  credentialsSecretName: my-minio-credentials

Resources

resources: # Defaults are set for minimal production usage
  minCpu: 1
  minMemory: 2Gi
  maxCpu: 2
  maxMemory: 4Gi

Storage

volumeset:
  capacity: 10 # initial capacity in GiB (minimum is 10)
  autoscaling:
    enabled: false # Set to true to enable autoscaling
    maxCapacity: 100 # Maximum capacity in GiB when autoscaling is enabled
    minFreePercentage: 10 # Minimum free percentage to trigger scaling when autoscaling is enabled
    scalingFactor: 1.2 # Scaling factor to determine how much to scale up when autoscaling is triggered

capacity is per replica. With the parity MinIO applies to a pool of this size, usable space is roughly replicas × capacity ÷ 2.

Internal Access

internalAccess: # Sets the internal firewall scope - if set to none, replicas will not be able to reach each other
  type: same-gvc # options: none, same-gvc, same-org, workload-list
  workloads:  # Note: can only be used if type is same-gvc or workload-list
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME
    #- //gvc/GVC_NAME/workload/WORKLOAD_NAME

Type	Description
`none`	No internal access allowed — breaks the cluster, see below
`same-gvc`	Allow access from all workloads in the same GVC
`same-org`	Allow access from all workloads in the same org
`workload-list`	Allow access only from the workloads listed in `internalAccess.workloads`

Do not set internalAccess.type to none. MinIO nodes discover and reach each other over internal GVC traffic, so cutting it off breaks the pool rather than merely isolating it from clients. With workload-list, the list must allow the MinIO workload itself as well as your clients.

A firewall change can take a few minutes to take effect. After changing internalAccess, re-test rather than trusting the first response.

Connecting

This template exposes no public endpoint — there is no publicAccess knob and no load balancer. Everything below is reached from inside the GVC or through a cpln port-forward tunnel.

What	Address	Notes
S3 API	`http://RELEASE_NAME-minio.GVC_NAME.cpln.local:9000`	Internal only; use path-style addressing
Web console	port `9001` on the same host	Reach it with `cpln port-forward` (below)
Individual node	`replica-INDEX.RELEASE_NAME-minio.LOCATION.GVC_NAME.cpln.local:9000`	Rarely needed; the service address balances across nodes
Credentials	`cpln secret reveal SECRET_NAME -o yaml`	`username` is the access key, `password` the secret key; `-o yaml` is required

Verify the pool from your terminal — /minio/health/live answers 200 once a node is up, and /minio/health/cluster answers 200 only once the pool has write quorum (healthcheck endpoints):

cpln port-forward RELEASE_NAME-minio 9000:9000 --gvc GVC_NAME
# in another terminal
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9000/minio/health/live
curl -s -o /dev/null -w '%{http_code}\n' http://localhost:9000/minio/health/cluster

To open the web console, tunnel to port 9001 and browse to http://localhost:9001, then sign in with the username and password from your credentials secret:

cpln port-forward RELEASE_NAME-minio 9001:9001 --gvc GVC_NAME

From another workload in the same GVC, point any S3 client at the internal address — the MinIO client (mc) and the AWS CLI both work:

mc alias set minio http://RELEASE_NAME-minio.GVC_NAME.cpln.local:9000 ACCESS_KEY SECRET_KEY
mc mb minio/my-bucket

aws --endpoint-url http://RELEASE_NAME-minio.GVC_NAME.cpln.local:9000 s3 ls

Other catalog templates that back up to MinIO take the same endpoint, with username as their access key and password as their secret key.

Operations

Backing Up

This template has no built-in backup. Objects live only on the per-replica volumes, and the workload has no outbound internet access, so mc mirror to a cloud bucket cannot run from inside the pool — mirror from a client inside the GVC, or to another in-org S3 target such as SeaweedFS. The volume set keeps a final snapshot for 7 days after it is deleted. Restoring a distributed, erasure-coded pool from volume-set snapshots has not been verified for this template; do not rely on it as a recovery path.

Upgrading From Earlier Versions

Template versions 1.2.1 and earlier took the root credentials as Helm values (admin.username, admin.password) and shipped a working default pair in the public template repository, so every install that kept them shares one publicly known access key and secret key. Version 1.3.0 moved them to the prerequisite secret and removed the chart-created RELEASE_NAME-minio-admin secret.

	1.2.1 and earlier	1.3.0 and later
Root credentials	`admin.username` and `admin.password` values	`admin.credentialsSecretName` → a dictionary secret you create
Where they live	Rendered into a `RELEASE_NAME-minio-admin` secret and recorded in the Helm release	Created by you, referenced by name, never in the release

Carrying the old values forward stops the upgrade. The chart rejects admin.username and admin.password at render time, so the upgrade fails and the running release is left untouched rather than restarting with different credentials:

admin.username was REMOVED in minio 1.3.0. The MinIO root credentials are no longer values: create a
`dictionary` secret holding the keys `username` and `password`, and set admin.credentialsSecretName to
its name. See Prerequisites in the README.

Read the credentials the cluster already uses

MinIO reads its root credentials from the environment on every start, so the upgrade must carry the current pair. Read them from the secret the old chart created, or from the values file the release was installed with:

cpln secret reveal RELEASE_NAME-minio-admin -o yaml

Create the prerequisite secret with those values

Follow Prerequisites using the existing username and password, under a name of your own — do not reuse RELEASE_NAME-minio-admin, which the upgrade removes.

Update your values and upgrade

Delete admin.username and admin.password, set admin.credentialsSecretName to the new secret’s name, and run the upgrade.

Rotate afterwards

If the install kept the published defaults, those keys are still publicly known after the upgrade. Rotate them as described in Rotating the Root Credentials.

Rotating the Root Credentials

The root credentials are the S3 access key and secret key, so rotating them is a fleet-wide change: every client and every other template configured with these keys has to be updated in the same window. cpln secret update cannot change a secret’s value — it edits only the description and tags. Write the new value with cpln apply, then force a redeployment so the nodes pick it up; running containers keep the credentials they started with until they restart.

# rotate.yaml
kind: secret
name: SECRET_NAME
type: dictionary
data:
  username: minioadmin
  password: NEW-STRONG-PASSWORD

cpln apply -f rotate.yaml
cpln workload force-redeployment RELEASE_NAME-minio --gvc GVC_NAME

Plan rotation as a maintenance window, not a restart. The redeployment cycles the nodes one at a time, and until every node has restarted the pool holds a mix of old and new credentials — clients see intermittent authentication failures with both keys. Once the rollout completes, the new pair is accepted everywhere and the old one refused everywhere. Existing buckets and objects remain readable; no re-encryption is needed.

Scaling and Availability

replicas must be an even number, minimum 4, and is fixed at install time. The peer list is baked into each node’s startup script, and MinIO grows by adding server pools, which this template does not model. Choose the count before you install.
Fault tolerance comes from erasure coding. With the parity MinIO applies to a pool of 4 to 7 nodes, half the raw capacity is parity; the pool keeps serving reads with up to half its nodes down and writes while a majority is up. Node restarts therefore do not interrupt clients as long as quorum holds.
One pool per location. The workload runs in every location of the GVC, and each location forms its own independent pool with its own data — the template does not replicate between locations. Deploy into a single-location GVC unless separate per-location stores are what you want.
Upgrades and forced redeployments restart the pool’s nodes. The first helm upgrade after an install re-applies resources even with identical values, so treat any upgrade as a planned restart.

Troubleshooting

The workload never becomes ready and cpln logs returns nothing

Cause: the secret named by admin.credentialsSecretName did not exist when the workload was created. No container starts, so there is nothing to log.Check: cpln workload get-deployments RELEASE_NAME-minio --gvc GVC_NAME -o yaml — status.versions[].message reads

The secret <name> no longer exists. Workload updates are paused until the secret is added or the reference to the secret removed.

Fix: create the secret as shown in Prerequisites, then cpln workload force-redeployment RELEASE_NAME-minio --gvc GVC_NAME.

Upgrade fails with admin.username was REMOVED in minio 1.3.0

Cause: your values still carry admin.username or admin.password, which 1.3.0 removed. The guard stops the upgrade before any resource changes, so the running release is unaffected.Fix: follow Upgrading From Earlier Versions.

Install is refused for exceeding the replica quota

Cause: the default replicas: 6 is above the default replicas-per-workload quota of 5.Fix: request a quota increase, or install with --set replicas=4. Check your org’s current limit with cpln quota get.

Every node starts but /minio/health/cluster never returns 200

Cause: the nodes cannot reach each other, so no pool forms. The usual reason is internalAccess.type: none, or a workload-list that does not include the MinIO workload itself.Fix: set internalAccess.type to same-gvc (or add //gvc/GVC_NAME/workload/RELEASE_NAME-minio to the list) and upgrade; allow a few minutes for the firewall change to apply.

Bucket replication or event notifications to an external endpoint never connect

Cause: the workload has no outbound internet access; this is fixed in the template, not a knob.Fix: use targets inside your org, or run replication from a client workload that has egress.

Important Notes

Create the credentials secret before you install; without it the workload wedges with no log output — see Prerequisites.
replicas must be even and at least 4, and is fixed at install time.
Do not set internalAccess.type to none — the pool needs internal GVC traffic to form.
There is no public endpoint and no outbound internet access; reach the console with cpln port-forward.
Rotating the root credentials requires a forced redeployment and is a maintenance window — see Rotating the Root Credentials.
Uninstalling the release deletes the volume sets, so stored objects do not survive a reinstall; your credentials secret is left alone.
Firewall changes take a few minutes to apply; re-test after changing internalAccess.

External References

MinIO Documentation

Official MinIO documentation

Erasure Coding

How MinIO stripes data and parity across nodes

MinIO Client (mc)

Command-line client for the S3 API

MinIO on GitHub

Source code and release notes for the MinIO server

MinIO Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Prerequisites

Installation

UI

CLI

Terraform

Pulumi

Configuration

Image and Replicas

Root Credentials

Resources

Storage

Internal Access

Connecting

Operations

Backing Up

Upgrading From Earlier Versions

Rotating the Root Credentials

Scaling and Availability

Troubleshooting

Important Notes

External References

MinIO Documentation

Erasure Coding

MinIO Client (mc)

MinIO on GitHub

MinIO Template

​Overview

​What Gets Created

​Prerequisites

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Image and Replicas

​Root Credentials

​Resources

​Storage

​Internal Access

​Connecting

​Operations

​Backing Up

​Upgrading From Earlier Versions

​Rotating the Root Credentials

​Scaling and Availability

​Troubleshooting

​Important Notes

​External References

MinIO Documentation

Erasure Coding

MinIO Client (mc)

MinIO on GitHub

MinIO Template

Overview

What Gets Created

Prerequisites

Installation

Configuration

Image and Replicas

Root Credentials

Resources

Storage

Internal Access

Connecting

Operations

Backing Up

Upgrading From Earlier Versions

Rotating the Root Credentials

Scaling and Availability

Troubleshooting

Important Notes

External References