Certificate rotation

This guide covers procedures for rotating TLS certificates in MinIO AIStor deployments without downtime.

For certificate setup, see the platform-specific guides under Installation. For troubleshooting certificate errors, see TLS certificate troubleshooting.

MinIO AIStor automatically detects certificate changes and reloads them without a restart. Understanding the reload mechanism helps avoid common rotation mistakes.

• File replacement: MinIO AIStor watches certificate directories using inotify (Linux) for IN_CLOSE_WRITE and IN_MOVED_TO events. Write the new certificate and key to a temporary file, then rename (atomic move) into place.
• Symlink updates: For certificates managed by symlinks (common with cert-manager), MinIO AIStor polls symlink targets every 10 seconds.
• Content verification: MinIO AIStor computes SHA-256 hashes of the new content and only reloads if the content has changed.
• Failure safety: If the new certificate is invalid or partially written, MinIO AIStor continues serving the previously loaded certificate.

For details, see Automatic certificate reloading.

Verify the new certificate before deploying:

openssl x509 -in new-public.crt -noout -subject -issuer -dates -ext subjectAltName

Confirm:

• The subject and SANs match the MinIO server hostnames
• The issuer matches the expected CA
• The expiry date is in the future

Use atomic replacement to avoid serving a partial file:

cp new-public.crt /tmp/public.crt.tmp
cp new-private.key /tmp/private.key.tmp
mv /tmp/private.key.tmp ~/.minio/certs/private.key
mv /tmp/public.crt.tmp ~/.minio/certs/public.crt

Check that MinIO AIStor is serving the new certificate:

openssl s_client -connect HOSTNAME:9000 </dev/null 2>/dev/null | openssl x509 -noout -enddate -serial

Compare the serial number and expiry with the new certificate file to confirm the reload succeeded.

If the CA itself changed (not just the server certificate), place the new CA in the CAs directory:

cp new-ca.crt ~/.minio/certs/CAs/

MinIO AIStor picks up new CA files automatically. To also remove an old CA or restructure the CAs directory, restart the MinIO AIStor service to trigger a full rescan.

Using the AIStor Client (restarts all nodes):

mc admin service restart ALIAS

Or restart the service on individual nodes:

sudo systemctl restart minio

cert-manager handles rotation automatically based on the renewBefore setting in the Certificate resource. No manual intervention is required.

Verify the Certificate resource is renewing correctly:

kubectl get certificate -n NAMESPACE -o wide

The READY column should show True and RENEWAL should indicate the next renewal time.

If a certificate is stuck in a not-ready state:

kubectl describe certificate CERT_NAME -n NAMESPACE

Check the Events section for errors from cert-manager (issuer unreachable, authorization failure, etc.).

For certificates provided via Kubernetes secrets (certificates.server in the ObjectStore spec):

1. Update the secret with the new certificate and key:

   kubectl create secret tls CERT_SECRET_NAME \
       --cert=new-public.crt --key=new-private.key \
       -n NAMESPACE --dry-run=client -o yaml | kubectl apply -f -
   

2. Delete the operator mount secret to force a refresh:

   kubectl delete secret OBJECTSTORE_NAME-generated -n NAMESPACE
   

   The operator recreates the mount secret from the current certificate secrets and restarts the pods.

3. Verify the new certificate is mounted:

   kubectl exec -n NAMESPACE POD -c minio -- openssl x509 -in /tmp/minio/certs/public.crt -noout -enddate -serial
   

The operator webhook certificate is separate from the tenant certificates. See Operator webhook TLS for rotation procedures.

MinIO AIStor exposes the minio_system_network_certificate_expires_in gauge metric (metrics v3 only), which reports the number of seconds until each certificate expires.

Alert on certificates expiring within 30 days:

minio_system_network_certificate_expires_in < 2592000

Alert on certificates expiring within 7 days (critical):

minio_system_network_certificate_expires_in < 604800

Check expiry from the command line:

openssl s_client -connect HOSTNAME:9000 </dev/null 2>/dev/null | openssl x509 -noout -enddate

For Kubernetes, check all certificates mounted in a pod:

kubectl exec -n NAMESPACE POD -c minio -- \
    find /tmp/minio/certs -name "*.crt" -exec openssl x509 -in {} -noout -subject -enddate \;

• Automatic certificate reloading for reload mechanism details
• TLS certificate management with cert-manager for automated provisioning
• TLS certificate troubleshooting for diagnosing errors after rotation
• Operator webhook TLS for operator certificate rotation