minio/docs
1
0
Fork 0
mirror of https://github.com/minio/docs.git synced 2025-08-08 01:43:18 +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

240
source/includes/k8s/file-transfer-protocol-k8s.rst
View File

@@ -1,153 +1,67 @@
.. versionadded:: Operator v5.0.7
Overview
--------
Starting with Operator 5.0.7 and :minio-release:`MinIO Server RELEASE.2023-04-20T17-56-55Z <RELEASE.2023-04-20T17-56-55Z>`, you can use the SSH File Transfer Protocol (SFTP) to interact with the objects on a MinIO Operator Tenant deployment.
SFTP is defined by the Internet Engineering Task Force (IETF) as an extension of SSH 2.0.
It allows file transfer over SSH for use with :ref:`Transport Layer Security (TLS) <minio-tls>` and virtual private network (VPN) applications.
Enabling SFTP does not affect other MinIO features.
Supported Commands
~~~~~~~~~~~~~~~~~~
When enabled, MinIO supports the following SFTP operations:
- ``get``
- ``put``
- ``ls``
- ``mkdir``
- ``rmdir``
- ``delete``
MinIO does not support either ``append`` or ``rename`` operations.
MinIO Operator only supports the SFTP file transfer protocol.
Other protocols, such as FTP, are not supported for accessing Tenants.
Considerations
--------------
Versioning
~~~~~~~~~~
SFTP clients can only operate on the :ref:`latest version <minio-bucket-versioning>` of an object.
Specifically:
- For read operations, MinIO only returns the latest version of the requested object(s) to the SFTP client.
- For write operations, MinIO applies normal versioning behavior and creates a new object version at the specified namespace.
``rm`` and ``rmdir`` operations create ``DeleteMarker`` objects.
Authentication and Access
~~~~~~~~~~~~~~~~~~~~~~~~~
SFTP access requires the same authentication as any other S3 client.
MinIO supports the following authentication providers:
- :ref:`MinIO IDP <minio-internal-idp>` users and their service accounts
- :ref:`Active Directory/LDAP <minio-external-identity-management-ad-ldap>` users and their service accounts
- :ref:`OpenID/OIDC <minio-external-identity-management-openid>` service accounts
- :ref:`Certificate Key File <minio-certificate-key-file-sftp-k8s>`
:ref:`STS <minio-security-token-service>` credentials **cannot** access buckets or objects over SFTP.
Authenticated users can access buckets and objects based on the :ref:`policies <minio-policy>` assigned to the user or parent user account.
The SFTP protocol does not require any of the ``admin:*`` :ref:`permissions <minio-policy-mc-admin-actions>`.
You may not perform other MinIO admin actions with SFTP.
Prerequisites
-------------
- MinIO Operator v5.0.7 or later.
- Enable an SFTP port (8022) for the server.
- A port to use for the SFTP commands and a range of ports to allow the SFTP server to request to use for the data transfer.
Procedure
---------
#. Enable SFTP for the desired Tenant:
.. tab-set::
Use the following Kubectl command to edit the Tenant YAML configuration:
.. tab-item:: Operator Console
.. code-block:: yaml
- In the Operator Console, click on the Tenant for which to enable SFTP.
- In the :guilabel:`Configuration` tab, toggle :guilabel:`SFTP` to :guilabel:`Enabled`.
- Click :guilabel:`Save`.
- Click :guilabel:`Restart` to restart MinIO and apply your changes.
kubectl edit tenants/my-tenant -n my-tenant-ns
.. tab-item:: Kubectl
Replace ``my-tenant`` and ``my-tenant-ns`` with the desired Tenant and namespace.
Use the following Kubectl command to edit the Tenant YAML configuration:
In the ``features:`` section, set the value of ``enableSFTP`` to ``true``:
.. code-block:: yaml
.. code-block:: yaml
kubectl edit tenants/my-tenant -n my-tenant-ns
spec:
configuration:
name: my-tenant-env-configuration
credsSecret:
name: my-tenant-secret
exposeServices:
console: true
minio: true
features:
enableSFTP: true
Replace ``my-tenant`` and ``my-tenant-ns`` with the desired Tenant and namespace.
Kubectl restarts MinIO to apply the change.
In the ``features:`` section, set the value of ``enableSFTP`` to ``true``:
.. code-block:: yaml
spec:
configuration:
name: my-tenant-env-configuration
exposeServices:
console: true
minio: true
features:
enableSFTP: true
Kubectl restarts MinIO to apply the change.
You may also set ``enableSFTP`` in your `Helm chart <https://github.com/minio/operator/blob/8385948929bc95648d1be82d96f829c810519674/helm/tenant/values.yaml>`__ or `Kustomize configuration <https://github.com/minio/operator/blob/8385948929bc95648d1be82d96f829c810519674/examples/kustomization/base/tenant.yaml>`__ to enable SFTP for newly created Tenants.
You may also set ``enableSFTP`` in your `Helm chart <https://github.com/minio/operator/blob/8385948929bc95648d1be82d96f829c810519674/helm/tenant/values.yaml>`__ or `Kustomize configuration <https://github.com/minio/operator/blob/8385948929bc95648d1be82d96f829c810519674/examples/kustomization/base/tenant.yaml>`__ to enable SFTP for newly created Tenants.
#. If needed, configure ingress for the SFTP port according to your local policies.
#. Validate the configuration
The following ``kubectl get`` command uses `yq <https://github.com/mikefarah/yq/#install>`__ to display the value of ``enableSFTP``, indicating whether SFTP is enabled:
.. code-block:: console
:class: copyable
kubectl get tenants/my-tenant -n my-tenant-ns -o yaml | yq '.spec.features'
Replace ``my-tenant`` and ``my-tenant-ns`` with the desired Tenant and namespace.
If SFTP is enabled, the output resembles the following:
.. code-block:: console
enableSFTP: true
#. Use your preferred SFTP client to connect to the MinIO deployment.
You must connect as a user whose :ref:`policies <minio-policy>` allow access to the desired buckets and objects.
The specifics of connecting to the MinIO deployment depend on your SFTP client.
Refer to the documentation for your client.
The following example connects to the MinIO Tenant SFTP server forwarded to the local host system, and lists the contents of a bucket named ``runner``.
Examples
--------
.. code-block:: console
The following examples use the `SFTP CLI client <https://linux.die.net/man/1/sftp>`__ on a Linux system.
Connect to MinIO Using SFTP
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The following example connects to an SFTP server, lists the contents of a bucket named ``test-bucket``, and downloads an object.
.. code-block:: console
sftp -P 8022 my-access-key@localhost
my-access-key@localhost's password:
Connected to localhost.
sftp> ls
test-bucket
sftp> ls test-bucket
test-bucket/test-file.txt
sftp> get test-bucket/test-file.txt
Fetching /test-bucket/test-file.txt to test-file.txt
test-file.txt 100% 6 1.3KB/s 00:00
Check if SFTP is Enabled for a Tenant
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
> sftp -P 8022 minio@localhost
minio@localhost's password:
Connected to localhost.
sftp> ls runner/
chunkdocs testdir
The following ``kubectl get`` command uses `yq <https://github.com/mikefarah/yq/#install>`__ to display the value of ``enableSFTP``, indicating whether SFTP is enabled:
@@ -164,73 +78,3 @@ If SFTP is enabled, the output resembles the following:
enableSFTP: true
.. _minio-certificate-key-file-sftp-k8s:
Connect to MinIO Using SFTP with a Certificate Key File
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. versionadded:: RELEASE.2024-05-07T06-41-25Z
MinIO supports mutual TLS (mTLS) certificate-based authentication on SFTP, where both the server and the client verify the authenticity of each other.
This type of authentication requires the following:
1. Public key file for the trusted certificate authority
2. Public key file for the MinIO Server minted and signed by the trusted certificate authority
3. Public key file for the user minted and signed by the trusted certificate authority for the client connecting by SFTP and located in the user's ``.ssh`` folder (or equivalent for the operating system)
The keys must include a `principals list <https://man.openbsd.org/ssh-keygen#CERTIFICATES>`__ of the user(s) that can authenticate with the key:
.. code-block:: console
:class: copyable
ssh-keygen -s ~/.ssh/ca_user_key -I miniouser -n miniouser -V +1h -z 1 miniouser1.pub
- ``-s`` specifies the path to the certificate authority public key to use for generating this key.
The specified public key must have a ``principals`` list that includes this user.
- ``-I`` specifies the key identity for the public key.
- ``-n`` creates the ``user principals`` list for which this key is valid.
You must include the user for which this key is valid, and the user must match the username in MinIO.
- ``-V`` limits the duration for which the generated key is valid.
In this example, the key is valid for one hour.
Adjust the duration for your requirements.
- ``-z`` adds a serial number to the key to distinguish this generated public key from other keys signed by the same certificate authority public key.
MinIO requires specifying the Certificate Authority used to sign the certificates for SFTP access.
Start or restart the MinIO Server and specify the path to the trusted certificate authority's public key using an ``--sftp="trusted-user-ca-key=PATH"`` flag:
.. code-block:: console
:class: copyable
minio server {path-to-server} --sftp="trusted-user-ca-key=/path/to/.ssh/ca_user_key.pub" {...other flags}
When connecting to the MinIO Server with SFTP, the client verifies the MinIO Server's certificate.
The client then passes its own certificate to the MinIO Server.
The MinIO Server verifies the key created above by comparing its value to the the known public key from the certificate authority provided at server startup.
Once the MinIO Server verifies the client's certificate, the user can connect to the MinIO server over SFTP:
.. code-block:: bash
:class: copyable:
sftp -P <SFTP port> <server IP>
Require service account or LDAP for authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To force authentication to SFTP using LDAP or service account credentials, append a suffix to the username.
Valid suffixes are either ``=ldap`` or ``=svc``.
.. code-block:: console
> sftp -P 8022 my-ldap-user=ldap@[minio@localhost]:/bucket
.. code-block:: console
> sftp -P 8022 my-ldap-user=svc@[minio@localhost]:/bucket
- Replace ``my-ldap-user`` with the username to use.
- Replace ``[minio@localhost]`` with the address of the MinIO server.

