MinIO

Overview

MinIO is a high-performance, S3-compatible object storage system. This template deploys a distributed MinIO cluster with erasure coding across multiple replicas for durability and fault tolerance, backed by persistent storage and an optional autoscaling volume set. The root credentials are not template values. They come from a secret you create before installing, so the access key and secret key never pass through Helm and never land in the release.

Template version 1.3.0 is a breaking security change. admin.username and admin.password were removed. An install or upgrade that still sets either one now fails at render instead of falling back to a published default. If you are running 1.2.1 or earlier, read Upgrading From Earlier Versions before you touch the release.

What Gets Created

Stateful Workload — (RELEASE_NAME-minio): a distributed MinIO cluster of replicas nodes forming one erasure-coded pool. S3 API on port 9000, web console on port 9001. Per-replica addressing is enabled so each node reaches its peers at a stable replica-{index} address.
Volume Set — (RELEASE_NAME-minio-vs): one ext4 general-purpose SSD volume per replica, mounted at /data, with a final snapshot and 7-day retention, and optional autoscaling.
Startup Secret — (RELEASE_NAME-minio-startup): an opaque secret holding the boot script each node runs. It derives the peer list from the replica index and holds no credentials.
Identity & Policy — (RELEASE_NAME-minio-identity, RELEASE_NAME-minio-policy): an identity bound to the workload, and a policy granting it reveal on exactly two secrets — the startup script and the credentials secret you created.

The template creates no credential secret of its own. The root user and password live only in the prerequisite secret described below.

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

Upgrading From Earlier Versions

Template version 1.2.1 and earlier took the MinIO root credentials as plain Helm values and shipped a working default username and password. Those defaults were published in the public template repository, so every install that kept them shares one publicly known credential — and because these are the S3 access key and secret key, that credential is not merely a console login. It is what every client, and every other template configured to back up to this MinIO, authenticates with.

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

The chart-created RELEASE_NAME-minio-admin secret no longer exists in 1.3.0. The secret you create is yours: the chart never writes to it, and uninstalling the release leaves it in place.

Treat a pre-1.3.0 cluster’s root credentials as compromised, not merely outdated. Upgrading moves them out of Helm values but does not change the values themselves. If the install kept the published defaults, those keys remain publicly known after the upgrade — rotate them, as described in Rotating the Root Credentials.

Carrying old values forward stops the upgrade. Three guards reject the removed keys at render time, so the upgrade fails and the existing release is left untouched and running rather than quietly restarting with different credentials:

Error: execution error at (minio/templates/workload.yaml:1:4): 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.

admin.password is rejected with the same message. An empty admin.credentialsSecretName gets its own:

admin.credentialsSecretName is required — it names the dictionary secret holding the username and password keys. Create that secret BEFORE installing.

Read the credentials the cluster already uses

MinIO reads its root credentials from the environment on every start, and version 1.2.1 stored them in a secret the chart created. Read them back from there:

cpln secret reveal RELEASE_NAME-minio-admin -o yaml

Failing that, they are in the values file the release was installed with.

Create the prerequisite secret

Follow Prerequisites, using the existing username and password, so the upgrade itself is not also a credential change. Give the secret a name of your own, such as my-minio-credentials — do not reuse RELEASE_NAME-minio-admin, which the upgrade removes.

Remove the old keys from your values

Delete admin.username and admin.password, and set admin.credentialsSecretName to the name you used.

Rotate afterwards, in a maintenance window

Once the upgrade is in, rotate any credential that came from a published default. Rotation is not a quick restart — see Rotating the Root Credentials for the procedure and the roughly eleven-minute window it takes.

Prerequisites

One secret must exist before you install. Its value never passes through Helm values, so it never lands in the release. 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 will use.

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

MinIO requires a username of at least 3 characters and a password of at least 8. Set admin.credentialsSecretName to the name you used.

Read the secret back later

The -o yaml is required — plain cpln secret reveal prints only a summary table, not the values:

cpln secret reveal my-minio-credentials -o yaml

Create the secret before installing. The template refuses to render when the name is blank, but a name pointing at a secret that does not exist installs “successfully” and then wedges: the install reports every resource 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.

The command is get-deployments — plain cpln workload get has no versions key at all. Creating the secret recovers the workload on its own in about 5.5 to 8.5 minutes (measured 5 minutes 39 seconds), or in roughly 90 seconds if you force a redeployment of the workload.

Replica Quota

The default replicas-per-workload quota is 5, and this template’s default is replicas: 6, so request a quota increase before installing. Check your org’s current limit with cpln quota get and look at replicas-per-workload — the value shown is your org’s, which may already have been raised above the default.

Installation

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

The default values.yaml for this template:

image: minio/minio:RELEASE.2025-09-07T16-13-09Z

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

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: # Defaults are set for minimal production usage
  minCpu: 1
  minMemory: 2Gi
  maxCpu: 2
  maxMemory: 4Gi

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

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

Credentials

admin.credentialsSecretName — Name of the dictionary secret holding the username and password keys. The secret must exist before you install; see Prerequisites.

Replicas

replicas — Number of MinIO nodes in the distributed cluster. Must be an even number, minimum 4; 6 or more is recommended for production.

