minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-12-24 01:42:07 +03:00
Code Activity

Attempting to reduce docs to single platform (#1258)

Browse Source 
##

We are going to make the following changes to the Object Store docs as
part of a larger QC/Content pass:

### Left Navigation

We want to modify the left navigation flow to be a natural progression
from a basic setup to more advanced.

For example:

- Core Concepts
  - Deployment Architecture
  - Availability and Resiliency
  - Erasure Coding and Object Healing
  - Object Scanner
  - Site Replication and Failover
  - Thresholds and Limits
- Installation
  - Deployment Checklist
  - Deploy MinIO on Kubernetes
  - Deploy MinIO on Red Hat Linux
  - Deploy MinIO on Ubuntu Linux
  - Deploy MinIO for Development (MacOS, Windows, Container)
- Security and Encryption (Conceptual Overview)
  - Network Encryption (TLS) (Conceptual overview)
    - Enable Network Encryption using Single Domain
    - Enable Network Encryption using Multiple Domains
    - Enable Network Encryption using certmanager (Kubernetes only)
  - Data Encryption (SSE) (Conceptual overview)
    - Enable SSE using AIStor Key Management Server
    - Enable SSE using KES (Summary page + linkouts)
  - External Identity Management (Conceptual Overview)
    - Enable External Identity management using OpenID
    - Enable External Identity management using AD/LDAP
- Backup and Recovery
  - Create a Multi-Site Replication Configuration
  - Recovery after Hardware Failure
    - Recover after drive failure
    - Recover after node failure
    - Recover after site failure
- Monitoring and Alerts
  - Metrics and Alerting (v3 reference)
    - Monitoring and Alerting using Prometheus
    - Monitoring and Alerting using InfluxDB
    - Monitoring and Alerting using Grafana
    - Metrics V2 Reference
  - Publish Server and Audit Logs to External Services
  - MinIO Healthcheck API

The Administration, Developer, and Reference sections will remain as-is
for now.

http://192.241.195.202:9000/staging/singleplat/mindocs/index.html

# Goals

Maintaining multiple platforms is getting to be too much, and based on
analytics the actual number of users taking advantage of it is minimal.

Furthermore, the majority of traffic is to installation pages.

Therefore we're going to try to collapse back into a single MinIO Object
Storage product, and use simple navigation and on-page selectors to
handle Baremetal vs Kubernetes.

This may also help to eventually stage us to migrate to Hugo + Markdown

---------

Co-authored-by: Daryl White <53910321+djwfyi@users.noreply.github.com>
Co-authored-by: Rushan <rushenn@minio.io>
Co-authored-by: rushenn <rushenn123@gmail.com>
This commit is contained in:
Ravind Kumar
2025-07-30 12:33:02 -04:00
committed by GitHub
parent b63d6d0f98
commit 571f188a4e
105 changed files with 4827 additions and 10318 deletions
Download Patch File Download Diff File Expand all files Collapse all files

606
source/operations/network-encryption.rst
View File

@@ -1,4 +1,6 @@
.. _minio-tls:
.. _minio-TLS-third-party-ca:
.. _minio-tls-user-generated:
========================
Network Encryption (TLS)
@@ -8,9 +10,7 @@ Network Encryption (TLS)
.. contents:: Table of Contents
:local:
:depth: 1
MinIO supports Transport Layer Security (TLS) 1.2+ encryption of incoming and outgoing traffic.
:depth: 2
.. admonition:: SSL is Deprecated
:class: note
@@ -18,38 +18,36 @@ MinIO supports Transport Layer Security (TLS) 1.2+ encryption of incoming and ou
TLS is the successor to Secure Socket Layer (SSL) encryption.
SSL is fully `deprecated <https://tools.ietf.org/html/rfc7568>`__ as of June 30th, 2018.
.. _minio-tls-user-generated:
Overview
--------
Enabling TLS
------------
MinIO supports Transport Layer Security (TLS) 1.2+ encryption of incoming and outgoing traffic.
MinIO can automatically detect certificates specified to either a default or custom search path and enable TLS for all connections.
MinIO supports Server Name Indication (SNI) requests from clients, where MinIO attempts to locate the appropriate TLS certificate for the hostname specified by the client.
.. cond:: not k8s
.. todo: add an image
The sections below describe how to enable TLS for MinIO.
You may use TLS certificates from a well-known Certificate Authority, an internal or private CA, or self-signed certs.
MinIO requires *at minimum* a single default TLS certificate and can support multiple TLS certificates in support of SNI connectivity.
MinIO uses the TLS Subject Alternate Name (SAN) list to determine which certificate to return to the client.
If MinIO cannot find a TLS certificate whose SAN covers the client-requested hostname, MinIO uses the default certificate and attempts to establish the handshake.
Before beginning, note these important points:
You can specify a single TLS certificate which covers all possible SANs for which the MinIO deployment accepts connections.
- Configure TLS on each node.
- Ensure certs are readable by the user who runs the MinIO Server process.
- Update :envvar:`MINIO_VOLUMES` and any needed services or apps to use an ``HTTPS`` URL.
This configuration requires the least configuration, but necessarily exposes all hostnames configured in the TLS SAN to connecting clients.
Depending on your TLS configuration, this may include internal or private SAN domains.
.. cond:: k8s
You can instead specify multiple TLS certificates separated by domain(s) with a single default certificate for any non-matching hostname requests.
This configuration requires more configuration, but only exposes those hostnames configured in the returned TLS SAN array.
For Kubernetes clusters with a valid :ref:`TLS Cluster Signing Certificate <minio-k8s-deploy-operator-tls>`,
the MinIO Kubernetes Operator can automatically generate TLS certificates while :ref:`deploying <minio-k8s-deploy-minio-tenant-security>` or :ref:`modifying <minio-k8s-modify-minio-tenant-security>` a MinIO Tenant.
The TLS certificate generation process is as follows:
.. _minio-tls-kubernetes:
- The Operator generates a Certificate Signing Request (CSR) associated to the Tenant.
The :abbr:`CSR (Certificate Signing Request)` includes the appropriate DNS Subject Alternate Names (SANs) for the Tenant services and pods.
MinIO TLS on Kubernetes
-----------------------
The Operator then waits for :abbr:`CSR (Certificate Signing Request)` approval
The MinIO Kubernetes Operator provides three approaches for configuring TLS on MinIO Tenants:
- The :abbr:`CSR (Certificate Signing Request)` waits pending approval.
The Kubernetes TLS API can automatically approve the :abbr:`CSR (Certificate Signing Request)` if properly configured.
Otherwise, a cluster administrator must manually approve the :abbr:`CSR (Certificate Signing Request)` before Kubernetes can generate the necessary certificates.
- The Operator applies the generated TLS Certificates to each MinIO Pod in the Tenant.
Automatic TLS using Cluster Signing API
For Kubernetes clusters with a valid :ref:`TLS Cluster Signing Certificate <minio-k8s-deploy-operator-tls>`,the MinIO Kubernetes Operator can automatically generate TLS certificates while :ref:`deploying <minio-k8s-deploy-minio-tenant-security>` or :ref:`modifying <minio-k8s-modify-minio-tenant-security>` a MinIO Tenant.
The Kubernetes TLS API uses the Kubernetes cluster Certificate Authority (CA) signature algorithm when generating new TLS certificates.
See :ref:`minio-TLS-supported-cipher-suites` for a complete list of MinIO's supported TLS Cipher Suites and recommended signature algorithms.
@@ -64,373 +62,161 @@ Enabling TLS
If you have a custom Subject Alternative Name (SAN) certificate that is *not* also a wildcard cert, the TLS certificate SAN **must** apply to the hostname for its parent node.
Without a wildcard, the SAN must match exactly to be able to connect to the tenant.
Certificate Management with cert-manager
----------------------------------------
cert-manager Certificate Management
The MinIO Operator supports using `cert-manager <https://cert-manager.io/>`__ as a full replacement for its built-in automatic certificate management *or* user-driven manual certificate management.
For instructions for deploying the MinIO Operator and tenants using cert-manager, refer to the :ref:`cert-manager page <minio-certmanager>`.
Manual Certificate Management
The Tenant CRD spec ``spec.externalCertsSecret`` supp .. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-cli
orts specifying either ``opaque`` or ``kubernetes.io/tls`` type :kube-docs:`secrets <concepts/configuration/secret/#secret-types>` containing the ``private.key`` and ``public.crt`` to use for TLS.
.. cond:: linux
You can specify multiple certificates to support Tenants which have multiple assigned hostnames.
The MinIO Server searches for TLS keys and certificates for each node and uses those credentials for enabling TLS.
The search location depends on your MinIO configuration:
.. tab-set::
Self-signed, Internal, Private Certificates, and Public CAs with Intermediate Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. tab-item:: Default Path
If deploying MinIO Tenants with certificates minted by a non-global or non-public Certificate Authority, *or* if using a global CA that requires the use of intermediate certificates, you must provide those CAs to the Operator to ensure it can trust those certificates.
By default, the MinIO server looks for the TLS keys and certificates for each node in the following directory:
The Operator may log warnings related to TLS cert validation for Tenants deployed with untrusted certificates.
.. code-block:: shell
The following procedure attaches a secret containing the ``public.crt`` of the Certificate Authority to the MinIO Operator.
You can specify multiple CAs in a single certificate, as long as you maintain the ``BEGIN`` and ``END`` delimiters as-is.
${HOME}/.minio/certs
1. Create the ``operator-ca-tls`` secret
Where ``${HOME}`` is the home directory of the user running the MinIO Server process.
You may need to create the ``${HOME}/.minio/certs`` directory if it does not exist.
For ``systemd`` managed deployments this must correspond to the ``USER`` running the MinIO process.
If that user has no home directory, use the :guilabel:`Custom Path` option instead.
.. tab-item:: Custom Path
You can specify a path for the MinIO server to search for certificates using the :mc-cmd:`minio server --certs-dir` or ``-S`` parameter.
For example, the following command fragment directs the MinIO process to use the ``/opt/minio/certs`` directory for TLS certificates.
.. code-block:: shell
minio server --certs-dir /opt/minio/certs ...
The user running the MinIO service *must* have read and write permissions to this directory.
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the ``/certs`` directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
For example:
The following creates a Kubernetes secret in the MinIO Operator namespace (``minio-operator``).
.. code-block:: shell
:class: copyable
/path/to/certs
private.key
public.crt
kubectl create secret generic operator-ca-tls \
--from-file=public.crt -n minio-operator
You can use the MinIO :minio-git:`certgen <certgen>` to mint self-signed certificates for evaluating MinIO with TLS enabled.
For example, the following command generates a self-signed certificate with a set of IP and DNS Subject Alternate Names (SANs) associated to the MinIO Server hosts:
The ``public.crt`` file must correspond to a valid TLS certificate containing one or more CA definitions.
2. Restart the Operator
Once created, you must restart the Operator to load the new CAs:
.. code-block:: shell
:class: copyable
certgen -host "localhost,minio-*.example.net"
kubectl rollout restart deployments.apps/minio-operator -n minio-operator
Place the generated ``public.crt`` and ``private.key`` into the ``/path/to/certs`` directory to enable TLS for the MinIO deployment.
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
Third-Party Certificate Authorities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
If you are reconfiguring an existing deployment that did not previously have TLS enabled, update :envvar:`MINIO_VOLUMES` to specify ``https`` instead of ``http``.
You may also need to update URLs used by applications or clients.
The MinIO Kubernetes Operator can automatically attach third-party Certificate Authorities when :ref:`deploying <minio-k8s-deploy-minio-tenant-security>` or :ref:`modifying <minio-k8s-modify-minio-tenant-security>` a MinIO Tenant.
.. cond:: container
You can add, update, or remove CAs from the tenant at any time.
You must restart the MinIO Tenant for the changes to the configured CAs to apply.
Start the MinIO container with the :mc-cmd:`minio/minio:latest server --certs-dir <minio server --certs-dir>` parameter and specify the path to a directory in which MinIO searches for certificates.
You must mount a local host volume to that path when starting the container to ensure the MinIO Server can access the necessary certificates.
The Operator places the specified CAs on each MinIO Server pod such that all pods have a consistent set of trusted CAs.
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the specified directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
For example:
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
.. code-block:: shell
.. _minio-tls-baremetal:
/opts/certs
private.key
public.crt
MinIO TLS on Baremetal
----------------------
You can use the MinIO :minio-git:`certgen <certgen>` to mint self-signed certificates for evaluating MinIO with TLS enabled.
For example, the following command generates a self-signed certificate with a set of IP and DNS SANs associated to the MinIO Server hosts:
The MinIO Server searches for TLS keys and certificates for each node and uses those credentials for enabling TLS.
MinIO automatically enables TLS upon discovery and validation of certificates.
The search location depends on your MinIO configuration:
.. code-block:: shell
.. tab-set::
certgen -host "localhost,minio-*.example.net"
.. tab-item:: Default Path
You may need to start the container and set a ``--hostname`` that matches the TLS certificate DNS SAN.
By default, the MinIO server looks for the TLS keys and certificates for each node in the following directory:
Move the certificates to the local host machine path that the container mounts to its ``--certs-dir`` path.
When the MinIO container starts, the server searches the specified location for certificates and uses them to enable TLS.
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
.. code-block:: shell
If you are reconfiguring an existing deployment that did not previously have TLS enabled, update :envvar:`MINIO_VOLUMES` to specify ``https`` instead of ``http``.
You may also need to update URLs used by applications or clients.
${HOME}/.minio/certs
Where ``${HOME}`` is the home directory of the user running the MinIO Server process.
You may need to create the ``${HOME}/.minio/certs`` directory if it does not exist.
.. cond:: macos
For ``systemd`` managed deployments this must correspond to the ``USER`` running the MinIO process.
If that user has no home directory, use the :guilabel:`Custom Path` option instead.
The MinIO server searches the following directory for TLS keys and certificates:
.. tab-item:: Custom Path
.. code-block:: shell
You can specify a path for the MinIO server to search for certificates using the :mc-cmd:`minio server --certs-dir` or ``-S`` parameter.
${HOME}/.minio/certs
For example, the following command fragment directs the MinIO process to use the ``/opt/minio/certs`` directory for TLS certificates.
For deployments started with a custom TLS directory :mc-cmd:`minio server --certs-dir`, use that directory instead of the defaults.
.. code-block:: shell
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the ``/certs`` directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
minio server --certs-dir /opt/minio/certs ...
For example:
The user running the MinIO service *must* have read and write permissions to this directory.
.. code-block:: shell
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the ``/certs`` directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
${HOME}/.minio/certs
private.key
public.crt
For distributed MinIO deployments, each node in the deployment must have matching TLS certificate configurations.
Where ``${HOME}`` is the home directory of the user running the MinIO Server process.
You may need to create the ``${HOME}/.minio/certs`` directory if it does not exist.
Self-signed, Internal, Private Certificates, and Public CAs with Intermediate Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
You can use the MinIO :minio-git:`certgen <certgen>` to mint self-signed certificates for evaluating MinIO with TLS enabled.
For example, the following command generates a self-signed certificate with a set of IP and DNS SANs associated to the MinIO Server hosts:
If using Certificates signed by a non-global or non-public Certificate Authority, *or* if using a global CA that requires the use of intermediate certificates, you must provide those CAs to the MinIO Server.
If the MinIO server does not have the necessary CAs, it may return warnings or errors related to TLS validation when connecting to other services.
.. code-block:: shell
Place the CA certificates in the ``/certs/CAs`` folder.
The root path for this folder depends on whether you use the default certificate path *or* a custom certificate path (:mc-cmd:`minio server --certs-dir` or ``-S``)
certgen -host "localhost,minio-*.example.net"
.. tab-set::
Place the generated ``public.crt`` and ``private.key`` into the ``/.minio/certs`` directory to enable TLS for the MinIO deployment.
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
.. tab-item:: Default Certificate Path
If you are reconfiguring an existing deployment that did not previously have TLS enabled, update :envvar:`MINIO_VOLUMES` to specify ``https`` instead of ``http``.
You may also need to update URLs used by applications or clients.
.. code-block:: shell
mv myCA.crt ${HOME}/.minio/certs/CAs
.. cond:: windows
.. tab-item:: Custom Certificate Path
The MinIO server searches the following directory for TLS keys and certificates:
The following example assumes the MinIO Server was started with ``--certs dir /opt/minio/certs``:
.. code-block:: shell
.. code-block:: shell
%%USERPROFILE%%\.minio\certs
mv myCA.crt /opt/minio/certs/CAs/
For deployments started with a custom TLS directory :mc-cmd:`minio server --certs-dir`, use that directory instead of the defaults.
For a self-signed certificate, the Certificate Authority is typically the private key used to sign the cert.
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the ``/certs`` directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
For certificates signed by an internal, private, or other non-global Certificate Authority, use the same CA that signed the cert.
A non-global CA must include the full chain of trust from the intermediate certificate to the root.
For example:
If the provided file is not an X.509 certificate, MinIO ignores it and may return errors for validating certificates signed by that CA.
.. code-block:: shell
Third-Party Certificate Authorities
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
%%USERPROFILE%%\.minio\certs
private.key
public.crt
The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.
Where ``%%USERPROFILE%%`` is the location of the `User Profile folder <https://docs.microsoft.com/en-us/windows/deployment/usmt/usmt-recognized-environment-variables>`__ of the user running the MinIO Server process.
Place the CA certificates in the ``/certs/CAs`` folder.
The root path for this folder depends on whether you use the default certificate path *or* a custom certificate path (:mc-cmd:`minio server --certs-dir` or ``-S``)
You can use the MinIO :minio-git:`certgen <certgen>` to mint self-signed certificates for evaluating MinIO with TLS enabled.
For example, the following command generates a self-signed certificate with a set of IP and DNS SANs associated to the MinIO Server hosts:
.. tab-set::
.. code-block:: shell
.. tab-item:: Default Certificate Path
certgen.exe -host "localhost,minio-*.example.net"
.. code-block:: shell
Place the generated ``public.crt`` and ``private.key`` into the ``\.minio\certs`` directory to enable TLS for the MinIO deployment.
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
mv myCA.crt ${HOME}/certs/CAs
If you are reconfiguring an existing deployment that did not previously have TLS enabled, update :envvar:`MINIO_VOLUMES` to specify ``https`` instead of ``http``.
You may also need to update URLs used by applications or clients.
.. tab-item:: Custom Certificate Path
The following example assumes the MinIO Server was started with ``--certs dir /opt/minio/certs``:
.. cond:: k8s
.. code-block:: shell
Supported Secret Types
~~~~~~~~~~~~~~~~~~~~~~
mv myCA.crt /opt/minio/certs/CAs/
MinIO supports three types of :kube-docs:`secrets in Kubernetes <concepts/configuration/secret/#secret-types>`.
#. ``opaque``
Using ``private.key`` and ``public.crt`` files.
#. ``tls``
Using ``tls.key`` and ``tls.crt`` files.
#. `cert-manager <https://cert-manager.io/>`__ 1.7.x or later
Running on Kubernetes 1.21 or later.
.. note::
For the best support of *tls* or *cert-manager* secrets, upgrade to Operator version 5.0.10 or later.
Multiple Domain-Based TLS Certificates
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. cond:: k8s
The MinIO Operator supports attaching user-specified TLS certificates when :ref:`deploying <minio-k8s-deploy-minio-tenant-security>` or :ref:`modifying <minio-k8s-modify-minio-tenant-security>` the MinIO Tenant.
These custom certificates support `Server Name Indication (SNI) <https://en.wikipedia.org/wiki/Server_Name_Indication>`__, where the MinIO server identifies which certificate to use based on the hostname specified by the connecting client.
For example, you can generate certificates signed by your organization's preferred Certificate Authority (CA) and attach those to the MinIO Tenant.
Applications which trust that :abbr:`CA (Certificate Authority)` can connect to the MinIO Tenant and fully validate the Tenant TLS certificates.
.. cond:: linux
The MinIO server supports multiple TLS certificates, where the server uses `Server Name Indication (SNI) <https://en.wikipedia.org/wiki/Server_Name_Indication>`__ to identify which certificate to use when responding to a client request.
When a client connects using a specific hostname, MinIO uses :abbr:`SNI (Server Name Indication)` to select the appropriate TLS certificate for that hostname.
For example, consider a MinIO deployment reachable through the following hostnames:
- ``https://minio.example.net`` (default TLS certificates)
- ``https://s3.example.net``
- ``https://minio.internal-example.net``
Place the certificates in the ``/certs`` folder, creating a subfolder in ``/certs`` for each additional domain for which MinIO should present TLS certificates.
While MinIO has no requirements for folder names, consider creating subfolders whose name matches the domain to improve human readability.
Place the TLS private and public key for that domain in the subfolder.
The root path for this folder depends on whether you use the default certificate path *or* a custom certificate path (:mc-cmd:`minio server --certs-dir` or ``-S``).
.. tab-set::
.. tab-item:: Default Certificate Path
.. code-block:: shell
${HOME}/.minio/certs
private.key
public.crt
s3-example.net/
private.key
public.crt
internal-example.net/
private.key
public.crt
.. tab-item:: Custom Certificate Path
The following example assumes the MinIO Server was started with ``--certs dir | -S /opt/minio/certs``:
.. code-block:: shell
/opt/minio/certs
private.key
public.crt
s3-example.net/
private.key
public.crt
internal-example.net/
private.key
public.crt
While you can have a single TLS certificate that covers all hostnames with multiple Subject Alternative Names (SANs), this would reveal the ``internal-example.net`` and ``s3-example.net`` hostnames to any client which inspects the server certificate.
Using a TLS certificate per hostname better protects each individual hostname from discovery.
The individual TLS certificate SANs **must** apply to the hostname for their respective parent node.
If the client-specified hostname or IP address does not match any of the configured TLS certificates, the connection typically fails with a certificate validation error.
.. cond:: container
The MinIO server supports multiple TLS certificates, where the server uses `Server Name Indication (SNI) <https://en.wikipedia.org/wiki/Server_Name_Indication>`__ to identify which certificate to use when responding to a client request.
When a client connects using a specific hostname, MinIO uses :abbr:`SNI (Server Name Indication)` to select the appropriate TLS certificate for that hostname.
For example, consider a MinIO deployment reachable through the following hostnames:
- ``https://minio.example.net`` (default TLS certificates)
- ``https://s3.example.net``
- ``https://minio.internal-example.net``
Start the MinIO container with the :mc-cmd:`minio/minio:latest server --certs-dir <minio server --certs-dir>` parameter and specify the path to a directory in which MinIO searches for certificates.
You must mount a local host volume to that path when starting the container to ensure the MinIO Server can access the necessary certificates.
Place the TLS certificates for the default domain (e.g. ``minio.example.net``) in the specified directory, with the private key as ``private.key`` and public certificate as ``public.crt``.
For other hostnames, create a subfolder whose name matches the domain to improve human readability.
Place the TLS private and public key for that domain in the subfolder.
For example:
.. code-block:: shell
/opts/certs
private.key
public.crt
s3-example.net/
private.key
public.crt
internal-example.net/
private.key
public.crt
When the MinIO container starts, the server searches the mounted location ``/opts/certs`` for certificates and uses them enable TLS.
MinIO serves clients connecting to the container using a supported hostname with the associated certificates.
Applications can use the ``public.crt`` as a trusted Certificate Authority to allow connections to the MinIO deployment without disabling certificate validation.
While you can have a single TLS certificate that covers all hostnames with multiple Subject Alternative Names (SANs), this would reveal the ``internal-example.net`` and ``s3-example.net`` hostnames to any client which inspects the server certificate.
Using one TLS certificate per hostname better protects each individual hostname from discovery.
The individual TLS certificate SANs **must** apply to the hostname for their respective parent node.
If the client-specified hostname or IP address does not match any of the configured TLS certificates, the connection typically fails with a certificate validation error.
.. cond:: macos
The MinIO server supports multiple TLS certificates, where the server uses `Server Name Indication (SNI) <https://en.wikipedia.org/wiki/Server_Name_Indication>`__ to identify which certificate to use when responding to a client request.
When a client connects using a specific hostname, MinIO uses SNI to select the appropriate TLS certificate for that hostname.
For example, consider a MinIO deployment reachable through the following hostnames:
- ``https://minio.example.net`` (default TLS certificates)
- ``https://s3.example.net``
- ``https://minio.internal-example.net``
Create a subfolder in ``/certs`` for each additional domain for which MinIO should present TLS certificates.
While MinIO has no requirements for folder names, consider creating subfolders whose name matches the domain to improve human readability.
Place the TLS private and public key for that domain in the subfolder.
For example:
.. code-block:: shell
${HOME}/.minio/certs
private.key
public.crt
s3-example.net/
private.key
public.crt
internal-example.net/
private.key
public.crt
While you can have a single TLS certificate that covers all hostnames with multiple Subject Alternative Names (SANs), this would reveal the ``internal-example.net`` and ``s3-example.net`` hostnames to any client which inspects the server certificate.
Using a TLS certificate per hostname better protects each individual hostname from discovery.
The individual TLS certificate SANs **must** apply to the hostname for their respective parent node.
If the client-specified hostname or IP address does not match any of the configured TLS certificates, the connection typically fails with a certificate validation error.
.. cond:: windows
The MinIO server supports multiple TLS certificates, where the server uses `Server Name Indication (SNI) <https://en.wikipedia.org/wiki/Server_Name_Indication>`__ to identify which certificate to use when responding to a client request.
When a client connects using a specific hostname, MinIO uses SNI to select the appropriate TLS certificate for that hostname.
For example, consider a MinIO deployment reachable through the following hostnames:
- ``https://minio.example.net`` (default TLS certificates)
- ``https://s3.example.net``
- ``https://minio.internal-example.net``
Create a subfolder in ``/certs`` for each additional domain for which MinIO should present TLS certificates.
While MinIO has no requirements for folder names, consider creating subfolders whose name matches the domain to improve human readability.
Place the TLS private and public key for that domain in the subfolder.
For example:
.. code-block:: shell
%%USERPROFILE%%\.minio\certs
private.key
public.crt
s3-example.net\
private.key
public.crt
internal-example.net\
private.key
public.crt
While you can have a single TLS certificate that covers all hostnames with multiple Subject Alternative Names (SANs), this would reveal the ``internal-example.net`` and ``s3-example.net`` hostnames to any client which inspects the server certificate.
Using a TLS certificate per hostname better protects each individual hostname from discovery.
The individual TLS certificate SANs **must** apply to the hostname for their respective parent node.
If the client-specified hostname or IP address does not match any of the configured TLS certificates, the connection typically fails with a certificate validation error.
Place the certificate file for each CA into the ``/CAs`` subdirectory.
Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory.
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
.. _minio-TLS-supported-cipher-suites:
@@ -458,169 +244,9 @@ MinIO supports the following TLS 1.2 and 1.3 cipher suites as supported by `Go <
- ``TLS_ECDHE_RSA_WITH_AES_128_GCM_SHA256``
- ``TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384``
.. _minio-TLS-third-party-ca:
.. toctree::
:hidden:
Third-Party Certificate Authorities
-----------------------------------
.. cond:: k8s
The MinIO Kubernetes Operator can automatically attach third-party Certificate Authorities when :ref:`deploying <minio-k8s-deploy-minio-tenant-security>` or :ref:`modifying <minio-k8s-modify-minio-tenant-security>` a MinIO Tenant.
You can add, update, or remove CAs from the tenant at any time.
You must restart the MinIO Tenant for the changes to the configured CAs to apply.
The Operator places the specified CAs on each MinIO Server pod such that all pods have a consistent set of trusted CAs.
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
.. cond:: linux
The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.
Place the CA certificates in the ``/certs/CAs`` folder.
The root path for this folder depends on whether you use the default certificate path *or* a custom certificate path (:mc-cmd:`minio server --certs-dir` or ``-S``)
.. tab-set::
.. tab-item:: Default Certificate Path
.. code-block:: shell
mv myCA.crt ${HOME}/certs/CAs
.. tab-item:: Custom Certificate Path
The following example assumes the MinIO Server was started with ``--certs dir /opt/minio/certs``:
.. code-block:: shell
mv myCA.crt /opt/minio/certs/CAs/
Place the certificate file for each CA into the ``/CAs`` subdirectory.
Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory.
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
.. cond:: container
Start the MinIO container with the :mc-cmd:`minio/minio:latest server --certs-dir <minio server --certs-dir>` parameter and specify the path to a directory in which MinIO searches for certificates.
You must mount a local host volume to that path when starting the container to ensure the MinIO Server can access the necessary certificates.
For deployments started with a custom TLS directory :mc-cmd:`minio server --certs-dir`, the server searches in the ``/CAs`` path at that specified directory.
For example:
.. code-block:: shell
/opts/certs
private.key
public.crt
/CAs
my-ca.crt
Place the certificate file for each CA into the ``/CAs`` subdirectory.
Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory.
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
.. cond:: macos
The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.
You can place additional trusted Certificate Authority files in the following directory:
.. code-block:: shell
${HOME}/.minio/certs/CAs
Where ``${HOME}`` is the home directory of the user running the MinIO Server process.
You may need to create the ``${HOME}/.minio/certs`` directory if it does not exist.
For deployments started with a custom TLS directory :mc-cmd:`minio server --certs-dir`, the server searches in the ``/certs/CAs`` path at that specified directory.
Place the certificate file for each CA into the ``/CAs`` subdirectory.
Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory.
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
.. cond:: windows
The MinIO Server validates the TLS certificate presented by each connecting client against the host system's trusted root certificate store.
You can place additional trusted Certificate Authority files in the following directory:
.. code-block:: shell
%%USERPROFILE%%\.minio\certs\CAs
Where ``%%USERPROFILE%%`` is the location of the `User Profile folder <https://docs.microsoft.com/en-us/windows/deployment/usmt/usmt-recognized-environment-variables>`__ of the user running the MinIO Server process.
For deployments started with a custom TLS directory :mc-cmd:`minio server --certs-dir`, the server searches in the ``\CAs`` path at that specified directory.
Place the certificate file for each CA into the ``/CAs`` subdirectory.
Ensure all hosts in the MinIO deployment have a consistent set of trusted CAs in that directory.
If the MinIO Server cannot match an incoming client's TLS certificate issuer against any of the available CAs, the server rejects the connection as invalid.
Self-signed, Internal, Private Certificates, and Public CAs with Intermediate Certificates
------------------------------------------------------------------------------------------
.. cond:: not k8s
If using Certificates signed by a non-global or non-public Certificate Authority, *or* if using a global CA that requires the use of intermediate certificates, you must provide those CAs to the MinIO Server.
If the MinIO server does not have the necessary CAs, it may return warnings or errors related to TLS validation when connecting to other services.
Place the CA certificates in the ``/certs/CAs`` folder.
The root path for this folder depends on whether you use the default certificate path *or* a custom certificate path (:mc-cmd:`minio server --certs-dir` or ``-S``)
.. tab-set::
.. tab-item:: Default Certificate Path
.. code-block:: shell
mv myCA.crt ${HOME}/.minio/certs/CAs
.. tab-item:: Custom Certificate Path
The following example assumes the MinIO Server was started with ``--certs dir /opt/minio/certs``:
.. code-block:: shell
mv myCA.crt /opt/minio/certs/CAs/
.. important::
Do not use or share the private key of the self-signed certificate.
Only the public certificate should be shared or distributed for trust purposes.
For certificates signed by an internal, private, or other non-global Certificate Authority, use the same CA that signed the cert.
A non-global CA must include the full chain of trust from the intermediate certificate to the root.
If the provided file is not an X.509 certificate, MinIO ignores it and may return errors for validating certificates signed by that CA.
.. cond:: k8s
If deploying MinIO Tenants with certificates minted by a non-global or non-public Certificate Authority, *or* if using a global CA that requires the use of intermediate certificates, you must provide those CAs to the Operator to ensure it can trust those certificates.
The Operator may log warnings related to TLS cert validation for Tenants deployed with untrusted certificates.
The following procedure attaches a secret containing the ``public.crt`` of the Certificate Authority to the MinIO Operator.
You can specify multiple CAs in a single certificate, as long as you maintain the ``BEGIN`` and ``END`` delimiters as-is.
1. Create the ``operator-ca-tls`` secret
The following creates a Kubernetes secret in the MinIO Operator namespace (``minio-operator``).
.. code-block:: shell
:class: copyable
kubectl create secret generic operator-ca-tls \
--from-file=public.crt -n minio-operator
The ``public.crt`` file must correspond to a valid TLS certificate containing one or more CA definitions.
2. Restart the Operator
Once created, you must restart the Operator to load the new CAs:
.. code-block:: shell
:class: copyable
kubectl rollout restart deployments.apps/minio-operator -n minio-operator
/operations/network-encryption/enable-minio-tls
/operations/network-encryption/enable-multiple-domain-minio-tls
/operations/network-encryption/cert-manager