141
source/includes/k8s/steps-configure-ad-ldap-external-identity-management.rst
View File

@@ -1,109 +1,102 @@
Deploy MinIO Tenant with Active Directory / LDAP Identity Management
--------------------------------------------------------------------
#. Access the Operator Console
1) Access the Operator Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Temporarily forward traffic between the local host machine and the MinIO Operator Console and retrieve the JWT token for your Operator deployment.
For instructions, see :ref:`Configure access to the Operator Console service <minio-k8s-deploy-operator-access-console>`.
Temporarily forward traffic between the local host machine and the MinIO Operator Console and retrieve the JWT token for your Operator deployment.
For instructions, see :ref:`Configure access to the Operator Console service <minio-k8s-deploy-operator-access-console>`.
Open your browser to the temporary URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
Open your browser to the temporary URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
To deploy a new MinIO Tenant with AD/LDAP external identity management, select the :guilabel:`+ Create Tenant` button.
Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant.
To configure an existing MinIO Tenant with AD/LDAP external identity management select that Tenant from the displayed list.
The following steps reference the necessary sections and configuration settings for existing Tenants.
If you are modifying an existing Tenant, select that Tenant from the list.
The following steps reference the necessary sections and configuration settings for existing Tenants.
#. Complete the :guilabel:`Identity Provider` Section
2) Complete the :guilabel:`Identity Provider` Section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable external identity management with an Active Directory / LDAP provider, select the :guilabel:`Identity Provider` section.
You can then change the radio button to :guilabel:`Active Directory` to display the configuration settings.
To enable external identity management with an Active Directory / LDAP provider, select the :guilabel:`Identity Provider` section.
You can then change the radio button to :guilabel:`Active Directory` to display the configuration settings.
.. image:: /images/k8s/operator-create-tenant-identity-provider-adldap.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - External Identity Provider Section - Active Directory / LDAP
.. image:: /images/k8s/operator-create-tenant-identity-provider-adldap.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - External Identity Provider Section - Active Directory / LDAP
An asterisk ``*`` marks required fields.
The following table provides general guidance for those fields:
An asterisk ``*`` marks required fields.
The following table provides general guidance for those fields:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Field
- Description
* - Field
- Description
* - LDAP Server Address
- The hostname of the Active Directory or LDAP server.
* - LDAP Server Address
- The hostname of the Active Directory or LDAP server.
* - Lookup Bind DN
- The Distinguished Name MinIO uses to authenticate and query the AD/LDAP server.
* - Lookup Bind DN
- The Distinguished Name MinIO uses to authenticate and query the AD/LDAP server.
See :ref:`minio-external-identity-management-ad-ldap-lookup-bind` for more information.
See :ref:`minio-external-identity-management-ad-ldap-lookup-bind` for more information.
* - List of user DNs (Distinguished Names) to be Tenant Administrators
- Specify a user :abbr:`DNs (Distinguished Names)` which MinIO assigns a :ref:`policy <minio-policy>` with administrative permissions for the Tenant.
You can specify multiple :abbr:`DNs (Distinguished Names)` by selecting the plus :octicon:`plus-circle` icon.
You can delete a DN by selecting the trash can :octicon:`trash` icon for that DN.
* - List of user DNs (Distinguished Names) to be Tenant Administrators
- Specify a user :abbr:`DNs (Distinguished Names)` which MinIO assigns a :ref:`policy <minio-policy>` with administrative permissions for the Tenant.
You can specify multiple :abbr:`DNs (Distinguished Names)` by selecting the plus :octicon:`plus-circle` icon.
You can delete a DN by selecting the trash can :octicon:`trash` icon for that DN.
Once you complete the section, you can finish any other required sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
Once you complete the section, you can finish any other required sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
#. Assign Policies to AD/LDAP Users
3) Assign Policies to AD/LDAP Users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO by default assigns no :ref:`policies <minio-policy>` to AD/LDAP users or groups.
You must explicitly assign MinIO policies to a given user or group Distinguished Name (DN) to grant that user or group access to the MinIO deployment.
MinIO by default assigns no :ref:`policies <minio-policy>` to AD/LDAP users or groups.
You must explicitly assign MinIO policies to a given user or group Distinguished Name (DN) to grant that user or group access to the MinIO deployment.
The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant.
The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant.
Use the :mc:`mc idp ldap policy attach` command to assign a user or group DN to an existing MinIO Policy:
Use the :mc:`mc idp ldap policy attach` command to assign a user or group DN to an existing MinIO Policy:
.. code-block:: shell
:class: copyable
.. code-block:: shell
:class: copyable
mc idp ldap policy attach minio-tenant POLICY --user='uid=primary,cn=applications,dc=domain,dc=com'
mc idp ldap policy attach minio-tenant POLICY --group='cn=applications,ou=groups,dc=domain,dc=com'
mc idp ldap policy attach minio-tenant POLICY --user='uid=primary,cn=applications,dc=domain,dc=com'
mc idp ldap policy attach minio-tenant POLICY --group='cn=applications,ou=groups,dc=domain,dc=com'
Replace ``POLICY`` with the name of the MinIO policy to assign to the user or group DN.
Replace ``POLICY`` with the name of the MinIO policy to assign to the user or group DN.
See :ref:`minio-external-identity-management-ad-ldap-access-control` for more information on access control with AD/LDAP users and groups.
See :ref:`minio-external-identity-management-ad-ldap-access-control` for more information on access control with AD/LDAP users and groups.
#. Generate S3-Compatible Temporary Credentials using AD/LDAP Credentials
4) Generate S3-Compatible Temporary Credentials using AD/LDAP Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Applications can use an AD/LDAP user credential to generate temporary S3-compatible credentials as-needed using the :ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API endpoint.
MinIO provides an example Go application :minio-git:`ldap.go <minio/blob/master/docs/sts/ldap.go>` with an example of managing this workflow.
Applications can use an AD/LDAP user credential to generate temporary S3-compatible credentials as-needed using the :ref:`minio-sts-assumerolewithldapidentity` Security Token Service (STS) API endpoint.
MinIO provides an example Go application :minio-git:`ldap.go <minio/blob/master/docs/sts/ldap.go>` with an example of managing this workflow.
.. code-block:: shell
.. code-block:: shell
POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity
&LDAPUsername=USERNAME
&LDAPPassword=PASSWORD
&Version=2011-06-15
&Policy={}
POST https://minio.example.net?Action=AssumeRoleWithLDAPIdentity
&LDAPUsername=USERNAME
&LDAPPassword=PASSWORD
&Version=2011-06-15
&Policy={}
- Replace ``minio.example.net`` with the hostname or URL for the MinIO Tenant service.
- Replace ``minio.example.net`` with the hostname or URL for the MinIO Tenant service.
- Replace the ``LDAPUsername`` with the username of the AD/LDAP user.
- Replace the ``LDAPUsername`` with the username of the AD/LDAP user.
- Replace the ``LDAPPassword`` with the password of the AD/LDAP user.
- Replace the ``LDAPPassword`` with the password of the AD/LDAP user.
- Replace the ``Policy`` with an inline URL-encoded JSON :ref:`policy <minio-policy>` that further restricts the permissions associated to the temporary credentials.
- Replace the ``Policy`` with an inline URL-encoded JSON :ref:`policy <minio-policy>` that further restricts the permissions associated to the temporary credentials.
Omit to use the :ref:`policy whose name matches <minio-external-identity-management-ad-ldap-access-control>` the Distinguished Name (DN) of the AD/LDAP user.
Omit to use the :ref:`policy whose name matches <minio-external-identity-management-ad-ldap-access-control>` the Distinguished Name (DN) of the AD/LDAP user.
The API response consists of an XML document containing the access key, secret key, session token, and expiration date.
Applications can use the access key and secret key to access and perform operations on MinIO.
The API response consists of an XML document containing the access key, secret key, session token, and expiration date.
Applications can use the access key and secret key to access and perform operations on MinIO.
See the :ref:`minio-sts-assumerolewithldapidentity` for reference documentation.
See the :ref:`minio-sts-assumerolewithldapidentity` for reference documentation.