MinIO stripes each object into data and parity blocks across every node in the pool, so the replica count sets both the usable capacity ratio and how many nodes may be lost while the cluster keeps serving. A six-replica install forms one erasure set with three parity blocks; a four-replica install forms one with two.

Treat replicas as fixed at install time. MinIO grows by adding server pools, which this template does not model. Changing the value rewrites every node’s peer list for the existing pool.

Resources

resources.minCpu / resources.minMemory — Reserved CPU and memory per replica.
resources.maxCpu / resources.maxMemory — Limits per replica.

Storage

volumeset.capacity — Initial volume size in GiB per replica (minimum 10). Usable space is roughly replicas × capacity ÷ 2 after erasure-coding parity.
volumeset.autoscaling.enabled — Automatically expand each volume as it fills. When enabled:
- maxCapacity — Maximum volume size in GiB.
- minFreePercentage — Trigger a scale-up when free space drops below this percentage.
- scalingFactor — Multiply the current capacity by this factor when scaling up.

Internal Access

internalAccess.type — Controls which workloads can reach MinIO on ports 9000 and 9001:

Type	Description
`none`	No internal access allowed
`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 cluster rather than merely isolating it from clients.

A firewall change takes roughly 30 seconds to 5 minutes to propagate. After changing internalAccess, re-test rather than trusting the first response.

Connecting to MinIO

This template exposes no public endpoint: there is no publicAccess knob and no load balancer, and the workload’s canonical endpoint returns 403. Everything below is reached from inside the GVC or through a tunnel.

What	Where
S3 API	`RELEASE_NAME-minio.GVC_NAME.cpln.local:9000` — the short name `RELEASE_NAME-minio` also resolves inside the same GVC
Web console	port `9001` on the same host, reached with `cpln port-forward`
Individual node	`replica-INDEX.RELEASE_NAME-minio.LOCATION.GVC_NAME.cpln.local`
Credentials	the dictionary secret named by `admin.credentialsSecretName`

From another workload in the same GVC, using the MinIO client:

mc alias set minio http://RELEASE_NAME-minio:9000 USERNAME PASSWORD

Other templates in this catalog that back up to MinIO take the same two values as their access key and secret key. To open the web console in a browser, tunnel to it — no public exposure required:

cpln port-forward RELEASE_NAME-minio 9001:9001 --gvc GVC_NAME
# then browse http://localhost:9001

Give the tunnel a few seconds before the first request; a request issued immediately after the command starts may not connect. Log in with the username and password from your credentials secret.

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 rotate the value. That command only edits a secret’s description and tags. Update the value with cpln apply -f <secret.yaml>, then restart the workload so the nodes pick it up:

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

Updating the secret alone changes nothing: running containers keep the credentials they started with.

Plan rotation as a maintenance window of about 11 minutes, not a restart. MinIO reads the root credentials from the environment on every start, and they are per-node, so the rollout restarts one replica at a time. For the whole rollout some nodes hold the old credential and some hold the new one, and a client using the service DNS sees intermittent authentication failures with both keys — measured mid-rollout, the new credential succeeded 15 times out of 20 while the old one failed all 20.It does converge cleanly: once every replica has cycled, the new credential is accepted on every request and the old one is refused everywhere. No re-encryption of MinIO’s internal identity data is required, and existing buckets and objects are readable with the new credential.

Important Notes

The credentials secret must exist before you install. Without it the workload wedges with no log output at all; see Prerequisites for the one diagnostic that shows it.
Rotating the root credentials is an ~11-minute window of split old/new state, not a cutover — see Rotating the Root Credentials.
replicas must be even and at least 4, and is effectively fixed at install time.
Do not set internalAccess.type to none — the cluster needs internal GVC traffic to form.
The workload has no outbound internet access, so bucket replication to a remote S3 and external notification targets will not work.
Uninstalling the release deletes the volume sets, so stored objects do not survive a reinstall. The credentials secret is yours and is left alone.
The first upgrade after an install re-applies resources even when values are identical, which restarts the pool. Nothing limits the rollout on a stateful workload, so treat it as a planned restart.

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 Template

View the source files, default values, and chart definition

Template Catalog

Templates

Overview

What Gets Created

Upgrading From Earlier Versions

Prerequisites

Replica Quota

Installation

UI

CLI

Terraform

Pulumi

Configuration

Credentials

Replicas

Resources

Storage

Internal Access

Connecting to MinIO

Rotating the Root Credentials

Important Notes

External References

MinIO Documentation

Erasure Coding

MinIO Client (mc)

MinIO Template

​Overview

​What Gets Created

​Upgrading From Earlier Versions

​Prerequisites

​Replica Quota

​Installation

UI

CLI

Terraform

Pulumi

​Configuration

​Credentials

​Replicas

​Resources

​Storage

​Internal Access

​Connecting to MinIO

​Rotating the Root Credentials

​Important Notes

​External References

MinIO Documentation

Erasure Coding

MinIO Client (mc)

MinIO Template

Overview

What Gets Created

Upgrading From Earlier Versions

Prerequisites

Replica Quota

Installation

Configuration

Credentials

Replicas

Resources

Storage

Internal Access

Connecting to MinIO

Rotating the Root Credentials

Important Notes

External References