Certificate Operations

• 1: cert-manager for Operator
• 2: cert-manager for Tenants

1 - cert-manager for Operator

MinIO Operator manages TLS certificate issuing for the services hosted in the minio-operator namespace.

This page describes how to manage the Operator’s TLS certificates with cert-manager.

Prerequisites

• A supported version of Kubernetes.
• kustomize installed
• kubectl access to your k8s cluster
• Completed the steps to set up cert-manager
• The MinIO Operator must not yet be installed.

1) Create a CA Issuer for the minio-operator namespace

This guide disables the automatic generation of certificates in MinIO Operator and issues certificates using cert-manager instead.

The minio-operator namespace must have its own certificate authority (CA), derived from the cluster’s ClusterIssuer certificate created during cert-manager setup. Create this CA certificate using cert-manager.

1. If it does not exist, create the minio-operator namespace

   kubectl create ns minio-operator

2. Request a new Certificate with spec.isCA: true specified.

   This certificate serves as the CA for the minio-operator namespace.

   Create a file called operator-ca-tls-secret.yaml with the following contents:

   # operator-ca-tls-secret.yaml
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: minio-operator-ca-certificate
     namespace: minio-operator
   spec:
     isCA: true
     commonName: operator
     secretName: operator-ca-tls
     duration: 70128h # 8y
     privateKey:
       algorithm: ECDSA
       size: 256
     issuerRef:
       name: selfsigned-root
       kind: ClusterIssuer
       group: cert-manager.io

   Warning

   Important

   The spec.issueRef.name must match the name of the ClusterIssuer created when setting up cert-manager. If you specified a different ClusterIssuer name or are using a different Issuer from the guide, modify the issuerRef to match your environment.

3. Apply the resource:

   kubectl apply -f operator-ca-tls-secret.yaml

Kubernetes creates a new secret with the name operator-ca-tls in the minio-operator namespace.

2) Use the secret to create the Issuer

Use the operator-ca-tls secret to add an Issuer resource for the minio-operator namespace.

1. Create a file called operator-ca-issuer.yaml with the following contents:

   # operator-ca-issuer.yaml
   apiVersion: cert-manager.io/v1
   kind: Issuer
   metadata:
     name: minio-operator-ca-issuer
     namespace: minio-operator
   spec:
     ca:
       secretName: operator-ca-tls

2. Apply the resource:

   kubectl apply -f operator-ca-issuer.yaml

3) Create TLS certificate

Now that the Issuer exists in the minio-operator namespace, cert-manager can add a certificate.

The certificate from cert-manager must be valid for the following DNS domains:

• sts

• sts.minio-operator.svc.

• sts.minio-operator.svc.<cluster domain>

  Warning

  Important

  Replace <cluster domain> with the actual value for your MinIO tenant. cluster domain is the internal root DNS domain assigned in your Kubernetes cluster. Typically, this is cluster.local, but confirm the value by checking your CoreDNS configuration for the correct value for your Kubernetes cluster.

  For example:

  kubectl get configmap coredns -n kube-system -o jsonpath="{.data}"

  Different Kubernetes providers manage the root domain differently. Check with your Kubernetes provider for more information.

1. Create a Certificate for the specified domains:

   Create a file named sts-tls-certificate.yaml with the following contents:

   # sts-tls-certificate.yaml
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: sts-certmanager-cert
     namespace: minio-operator
   spec:
     dnsNames:
       - sts
       - sts.minio-operator.svc
       - sts.minio-operator.svc.cluster.local # Replace cluster.local with the value for your domain.
     secretName: sts-tls
     issuerRef:
       name: minio-operator-ca-issuer

   Warning

   Important

   The spec.secretName is not optional.

   The secret name must be sts-tls. Confirm this by setting spec.secretName: sts-tls as highlighted in the certificate YAML.

2. Apply the resource:

   kubectl apply -f sts-tls-certificate.yaml