54
source/includes/k8s/steps-configure-keycloak-identity-management.rst
View File

@@ -2,38 +2,34 @@
.. |MINIO_S3_URL| replace:: minio.minio-tenant.svc.cluster-domain.example
.. |MINIO_CONSOLE_URL| replace:: minio-console.minio-tenant.svc.cluster-domain.example
1) Configure or Create a Client for Accessing Keycloak
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Configure or Create a Client for Accessing Keycloak
Authenticate to the Keycloak :guilabel:`Administrative Console` and navigate to :guilabel:`Clients`.
Authenticate to the Keycloak :guilabel:`Administrative Console` and navigate to :guilabel:`Clients`.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client
:end-before: end-configure-keycloak-client
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client
:end-before: end-configure-keycloak-client
2) Create Client Scope for MinIO Client
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Create Client Scope for MinIO Client
Client scopes allow Keycloak to map user attributes as part of the JSON Web Token (JWT) returned in authentication requests.
This allows MinIO to reference those attributes when assigning policies to the user.
This step creates the necessary client scope to support MinIO authorization after successful Keycloak authentication.
Client scopes allow Keycloak to map user attributes as part of the JSON Web Token (JWT) returned in authentication requests.
This allows MinIO to reference those attributes when assigning policies to the user.
This step creates the necessary client scope to support MinIO authorization after successful Keycloak authentication.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client-scope
:end-before: end-configure-keycloak-client-scope
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-client-scope
:end-before: end-configure-keycloak-client-scope
3) Apply the Necessary Attribute to Keycloak Users/Groups
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Apply the Necessary Attribute to Keycloak Users/Groups
You must assign an attribute named ``policy`` to the Keycloak Users or Groups.
Set the value to any :ref:`policy <minio-policy>` on the MinIO deployment.
You must assign an attribute named ``policy`` to the Keycloak Users or Groups.
Set the value to any :ref:`policy <minio-policy>` on the MinIO deployment.
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-user-group-attributes
:end-before: end-configure-keycloak-user-group-attributes
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-user-group-attributes
:end-before: end-configure-keycloak-user-group-attributes
4) Configure MinIO for Keycloak Authentication
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Configure MinIO for Keycloak Authentication
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-minio-cli
@@ -44,16 +40,14 @@ Restart the MinIO deployment for the changes to apply.
Check the MinIO logs and verify that startup succeeded with no errors related to the OIDC configuration.
5) Generate Application Credentials using the Security Token Service (STS)
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Generate Application Credentials using the Security Token Service (STS)
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-sts
:end-before: end-configure-keycloak-sts
.. include:: /includes/common/common-configure-keycloak-identity-management.rst
:start-after: start-configure-keycloak-sts
:end-before: end-configure-keycloak-sts
#. Next Steps
Next Steps
~~~~~~~~~~
Applications should implement the :ref:`STS AssumeRoleWithWebIdentity <minio-sts-assumerolewithwebidentity>` flow using their :ref:`SDK <minio-drivers>` of choice.
When STS credentials expire, applications should have logic in place to regenerate the JWT token, STS token, and MinIO credentials before retrying and continuing operations.

66
source/includes/k8s/steps-configure-minio-kes-hashicorp.rst
View File

@@ -1,53 +1,41 @@
Deploy MinIO Tenant with Server-Side Encryption
-----------------------------------------------
#. Review the Tenant CRD
1) Access the Operator Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Review the :ref:`Tenant CRD <minio-operator-crd>` ``TenantSpec.kes`` object, the ``TenantSpec.configuration`` object, and the :minio-docs:`KES Configuration reference</kes/tutorials/configuration>`.
Temporarily forward traffic between the local host machine and the MinIO Operator Console and retrieve the JWT token for your Operator deployment.
For instructions, see :ref:`Configure access to the Operator Console service <minio-k8s-deploy-operator-access-console>`.
You must prepare all necessary configurations associated to your external Key Management Service of choice before proceeding.
Open your browser to the temporary URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
#. Create or Modify your Tenant YAML to set the values of ``KesConfig`` as necessary:
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
You must modify your Tenant YAML or ``Kustomize`` templates to reflect the necessary KES configuration.
The following example is taken from the :minio-git:`MinIO Operator Kustomize examples </operator/blob/master/examples/kustomization/tenant-kes-encryption/tenant.yaml>`
Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant.
.. code-block:: yaml
2) Complete the :guilabel:`Encryption` Section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
kes:
image: "" # minio/kes:2024-06-17T15-47-05Z
env: [ ]
replicas: 2
kesSecret:
name: kes-configuration
imagePullPolicy: "IfNotPresent"
Reference the :ref:`Deploy a MinIO Tenant <minio-k8s-deploy-minio-tenant>` procedure for complete documentation of other Tenant settings.
The ``kes-configuration`` secret must reference a Kubernetes Opaque Secret which contains a ``stringData`` object with the full KES configuration as ``server-config.yaml``.
The ``keystore`` field must contain the full configuration associated with your preferred Key Management System.
To enable |SSE| with a :kes-docs:`supported KMS target <#supported-kms-targets>` during Tenant deployment, select the :guilabel:`Encryption` section and toggle the switch to :guilabel:`Enabled`.
You can then select the Radio button for the chosen KMS provider to display configuration settings for that provider.
Reference :minio-git:`the Kustomize example <operator/blob/master/examples/kustomization/tenant-kes-encryption/kes-configuration-secret.yaml>` for additional guidance.
.. image:: /images/k8s/operator-create-tenant-encryption.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - Encryption Section
#. Create or Modify your Tenant YAML to set the values of ``TenantSpec.configuration`` as necessary.
An asterisk ``*`` marks required fields.
TODO
Refer to the Configuration References section of the tutorial for your chosen :kes-docs:`supported KMS target <#supported-kms-targets>` for more information on the configuration options for your KMS.
#. Generate a New Encryption Key
Once you have completed the configuration, you can finish any remaining sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
3) Generate a New Encryption Key
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
#. Enable SSE-KMS for a Bucket
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-generate-key-desc
:end-before: end-kes-generate-key-desc
4) Enable SSE-KMS for a Bucket
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc
.. include:: /includes/k8s/common-minio-kes.rst
:start-after: start-kes-enable-sse-kms-desc
:end-before: end-kes-enable-sse-kms-desc