This creates a secret called sts-tls in the minio-operator namespace.

4) Install Operator with Auto TLS disabled

You can now install the MinIO Operator.

When installing the Operator deployment, set the OPERATOR_STS_AUTO_TLS_ENABLED environment variable to off in the minio-operator container.

Disabling this environment variable prevents the MinIO Operator from issuing the certificates. Instead, Operator relies on cert-manager to issue the TLS certificate.

There are various methods to define an environment variable depending on how you install the Operator. The following steps define the variable with kustomize.

1. Create a kustomization patch file called kustomization.yaml with the following contents:

   # minio-operator/kustomization.yaml
   apiVersion: kustomize.config.k8s.io/v1beta1
   kind: Kustomization
   
   resources:
   - github.com/minio/operator/resources
   
   patches:
   - patch: |-
       apiVersion: apps/v1
       kind: Deployment
       metadata:
         name: minio-operator
         namespace: minio-operator
       spec:
         template:
           spec:
             containers:
               - name: minio-operator
                 env:
                   - name: OPERATOR_STS_AUTO_TLS_ENABLED
                     value: "off"
                   - name: OPERATOR_STS_ENABLED
                     value: "on"

2. Apply the kustomization resource to the cluster:

   kubectl apply -k minio-operator

Migrate an existing MinIO Operator deployment to cert-manager

To transition an existing MinIO Operator deployment from using AutoCert to cert-manager, complete the following steps:

1. Complete the steps for installing cert-manager, including disabling auto-cert.
2. Complete steps 1-3 on this page to generate the certificate authority for the Operator.
3. When you get to the install step on this page, instead replace the existing Operator TLS certificate with the cert-manager issued certificate.
4. Create new cert-manager certificates for each tenant, similar to the steps described on the cert-manager for Tenants page.
5. Replace the secrets in the MinIO Operator namespace for the tenants with secrets related to each tenant’s cert-manager issued certificate.

Next steps

Set up cert-manager for a MinIO Tenant.

2 - cert-manager for Tenants

The following procedures create and apply the resources necessary to use cert-manager for the TLS certificates within a tenant.

Prerequisites

• kustomize installed
• kubectl access to your k8s cluster
• Completed the steps to set up cert-manager
• The MinIO Operator installed and set up for cert-manager.

1) Create the tenant namespace CA Issuer

Before deploying a new tenant, create a Certificate Authority and Issuer for the tenant’s namespace.

1. If necessary, create the tenant’s namespace.

   kubectl create ns tenant-1

   This much match the value of the metadata.namespace field in the tenant’s YAML.

2. Request a Certificate for a new Certificate Authority with spec.isCA set to true.

   Create a file called tenant-1-ca-certificate.yaml with the following contents:

   # tenant-1-ca-certificate.yaml
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: tenant-1-ca-certificate
     namespace: tenant-1
   spec:
     isCA: true
     commonName: tenant-1-ca
     secretName: tenant-1-ca-tls
     duration: 70128h # 8y
     privateKey:
       algorithm: ECDSA
       size: 256
     issuerRef:
       name: selfsigned-root
       kind: ClusterIssuer
       group: cert-manager.io

   Warning

   Important

   The spec.issueRef.name must match the name of the ClusterIssuer created when setting up cert-manager. If you specified a different ClusterIssuer name or are using a different Issuer from the guide, modify the issuerRef to match your environment.

3. Apply the resource:

   kubectl apply -f tenant-1-ca-certificate.yaml

2) Create the Issuer

The Issuer issues the certificates within the tenant namespace.

1. Generate a resource definition for an Issuer.

   Create a file called tenant-1-ca-issuer.yaml with the following contents:

   # tenant-1-ca-issuer.yaml
   apiVersion: cert-manager.io/v1
   kind: Issuer
   metadata:
     name: tenant-1-ca-issuer
     namespace: tenant-1
   spec:
     ca:
       secretName: tenant-1-ca-tls