181
source/includes/k8s/steps-configure-openid-external-identity-management.rst
View File

@@ -1,131 +1,124 @@
Deploy MinIO Tenant with OpenID Connect Identity Management
-----------------------------------------------------------
1. Access the Operator Console
1) Access the Operator Console
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Temporarily forward traffic between the local host machine and the MinIO Operator Console and retrieve the JWT token for your Operator deployment.
For instructions, see :ref:`Configure access to the Operator Console service <minio-k8s-deploy-operator-access-console>`.
Temporarily forward traffic between the local host machine and the MinIO Operator Console and retrieve the JWT token for your Operator deployment.
For instructions, see :ref:`Configure access to the Operator Console service <minio-k8s-deploy-operator-access-console>`.
Open your browser to the temporary URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
Open your browser to the temporary URL and enter the JWT Token into the login page.
You should see the :guilabel:`Tenants` page:
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
.. image:: /images/k8s/operator-dashboard.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console
To deploy a new MinIO Tenant with OIDC external identity management, select the :guilabel:`+ Create Tenant` button.
Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant.
TO configure an existing MinIO Tenant with OIDC external identity management select that Tenant from the displayed list.
The following steps reference the necessary sections and configuration settings for existing Tenants.
If you are modifying an existing Tenant, select that Tenant from the list.
The following steps reference the necessary sections and configuration settings for existing Tenants.
#. Complete the :guilabel:`Identity Provider` Section
2) Complete the :guilabel:`Identity Provider` Section
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
To enable external identity management with an OIDC select the :guilabel:`Identity Provider` section.
You can then change the radio button to :guilabel:`OIDC` to display the configuration settings.
To enable external identity management with an OIDC select the :guilabel:`Identity Provider` section.
You can then change the radio button to :guilabel:`OIDC` to display the configuration settings.
.. image:: /images/k8s/operator-create-tenant-identity-provider-openid.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - External Identity Provider Section - OpenID
.. image:: /images/k8s/operator-create-tenant-identity-provider-openid.png
:align: center
:width: 70%
:class: no-scaled-link
:alt: MinIO Operator Console - Create a Tenant - External Identity Provider Section - OpenID
An asterisk ``*`` marks required fields.
The following table provides general guidance for those fields:
An asterisk ``*`` marks required fields.
The following table provides general guidance for those fields:
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
.. list-table::
:header-rows: 1
:widths: 40 60
:width: 100%
* - Field
- Description
* - Field
- Description
* - Configuration URL
- The hostname of the OpenID ``.well-known/openid-configuration`` file.
* - Configuration URL
- The hostname of the OpenID ``.well-known/openid-configuration`` file.
* - | Client ID
| Secret ID
- The Client and Secret ID MinIO uses when authenticating OIDC user credentials against OIDC service.
* - | Client ID
| Secret ID
- The Client and Secret ID MinIO uses when authenticating OIDC user credentials against OIDC service.
* - Claim Name
- The OIDC Claim MinIO uses for identifying the :ref:`policies <minio-policy>` to attach to the authenticated user.
* - Claim Name
- The OIDC Claim MinIO uses for identifying the :ref:`policies <minio-policy>` to attach to the authenticated user.
Once you complete the section, you can finish any other required sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
Once you complete the section, you can finish any other required sections of :ref:`Tenant Deployment <minio-k8s-deploy-minio-tenant>`.
#. Assign Policies to OIDC Users
3) Assign Policies to OIDC Users
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
MinIO by default assigns no :ref:`policies <minio-policy>` to OIDC users.
MinIO uses the specified user Claim to identify one or more policies to attach to the authenticated user.
If the Claim is empty or specifies policies which do not exist on the deployment, the authenticated user has no permissions on the Tenant.
MinIO by default assigns no :ref:`policies <minio-policy>` to OIDC users.
MinIO uses the specified user Claim to identify one or more policies to attach to the authenticated user.
If the Claim is empty or specifies policies which do not exist on the deployment, the authenticated user has no permissions on the Tenant.
The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant.
The following example assumes an existing :ref:`alias <alias>` configured for the MinIO Tenant.
Consider the following example policy that grants general S3 API access on only the ``data`` bucket:
Consider the following example policy that grants general S3 API access on only the ``data`` bucket:
.. code-block:: json
:class: copyable
.. code-block:: json
:class: copyable
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::data",
"arn:aws:s3:::data/*"
]
}
]
}
{
"Version": "2012-10-17",
"Statement": [
{
"Effect": "Allow",
"Action": [
"s3:*"
],
"Resource": [
"arn:aws:s3:::data",
"arn:aws:s3:::data/*"
]
}
]
}
Use the :mc:`mc admin policy create` command to create a policy for use by an OIDC user:
Use the :mc:`mc admin policy create` command to create a policy for use by an OIDC user:
.. code-block:: shell
:class: copyable
.. code-block:: shell
:class: copyable
mc admin policy create minio-tenant datareadonly /path/to/datareadonly.json
mc admin policy create minio-tenant datareadonly /path/to/datareadonly.json
MinIO attaches the ``datareadonly`` policy to any authenticated OIDC user with ``datareadonly`` included in the configured claim.
MinIO attaches the ``datareadonly`` policy to any authenticated OIDC user with ``datareadonly`` included in the configured claim.
See :ref:`minio-external-identity-management-openid-access-control` for more information on access control with OIDC users and groups.
See :ref:`minio-external-identity-management-openid-access-control` for more information on access control with OIDC users and groups.
#. Generate S3-Compatible Temporary Credentials using OIDC Credentials
4) Generate S3-Compatible Temporary Credentials using OIDC Credentials
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Applications can generate temporary access credentials as-needed using the :ref:`minio-sts-assumerolewithwebidentity` Security Token Service (STS) API endpoint and the JSON Web Token (JWT) returned by the :abbr:`OIDC (OpenID Connect)` provider.
Applications can generate temporary access credentials as-needed using the :ref:`minio-sts-assumerolewithwebidentity` Security Token Service (STS) API endpoint and the JSON Web Token (JWT) returned by the :abbr:`OIDC (OpenID Connect)` provider.
The application must provide a workflow for logging into the :abbr:`OIDC (OpenID Connect)` provider and retrieving the JSON Web Token (JWT) associated to the authentication session.
Defer to the provider documentation for obtaining and parsing the JWT token after successful authentication.
MinIO provides an example Go application :minio-git:`web-identity.go <minio/blob/master/docs/sts/web-identity.go>` with an example of managing this workflow.
The application must provide a workflow for logging into the :abbr:`OIDC (OpenID Connect)` provider and retrieving the JSON Web Token (JWT) associated to the authentication session.
Defer to the provider documentation for obtaining and parsing the JWT token after successful authentication.
MinIO provides an example Go application :minio-git:`web-identity.go <minio/blob/master/docs/sts/web-identity.go>` with an example of managing this workflow.
Once the application retrieves the JWT token, use the ``AssumeRoleWithWebIdentity`` endpoint to generate the temporary credentials:
Once the application retrieves the JWT token, use the ``AssumeRoleWithWebIdentity`` endpoint to generate the temporary credentials:
.. code-block:: shell
:class: copyable
.. code-block:: shell
:class: copyable
POST https://minio.example.net?Action=AssumeRoleWithWebIdentity
&WebIdentityToken=TOKEN
&Version=2011-06-15
&DurationSeconds=86400
&Policy=Policy
POST https://minio.example.net?Action=AssumeRoleWithWebIdentity
&WebIdentityToken=TOKEN
&Version=2011-06-15
&DurationSeconds=86400
&Policy=Policy
- Replace ``minio.example.net`` with the hostname or URL of the MinIO Tenant service.
- Replace the ``TOKEN`` with the JWT token returned in the previous step.
- Replace the ``DurationSeconds`` with the duration in seconds until the temporary credentials expire. The example above specifies a period of ``86400`` seconds, or 24 hours.
- Replace the ``Policy`` with an inline URL-encoded JSON :ref:`policy <minio-policy>` that further restricts the permissions associated to the temporary credentials.
- Replace ``minio.example.net`` with the hostname or URL of the MinIO Tenant service.
- Replace the ``TOKEN`` with the JWT token returned in the previous step.
- Replace the ``DurationSeconds`` with the duration in seconds until the temporary credentials expire. The example above specifies a period of ``86400`` seconds, or 24 hours.
- Replace the ``Policy`` with an inline URL-encoded JSON :ref:`policy <minio-policy>` that further restricts the permissions associated to the temporary credentials.
Omit to use the policy associated to the OpenID user :ref:`policy claim <minio-external-identity-management-openid-access-control>`.
Omit to use the policy associated to the OpenID user :ref:`policy claim <minio-external-identity-management-openid-access-control>`.
The API response consists of an XML document containing the access key, secret key, session token, and expiration date.
Applications can use the access key and secret key to access and perform operations on MinIO.
The API response consists of an XML document containing the access key, secret key, session token, and expiration date.
Applications can use the access key and secret key to access and perform operations on MinIO.
See the :ref:`minio-sts-assumerolewithwebidentity` for reference documentation.
See the :ref:`minio-sts-assumerolewithwebidentity` for reference documentation.