2. Apply the Issuer resource definition:

   kubectl apply -f tenant-1-ca-issuer.yaml

3) Create a certificate for the tenant

Request that cert-manager issue a new TLS server certificate for MinIO. The certificate must be valid for the following DNS domains:

• minio.<namespace>
• minio.<namespace>.svc
• minio.<namespace>.svc.<cluster domain>
• *.<tenant-name>-hl.<namespace>.svc.<cluster domain>
• *.<namespace>.svc.<cluster domain>
• *.<tenant-name>.minio.<namespace>.svc.<cluster domain>'

1. Request a Certificate for the specified domains

   Create a file called tenant-1-minio-certificate.yaml. The contents of the file should resemble the following, modified to reflect your cluster and tenant configurations:

   # tenant-1-minio-certificate.yaml
   apiVersion: cert-manager.io/v1
   kind: Certificate
   metadata:
     name: tenant-certmanager-cert
     namespace: tenant-1
   spec:
     dnsNames:
       - "minio.tenant-1"
       - "minio.tenant-1.svc"
       - 'minio.tenant-1.svc.cluster.local'
       - '*.minio.tenant-1.svc.cluster.local'
       - '*.myminio-hl.tenant-1.svc.cluster.local'
       - '*.myminio.minio.tenant-1.svc.cluster.local'
     secretName: myminio-tls
     issuerRef:
       name: tenant-1-ca-issuer

   Note

   Tip

   For this example, the Tenant name is myminio. We recommend naming the secret in the field spec.secretName as <tenant-name>-tls as a naming convention.

2. Apply the certificate resource:

   kubectl apply -f tenant-1-minio-certificate.yaml

3. Validate the changes took effect:

   kubectl describe secret/myminio-tls -n tenant-1

   Note

   Note

   • Replace tenant-1 with the namespace for your tenant.
   • Replace myminio-tls with the name of your secret, if different.

4) Deploy the tenant using cert-manager for TLS certificate management

When deploying a Tenant, you must set the TLS configuration such that:

• The Tenant does not automatically generate its own certificates (spec.requestAutoCert: false) and
• The Tenant has a valid cert-manager reference (spec.externalCertSecret)

This directs the Operator to deploy the Tenant using the cert-manager certificates exclusively.

The following YAML spec provides a baseline configuration meeting these requirements:

apiVersion: minio.min.io/v2
kind: Tenant
metadata:
  name: myminio
  namespace: tenant-1
spec:
...
  ## Disable default tls certificates.
  requestAutoCert: false
  ## Use certificates generated by cert-manager.
  externalCertSecret:
    - name: myminio-tls
      type: cert-manager.io/v1
...

5) Trust the tenant’s CA in MinIO Operator

The MinIO Operator does not trust the tenant’s CA by default. To trust the tenant’s CA, you must pass the certificate to the Operator as a secret.

To do this, create a secret with the prefix operator-ca-tls- followed by a unique identifier in the minio-operator namespace.

MinIO Operator mounts and trusts all certificates issued by the provided Certificate Authorities. This is required because the MinIO Operator performs health checks using the /minio/health/cluster endpoint.

Create operator-ca-tls-tenant-1 secret

Copy the tenant’s cert-manager generated CA public key (ca.crt) into the minio-operator namespace. This allows Operator to trust the cert-manager issued CA and all certificates derived from it.

1. Create a ca.crt file containing the CA:

   kubectl get secrets -n tenant-1 tenant-1-ca-tls -o=jsonpath='{.data.ca\.crt}' | base64 -d > ca.crt

2. Create the secret:

   kubectl create secret generic operator-ca-tls-tenant-1 --from-file=ca.crt -n minio-operator

6) Deploy the tenant

With the Certificate Authority and Issuer in place for the tenant’s namespace, you can now deploy the object store tenant.

Use the modified baseline tenant YAML to disable AutoCert and reference the secret you generated.