diff --git a/source/administration/server-side-encryption.rst b/source/administration/server-side-encryption.rst index 9876752d..c542daaf 100644 --- a/source/administration/server-side-encryption.rst +++ b/source/administration/server-side-encryption.rst @@ -46,7 +46,7 @@ MinIO SSE is feature and API compatible with :s3-docs:`AWS Server-Side Encryptio - :kes-docs:`Entrust KeyControl ` - :kes-docs:`Fortanix SDKMS ` - :kes-docs:`Google Cloud Secret Manager ` - - :kes-docs:`Hashicorp Vault Keystore ` + - :kes-docs:`HashiCorp Vault Keystore ` - :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) ` .. tab-item:: SSE-S3 @@ -71,7 +71,7 @@ MinIO SSE is feature and API compatible with :s3-docs:`AWS Server-Side Encryptio - :kes-docs:`Entrust KeyControl ` - :kes-docs:`Fortanix SDKMS ` - :kes-docs:`Google Cloud Secret Manager ` - - :kes-docs:`Hashicorp Vault Keystore ` + - :kes-docs:`HashiCorp Vault Keystore ` - :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) ` .. tab-item:: SSE-C diff --git a/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst b/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst index 89aaaf7d..172cc6ae 100644 --- a/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst +++ b/source/administration/server-side-encryption/server-side-encryption-sse-kms.rst @@ -56,7 +56,7 @@ MinIO SSE-KMS is functionally compatible with AWS S3 :s3-docs:`Server-Side Encry - :kes-docs:`Entrust KeyControl ` - :kes-docs:`Fortanix SDKMS ` - :kes-docs:`Google Cloud Secret Manager ` -- :kes-docs:`Hashicorp Vault Keystore ` +- :kes-docs:`HashiCorp Vault Keystore ` - :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) ` .. _minio-encryption-sse-kms-quickstart: @@ -81,7 +81,7 @@ supported external Key Management Services (KMS): - :kes-docs:`Entrust KeyControl ` - :kes-docs:`Fortanix SDKMS ` - :kes-docs:`Google Cloud Secret Manager ` -- :kes-docs:`Hashicorp Vault Keystore ` +- :kes-docs:`HashiCorp Vault Keystore ` - :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) ` .. include:: /includes/common/common-minio-kes.rst diff --git a/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst b/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst index 3deb9675..b3c9c2a2 100644 --- a/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst +++ b/source/administration/server-side-encryption/server-side-encryption-sse-s3.rst @@ -53,7 +53,7 @@ following KMS providers: - :ref:`AWS SecretsManager ` - :ref:`Google Cloud SecretManager ` - :ref:`Azure Key Vault ` -- :ref:`Hashicorp KeyVault ` +- :ref:`HashiCorp KeyVault ` - Thales CipherTrust (formerly Gemalto KeySecure) .. _minio-encryption-sse-s3-quickstart: @@ -76,7 +76,7 @@ supported external Key Management Services (KMS): - :ref:`AWS SecretsManager ` - :ref:`Google Cloud SecretManager ` - :ref:`Azure Key Vault ` -- :ref:`Hashicorp KeyVault ` +- :ref:`HashiCorp KeyVault ` - Thales CipherTrust (formerly Gemalto KeySecure) .. include:: /includes/common/common-minio-kes.rst diff --git a/source/includes/aks/deploy-minio-on-azure-kubernetes-service.rst b/source/includes/aks/deploy-minio-on-azure-kubernetes-service.rst index 3f783b7d..0c553b83 100644 --- a/source/includes/aks/deploy-minio-on-azure-kubernetes-service.rst +++ b/source/includes/aks/deploy-minio-on-azure-kubernetes-service.rst @@ -1,3 +1,4 @@ + .. _deploy-operator-gke: ================================================= @@ -20,11 +21,7 @@ The MinIO Kubernetes Operator supports deploying MinIO Tenants onto AKS infrastr MinIO maintains an `AKS Marketplace listing `__ through which you can register your AKS cluster with |subnet|. Any MinIO tenant you deploy through Marketplace-connected clusters can take advantage of SUBNET registration, including 24/7 access to MinIO engineers. -Using the MinIO ``kubectl`` Plugin - MinIO provides a ``kubectl`` plugin for installing and managing the MinIO Operator and Tenants through a terminal or shell (CLI) environment. - You can manually register these tenants with |subnet| at any time. - -This page documents deploying the MinIO Operator through the CLI using the ``kubectl minio`` plugin. +This page documents deploying the MinIO Operator through the CLI using Kustomize. For instructions on deploying the MinIO Operator through the AKS Marketplace, see :minio-web:`Deploy MinIO through AKS ` This documentation assumes familiarity with all referenced Kubernetes and Azure Kubernetes Service concepts, utilities, and procedures. @@ -51,5 +48,6 @@ For guidance on connecting ``kubectl`` to AKS, see :aks-docs:`Install kubectl an Procedure --------- -.. include:: /includes/common/common-install-operator-kubectl-plugin.rst +The following steps deploy Operator using Kustomize and a ``kustomization.yaml`` file from the MinIO Operator GitHub repository. +.. include:: /includes/common/common-install-operator-kustomize.rst diff --git a/source/includes/common/common-install-operator-kubectl-plugin.rst b/source/includes/common/common-install-operator-kubectl-plugin.rst deleted file mode 100644 index cc23a0df..00000000 --- a/source/includes/common/common-install-operator-kubectl-plugin.rst +++ /dev/null @@ -1,81 +0,0 @@ -1) Install the MinIO Kubernetes Plugin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The MinIO Kubernetes Plugin provides a command for initializing the MinIO Operator. - -.. include:: /includes/k8s/install-minio-kubectl-plugin.rst - -2) Initialize the MinIO Kubernetes Operator -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Run the :mc:`kubectl minio init` command to initialize the MinIO Operator: - -.. code-block:: shell - :class: copyable - - kubectl minio init - -The command initializes the MinIO Operator with the following default settings: - -- Deploy the Operator into the ``minio-operator`` namespace. - Specify the :mc-cmd:`kubectl minio init --namespace` argument to - deploy the operator into a different namespace. - -- Use ``cluster.local`` as the cluster domain when configuring the DNS hostname - of the operator. Specify the - :mc-cmd:`kubectl minio init --cluster-domain` argument to set a - different :kube-docs:`cluster domain - ` value. - - -The Operator deploys with certain default settings and resource requests. -To modify these settings, do the following: - -1. Append the ``kubectl minio init -o > operator.yaml`` to save the YAML configuration to file -2. Modify settings as-needed to fit your deployment -3. Run ``kubectl apply -f operator.yaml`` to apply the customized Operator deployment. - -.. important:: - - Document all arguments used when initializing the MinIO Operator. - -3) Validate the Operator Installation -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -To verify the installation, run the following command: - -.. code-block:: shell - :class: copyable - - kubectl get all --namespace minio-operator - -If you initialized the Operator with a custom namespace, replace -``minio-operator`` with that namespace. - -The output resembles the following: - -.. code-block:: shell - - NAME READY STATUS RESTARTS AGE - pod/console-59b769c486-cv7zv 1/1 Running 0 81m - pod/minio-operator-7976b4df5b-rsskl 1/1 Running 0 81m - - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - service/console ClusterIP 10.105.218.94 9090/TCP,9443/TCP 81m - service/operator ClusterIP 10.110.113.146 4222/TCP,4233/TCP 81m - - NAME READY UP-TO-DATE AVAILABLE AGE - deployment.apps/console 1/1 1 1 81m - deployment.apps/minio-operator 1/1 1 1 81m - - NAME DESIRED CURRENT READY AGE - replicaset.apps/console-59b769c486 1 1 1 81m - replicaset.apps/minio-operator-7976b4df5b 1 1 1 81m - -4) Open the Operator Console -~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/common/common-k8s-connect-operator-console.rst - - - diff --git a/source/operations/install-deploy-manage/deploy-operator-kustomize.rst b/source/includes/common/common-install-operator-kustomize.rst similarity index 67% rename from source/operations/install-deploy-manage/deploy-operator-kustomize.rst rename to source/includes/common/common-install-operator-kustomize.rst index 61b4dba5..75ef08ee 100644 --- a/source/operations/install-deploy-manage/deploy-operator-kustomize.rst +++ b/source/includes/common/common-install-operator-kustomize.rst @@ -1,52 +1,17 @@ -.. _minio-k8s-deploy-operator-kustomize: - -============================== -Deploy Operator With Kustomize -============================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - - -Overview --------- - -`Kustomize `__ is a YAML-based templating tool that allows you to define Kubernetes resources in a declarative and repeatable fashion. -Kustomize is included with the :kube-docs:`kubectl ` command line tool. - -The `default MinIO Operator Kustomize template `__ provides a starting point for customizing configurations for your local environment. -You can modify the default Kustomization file or apply your own `patches `__ to customize the Operator deployment for your Kubernetes cluster. - - -Prerequisites -------------- - -Installing Operator with Kustomize requires the following prerequisites: - -* An existing Kubernetes cluster, v1.21 or later. -* A local ``kubectl`` installation with the same version as the cluster. -* Access to run ``kubectl`` commands on the cluster from your local host. - -For more about Operator installation requirements, including TLS certificates, see the :ref:`Operator deployment prerequisites `. - -This procedure assumes familiarity with the referenced Kubernetes concepts and utilities. -While this documentation may provide guidance for configuring or deploying Kubernetes-related resources on a best-effort basis, it is not a replacement for the official :kube-docs:`Kubernetes Documentation <>`. - -.. _minio-k8s-deploy-operator-kustomize-repo: +.. _minio-k8s-deploy-operator-kustomize-repo-2: Install the MinIO Operator using Kustomize ------------------------------------------- +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The following procedure uses ``kubectl -k`` to install the Operator from the MinIO Operator GitHub repository. ``kubectl -k`` and ``kubectl --kustomize`` are aliases that perform the same command. .. important:: - If you use Kustomize to install the Operator, you must use Kustomize to manage or update that installation. - Do not use ``kubectl krew``, a Helm chart, or similar methods to manage or update the MinIO Operator installation. + If you use Kustomize to install the Operator, you must use Kustomize to manage or upgrade that installation. + Do not use ``kubectl krew``, a Helm chart, or similar methods to manage or upgrade a MinIO Operator installation deployed with Kustomize. + + You can, however, use Kustomize to upgrade a previous version of Operator (5.0.14 or earlier) installed with the MinIO Kubernetes Plugin. #. Install the latest version of Operator @@ -89,15 +54,18 @@ The following procedure uses ``kubectl -k`` to install the Operator from the Min .. code-block:: shell - NAME READY STATUS RESTARTS AGE - console-6b6cf8946c-9cj25 1/1 Running 0 99s - minio-operator-69fd675557-lsrqg 1/1 Running 0 99s + NAME READY STATUS RESTARTS AGE + console-56c7d8bd89-485qh 1/1 Running 0 2m42s + minio-operator-6c758b8c45-nkhlx 1/1 Running 0 2m42s + minio-operator-6c758b8c45-dgd8n 1/1 Running 0 2m42s In this example, the ``minio-operator`` pod is MinIO Operator and the ``console`` pod is the Operator Console. - You can modify your Operator deplyoment by applying kubectl patches. + You can modify your Operator deployment by applying kubectl patches. You can find examples for common configurations in the `Operator GitHub repository `__. + .. _minio-k8s-deploy-operator-access-console: + #. *(Optional)* Configure access to the Operator Console service The Operator Console service does not automatically bind or expose itself for external access on the Kubernetes cluster. @@ -131,7 +99,8 @@ The following procedure uses ``kubectl -k`` to install the Operator from the Min } }' - You can now access the service through port ``30433`` on any of your Kubernetes worker nodes. + The patch command should output ``service/console patched``. + You can now access the service through ports ``30433`` (HTTPS) or ``30090`` (HTTP) on any of your Kubernetes worker nodes. #. Verify the Operator installation @@ -147,23 +116,22 @@ The following procedure uses ``kubectl -k`` to install the Operator from the Min .. code-block:: shell NAME READY STATUS RESTARTS AGE - pod/console-68d955874d-vxlzm 1/1 Running 0 25h - pod/minio-operator-699f797b8b-th5bk 1/1 Running 0 25h - pod/minio-operator-699f797b8b-nkrn9 1/1 Running 0 25h + pod/console-56c7d8bd89-485qh 1/1 Running 0 5m20s + pod/minio-operator-6c758b8c45-nkhlx 1/1 Running 0 5m20s + pod/minio-operator-6c758b8c45-dgd8n 1/1 Running 0 5m20s - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - service/console ClusterIP 10.43.195.224 9090/TCP,9443/TCP 25h - service/operator ClusterIP 10.43.44.204 4221/TCP 25h - service/sts ClusterIP 10.43.70.4 4223/TCP 25h + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + service/operator ClusterIP 10.43.135.241 4221/TCP 5m20s + service/sts ClusterIP 10.43.117.251 4223/TCP 5m20s + service/console NodePort 10.43.235.38 9090:30090/TCP,9443:30433/TCP 5m20s NAME READY UP-TO-DATE AVAILABLE AGE - deployment.apps/console 1/1 1 1 25h - deployment.apps/minio-operator 2/2 2 2 25h + deployment.apps/console 1/1 1 1 5m20s + deployment.apps/minio-operator 2/2 2 2 5m20s NAME DESIRED CURRENT READY AGE - replicaset.apps/console-68d955874d 1 1 1 25h - replicaset.apps/minio-operator-699f797b8b 2 2 2 25h - + replicaset.apps/console-56c7d8bd89 1 1 1 5m20s + replicaset.apps/minio-operator-6c758b8c45 2 2 2 5m20s #. Retrieve the Operator Console JWT for login @@ -183,6 +151,7 @@ The following procedure uses ``kubectl -k`` to install the Operator from the Min SA_TOKEN=$(kubectl -n minio-operator get secret console-sa-secret -o jsonpath="{.data.token}" | base64 --decode) echo $SA_TOKEN + The output of this command is the JSON Web Token (JWT) login credential for Operator Console. #. Log into the MinIO Operator Console @@ -199,7 +168,7 @@ The following procedure uses ``kubectl -k`` to install the Operator from the Min .. code-block:: shell :class: copyable - $ kubectl get nodes -o custom-columns=IP:.status.addresses[:] + kubectl get nodes -o custom-columns=IP:.status.addresses[:] IP map[address:172.18.0.5 type:InternalIP],map[address:k3d-MINIO-agent-3 type:Hostname] map[address:172.18.0.6 type:InternalIP],map[address:k3d-MINIO-agent-2 type:Hostname] diff --git a/source/includes/common/common-k8s-connect-operator-console-no-plugin.rst b/source/includes/common/common-k8s-connect-operator-console-no-plugin.rst new file mode 100644 index 00000000..64ba0fcc --- /dev/null +++ b/source/includes/common/common-k8s-connect-operator-console-no-plugin.rst @@ -0,0 +1,37 @@ +The Operator Console service does not automatically bind or expose itself for external access on the Kubernetes cluster. +Instead, you must configure a network control plane component, such as a load balancer or ingress, to grant external access. + +.. cond:: k8s + +For testing purposes or short-term access, expose the Operator Console service through a NodePort using the following patch: + +.. code-block:: shell + :class: copyable + + kubectl patch service -n minio-operator console -p ' + { + "spec": { + "ports": [ + { + "name": "http", + "port": 9090, + "protocol": "TCP", + "targetPort": 9090, + "nodePort": 30090 + }, + { + "name": "https", + "port": 9443, + "protocol": "TCP", + "targetPort": 9443, + "nodePort": 30433 + } + ], + "type": "NodePort" + } + }' + +After applying the path, you can access the service through port ``30433`` on any of the Kubernetes worker nodes. + +Append the ``nodePort`` value to the externally-accessible IP address of a worker node in your Kubernetes cluster. +Use the appropriate ``http`` or ``https`` port depending on whether you deployed Operator Console with TLS. diff --git a/source/includes/common/common-k8s-connect-operator-console.rst b/source/includes/common/common-k8s-connect-operator-console.rst index 9939ca59..b8c50dca 100644 --- a/source/includes/common/common-k8s-connect-operator-console.rst +++ b/source/includes/common/common-k8s-connect-operator-console.rst @@ -1,77 +1,60 @@ .. dropdown:: Port Forwarding :open: - .. note:: - - Some Kubernetes deployments may experience issues with timeouts during port-forwarding operations with the Operator Console. - Select the :guilabel:`NodePorts` section to view instructions for alternative access. - You can alternatively configure your preferred Ingress to grant access to the Operator Console service. - See https://github.com/kubernetes/kubectl/issues/1368 for more information. - - Run the :mc:`kubectl minio proxy` command to temporarily forward traffic from the :ref:`MinIO Operator Console ` service to your local machine: + The :ref:`Operator Console service ` does not automatically bind or expose itself for external access on the Kubernetes cluster. + Instead, configure a network control plane component, such as a load balancer or ingress, to grant external access. .. cond:: k8s and not openshift - .. code-block:: shell - :class: copyable - - kubectl minio proxy - - .. cond:: openshift - - .. code-block:: shell - :class: copyable - - oc minio proxy - - The command output includes a required token for logging into the Operator Console. - - .. image:: /images/k8s/operator-dashboard.png - :align: center - :width: 70% - :class: no-scaled-link - :alt: MinIO Operator Console - - You can deploy a new :ref:`MinIO Tenant ` from the Operator Dashboard. - -.. dropdown:: NodePorts - - Use the following command to identify the :kube-docs:`NodePorts ` configured for the Operator Console. - If your local host does not have the ``jq`` utility installed, you can run the first command and locate the ``spec.ports`` section of the output. + For testing purposes or short-term access, expose the Operator Console service through a NodePort using the following patch: .. code-block:: shell :class: copyable - kubectl get svc/console -n minio-operator -o json | jq -r '.spec.ports' - - The output resembles the following: - - .. code-block:: json + kubectl patch service -n minio-operator console -p ' + { + "spec": { + "ports": [ + { + "name": "http", + "port": 9090, + "protocol": "TCP", + "targetPort": 9090, + "nodePort": 30090 + }, + { + "name": "https", + "port": 9443, + "protocol": "TCP", + "targetPort": 9443, + "nodePort": 30433 + } + ], + "type": "NodePort" + } + }' + + The patch command should output ``service/console patched``. + You can now access the service through ports ``30433`` (HTTPS) or ``30090`` (HTTP) on any of your Kubernetes worker nodes. + + For example, a Kubernetes cluster with the following Operator nodes might be accessed at ``https://172.18.0.2:30443``: - [ - { - "name": "http", - "nodePort": 31055, - "port": 9090, - "protocol": "TCP", - "targetPort": 9090 - }, - { - "name": "https", - "nodePort": 31388, - "port": 9443, - "protocol": "TCP", - "targetPort": 9443 - } - ] - - Use the ``http`` or ``https`` port depending on whether you deployed the Operator with Console TLS enabled via :mc-cmd:`kubectl minio init --console-tls`. + .. code-block:: shell - Append the ``nodePort`` value to the externally-accessible IP address of a worker node in your Kubernetes cluster. + kubectl get nodes -o custom-columns=IP:.status.addresses[:] + IP + map[address:172.18.0.5 type:InternalIP],map[address:k3d-MINIO-agent-3 type:Hostname] + map[address:172.18.0.6 type:InternalIP],map[address:k3d-MINIO-agent-2 type:Hostname] + map[address:172.18.0.2 type:InternalIP],map[address:k3d-MINIO-server-0 type:Hostname] + map[address:172.18.0.4 type:InternalIP],map[address:k3d-MINIO-agent-1 type:Hostname] + map[address:172.18.0.3 type:InternalIP],map[address:k3d-MINIO-agent-0 type:Hostname] Use the following command to retrieve the JWT token necessary for logging into the Operator Console: .. code-block:: shell :class: copyable - kubectl get secret/console-sa-secret -n minio-operator -o json | jq -r '.data.token' | base64 -d \ No newline at end of file + kubectl get secret/console-sa-secret -n minio-operator -o json | jq -r '.data.token' | base64 -d + + If your local host does not have the ``jq`` utility installed, you can run the ``kubectl`` part of this command (before ``| jq``) and locate the ``data.token`` section of the output. + diff --git a/source/includes/common/common-k8s-operator-console-jwt.rst b/source/includes/common/common-k8s-operator-console-jwt.rst new file mode 100644 index 00000000..8b326034 --- /dev/null +++ b/source/includes/common/common-k8s-operator-console-jwt.rst @@ -0,0 +1,8 @@ +Use the following command to retrieve the JSON Web Token (JWT) necessary for logging in to the Operator Console: + +.. code-block:: shell + :class: copyable + + kubectl get secret/console-sa-secret -n minio-operator -o json | jq -r '.data.token' | base64 -d + +If your local host does not have the ``jq`` utility installed, you can run the ``kubectl`` part of this command (before ``| jq``) and locate the ``data.token`` section of the output. diff --git a/source/includes/common/common-minio-kes-hashicorp.rst b/source/includes/common/common-minio-kes-hashicorp.rst index 695c360d..7f57ae9a 100644 --- a/source/includes/common/common-minio-kes-hashicorp.rst +++ b/source/includes/common/common-minio-kes-hashicorp.rst @@ -1,7 +1,7 @@ .. start-kes-configuration-hashicorp-vault-desc |KES| uses a YAML-formatted configuration file. -The following YAML provides the minimum required fields for using Hashicorp Vault as the root |KMS|. +The following YAML provides the minimum required fields for using HashiCorp Vault as the root |KMS|. You must modify this YAML to reflect your deployment environment. .. code-block:: shell @@ -54,8 +54,8 @@ You must modify this YAML to reflect your deployment environment. engine: "/path/to/engine" # Replace with the path to the K/V Engine version: "v1|v2" # Specify v1 or v2 depending on the version of the K/V Engine approle: - id: "VAULTAPPID" # Hashicorp Vault AppRole ID - secret: "VAULTAPPSECRET" # Hashicorp Vault AppRole Secret ID + id: "VAULTAPPID" # HashiCorp Vault AppRole ID + secret: "VAULTAPPSECRET" # HashiCorp Vault AppRole Secret ID retry: 15s status: ping: 10s @@ -70,7 +70,7 @@ You must modify this YAML to reflect your deployment environment. .. start-kes-prereq-hashicorp-vault-desc -This procedure assumes an existing `Hashicorp Vault `__ installation accessible from the local host. +This procedure assumes an existing `HashiCorp Vault `__ installation accessible from the local host. The Vault `Quick Start `__ provides a sufficient foundation for the purposes of this procedure. Defer to the `Vault Documentation `__ for guidance on deployment and configuration. @@ -95,4 +95,4 @@ Defer to the `Vault Documentation `__ for gui You must unseal the Vault instance to allow normal cryptographic operations, including key creation or retrieval. See the Vault documentation on `Seal/Unseal `__ for more information. -.. end-kes-vault-seal-unseal-desc \ No newline at end of file +.. end-kes-vault-seal-unseal-desc diff --git a/source/includes/container/steps-deploy-minio-single-node-single-drive.rst b/source/includes/container/steps-deploy-minio-single-node-single-drive.rst index 5e6308d0..21a69ce1 100644 --- a/source/includes/container/steps-deploy-minio-single-node-single-drive.rst +++ b/source/includes/container/steps-deploy-minio-single-node-single-drive.rst @@ -89,7 +89,7 @@ The following table describes each line of the command and provides additional c Replace this value with the full path to a storage volume or folder on the local machine. For example: - Linux or MacOS + Linux or macOS ``~/minio/data/`` Windows diff --git a/source/includes/eks/deploy-minio-on-elastic-kubernetes-service.rst b/source/includes/eks/deploy-minio-on-elastic-kubernetes-service.rst index afa36e9f..b7c7f1a5 100644 --- a/source/includes/eks/deploy-minio-on-elastic-kubernetes-service.rst +++ b/source/includes/eks/deploy-minio-on-elastic-kubernetes-service.rst @@ -22,11 +22,7 @@ MinIO supports the following methods for installing the MinIO Operator onto your MinIO maintains an `AWS Marketplace listing `__ through which you can register your EKS cluster with |subnet|. Any tenant you deploy through Marketplace-connected clusters can take advantage of SUBNET registration, including 24/7 direct access to MinIO engineers. -Using the MinIO ``kubectl`` Plugin - MinIO provides a ``kubectl`` plugin for installing and managing the MinIO Operator and Tenants through a terminal or shell (CLI) environment. - You can manually register these tenants with |subnet| at any time. - -This page documents deploying the MinIO Operator through the CLI using the ``kubectl minio`` plugin. +This page documents deploying the MinIO Operator through the CLI using Kustomize. For instructions on deploying the MinIO Operator through the AWS Marketplace, see :minio-web:`Deploy MinIO through EKS ` This documentation assumes familiarity with all referenced Kubernetes and Elastic Kubernetes Service concepts, utilities, and procedures. @@ -57,4 +53,6 @@ You can use this policy as a baseline for manual Operator installations. Procedure --------- -.. include:: /includes/common/common-install-operator-kubectl-plugin.rst +The following steps deploy Operator using Kustomize and a ``kustomization.yaml`` file from the MinIO Operator GitHub repository. + +.. include:: /includes/common/common-install-operator-kustomize.rst diff --git a/source/includes/facts-kubectl-plugin.rst b/source/includes/facts-kubectl-plugin.rst deleted file mode 100644 index 499d785a..00000000 --- a/source/includes/facts-kubectl-plugin.rst +++ /dev/null @@ -1,20 +0,0 @@ -.. default-domain:: minio - -.. start-kubectl-minio-requires-operator-desc - -.. admonition:: Command Requires MinIO Operator - :class: note - - Use the following command to validate that the operator - is online and available prior to running this command: - - .. code-block:: shell - :class: copyable - - kubectl get deployments -A --field-selector metadata.name=minio-operator - - Issue the :mc-cmd:`kubectl minio init` command to initiate the operator - if it is not already running in the Kubernetes cluster. - - -.. end-kubectl-minio-requires-operator-desc \ No newline at end of file diff --git a/source/includes/gke/deploy-minio-on-google-kubernetes-engine.rst b/source/includes/gke/deploy-minio-on-google-kubernetes-engine.rst index 70f1f30d..38460014 100644 --- a/source/includes/gke/deploy-minio-on-google-kubernetes-engine.rst +++ b/source/includes/gke/deploy-minio-on-google-kubernetes-engine.rst @@ -24,7 +24,7 @@ Using the MinIO ``kubectl`` Plugin MinIO provides a ``kubectl`` plugin for installing and managing the MinIO Operator and Tenants through a terminal or shell (CLI) environment. You can manually register these tenants with |subnet| at any time. -This page documents deploying the MinIO Operator through the CLI using the ``kubectl minio`` plugin. +This page documents deploying the MinIO Operator through the CLI using Kustomize. For instructions on deploying the MinIO Operator through the GKE Marketplace, see :minio-web:`Deploy MinIO through GKE ` This documentation assumes familiarity with all referenced Kubernetes and Google Kubernetes Engine concepts, utilities, and procedures. @@ -51,4 +51,6 @@ For guidance on connecting ``kubectl`` to GKE, see :gke-docs:`Install kubectl an Procedure --------- -.. include:: /includes/common/common-install-operator-kubectl-plugin.rst +The following steps deploy Operator using Kustomize and a ``kustomization.yaml`` file from the MinIO Operator GitHub repository. + +.. include:: /includes/common/common-install-operator-kustomize.rst diff --git a/source/includes/k8s/common-operator.rst b/source/includes/k8s/common-operator.rst index c7437c80..930d5130 100644 --- a/source/includes/k8s/common-operator.rst +++ b/source/includes/k8s/common-operator.rst @@ -1,9 +1,7 @@ .. start-requires-operator-plugin Ensure your target Kubernetes cluster has a valid and working installation of the MinIO Kubernetes Operator. -The host machine from which you perform the procedure should have a matching installation of the MinIO Kubernetes Plugin - -This documentation assumes the latest stable Operator and Plugin version |operator-version-stable|. +This documentation assumes the latest stable Operator, version |operator-version-stable|. .. end-requires-operator-plugin diff --git a/source/includes/k8s/deploy-operator.rst b/source/includes/k8s/deploy-operator.rst index 8498f187..0dbd2056 100644 --- a/source/includes/k8s/deploy-operator.rst +++ b/source/includes/k8s/deploy-operator.rst @@ -1,5 +1,5 @@ -.. _minio-operator-installation: -.. _deploy-operator-kubernetes: +.. _minio-operator-installation-kustomize: +.. _deploy-operator-kubernetes-kustomize: ========================= Deploy the MinIO Operator @@ -17,22 +17,21 @@ Overview MinIO is a Kubernetes-native high performance object store with an S3-compatible API. The MinIO Kubernetes Operator supports deploying MinIO Tenants onto private and public cloud infrastructures ("Hybrid" Cloud). -The following procedure installs the latest stable version (|operator-version-stable|) of the MinIO Operator and MinIO Plugin on Kubernetes infrastructure: +The following procedure installs the latest stable version (|operator-version-stable|) of the MinIO Operator on Kubernetes infrastructure. -- The MinIO Operator installs a :kube-docs:`Custom Resource Definition (CRD) ` to support describing MinIO tenants as a Kubernetes :kube-docs:`object `. - See the MinIO Operator :minio-git:`CRD Reference ` for complete documentation on the MinIO CRD. - -- The MinIO Kubernetes Plugin brings native support for deploying and managing MinIO tenants on a Kubernetes cluster using the :mc:`kubectl minio` command. +The MinIO Operator installs a :kube-docs:`Custom Resource Definition (CRD) ` to support describing MinIO tenants as a Kubernetes :kube-docs:`object `. +See the MinIO Operator :minio-git:`CRD Reference ` for complete documentation on the MinIO CRD. This documentation assumes familiarity with referenced Kubernetes concepts, utilities, and procedures. While this documentation *may* provide guidance for configuring or deploying Kubernetes-related resources on a best-effort basis, it is not a replacement for the official :kube-docs:`Kubernetes Documentation <>`. + MinIO Operator Components ------------------------- The MinIO Operator exists in its own namespace. - Within the Operator's namespace, the MinIO Operator utilizes two pods: + - The Operator pod for the base Operator functions to deploy, manage, modify, and maintain tenants. - Console pod for the Operator's Graphical User Interface, the Operator Console. @@ -64,30 +63,30 @@ The tenant utilizes Persistent Volume Claims to talk to the Persistent Volumes t Prerequisites ------------- -Kubernetes Version 1.19.0 +Kubernetes Version 1.21.0 ~~~~~~~~~~~~~~~~~~~~~~~~~ .. important:: MinIO **strongly recommends** upgrading Production clusters running `End-Of-Life `__ Kubernetes APIs. -Starting with v4.0.0, the MinIO Operator and MinIO Kubernetes Plugin **require** Kubernetes 1.19.0 and later. -The Kubernetes infrastructure *and* the ``kubectl`` CLI tool must have the same version of 1.19.0+. - -Prior to v4.0.0, the MinIO Operator and Plugin required Kubernetes 1.17.0. -You *must* upgrade your Kubernetes infrastructure to 1.19.0 or later to use the MinIO Operator or Plugin v4.0.0 or later. - -Starting with v5.0.0, MinIO *recommends* Kubernetes 1.21.0 or later for both the infrastructure and the ``kubectl`` CLI tool. +Starting with v5.0.0, MinIO **requires** Kubernetes 1.21.0 or later for both the infrastructure and the ``kubectl`` CLI tool. .. versionadded:: Operator 5.0.6 For Kubernetes 1.25.0 and later, MinIO supports deploying in environments with the :kube-docs:`Pod Security admission (PSA) ` ``restricted`` policy enabled. -``kubectl`` Configuration +Kustomize and ``kubectl`` ~~~~~~~~~~~~~~~~~~~~~~~~~ -This procedure assumes that your local host machine has both the correct version of ``kubectl`` for your Kubernetes cluster *and* the necessary access to that cluster to create new resources. +`Kustomize `__ is a YAML-based templating tool that allows you to define Kubernetes resources in a declarative and repeatable fashion. +Kustomize is included with the :kube-docs:`kubectl ` command line tool. + +This procedure assumes that your local host machine has both the matching version of ``kubectl`` for your Kubernetes cluster *and* the necessary access to that cluster to create new resources. + +The `default MinIO Operator Kustomize template `__ provides a starting point for customizing configurations for your local environment. +You can modify the default Kustomization file or apply your own `patches `__ to customize the Operator deployment for your Kubernetes cluster. .. _minio-k8s-deploy-operator-tls: @@ -162,15 +161,14 @@ The output of the example command above may differ from the output in your termi Procedure --------- -The following steps deploy Operator using the MinIO Kubernetes Plugin. +The following steps deploy Operator using Kustomize and a ``kustomization.yaml`` file from the MinIO Operator GitHub repository. To install Operator using a Helm chart, see :ref:`Deploy Operator with Helm `. -.. include:: /includes/common/common-install-operator-kubectl-plugin.rst +.. include:: /includes/common/common-install-operator-kustomize.rst .. toctree:: :titlesonly: :hidden: /operations/install-deploy-manage/deploy-operator-helm - /operations/install-deploy-manage/deploy-operator-kustomize diff --git a/source/includes/k8s/install-minio-kubectl-plugin.rst b/source/includes/k8s/install-minio-kubectl-plugin.rst index 6db43653..29bc6861 100644 --- a/source/includes/k8s/install-minio-kubectl-plugin.rst +++ b/source/includes/k8s/install-minio-kubectl-plugin.rst @@ -6,7 +6,7 @@ You can install the MinIO plugin using either the Kubernetes Krew plugin manager Krew is a ``kubectl`` plugin manager developed by the `Kubernetes SIG CLI group `__. See the ``krew`` `installation documentation `__ for specific instructions. - You can use the Krew plugin for Linux, MacOS, and Windows operating systems. + You can use the Krew plugin for Linux, macOS, and Windows operating systems. You can use Krew to install the MinIO ``kubectl`` plugin using the following commands: @@ -23,27 +23,18 @@ You can install the MinIO plugin using either the Kubernetes Krew plugin manager kubectl krew upgrade minio - You can validate the installation of the MinIO plugin using the following command: - - .. code-block:: shell - :class: copyable - - kubectl minio version - - The output should match |operator-version-stable|. - .. tab-item:: Manual (Linux, MacOS) You can download the MinIO ``kubectl`` plugin to your local system path. The ``kubectl`` CLI automatically discovers and runs compatible plugins. - The following code downloads the latest stable version |operator-version-stable| of the MinIO Kubernetes plugin and installs it to the system path: + The following code downloads the most recent version of the MinIO Kubernetes plugin and installs it to the system path: .. code-block:: shell :substitutions: :class: copyable - curl https://github.com/minio/operator/releases/download/v|operator-version-stable|/kubectl-minio_|operator-version-stable|_linux_amd64 -o kubectl-minio + curl https://github.com/minio/operator/releases/download/v5.0.14/kubectl-minio_5.0.14_linux_amd64 -o kubectl-minio chmod +x kubectl-minio mv kubectl-minio /usr/local/bin/ @@ -56,20 +47,20 @@ You can install the MinIO plugin using either the Kubernetes Krew plugin manager kubectl minio version - The output should display the Operator version as |operator-version-stable|. + The output should display the Operator version as 5.0.14. .. tab-item:: Manual (Windows) You can download the MinIO ``kubectl`` plugin to your local system path. The ``kubectl`` CLI automatically discovers and runs compatible plugins. - The following PowerShell command downloads the latest stable version |operator-version-stable| of the MinIO Kubernetes plugin and installs it to the system path: + The following PowerShell command downloads the most recent version of the MinIO Kubernetes plugin and installs it to the system path: .. code-block:: powershell :substitutions: :class: copyable - Invoke-WebRequest -Uri "https://github.com/minio/operator/releases/download/v|operator-version-stable|/kubectl-minio_|operator-version-stable|_windows_amd64.exe" -OutFile "C:\kubectl-plugins\kubectl-minio.exe" + Invoke-WebRequest -Uri "https://github.com/minio/operator/releases/download/v5.0.14/kubectl-minio_5.0.14_windows_amd64.exe" -OutFile "C:\kubectl-plugins\kubectl-minio.exe" Ensure the path to the plugin folder is included in the Windows PATH. @@ -80,4 +71,4 @@ You can install the MinIO plugin using either the Kubernetes Krew plugin manager kubectl minio version - The output should display the Operator version as |operator-version-stable|. + The output should display the Operator version as 5.0.14. diff --git a/source/includes/k8s/steps-configure-ad-ldap-external-identity-management.rst b/source/includes/k8s/steps-configure-ad-ldap-external-identity-management.rst index e920271d..a4270a8d 100644 --- a/source/includes/k8s/steps-configure-ad-ldap-external-identity-management.rst +++ b/source/includes/k8s/steps-configure-ad-ldap-external-identity-management.rst @@ -4,24 +4,10 @@ Deploy MinIO Tenant with Active Directory / LDAP Identity Management 1) Access the Operator Console ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward traffic between the local host machine and the MinIO 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 `. -.. code-block:: shell - :class: copyable - - kubectl minio proxy - -The command returns output similar to the following: - -.. code-block:: shell - - Starting port forward of the Console UI. - - To connect open a browser and go to http://localhost:9001 - - Current JWT to login: TOKEN - -Open your browser to the specified URL and enter the JWT Token into the login 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 diff --git a/source/includes/k8s/steps-configure-minio-kes-hashicorp.rst b/source/includes/k8s/steps-configure-minio-kes-hashicorp.rst index 4f812cc5..e1f94c98 100644 --- a/source/includes/k8s/steps-configure-minio-kes-hashicorp.rst +++ b/source/includes/k8s/steps-configure-minio-kes-hashicorp.rst @@ -4,24 +4,10 @@ Deploy MinIO Tenant with Server-Side Encryption 1) Access the Operator Console ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward traffic between the local host machine and the MinIO 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 `. -.. code-block:: shell - :class: copyable - - kubectl minio proxy - -The command returns output similar to the following: - -.. code-block:: shell - - Starting port forward of the Console UI. - - To connect open a browser and go to http://localhost:9001 - - Current JWT to login: TOKEN - -Open your browser to the specified URL and enter the JWT Token into the login 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 @@ -64,4 +50,4 @@ Once you have completed the configuration, you can finish any remaining sections .. include:: /includes/k8s/common-minio-kes.rst :start-after: start-kes-enable-sse-kms-desc - :end-before: end-kes-enable-sse-kms-desc \ No newline at end of file + :end-before: end-kes-enable-sse-kms-desc diff --git a/source/includes/k8s/steps-configure-openid-external-identity-management.rst b/source/includes/k8s/steps-configure-openid-external-identity-management.rst index be1152df..3ddb379d 100644 --- a/source/includes/k8s/steps-configure-openid-external-identity-management.rst +++ b/source/includes/k8s/steps-configure-openid-external-identity-management.rst @@ -4,24 +4,10 @@ Deploy MinIO Tenant with OpenID Connect Identity Management 1) Access the Operator Console ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward traffic between the local host machine and the MinIO 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 `. -.. code-block:: shell - :class: copyable - - kubectl minio proxy - -The command returns output similar to the following: - -.. code-block:: shell - - Starting port forward of the Console UI. - - To connect open a browser and go to http://localhost:9001 - - Current JWT to login: TOKEN - -Open your browser to the specified URL and enter the JWT Token into the login 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 diff --git a/source/includes/k8s/steps-deploy-tenant-cli.rst b/source/includes/k8s/steps-deploy-tenant-cli.rst deleted file mode 100644 index 1d5f60a5..00000000 --- a/source/includes/k8s/steps-deploy-tenant-cli.rst +++ /dev/null @@ -1,286 +0,0 @@ -.. _minio-k8s-deploy-minio-tenant-commandline: - -Deploy a MinIO Tenant using the Command Line --------------------------------------------- - -The :mc:`kubectl minio tenant create` command supports creating a MinIO Tenant in your Kubernetes cluster. -The command *requires* that the cluster have a functional MinIO Operator installation. - -To deploy a tenant from the command line, complete the following steps: - -:ref:`create-tenant-cli-determine-settings-required-options` - -:ref:`create-tenant-cli-determine-additional-options` - -:ref:`create-tenant-cli-enter-command` - -:ref:`create-tenant-cli-record-access-info` - -:ref:`create-tenant-cli-access-tenant-console` - -.. _create-tenant-cli-determine-settings-required-options: - -1) Determine Values for Required Settings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The :mc:`kubectl minio tenant create` command requires several configuration settings. -Determine the values for all required settings. - -.. tab-set:: - - .. tab-item:: Required Settings - - The command requires values for each of the items in this table. - - .. list-table:: - :header-rows: 1 - :widths: 25 75 - :width: 100% - - * - Setting - - Description - - * - :mc:`~kubectl minio tenant create TENANT_NAME` - - The name to use for the new tenant. - - * - :mc:`~kubectl minio tenant create --capacity` - - The total raw storage size for the Tenant across all volumes. - Specify both the total storage size *and* the :guilabel:`Unit` of that storage. - All storage units are in SI values, e.g. :math:`Gi = GiB = 1024^3` bytes. - - For example, 16 Ti for 16 Tebibytes. - - * - :mc:`~kubectl minio tenant create --servers` - - The total number of MinIO server pods to deploy in the Tenant. - - The Operator by default uses pod anti-affinity, such that the Kubernetes cluster *must* have at least one worker node per MinIO server pod. - - * - :mc:`~kubectl minio tenant create --volumes` - - The total number of storage volumes (Persistent Volume Claims). - The Operator generates an equal number of PVC *plus one* for supporting logging. - - The total number of persistent volume claims (``PVC``) per server is determined by dividing the number of volumes by the number of servers. - The storage available for each ``PVC`` is determined by dividing the capacity by the number of volumes. - - The generated claims have pod selectors so that claims are only made for volumes attached to node running the pod. - - If the number of volumes exceeds the numnber of persistent volumes available on the cluster, ``MinIO`` hangs until the number of persistent volumes are available. - - * - :mc:`~kubectl minio tenant create --namespace` - - Each MinIO tenant requires its own ``namespace``. - - Specify a namespace with the :mc:`~kubectl minio tenant create --namespace` flag. - If not specified, the MinIO Operator to uses ``minio``. - - The namespace must already exist in the Kubernetes cluster. - Run ``kubectl create ns `` to add one. - - * - :mc:`~kubectl minio tenant create --storage-class` - - Specify the storage class to use. - - New MinIO tenants use the ``default`` storage class. - To specify a different storage class, add the :mc:`~kubectl minio tenant create --storage-class` flag. - - The specified :mc-cmd:`~kubectl minio tenant create --storage-class` *must* match the ``storage-class`` of the Persistent Volumes (``PVs``) to which the ``PVCs`` should bind. - - MinIO strongly recommends creating a Storage Class that corresponds to locally-attached volumes on the host machines on which the Tenant deploys. - This ensures each pod can use locally-attached storage for maximum performance and throughput. - - .. tab-item:: Example - - For example, the following command creates a new tenant with the following settings: - - Name - ``miniotenant`` - - Capacity - 16 Tebibytes - - Servers - 4 - - Volumes - 16 - - Namespace - ``minio`` - - Storage Class - ``warm`` - - .. code-block:: shell - :class: copyable - - kubectl minio tenant create miniotenant \ - --capacity 16Ti \ - --servers 4 \ - --volumes 16 \ - --namespace minio \ - --storage-class warm - - -.. _create-tenant-cli-determine-additional-options: - -2) Determine Values for Optional Settings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -You can further customize your tenant by including any or all of the following *optional* flags when running the :mc:`kubectl minio tenant create` command: - -.. list-table:: - :header-rows: 1 - :widths: 25 75 - :width: 100% - - * - Setting - - Description - - * - :mc:`~kubectl minio tenant create --image` - - Customize the ``minio`` image to use. - - By default, the Operator uses the release image available at the time of the Operator's release. - To specify a different MinIO version for the tenant, such as the latest available, use the :mc:`~kubectl minio tenant create --image` flag. - - See the `MinIO Quay `__ or the `MinIO DockerHub `__ repositories for a list of valid tags. - - * - :mc:`~kubectl minio tenant create --image-pull-secret` - - If using a custom container registry, specify the secret to use when pulling the ``minio`` image. - - Use :mc:`~kubectl minio tenant create --image-pull-secret` to specify the secret. - - * - :mc:`~kubectl minio tenant create --kes-config` - - Configure a :minio-git:`Key Encrption Service (KES) ` - - Use the :mc:`~kubectl minio tenant create --kes-config` flag to specify the name of the secret to use for KES Key Management Service (KMS) setup. - - Enabling Server Side Encryption (SSE) also deploys a MinIO :minio-git:`KES ` service in the Tenant to faciliate SSE operations. - - For more, see the `Github documentation `__. - -.. note:: Generate a YAML File for Further Customizations - - The MinIO Operator installs a `Custom Resource Definition (CRD) `__ to describe tenants. - Advanced users can generate a YAML file from the command line and customize the tenant based on the CRD. - - Do a dry run of a tenant creation process to generate a YAML file using the :mc:`~kubectl minio tenant create --output` flag. - - When using this flag, the operator does **not** create the tenant. - Modify the generated YAML file as desired, then use ``kubectl apply -f `` to manually create the MinIO tenant using the file. - -.. _create-tenant-cli-enter-command: - -3) Run the Command with Required and Optional Settings -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -At the command line, enter the full command with all *Required* and any *Optional* flags. - -Consider a tenant we want to create: - -Tenant Name - ``minio1`` - -Capacity - 16 Tebibytes - -Servers - 4 - -Volumes - 16 (four per node) - -Namespace - ``miniotenantspace`` - -MinIO Image - Latest version, |minio-latest| - -Key ecnryption file - ``minio-secret`` - -Storage class - ``warm`` - -.. code-block:: shell - :substitutions: - - kubectl minio tenant create \ - minio1 \ - --capacity 16Ti \ - --servers 4 \ - --volumes 16 \ - --namespace miniotenantspace \ - --image |minio-latest| \ - --kes-config minio-kes-secret \ - --storage-class warm - -.. _create-tenant-cli-record-access-info: - -4) Record the Access Credentials -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -When generating the tenant, the MinIO Operator displays the access credentials to use for the tenant. - -.. important:: - - This is the only time the credentials display. - Copy the credentials to a secure location. - MinIO does not show these credentials again. - -In addition to access credentials, the output shows the service name and service ports to use for accessing the tenant. - -.. _create-tenant-cli-access-tenant-console: - -5) Access the Tenant's MinIO Console -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -The MinIO Operator creates services for the MinIO Tenant. - -.. cond:: openshift - - Use the ``oc get svc -n TENANT-PROJECT`` command to review the deployed services: - - .. code-block:: shell - :class: copyable - - oc get svc -n minio-tenant-1 - -.. cond:: k8s and not openshift - - Use the ``kubectl get svc -n NAMESPACE`` command to review the deployed services: - - .. code-block:: shell - :class: copyable - - kubectl get svc -n minio-tenant-1 - -.. code-block:: shell - - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - minio LoadBalancer 10.97.114.60 443:30979/TCP 2d3h - minio-tenant-1-console LoadBalancer 10.106.103.247 9443:32095/TCP 2d3h - minio-tenant-1-hl ClusterIP None 9000/TCP 2d3h - minio-tenant-1-log-hl-svc ClusterIP None 5432/TCP 2d3h - minio-tenant-1-log-search-api ClusterIP 10.103.5.235 8080/TCP 2d3h - minio-tenant-1-prometheus-hl-svc ClusterIP None 9090/TCP 7h39m - -- The ``minio`` service corresponds to the MinIO Tenant service. - Applications should use this service for performing operations against the MinIO Tenant. - -- The ``*-console`` service corresponds to the :minio-git:`MinIO Console `. - Administrators should use this service for accessing the MinIO Console and performing administrative operations on the MinIO Tenant. - -The remaining services support Tenant operations and are not intended for consumption by users or administrators. - -By default each service is visible only within the Kubernetes cluster. -Applications deployed inside the cluster can access the services using the ``CLUSTER-IP``. - -Applications external to the Kubernetes cluster can access the services using the ``EXTERNAL-IP``. -This value is only populated for Kubernetes clusters configured for Ingress or a similar network access service. -Kubernetes provides multiple options for configuring external access to services. - -.. cond:: k8s and not openshift - - See the Kubernetes documentation on :kube-docs:`Publishing Services (ServiceTypes) ` and :kube-docs:`Ingress ` for more complete information on configuring external access to services. - -.. cond:: openshift - - See the OpenShift documentation on :openshift-docs:`Route or Ingress ` for more complete information on configuring external access to services. \ No newline at end of file diff --git a/source/includes/openshift/deploy-minio-on-openshift.rst b/source/includes/openshift/deploy-minio-on-openshift.rst index 4d4d05a9..9af77bab 100644 --- a/source/includes/openshift/deploy-minio-on-openshift.rst +++ b/source/includes/openshift/deploy-minio-on-openshift.rst @@ -53,13 +53,6 @@ OpenShift ``oc`` CLI :openshift-docs:`Download and Install ` the OpenShift :abbr:`CLI (command-line interface)` ``oc`` for use in this procedure. -MinIO ``kubectl`` Plugin -~~~~~~~~~~~~~~~~~~~~~~~~ - -The MinIO Kubernetes Plugin provides a command line interface for the MinIO Operator. -This procedure uses the ``oc minio`` plugin as part of the installation. - -.. include:: /includes/openshift/install-minio-kubectl-plugin.rst Procedure --------- diff --git a/source/includes/openshift/install-minio-kubectl-plugin.rst b/source/includes/openshift/install-minio-kubectl-plugin.rst deleted file mode 100644 index 3cf63f14..00000000 --- a/source/includes/openshift/install-minio-kubectl-plugin.rst +++ /dev/null @@ -1,53 +0,0 @@ -You can install the MinIO Kubernetes plugin by downloading and installing the plugin binary to your local host: - -.. tab-set:: - - .. tab-item:: Linux, MacOS - - You can download the MinIO ``kubectl`` plugin to your local system path. - The ``oc`` CLI automatically discovers and runs compatible plugins. - - The following code downloads the latest stable version |operator-version-stable| of the MinIO Kubernetes plugin and installs it to the system path: - - .. code-block:: shell - :substitutions: - :class: copyable - - curl https://github.com/minio/operator/releases/download/v|operator-version-stable|/kubectl-minio_|operator-version-stable|_linux_amd64 -o kubectl-minio - chmod +x kubectl-minio - mv kubectl-minio /usr/local/bin/ - - The ``mv`` command above may require ``sudo`` escalation depending on the permissions of the authenticated user. - - Run the following command to verify installation of the plugin: - - .. code-block:: shell - :class: copyable - - oc minio version - - The output should display the Operator version as |operator-version-stable|. - - .. tab-item:: Windows - - You can download the MinIO ``kubectl`` plugin to your local system path. - The ``oc`` CLI automatically discovers and runs compatible plugins. - - The following PowerShell command downloads the latest stable version |operator-version-stable| of the MinIO Kubernetes plugin and installs it to the system path: - - .. code-block:: powershell - :substitutions: - :class: copyable - - Invoke-WebRequest -Uri "https://github.com/minio/operator/releases/download/v|operator-version-stable|/kubectl-minio_|operator-version-stable|_windows_amd64.exe" -OutFile "C:\kubectl-plugins\kubectl-minio.exe" - - Ensure the path to the plugin folder is included in the Windows PATH. - - Run the following command to verify installation of the plugin: - - .. code-block:: shell - :class: copyable - - oc minio version - - The output should display the Operator version as |operator-version-stable|. \ No newline at end of file diff --git a/source/index.rst b/source/index.rst index 3e0c621b..e3d376e4 100644 --- a/source/index.rst +++ b/source/index.rst @@ -21,7 +21,7 @@ MinIO is built to deploy anywhere - public or private cloud, baremetal infrastru .. cond:: macos - This site documents Operations, Administration, and Development of MinIO deployments on Mac OSX platforms for the latest stable version of MinIO: |minio-tag|. + This site documents Operations, Administration, and Development of MinIO deployments on macOS platforms for the latest stable version of MinIO: |minio-tag|. .. cond:: container @@ -213,7 +213,6 @@ For more about connecting to ``play``, see :ref:`MinIO Console play Login S3 API Compatibility Integrations - /reference/kubectl-minio-plugin /reference/operator-crd /reference/operator-chart-values /reference/tenant-chart-values diff --git a/source/operations/checklists/security.rst b/source/operations/checklists/security.rst index 4296123f..d02adea1 100644 --- a/source/operations/checklists/security.rst +++ b/source/operations/checklists/security.rst @@ -40,7 +40,7 @@ Required Steps MinIO supports the following external KMS providers through Key Encryption Service (KES): -- :ref:`Hashicorp Vault Root KMS ` +- :ref:`HashiCorp Vault Root KMS ` - :ref:`AWS Root KMS ` - :ref:`Google Cloud Platform Secret Manager Root KMS ` - :ref:`Azure Key Vault Root KMS ` diff --git a/source/operations/deploy-manage-tenants.rst b/source/operations/deploy-manage-tenants.rst index 41261181..3aabb78f 100644 --- a/source/operations/deploy-manage-tenants.rst +++ b/source/operations/deploy-manage-tenants.rst @@ -10,9 +10,10 @@ Deploy and Manage MinIO Tenants :local: :depth: 1 -The MinIO Kubernetes Operator supports deploying and managing MinIO Tenants onto your Kubernetes cluster through either the Operator Console web interface or the MinIO Kubernetes Plugin. +The MinIO Kubernetes Operator supports deploying and managing MinIO Tenants onto your Kubernetes cluster through the Operator Console web interface. -The following tutorials provide steps for tenant management via the Operator Console and MinIO Kubernetes Plugin: + +The following tutorials provide steps for tenant management via the Operator Console and Kustomize: .. list-table:: :stub-columns: 1 diff --git a/source/operations/external-iam/configure-ad-ldap-external-identity-management.rst b/source/operations/external-iam/configure-ad-ldap-external-identity-management.rst index 361a7371..636f8d92 100644 --- a/source/operations/external-iam/configure-ad-ldap-external-identity-management.rst +++ b/source/operations/external-iam/configure-ad-ldap-external-identity-management.rst @@ -39,8 +39,8 @@ Prerequisites .. cond:: k8s - MinIO Kubernetes Operator and Plugin - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + MinIO Kubernetes Operator + ~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/k8s/common-operator.rst :start-after: start-requires-operator-plugin diff --git a/source/operations/external-iam/configure-keycloak-identity-management.rst b/source/operations/external-iam/configure-keycloak-identity-management.rst index 76359bf7..cde64d15 100644 --- a/source/operations/external-iam/configure-keycloak-identity-management.rst +++ b/source/operations/external-iam/configure-keycloak-identity-management.rst @@ -52,8 +52,8 @@ Prerequisites .. cond:: k8s - MinIO Kubernetes Operator and Plugin - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + MinIO Kubernetes Operator + ~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/k8s/common-operator.rst :start-after: start-requires-operator-plugin diff --git a/source/operations/external-iam/configure-openid-external-identity-management.rst b/source/operations/external-iam/configure-openid-external-identity-management.rst index 254c7960..9b1dc52e 100644 --- a/source/operations/external-iam/configure-openid-external-identity-management.rst +++ b/source/operations/external-iam/configure-openid-external-identity-management.rst @@ -36,8 +36,8 @@ Prerequisites .. cond:: k8s - MinIO Kubernetes Operator and Plugin - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + MinIO Kubernetes Operator + ~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/k8s/common-operator.rst :start-after: start-requires-operator-plugin diff --git a/source/operations/install-deploy-manage/delete-minio-tenant.rst b/source/operations/install-deploy-manage/delete-minio-tenant.rst index d700270d..74be7c23 100644 --- a/source/operations/install-deploy-manage/delete-minio-tenant.rst +++ b/source/operations/install-deploy-manage/delete-minio-tenant.rst @@ -13,20 +13,17 @@ Delete a MinIO Tenant Prerequisites ------------- -MinIO Kubernetes Operator and Plugin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +MinIO Kubernetes Operator +~~~~~~~~~~~~~~~~~~~~~~~~~ This procedures on this page *requires* a valid installation of the MinIO Kubernetes Operator and assumes the local host has a matching installation of the MinIO Kubernetes Operator. -This procedure assumes the latest stable Operator and Plugin version |operator-version-stable|. +This procedure assumes the latest stable Operator, version |operator-version-stable|. See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator. -.. include:: /includes/k8s/install-minio-kubectl-plugin.rst -Procedure (CLI) ---------------- - -Use the :mc-cmd:`kubectl minio tenant delete` command to delete a MinIO Tenant and its associated resources. +Tenant Persistent Volume Claims +------------------------------- The delete behavior of each Persistent Volume Claims (``PVC``) generated by the Tenant depends on the :kube-docs:`Reclaim Policy ` of its bound Persistent Volume (``PV``): @@ -40,13 +37,13 @@ The delete behavior of each Persistent Volume Claims (``PVC``) generated by the Perform all due diligence in ensuring the safety of stored data *prior* to deleting the Tenant. -.. code-block:: shell - :class: copyable - - kubectl minio tenant delete TENANT_NAME \ - --namespace TENANT_NAMESPACE +Procedure (Operator Console) +---------------------------- + +#. From the Operator Console view, select the Tenant to open the summary view, then select :guilabel:`Pools`. + Select :guilabel:`Delete`. -- Replace ``TENANT_NAME`` with the name of the Tenant. -- Replace ``TENANT_NAMESPACE`` with the namespace of the Tenant. +#. Enter the Tenant name in the confirmation dialog to confirm you want to delete this Tenant. + To delete the Tenant's associated volumes, toggle :guilabel:`Delete Volumes` to :guilabel:`ON`. -The command includes a confirmation prompt that requires explicit approval of the delete operation. +#. Select :guilabel:`Delete`. diff --git a/source/operations/install-deploy-manage/deploy-minio-tenant.rst b/source/operations/install-deploy-manage/deploy-minio-tenant.rst index 699a9426..ad9e3bc9 100644 --- a/source/operations/install-deploy-manage/deploy-minio-tenant.rst +++ b/source/operations/install-deploy-manage/deploy-minio-tenant.rst @@ -27,7 +27,9 @@ Deploy a MinIO Tenant This procedure documents deploying a MinIO Tenant onto a stock Kubernetes cluster using the MinIO Operator Console. -.. image:: /images/k8s/operator-dashboard.png +.. screenshot temporarily removed + + .. image:: /images/k8s/operator-dashboard.png :align: center :width: 70% :class: no-scaled-link @@ -47,36 +49,27 @@ Installing the MinIO :ref:`Kubernetes Operator ` aut This documentation assumes familiarity with all referenced Kubernetes concepts, utilities, and procedures. While this documentation *may* provide guidance for configuring or deploying Kubernetes-related resources on a best-effort basis, it is not a replacement for the official :kube-docs:`Kubernetes Documentation <>`. -.. _deploy-minio-distributed-prereqs-storage: Prerequisites ------------- -MinIO Kubernetes Operator and Plugin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +MinIO Kubernetes Operator +~~~~~~~~~~~~~~~~~~~~~~~~~ The procedures on this page *requires* a valid installation of the MinIO Kubernetes Operator and assumes the local host has a matching installation of -the MinIO Kubernetes Operator. This procedure assumes the latest stable Operator -and Plugin version |operator-version-stable|. +the MinIO Kubernetes Operator. This procedure assumes the latest stable Operator, version |operator-version-stable|. See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator. -.. cond:: k8s and not openshift - - .. include:: /includes/k8s/install-minio-kubectl-plugin.rst - -.. cond:: openshift - - .. include:: /includes/openshift/install-minio-kubectl-plugin.rst - .. cond:: k8s and not (openshift or eks or gke or aks) - Kubernetes Version 1.19.0 + Kubernetes Version 1.21.0 ~~~~~~~~~~~~~~~~~~~~~~~~~ - Starting with v4.0.0, the MinIO Operator requires Kubernetes 1.19.0 and later. - The Kubernetes infrastructure *and* the ``kubectl`` CLI tool must have the same version of 1.19.0+. + MinIO Operator requires Kubernetes 1.21.0 or later. + The Kubernetes infrastructure *and* the ``kubectl`` CLI tool must be the same version. + Upgrade ``kubectl`` to the same version as the Kubernetes version used on the cluster. This procedure assumes the host machine has ``kubectl`` installed and configured with access to the target Kubernetes cluster. The host machine *must* have access to a web browser application. @@ -210,6 +203,7 @@ Persistent Volumes MinIO strongly recommends SSD-backed disk types for best performance. For more information on AKS disk types, see :azure-docs:`Azure disk types `. + Deploy a Tenant using the MinIO Operator Console ------------------------------------------------ @@ -231,10 +225,6 @@ To deploy a tenant from the MinIO Operator Console, complete the following steps :ref:`create-tenant-encryption-section` -:ref:`minio-tenant-audit-logging-settings` - -:ref:`minio-tenant-monitoring-settings` - :ref:`create-tenant-deploy-view-tenant` :ref:`create-tenant-connect-tenant` @@ -246,16 +236,18 @@ To deploy a tenant from the MinIO Operator Console, complete the following steps .. include:: /includes/common/common-k8s-connect-operator-console.rst -Open your browser to the specified URL and enter the JWT Token into the login page. -You should see the :guilabel:`Tenants` page: +Open your browser to the appropriate URL and enter the JWT Token into the login page. +You should see the :guilabel:`Tenants` page. -.. image:: /images/k8s/operator-dashboard.png +.. screenshot temporarily removed + + .. image:: /images/k8s/operator-dashboard.png :align: center :width: 70% :class: no-scaled-link :alt: MinIO Operator Console -Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant. +Select :guilabel:`+ Create Tenant` to start creating a MinIO Tenant. .. _create-tenant-complete-tenant-setup: @@ -331,7 +323,7 @@ Settings marked with an asterisk :guilabel:`*` are *required*: The Operator by default uses pod anti-affinity, such that the Kubernetes cluster *must* have at least one worker node per MinIO server pod. Use the :guilabel:`Pod Placement` pane to modify the pod scheduling settings for the Tenant. - * - :guilabel:`Number of Drives per Server` + * - :guilabel:`Drives per Server` - The number of storage volumes (Persistent Volume Claims) the Operator requests per Server. The Operator displays the :guilabel:`Total Volumes` under the :guilabel:`Resource Allocation` section. @@ -363,21 +355,27 @@ Settings marked with an asterisk :guilabel:`*` are *required*: The specified :guilabel:`Storage Class` *must* correspond to a set of Persistent Volumes sufficient in capacity to match each generated PVC. - * - :guilabel:`Memory per Node [Gi]` - - Specify the total amount of memory (RAM) to allocate per MinIO server pod. + * - :guilabel:`Erasure Code Parity` + - The Erasure Code Parity to set for the deployment. + + The Operator displays the selected parity and its effect on the deployment under the :guilabel:`Erasure Code Configuration` section. + Erasure Code parity defines the overall resiliency and availability of data on the cluster. + Higher parity values increase tolerance to drive or node failure at the cost of total storage. + See :ref:`minio-erasure-coding` for more complete documentation. + + * - :guilabel:`CPU Request` + - Specify the desired number of CPUs to allocate per MinIO server pod. + + * - :guilabel:`Memory Request [Gi]` + - Specify the desired amount of memory (RAM) to allocate per MinIO server pod. See :ref:`minio-hardware-checklist-memory` for guidance on setting this value. MinIO **requires** a minimum of 2GiB of memory per worker. The Kubernetes cluster *must* have worker nodes with sufficient free RAM to match the pod request. - * - :guilabel:`Erasure Code Parity` - - The Erasure Code Parity to set for the deployment. + * - :guilabel:`Specify Limit` + - Toggle to :guilabel:`ON` to specify maximum CPU and memory limits. - The Operator displays the selected parity and its effect on the deployment under the :guilabel:`Erasure Code Configuration` section. - Erasure Code parity defines the overall resiliency and availability of data on the cluster. - Higher parity values increase tolerance to drive or node failure at the cost of total storage. - See :ref:`minio-erasure-coding` for more complete documentation. - Select :guilabel:`Create` to create the Tenant using the current configuration. While all subsequent sections are *optional*, MinIO recommends reviewing them prior to deploying the Tenant. @@ -463,25 +461,15 @@ The :guilabel:`Images` section displays container image settings used by the Min * - Field - Description - * - :guilabel:`MinIO's Image` + * - :guilabel:`MinIO` - The container image to use for the MinIO Server. See the `MinIO Quay `__ or the `MinIO DockerHub `__ repositories for a list of valid tags. - * - :guilabel:`Log Search API's Image` - - The container image to use for MinIO Log Search API. - * - :guilabel:`KES Image` - The container image to use for MinIO :minio-git:`KES `. - * - | :guilabel:`Log Search Postgres Image` - | :guilabel:`Log Search Postgres Init Image` - - The container images to use for starting the PostgreSQL service supporting the Log Search API - - * - | :guilabel:`Prometheus Image` - | :guilabel:`Prometheus Sidecar Image` - | :guilabel:`Prometheus Init Image` - - - The container images to use for starting the Prometheus service supporting the Log Search API. + * - :guilabel:`Use a private container registry` + - If the tenant requires a private container registry, toggle to :guilabel:`ON`, then specify the location and credentials for the private registry. .. _create-tenant-pod-placement-section: @@ -513,6 +501,9 @@ The :guilabel:`Pod Placement` section displays pod scheduler settings for the Mi * - :guilabel:`Node Selector` - Directs the operator to set a Node Selector such that pods only deploy onto Kubernetes workers whose labels match the selector. + * - :guilabel:`Tolerations` + - Specify any required tolerations for this tenant's pods. + .. _create-tenant-identity-provider-section: 6) The :guilabel:`Identity Provider` Section @@ -555,10 +546,10 @@ The :guilabel:`Security` section displays TLS certificate settings for the MinIO * - Field - Description - * - :guilabel:`Enable TLS` + * - :guilabel:`TLS` - Enable or disable TLS for the MinIO Tenant. - * - :guilabel:`Enable AutoCert` + * - :guilabel:`AutoCert` - Directs the Operator to generate Certificate Signing Requests for submission to the Kubernetes TLS API. The MinIO Tenant uses the generated certificates for enabling and establishing TLS connections. @@ -615,13 +606,17 @@ Enabling SSE also creates :minio-git:`MinIO Key Encryption Service ` pods i - Description * - :guilabel:`Vault` - - Configure `Hashicorp Vault `__ as the external KMS for storing root encryption keys. + - Configure `HashiCorp Vault `__ as the external KMS for storing root encryption keys. See :ref:`minio-sse-vault` for guidance on the displayed fields. * - :guilabel:`AWS` - Configure `AWS Secrets Manager `__ as the external KMS for storing root encryption keys. See :ref:`minio-sse-aws` for guidance on the displayed fields. + * - :guilabel:`Gemalto` + - Configure `Gemalto (Thales Digital Identity and Security) `__ as the external KMS for storing root encryption keys. + See :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) ` for guidance on the displayed fields. + * - :guilabel:`GCP` - Configure `Google Cloud Platform Secret Manager `__ as the external KMS for storing root encryption keys. See :ref:`minio-sse-gcp` for guidance on the displayed fields. @@ -632,82 +627,10 @@ Enabling SSE also creates :minio-git:`MinIO Key Encryption Service ` pods i .. _minio-tenant-audit-logging-settings: -9) Audit Log Settings -~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/common/common-k8s-deprecation-audit-prometheus.rst - :start-after: start-deprecate-audit-logs - :end-before: end-deprecate-audit-logs - -.. versionchanged:: Console 0.23.1 and Operator 5.0.0 - - New tenants have Audit Logs :guilabel:`Disabled` by default. - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - :width: 100% - - * - Field - - Description - - * - Log Search Storage Class - - Select the storage class and requested capacity associated to the PVC generated to support audit logging. - - * - Storage Size - - Specify the size of storage to make available for audit logging. - - * - :guilabel:`SecurityContext for LogSearch` - - The MinIO Operator deploys a Log Search service (SQL Database and Log Search API) to support Audit Log search in the MinIO Tenant Console. - - You can modify the Security Context to run the associated pod commands using a different ``User``, ``Group``, ``FsGroup``, or ``FSGroupChangePolicy``. - You can also direct the pod to not run commands as the ``Root`` user. - - * - :guilabel:`SecurityContext for PostgreSQL` - - The MinIO Operator deploys a PostgreSQL database to support logging services. - - You can modify the Security Context to run the associated pod commands using a different ``User``, ``Group``, ``FsGroup``, or ``FSGroupChangePolicy``. - You can also direct the pod to not run commands as the ``Root`` user. - - You can also modify the storage class and requested capacity associated to the PVC generated to support the Prometheus service. - -.. _minio-tenant-monitoring-settings: - -10) Monitoring Settings -~~~~~~~~~~~~~~~~~~~~~~~ - -.. include:: /includes/common/common-k8s-deprecation-audit-prometheus.rst - :start-after: start-deprecate-prometheus - :end-before: end-deprecate-prometheus - -.. versionchanged:: Console 0.23.1 and Operator 5.0.0 - - New tenants have monitoring :guilabel:`Disabled` by default. - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - :width: 100% - - * - Field - - Description - - * - Storage Class - - Select the storage class and requested capacity associated to the PVC generated to support Prometheus. - - * - Storage Size - - Specify the size of storage to make available for Prometheus. - - * - :guilabel:`SecurityContext` - - The MinIO Operator assigns this Security Context for the Prometheus pod. - - You can modify the Security Context to run the associated pod commands using a different ``User``, ``Group``, ``FsGroup``, or ``FSGroupChangePolicy``. - You can also direct the pod to not run commands as the ``Root`` user. - .. _create-tenant-deploy-view-tenant: -11) Deploy and View the Tenant -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +9) Deploy and View the Tenant +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Select :guilabel:`Create` at any time to begin the deployment process. The MinIO Operator displays the root user credentials *once* as part of deploying the Tenant. @@ -717,9 +640,11 @@ You can monitor the Tenant creation process from the :guilabel:`Tenants` view. The :guilabel:`State` column updates throughout the deployment process. Tenant deployment can take several minutes to complete. -Once the :guilabel:`State` reads as :guilabel:`Initialized`, click the Tenant to view its details. +Once the :guilabel:`State` reads as :guilabel:`Initialized`, select the Tenant to view its details. + +.. screenshot temporarily removed -.. image:: /images/k8s/operator-tenant-view.png + .. image:: /images/k8s/operator-tenant-view.png :align: center :width: 70% :class: no-scaled-link @@ -734,7 +659,7 @@ Each tab provides additional details or configuration options for the MinIO Tena .. _create-tenant-connect-tenant: -12) Connect to the Tenant +10) Connect to the Tenant ~~~~~~~~~~~~~~~~~~~~~~~~~ The MinIO Operator creates services for the MinIO Tenant. @@ -794,12 +719,8 @@ Kubernetes provides multiple options for configuring external access to services .. include:: /includes/openshift/steps-deploy-minio-tenant.rst -.. cond:: k8s and not (openshift or eks) - - .. include:: /includes/k8s/steps-deploy-tenant-cli.rst - .. toctree:: :titlesonly: :hidden: - /operations/install-deploy-manage/deploy-minio-tenant-helm \ No newline at end of file + /operations/install-deploy-manage/deploy-minio-tenant-helm diff --git a/source/operations/install-deploy-manage/expand-minio-tenant.rst b/source/operations/install-deploy-manage/expand-minio-tenant.rst index 507463fc..48303d07 100644 --- a/source/operations/install-deploy-manage/expand-minio-tenant.rst +++ b/source/operations/install-deploy-manage/expand-minio-tenant.rst @@ -16,15 +16,14 @@ This procedure documents expanding the available storage capacity of an existing Prerequisites ------------- -MinIO Kubernetes Operator and Plugin -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ +MinIO Kubernetes Operator +~~~~~~~~~~~~~~~~~~~~~~~~~ This procedure on this page *requires* a valid installation of the MinIO Kubernetes Operator and assumes the local host has a matching installation of the MinIO Kubernetes Operator. -This procedure assumes the latest stable Operator and Plugin version, |operator-version-stable|. +This procedure assumes the latest stable Operator, version |operator-version-stable|. See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator. -.. include:: /includes/k8s/install-minio-kubectl-plugin.rst Available Worker Nodes ~~~~~~~~~~~~~~~~~~~~~~ @@ -56,85 +55,44 @@ Persistent Volumes MinIO strongly recommends using SSD-backed EBS volumes for best performance. For more information on EBS resources, see `EBS Volume Types `__. -Procedure (CLI) ---------------- +Procedure (Operator Console) +---------------------------- -1) Expand the MinIO Tenant -~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Use the :mc-cmd:`kubectl minio tenant expand` command to create the MinIO -Tenant. - -The following example expands a MinIO Tenant with a Pool consisting of -4 Nodes with 4 locally-attached drives of 1Ti each: +The MinIO Operator Console supports expanding a MinIO Tenant by adding additional pools. -.. code-block:: shell - :class: copyable - kubectl minio tenant expand minio-tenant-1 \ - --servers 4 \ - --volumes 16 \ - --capacity 16Ti \ - --storage-class local-storage \ - --namespace minio-tenant-1 - -The following table explains each argument specified to the command: - -.. list-table:: - :header-rows: 1 - :widths: 30 70 - :width: 100% - - * - Argument - - Description +1) Expand the MinIO Tenant +~~~~~~~~~~~~~~~~~~~~~~~~~~ - * - :mc-cmd:`minio-tenant-1 ` - - The name of the MinIO Tenant which the command expands with the new pool. +#. From the Operator Console view, select the Tenant to open the summary view, then select :guilabel:`Pools`. + Select :guilabel:`Expand Tenant`. - * - :mc-cmd:`~kubectl minio tenant expand --servers` - - The number of ``minio`` servers to deploy in the new Tenant Pool across - the Kubernetes cluster. +#. Specify the following information for the new pool: - * - :mc-cmd:`~kubectl minio tenant expand --volumes` - - The number of volumes in the new Tenant Pool. :mc:`kubectl minio` - determines the number of volumes per server by dividing ``volumes`` by - ``servers``. + .. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% - * - :mc-cmd:`~kubectl minio tenant expand --capacity` - - The total capacity of the Tenant Pool. :mc:`kubectl minio` determines the - capacity of each volume by dividing ``capacity`` by ``volumes``. + * - Field + - Description - * - :mc-cmd:`~kubectl minio tenant expand --storage-class` - - .. cond:: not eks + * - Number of Servers + - The number of servers to deploy in the new Tenant Pool across the Kubernetes cluster. - Specify the Kubernetes Storage Class the Operator uses when generating Persistent Volume Claims for the Tenant. - - Ensure the specified storage class has sufficient available Persistent Volume resources to match each generated Persistent Volume Claim. - - .. cond:: eks - - Specify the EBS volume type to use for this tenant. - The following list is populated based on the AWS EBS CSI driver list of supported :github:`EBS volume types `: + * - Volume Size + - The capacity of each volume in the new Tenant Pool. + + * - Volumes per Server + - The number of volumes for each server in the new Tenant Pool. - - ``gp3`` (General Purpose SSD) - - ``gp2`` (General Purpose SSD) - - ``io2`` (Provisioned IOPS SSD) - - ``io1`` (Provisioned IOPS SSD) - - ``st1`` (Throughput Optimized HDD) - - ``sc1`` (Cold Storage HDD) + * - Storage Class + - Specify the Kubernetes Storage Class the Operator uses when generating Persistent Volume Claims for the Tenant. + +#. Select :guilabel:`Create`. - * - :mc-cmd:`~kubectl minio tenant expand --namespace` - - The Kubernetes namespace of the existing MinIO Tenant to which to add - the new Tenant pool. 2) Validate the Expanded MinIO Tenant ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Use the :mc-cmd:`kubectl minio tenant info` command to return a summary of -the MinIO Tenant, including the new Pool: - -.. code-block:: shell - :class: copyable - - kubectl minio tenant info minio-tenant-1 \ - --namespace minio-tenant-1 +In the :guilabel:`Pools` tab, select the new Pool to confirm its details. diff --git a/source/operations/install-deploy-manage/minio-operator-console.rst b/source/operations/install-deploy-manage/minio-operator-console.rst index 72b96b25..f6fd886f 100644 --- a/source/operations/install-deploy-manage/minio-operator-console.rst +++ b/source/operations/install-deploy-manage/minio-operator-console.rst @@ -15,7 +15,8 @@ managing MinIO Tenants on Kubernetes infrastructure. Installing the MinIO :ref:`Kubernetes Operator ` automatically installs and configures the Operator Console. -.. image:: /images/k8s/operator-dashboard.png +.. screenshot temporarily removed + .. image:: /images/k8s/operator-dashboard.png :align: center :width: 70% :class: no-scaled-link @@ -35,7 +36,8 @@ Tenant Management The MinIO Operator Console supports deploying, managing, and monitoring MinIO Tenants on the Kubernetes cluster. -.. image:: /images/k8s/operator-dashboard.png +.. screenshot temporarily removed + .. image:: /images/k8s/operator-dashboard.png :align: center :width: 70% :class: no-scaled-link @@ -46,7 +48,6 @@ You can :ref:`deploy a MinIO Tenant ` through the The Operator Console automatically detects MinIO Tenants deployed on the cluster when provisioned through: - Operator Console -- :ref:`MinIO Kubernetes Plugin ` - Helm - Kustomize @@ -68,7 +69,8 @@ Tenant Registration |subnet| users relying on the commercial license should register the MinIO tenants to their SUBNET account, which can be done through the Operator Console. -.. image:: /images/k8s/operator-console-register.png +.. screenshot temporarily removed + .. image:: /images/k8s/operator-console-register.png :align: center :width: 70% :class: no-scaled-link @@ -112,4 +114,4 @@ To review which license you are using and the features available through differe MinIO supports two licenses: `AGPLv3 Open Source `__ or a `MinIO Commercial License `__. Subscribers to |SUBNET| use MinIO under a commercial license. -You can also :guilabel:`Subscribe` from the License screen. \ No newline at end of file +You can also :guilabel:`Subscribe` from the License screen. diff --git a/source/operations/install-deploy-manage/modify-minio-tenant.rst b/source/operations/install-deploy-manage/modify-minio-tenant.rst index efbb7652..138bcc4d 100644 --- a/source/operations/install-deploy-manage/modify-minio-tenant.rst +++ b/source/operations/install-deploy-manage/modify-minio-tenant.rst @@ -12,7 +12,8 @@ Modify a MinIO Tenant The procedures on this page use the :ref:`MinIO Operator Console ` for modifying an existing tenant. -.. image:: /images/k8s/operator-manage-tenant.png +.. screenshot temporarily removed + .. image:: /images/k8s/operator-manage-tenant.png :align: center :width: 70% :class: no-scaled-link diff --git a/source/operations/install-deploy-manage/multi-site-replication.rst b/source/operations/install-deploy-manage/multi-site-replication.rst index d30c03d9..d26fae49 100644 --- a/source/operations/install-deploy-manage/multi-site-replication.rst +++ b/source/operations/install-deploy-manage/multi-site-replication.rst @@ -234,14 +234,16 @@ Configure Site Replication #. Select **Settings**, then **Site Replication** - .. image:: /images/minio-console/console-settings-site-replication.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-settings-site-replication.png :width: 400px :alt: MinIO Console menu with the Settings heading expanded to show Site Replication :align: center #. Select :guilabel:`Add Sites +` - .. image:: /images/minio-console/console-settings-site-replication-add.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-settings-site-replication-add.png :width: 600px :alt: MinIO Console's Add Sites for Replication screen :align: center @@ -390,14 +392,16 @@ The new site must meet the following requirements: #. Select **Settings**, then **Site Replication** - .. image:: /images/minio-console/console-site-replication-list-of-sites.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-site-replication-list-of-sites.png :width: 600px :alt: MinIO Console Site Replication with three sites listed :align: center #. Select :guilabel:`Add Sites +` - .. image:: /images/minio-console/console-settings-site-replication-add.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-settings-site-replication-add.png :width: 600px :alt: MinIO Console's Add Sites for Replication screen :align: center @@ -481,7 +485,8 @@ If a peer site changes its hostname, you can modify the replication configuratio #. Select the pencil **Edit** icon to the side of the site to update - .. image:: /images/minio-console/console-site-replication-edit-button.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-site-replication-edit-button.png :width: 600px :alt: MinIO Console's List of Replicated Sites screen with the edit buttons highlighted :align: center @@ -494,7 +499,8 @@ If a peer site changes its hostname, you can modify the replication configuratio :start-after: start-mc-admin-replicate-load-balancing :end-before: end-mc-admin-replicate-load-balancing - .. image:: /images/minio-console/console-settings-site-replication-edit-endpoint.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-settings-site-replication-edit-endpoint.png :width: 600px :alt: Example of the MinIO Console's Edit Replication Endpoint screen :align: center @@ -544,14 +550,16 @@ You can re-add the site at a later date, but you must first completely wipe buck #. Select the trash can Delete icon to the side of the site to update - .. image:: /images/minio-console/console-site-replication-delete-button.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-site-replication-delete-button.png :width: 600px :alt: MinIO Console's List of Replicated Sites screen with the delete buttons highlighted :align: center #. Confirm the site deletion at the prompt by selecting **Delete** - .. image:: /images/minio-console/console-settings-site-replication-confirm-delete.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-settings-site-replication-confirm-delete.png :width: 600px :alt: Example of the MinIO Console's Edit Replication Endpoint screen :align: center @@ -595,7 +603,8 @@ The summary information includes the number of **Synced** and **Failed** items f #. Select :guilabel:`Replication Status` - .. image:: /images/minio-console/console-settings-site-replication-status-summary.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-settings-site-replication-status-summary.png :width: 600px :alt: MinIO Console's Replication status from all Sites screen :align: center @@ -606,7 +615,8 @@ The summary information includes the number of **Synced** and **Failed** items f Specify the name of the specific Bucket, Group, Policy, or User to view - .. image:: /images/minio-console/console-settings-site-replication-status-item.png + .. screenshot temporarily removed + .. image:: /images/minio-console/console-settings-site-replication-status-item.png :width: 600px :alt: Example of replication status for a particular bucket item :align: center diff --git a/source/operations/install-deploy-manage/upgrade-minio-operator-4.5.7-earlier.rst b/source/operations/install-deploy-manage/upgrade-minio-operator-4.5.7-earlier.rst new file mode 100644 index 00000000..0cf7eaea --- /dev/null +++ b/source/operations/install-deploy-manage/upgrade-minio-operator-4.5.7-earlier.rst @@ -0,0 +1,327 @@ +:orphan: + +.. _minio-k8s-upgrade-minio-operator-to-4.5.8: + +================================ +Upgrade MinIO Operator to v4.5.8 +================================ + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 1 + + +To upgrade from Operator to |operator-version-stable| from version 4.5.7 or earlier, you must first upgrade to version 4.5.8. +Depending on your current version, you may need to do one or more intermediate upgrades to reach v4.5.8. + +The following table lists the upgrade paths for older versions of MinIO Operator: + +.. list-table:: + :header-rows: 1 + :widths: 40 40 + :width: 100% + + * - Current Version + - Supported Upgrade Target + + * - 4.2.3 to 4.5.7 + - 4.5.8 + + * - 4.0.0 through 4.2.2 + - 4.2.3 + + * - 3.X.X + - 4.2.2 + + +Upgrade MinIO Operator 4.2.3 through 4.5.7 to 4.5.8 +--------------------------------------------------- + +Prerequisites +~~~~~~~~~~~~~ + +This procedure requires the following: + +- You have an existing MinIO Operator deployment running 4.2.3 through 4.5.7 +- Your Kubernetes cluster runs 1.19.0 or later +- Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster + +Procedure +~~~~~~~~~ + +This procedure upgrades MinIO Operator release 4.2.3 through 4.5.7 to release 4.5.8. +You can then upgrade from release 4.5.8 to |operator-version-stable|. + +1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. + + Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. + + Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. + + See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. + +#. Verify the existing Operator installation. + + Use ``kubectl get all -n minio-operator`` to verify the health and status of all Operator pods and services. + + If you installed the Operator to a custom namespace, specify that namespace as ``-n ``. + + You can verify the currently installed Operator version by retrieving the object specification for an operator pod in the namespace. + The following example uses the ``jq`` tool to filter the necessary information from ``kubectl``: + + .. code-block:: shell + :class: copyable + + kubectl get pod -l 'name=minio-operator' -n minio-operator -o json | jq '.items[0].spec.containers' + + The output resembles the following: + + .. code-block:: json + :emphasize-lines: 8-10 + + { + "env": [ + { + "name": "CLUSTER_DOMAIN", + "value": "cluster.local" + } + ], + "image": "minio/operator:v4.5.1", + "imagePullPolicy": "IfNotPresent", + "name": "minio-operator" + } + +#. Download the Latest Stable Version of the MinIO Kubernetes Plugin + + .. include:: /includes/k8s/install-minio-kubectl-plugin.rst + +#. Run the initialization command to upgrade the Operator + + Use the ``kubectl minio init`` command to upgrade the existing MinIO Operator installation + + .. code-block:: shell + :class: copyable + + kubectl minio init + +#. Validate the Operator upgrade + + You can check the Operator version by reviewing the object specification for an Operator Pod using a previous step. + + .. include:: /includes/common/common-k8s-connect-operator-console.rst + +.. _minio-k8s-upgrade-minio-operator-4.2.2-procedure: + +Upgrade MinIO Operator 4.0.0 through 4.2.2 to 4.2.3 +--------------------------------------------------- + +Prerequisites +~~~~~~~~~~~~~ + +This procedure assumes that: + +- You have an existing MinIO Operator deployment running any release from 4.0.0 through 4.2.2 +- Your Kubernetes cluster runs 1.19.0 or later +- Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster + +Procedure +~~~~~~~~~ + +This procedure covers the necessary steps to upgrade a MinIO Operator deployment running any release from 4.0.0 through 4.2.2 to 4.2.3. +You can then perform :ref:`minio-k8s-upgrade-minio-operator-procedure` to complete the upgrade to |operator-version-stable|. + +There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-version-stable|. + +1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. + + Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. + Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. + + See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. + +#. Check the Security Context for each Tenant Pool + + Use the following command to validate the specification for each managed MinIO Tenant: + + .. code-block:: shell + :class: copyable + + kubectl get tenants -n -o yaml + + If the ``spec.pools.securityContext`` field does not exist for a Tenant, the tenant pods likely run as root. + + As part of the 4.2.3 and later series, pods run with a limited permission set enforced as part of the Operator upgrade. + However, Tenants running pods as root may fail to start due to the security context mismatch. + You can set an explicit Security Context that allows pods to run as root for those Tenants: + + .. code-block:: yaml + :class: copyable + + securityContext: + runAsUser: 0 + runAsGroup: 0 + runAsNonRoot: false + fsGroup: 0 + + You can use the following command to edit the tenant and apply the changes: + + .. code-block:: shell + + kubectl edit tenants -n + # Modify the securityContext as needed + + See :kube-docs:`Pod Security Standards ` for more information on Kubernetes Security Contexts. + +#. Upgrade to Operator 4.2.3 + + Download the MinIO Kubernetes Plugin 4.2.3 and use it to upgrade the Operator. + Open https://github.com/minio/operator/releases/tag/v4.2.3 in a browser and download the binary that corresponds to your local host OS. + + For example, Linux hosts running an Intel or AMD processor can run the following commands: + + .. code-block:: shell + :class: copyable + + wget https://github.com/minio/operator/releases/download/v4.2.3/kubectl-minio_4.2.3_linux_amd64 -o kubectl-minio_4.2.3 + chmod +x kubectl-minio_4.2.3 + ./kubectl-minio_4.2.3 init + +#. Validate all Tenants and Operator pods + + Check the Operator and MinIO Tenant namespaces to ensure all pods and services started successfully. + + For example: + + .. code-block:: shell + :class: copyable + + kubectl get all -n minio-operator + kubectl get pods -l "v1.min.io/tenant" --all-namespaces + +#. Upgrade to |operator-version-stable| + + Follow the :ref:`minio-k8s-upgrade-minio-operator-procedure` procedure to upgrade to the latest stable Operator version. + +Upgrade MinIO Operator 3.0.0 through 3.0.29 to 4.2.2 +---------------------------------------------------- + +Prerequisites +~~~~~~~~~~~~~ + +This procedure assumes that: + +- You have an existing MinIO Operator deployment running 3.X.X +- Your Kubernetes cluster runs 1.19.0 or later +- Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster + +Procedure +~~~~~~~~~ + +This procedure covers the necessary steps to upgrade a MinIO Operator deployment running any release from 3.0.0 through 3.2.9 to 4.2.2. +You can then perform :ref:`minio-k8s-upgrade-minio-operator-4.2.2-procedure`, followed by :ref:`minio-k8s-upgrade-minio-operator-procedure`. + +There is no direct upgrade path from a 3.X.X series installation to |operator-version-stable|. + +1. (Optional) Update each MinIO Tenant to the latest stable MinIO Version. + + Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. + + Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. + + See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. + +#. Validate the Tenant ``tenant.spec.zones`` values + + Use the following command to validate the specification for each managed MinIO Tenant: + + .. code-block:: shell + :class: copyable + + kubectl get tenants -n -o yaml + + - Ensure each ``tenant.spec.zones`` element has a ``name`` field set to the name for that zone. + Each zone must have a unique name for that Tenant, such as ``zone-0`` and ``zone-1`` for the first and second zones respectively. + + - Ensure each ``tenant.spec.zones`` has an explicit ``securityContext`` describing the permission set with which pods run in the cluster. + + The following example tenant YAML fragment sets the specified fields: + + .. code-block:: yaml + + image: "minio/minio:$(LATEST-VERSION)" + ... + zones: + - servers: 4 + name: "zone-0" + volumesPerServer: 4 + volumeClaimTemplate: + metadata: + name: data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Ti + securityContext: + runAsUser: 0 + runAsGroup: 0 + runAsNonRoot: false + fsGroup: 0 + - servers: 4 + name: "zone-1" + volumesPerServer: 4 + volumeClaimTemplate: + metadata: + name: data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Ti + securityContext: + runAsUser: 0 + runAsGroup: 0 + runAsNonRoot: false + fsGroup: 0 + + You can use the following command to edit the tenant and apply the changes: + + .. code-block:: shell + + kubectl edit tenants -n + +#. Upgrade to Operator 4.2.2 + + Download the MinIO Kubernetes Plugin 4.2.2 and use it to upgrade the Operator. + Open https://github.com/minio/operator/releases/tag/v4.2.2 in a browser and download the binary that corresponds to your local host OS. + For example, Linux hosts running an Intel or AMD processor can run the following commands: + + .. code-block:: shell + :class: copyable + + wget https://github.com/minio/operator/releases/download/v4.2.3/kubectl-minio_4.2.2_linux_amd64 -o kubectl-minio_4.2.2 + chmod +x kubectl-minio_4.2.2 + + ./kubectl-minio_4.2.2 init + +#. Validate all Tenants and Operator pods + + Check the Operator and MinIO Tenant namespaces to ensure all pods and services started successfully. + + For example: + + .. code-block:: shell + :class: copyable + + kubectl get all -n minio-operator + + kubectl get pods -l "v1.min.io/tenant" --all-namespaces + +#. Upgrade to 4.2.3 + + Follow the :ref:`minio-k8s-upgrade-minio-operator-4.2.2-procedure` procedure to upgrade to Operator 4.2.3. + You can then upgrade to |operator-version-stable|. diff --git a/source/operations/install-deploy-manage/upgrade-minio-operator.rst b/source/operations/install-deploy-manage/upgrade-minio-operator.rst index 1cc101cf..9aea52a1 100644 --- a/source/operations/install-deploy-manage/upgrade-minio-operator.rst +++ b/source/operations/install-deploy-manage/upgrade-minio-operator.rst @@ -15,27 +15,8 @@ You can upgrade the MinIO Operator at any time without impacting your managed Mi As part of the upgrade process, the Operator may update and restart Tenants to support changes to the MinIO Custom Resource Definition (CRD). These changes require no action on the part of any operator or administrator, and do not impact Tenant operations. -The following table lists the upgrade paths from previous versions of the MinIO Operator: - -.. list-table:: - :header-rows: 1 - :widths: 40 40 - :width: 100% - - * - Current Version - - Supported Upgrade Target - - * - 4.5.8 or later - - |operator-version-stable| - - * - 4.2.3 to 4.5.7 - - 4.5.8 - - * - 4.0.0 through 4.2.2 - - 4.2.3 - - * - 3.X.X - - 4.2.2 +This page describes how to upgrade from Operator 4.5.8 or later to |operator-version-stable|. +To upgrade from Operator 4.5.7 or earlier, see :ref:`Upgrade MinIO Operator to v4.5.8 `. .. _minio-k8s-upgrade-minio-operator-procedure: @@ -48,7 +29,7 @@ Upgrade MinIO Operator 4.5.8 and Later to |operator-version-stable| This procedure requires the following: - You have an existing MinIO Operator deployment running 4.5.8 or later - - Your Kubernetes cluster runs 1.19.0 or later + - Your Kubernetes cluster runs 1.21.0 or later - Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster This procedure upgrades the MinIO Operator from any 4.5.8 or later release to |operator-version-stable|. @@ -62,7 +43,7 @@ The following changes apply for Operator v5.0.0 or later: - The ``.spec.credsSecret`` field is replaced by the ``.spec.configuration`` field. The ``.spec.credsSecret`` should hold all the environment variables for the MinIO deployment that contain sensitive information and should not show in ``.spec.env``. - This change impacts the Tenant :abbr:`CRD ` and only impacts users editing a tenant YAML directly, such as through Helm or Kustomize. + This change impacts the Tenant :abbr:`CRD (CustomResourceDefinition)` and only impacts users editing a tenant YAML directly, such as through Helm or Kustomize. - Both the **Log Search API** (``.spec.log``) and **Prometheus** (``.spec.prometheus``) deployments have been removed. However, existing deployments are left running as standalone deployments / statefulsets with no connection to the Tenant CR. Deleting the Tenant :abbr:`CRD (Custom Resource Definition)` does **not** cascade to the log or Prometheus deployments. @@ -77,7 +58,7 @@ Log Search and Prometheus The latest releases of Operator remove Log Search and Prometheus from included Operator tools. The following steps back up the existing yaml files, perform some clean up, and provide steps to continue using either or both of these functions. -1. Back up Prometheus and Log Search yaml files. +#. Back up Prometheus and Log Search yaml files. .. code-block:: shell :class: copyable @@ -98,9 +79,9 @@ The following steps back up the existing yaml files, perform some clean up, and Repeat for each tenant. -2. Remove ``.metadata.ownerReferences`` for all backed up files for all tenants. +#. Remove ``.metadata.ownerReferences`` for all backed up files for all tenants. -3. *(Optional)* To continue using Log Search API and Prometheus, add the following variables to the tenant's yaml specification file under ``.spec.env`` +#. *(Optional)* To continue using Log Search API and Prometheus, add the following variables to the tenant's yaml specification file under ``.spec.env`` Use the following command to edit a tenant: @@ -136,21 +117,22 @@ Upgrade Operator to |operator-version-stable| .. tab-set:: - .. tab-item:: Upgrade using MinIO Kubernetes Plugin + .. tab-item:: Upgrade using Kustomize - The following procedure upgrades the MinIO Operator using the :mc:`kubectl minio ` plugin. + The following procedure upgrades the MinIO Operator using Kustomize. + For Operator versions 4.5.8 to 5.0.14 installed with the MinIO Kubernetes Plugin, follow the Kustomize instructions to upgrade to 5.0.15 or later. If you installed the Operator using :ref:`Helm `, use the :guilabel:`Upgrade using Helm` instructions instead. - 1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. - + #. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. + Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. - 2. Verify the existing Operator installation. + #. Verify the existing Operator installation. Use ``kubectl get all -n minio-operator`` to verify the health and status of all Operator pods and services. - + If you installed the Operator to a custom namespace, specify that namespace as ``-n ``. You can verify the currently installed Operator version by retrieving the object specification for an operator pod in the namespace. @@ -160,9 +142,9 @@ Upgrade Operator to |operator-version-stable| :class: copyable kubectl get pod -l 'name=minio-operator' -n minio-operator -o json | jq '.items[0].spec.containers' - + The output resembles the following: - + .. code-block:: json :emphasize-lines: 8-10 :substitutions: @@ -179,41 +161,74 @@ Upgrade Operator to |operator-version-stable| "name": "minio-operator" } - 3. Download the latest stable version of the MinIO Kubernetes Plugin + If your local host does not have the ``jq`` utility installed, you can run the first part of the command and locate the ``spec.containers`` section of the output. + + #. Upgrade Operator with Kustomize + + The following command upgrades Operator to version |operator-version-stable|: + + .. code-block:: shell + :class: copyable + + kubectl apply -k github.com/minio/operator + + In the sample output below, ``configured`` indicates where a new change was applied from the updated CRD: + + .. code-block:: shell + + namespace/minio-operator configured + customresourcedefinition.apiextensions.k8s.io/miniojobs.job.min.io configured + customresourcedefinition.apiextensions.k8s.io/policybindings.sts.min.io configured + customresourcedefinition.apiextensions.k8s.io/tenants.minio.min.io configured + serviceaccount/console-sa unchanged + serviceaccount/minio-operator unchanged + clusterrole.rbac.authorization.k8s.io/console-sa-role unchanged + clusterrole.rbac.authorization.k8s.io/minio-operator-role unchanged + clusterrolebinding.rbac.authorization.k8s.io/console-sa-binding unchanged + clusterrolebinding.rbac.authorization.k8s.io/minio-operator-binding unchanged + configmap/console-env unchanged + secret/console-sa-secret configured + service/console unchanged + service/operator unchanged + service/sts unchanged + deployment.apps/console configured + deployment.apps/minio-operator configured - .. include:: /includes/k8s/install-minio-kubectl-plugin.rst - 4. Run the initialization command to upgrade the Operator + #. Validate the Operator upgrade - Use the :mc-cmd:`kubectl minio init` command to upgrade the existing MinIO Operator installation: + You can check the new Operator version with the same ``kubectl`` command used previously: .. code-block:: shell :class: copyable - kubectl minio init + kubectl get pod -l 'name=minio-operator' -n minio-operator -o json | jq '.items[0].spec.containers' + + #. *(Optional)* Connect to the Operator Console + + .. include:: /includes/common/common-k8s-connect-operator-console-no-plugin.rst - 5. Validate the Operator upgrade + #. Retrieve the Operator Console JWT for login - You can check the Operator version by reviewing the object specification for an Operator Pod using a previous step. + .. include:: /includes/common/common-k8s-operator-console-jwt.rst - .. include:: /includes/common/common-k8s-connect-operator-console.rst .. tab-item:: Upgrade using Helm The following procedure upgrades an existing MinIO Operator Installation using Helm. - If you installed the Operator using :ref:`the MinIO Kubernetes Plugin `, use the :guilabel:`Upgrade using MinIO Kubernetes Plugin` instructions instead. + If you installed the Operator using Kustomize, use the :guilabel:`Upgrade using Kustomize` instructions instead. + + #. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. - 1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. - Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. - #. Verify the existing Operator installation. + #. Verify the existing Operator installation. Use ``kubectl get all -n minio-operator`` to verify the health and status of all Operator pods and services. - + If you installed the Operator to a custom namespace, specify that namespace as ``-n ``. Use the ``helm list`` command to view the installed charts in the namespace: @@ -234,7 +249,7 @@ Upgrade Operator to |operator-version-stable| #. Update the Operator Repository Use ``helm repo update minio-operator`` to update the MinIO Operator repo. - If you set a different alias for the MinIO Operator repository, specify that to the command. + If you set a different alias for the MinIO Operator repository, specify that in the command instead of ``minio-operator``. You can use ``helm repo list`` to review your installed repositories. Use ``helm search`` to check the latest available chart version after updating the Operator Repo: @@ -250,7 +265,7 @@ Upgrade Operator to |operator-version-stable| :class: copyable :substitutions: - NAME CHART VERSION APP VERSION DESCRIPTION + NAME CHART VERSION APP VERSION DESCRIPTION minio-operator/minio-operator 4.3.7 v4.3.7 A Helm chart for MinIO Operator minio-operator/operator |operator-version-stable| v|operator-version-stable| A Helm chart for MinIO Operator minio-operator/tenant |operator-version-stable| v|operator-version-stable| A Helm chart for MinIO Operator @@ -267,7 +282,7 @@ Upgrade Operator to |operator-version-stable| helm upgrade -n minio-operator \ operator minio-operator/operator - If you installed the MinIO Operator to a different namespace, specify that to the ``-n`` argument. + If you installed the MinIO Operator to a different namespace, specify that in the ``-n`` argument. If you used a different installation name from ``operator``, replace the value above with the installation name. @@ -275,297 +290,8 @@ Upgrade Operator to |operator-version-stable| #. Validate the Operator upgrade - You can check the Operator version by reviewing the object specification for an Operator Pod using a previous step. - - .. include:: /includes/common/common-k8s-connect-operator-console.rst - - -Upgrade MinIO Operator 4.2.3 through 4.5.7 to 4.5.8 ---------------------------------------------------- - -Prerequisites -~~~~~~~~~~~~~ - -This procedure requires the following: - -- You have an existing MinIO Operator deployment running 4.2.3 through 4.5.7 -- Your Kubernetes cluster runs 1.19.0 or later -- Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster - -Procedure -~~~~~~~~~ - -This procedure upgrades MinIO Operator release 4.2.3 through 4.5.7 to release 4.5.8. -You can then upgrade from release 4.5.8 to |operator-version-stable|. - -1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. - - Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. - - Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. - - See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. - -#. Verify the existing Operator installation. - - Use ``kubectl get all -n minio-operator`` to verify the health and status of all Operator pods and services. - - If you installed the Operator to a custom namespace, specify that namespace as ``-n ``. - - You can verify the currently installed Operator version by retrieving the object specification for an operator pod in the namespace. - The following example uses the ``jq`` tool to filter the necessary information from ``kubectl``: - - .. code-block:: shell - :class: copyable - - kubectl get pod -l 'name=minio-operator' -n minio-operator -o json | jq '.items[0].spec.containers' - - The output resembles the following: - - .. code-block:: json - :emphasize-lines: 8-10 - - { - "env": [ - { - "name": "CLUSTER_DOMAIN", - "value": "cluster.local" - } - ], - "image": "minio/operator:v4.5.1", - "imagePullPolicy": "IfNotPresent", - "name": "minio-operator" - } - -#. Download the Latest Stable Version of the MinIO Kubernetes Plugin - - .. include:: /includes/k8s/install-minio-kubectl-plugin.rst - -#. Run the initialization command to upgrade the Operator - - Use the :mc-cmd:`kubectl minio init` command to upgrade the existing MinIO Operator installation - - .. code-block:: shell - :class: copyable - - kubectl minio init - -#. Validate the Operator upgrade - - You can check the Operator version by reviewing the object specification for an Operator Pod using a previous step. - - .. include:: /includes/common/common-k8s-connect-operator-console.rst - -.. _minio-k8s-upgrade-minio-operator-4.2.2-procedure: - -Upgrade MinIO Operator 4.0.0 through 4.2.2 to 4.2.3 ---------------------------------------------------- - -Prerequisites -~~~~~~~~~~~~~ - -This procedure assumes that: - -- You have an existing MinIO Operator deployment running any release from 4.0.0 through 4.2.2 -- Your Kubernetes cluster runs 1.19.0 or later -- Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster - -Procedure -~~~~~~~~~ - -This procedure covers the necessary steps to upgrade a MinIO Operator deployment running any release from 4.0.0 through 4.2.2 to 4.2.3. -You can then perform :ref:`minio-k8s-upgrade-minio-operator-procedure` to complete the upgrade to |operator-version-stable|. - -There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-version-stable|. - -1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version. - - Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. - Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. - - See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. - -#. Check the Security Context for each Tenant Pool - - Use the following command to validate the specification for each managed MinIO Tenant: - - .. code-block:: shell - :class: copyable - - kubectl get tenants -n -o yaml - - If the ``spec.pools.securityContext`` field does not exist for a Tenant, the tenant pods likely run as root. - - As part of the 4.2.3 and later series, pods run with a limited permission set enforced as part of the Operator upgrade. - However, Tenants running pods as root may fail to start due to the security context mismatch. - You can set an explicit Security Context that allows pods to run as root for those Tenants: - - .. code-block:: yaml - :class: copyable - - securityContext: - runAsUser: 0 - runAsGroup: 0 - runAsNonRoot: false - fsGroup: 0 - - You can use the following command to edit the tenant and apply the changes: - - .. code-block:: shell - - kubectl edit tenants -n - # Modify the securityContext as needed - - See :kube-docs:`Pod Security Standards ` for more information on Kubernetes Security Contexts. - -#. Upgrade to Operator 4.2.3 - - Download the MinIO Kubernetes Plugin 4.2.3 and use it to upgrade the Operator. - Open https://github.com/minio/operator/releases/tag/v4.2.3 in a browser and download the binary that corresponds to your local host OS. - - For example, Linux hosts running an Intel or AMD processor can run the following commands: - - .. code-block:: shell - :class: copyable - - wget https://github.com/minio/operator/releases/download/v4.2.3/kubectl-minio_4.2.3_linux_amd64 -o kubectl-minio_4.2.3 - chmod +x kubectl-minio_4.2.3 - ./kubectl-minio_4.2.3 init - -#. Validate all Tenants and Operator pods - - Check the Operator and MinIO Tenant namespaces to ensure all pods and services started successfully. - - For example: - - .. code-block:: shell - :class: copyable - - kubectl get all -n minio-operator - kubectl get pods -l "v1.min.io/tenant" --all-namespaces - -#. Upgrade to |operator-version-stable| - - Follow the :ref:`minio-k8s-upgrade-minio-operator-procedure` procedure to upgrade to the latest stable Operator version. - -Upgrade MinIO Operator 3.0.0 through 3.0.29 to 4.2.2 ----------------------------------------------------- - -Prerequisites -~~~~~~~~~~~~~ - -This procedure assumes that: - -- You have an existing MinIO Operator deployment running 3.X.X -- Your Kubernetes cluster runs 1.19.0 or later -- Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster - -Procedure -~~~~~~~~~ - -This procedure covers the necessary steps to upgrade a MinIO Operator deployment running any release from 3.0.0 through 3.2.9 to 4.2.2. -You can then perform :ref:`minio-k8s-upgrade-minio-operator-4.2.2-procedure`, followed by :ref:`minio-k8s-upgrade-minio-operator-procedure`. - -There is no direct upgrade path from a 3.X.X series installation to |operator-version-stable|. - -1. (Optional) Update each MinIO Tenant to the latest stable MinIO Version. - - Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements. - - Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants. - - See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants. - -#. Validate the Tenant ``tenant.spec.zones`` values - - Use the following command to validate the specification for each managed MinIO Tenant: - - .. code-block:: shell - :class: copyable - - kubectl get tenants -n -o yaml - - - Ensure each ``tenant.spec.zones`` element has a ``name`` field set to the name for that zone. - Each zone must have a unique name for that Tenant, such as ``zone-0`` and ``zone-1`` for the first and second zones respectively. - - - Ensure each ``tenant.spec.zones`` has an explicit ``securityContext`` describing the permission set with which pods run in the cluster. - - The following example tenant YAML fragment sets the specified fields: - - .. code-block:: yaml - - image: "minio/minio:$(LATEST-VERSION)" - ... - zones: - - servers: 4 - name: "zone-0" - volumesPerServer: 4 - volumeClaimTemplate: - metadata: - name: data - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Ti - securityContext: - runAsUser: 0 - runAsGroup: 0 - runAsNonRoot: false - fsGroup: 0 - - servers: 4 - name: "zone-1" - volumesPerServer: 4 - volumeClaimTemplate: - metadata: - name: data - spec: - accessModes: - - ReadWriteOnce - resources: - requests: - storage: 1Ti - securityContext: - runAsUser: 0 - runAsGroup: 0 - runAsNonRoot: false - fsGroup: 0 - - You can use the following command to edit the tenant and apply the changes: - - .. code-block:: shell - - kubectl edit tenants -n - -#. Upgrade to Operator 4.2.2 - - Download the MinIO Kubernetes Plugin 4.2.2 and use it to upgrade the Operator. - Open https://github.com/minio/operator/releases/tag/v4.2.2 in a browser and download the binary that corresponds to your local host OS. - For example, Linux hosts running an Intel or AMD processor can run the following commands: - - .. code-block:: shell - :class: copyable - - wget https://github.com/minio/operator/releases/download/v4.2.3/kubectl-minio_4.2.2_linux_amd64 -o kubectl-minio_4.2.2 - chmod +x kubectl-minio_4.2.2 - - ./kubectl-minio_4.2.2 init - -#. Validate all Tenants and Operator pods - - Check the Operator and MinIO Tenant namespaces to ensure all pods and services started successfully. - - For example: - - .. code-block:: shell - :class: copyable - - kubectl get all -n minio-operator - - kubectl get pods -l "v1.min.io/tenant" --all-namespaces + .. include:: /includes/common/common-k8s-connect-operator-console-no-plugin.rst -#. Upgrade to 4.2.3 + #. Retrieve the Operator Console JWT for login - Follow the :ref:`minio-k8s-upgrade-minio-operator-4.2.2-procedure` procedure to upgrade to Operator 4.2.3. - You can then upgrade to |operator-version-stable|. + .. include:: /includes/common/common-k8s-operator-console-jwt.rst diff --git a/source/operations/install-deploy-manage/upgrade-minio-tenant.rst b/source/operations/install-deploy-manage/upgrade-minio-tenant.rst index c0ecdda8..41696ea7 100644 --- a/source/operations/install-deploy-manage/upgrade-minio-tenant.rst +++ b/source/operations/install-deploy-manage/upgrade-minio-tenant.rst @@ -10,71 +10,127 @@ Upgrade a MinIO Tenant :local: :depth: 1 + +The following procedures upgrade a single MinIO Tenant, using either Kustomize or Helm. +MinIO recommends you test upgrades in a lower environment such as a Dev or QA Tenant, before upgrading production Tenants. + .. important:: For Tenants using a MinIO Image older than :minio-release:`RELEASE.2024-03-30T09-41-56Z` running with :ref:`AD/LDAP ` enabled, you **must** read through the release notes for :minio-release:`RELEASE.2024-04-18T19-09-19Z` before starting this procedure. You must take the extra steps documented in the linked release as part of the upgrade procedure. .. _minio-upgrade-tenant-plugin: +.. _minio-upgrade-tenant-kustomize: -Upgrade the Tenant using the MinIO Kubernetes Plugin ----------------------------------------------------- - -The following procedure upgrades the MinIO Operator using the :mc:`kubectl minio tenant upgrade` command. +Upgrade a Tenant using Kustomize +-------------------------------- +The following procedure upgrades a MinIO Tenant using Kustomize and the ``kubectl`` CLI. If you deployed the Tenant using :ref:`Helm `, use the :ref:`minio-upgrade-tenant-helm` procedure instead. -This procedure *requires* a valid installation of the MinIO Kubernetes Operator and assumes the local host has a matching installation of the MinIO Kubernetes Operator and plugin. -This procedure assumes the latest stable Operator version |operator-version-stable|. +To upgrade a Tenant with Kustomize: -.. include:: /includes/k8s/install-minio-kubectl-plugin.rst +If the tenant was deployed with Operator Console, there are additional steps to create a base configuration file before upgrading. -See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator. +If the tenant was deployed with Kustomize, the base configuration is your existing ``kustomization`` files from the original tenant deployment. -.. important:: +Choose a tab below depending on how the tenant was deployed: - If you are upgrading the MinIO Operator, there may be additional changes to the tenant specs required. - Refer to the :ref:`MinIO Operator Upgrade ` for specifics on any changes necessary to the tenant spec. - The required changes vary based on the Operator version you are upgrading from and to. - - If required changes are not made to the tenant before upgrading the Operator, your tenant may not be accessible after the upgrade. +.. tab-set:: -1) Validate the Active MinIO Version -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + .. tab-item:: Operator Console-Deployed Tenant + :selected: -Use the :mc-cmd:`kubectl minio tenant info` command to return a summary of the MinIO Tenant, including the new Pool: + 1. Create the base configuration file: -.. code-block:: shell - :class: copyable + a. In a convenient directory, save the current Tenant configuration to a file using ``kubectl get``: + + .. code-block:: shell + :class: copyable + + kubectl get tenant/my-tenant -n my-tenant-ns -o yaml > my-tenant-base.yaml + + Replace ``my-tenant`` and ``my-tenant-ns`` with the name and namespace of the Tenant to upgrade. + + Edit the file to remove the following lines: + + - ``creationTimestamp:`` + - ``resourceVersion:`` + - ``uid:`` + - ``selfLink:`` (if present) + + For example, remove the highlighted lines: + + .. code-block:: shell + :emphasize-lines: 2, 6, 7 + + metadata: + creationTimestamp: "2024-05-29T21:22:20Z" + generation: 1 + name: my-tenant + namespace: my-tenant-ns + resourceVersion: "4699" + uid: d5b8e468-3bed-4aa3-8ddb-dfe1ee0362da - kubectl minio tenant info TENANT_NAME \ - --namespace TENANT_NAMESPACE + b. In the same directory, create a ``kustomization.yaml`` file with contents resembling the following: -- Replace ``TENANT_NAME`` with the name of the Tenant. -- Replace ``TENANT_NAMESPACE`` with the namespace of the Tenant. + .. code-block:: shell + :class: copyable -The output includes the version of the MinIO Server used by all Pods in the Tenant. + apiVersion: kustomize.config.k8s.io/v1beta1 + kind: Kustomization -2) Upgrade the MinIO Tenant -~~~~~~~~~~~~~~~~~~~~~~~~~~~ + resources: + - my-tenant-base.yaml -Use the :mc-cmd:`kubectl minio tenant upgrade` command to upgrade the container image used by *all* MinIO Pods in the Tenant. -MinIO upgrades *all* ``minio`` server processes at once. -This may result in downtime until the upgrade process completes. + patches: + - path: upgrade-minio-tenant.yaml + + If you used a different filename for the ``kubectl get`` output in the previous step, replace ``my-tenant-base.yaml`` with the name of that file. + + .. tab-item:: Existing Kustomized-deployed Tenant + + 1. You can upgrade the tenant using the ``kustomization`` files from the original deployment as the base configuration. + If you no longer have these files, follow the instructions in the Operator Console-Deployed Tenant tab. + +2. Create a ``upgrade-minio-tenant.yaml`` file with contents resembling the following: .. code-block:: shell :class: copyable + :substitutions: + + apiVersion: minio.min.io/v2 + kind: Tenant + + metadata: + name: my-tenant + namespace: my-tenant-ns + + spec: + image: minio/minio:|minio-tag| + +This file instructs Kustomize to upgrade the tenant using the specified image. +The name of this file, ``upgrade-minio-tenant.yaml``, must match the ``patches.path`` filename specified in the ``kustomization.yaml`` file created in the previous step. + +Replace ``my-tenant`` and ``my-tenant-ns`` with the name and namespace of the Tenant to upgrade. +Specify the MinIO version to upgrade to in ``image:``. + +Alternatively, you can update the base configuration directly, according to your local procedures. +Refer to the :kube-docs:`Kustomize Documentation ` for more information. + +3. From the same directory as the above files, apply the updated configuration to the Tenant with ``kubectl apply``: + + .. code-block:: shell + :class: copyable + + kubectl apply -f ./ + + The output resembles the following: - kubectl minio tenant upgrade TENANT_NAME \ - --image minio:minio:RELEASE:YYYY-MM-DDTHH-MM-SSZ \ - --namespace TENANT_NAMESPACE + .. code-block:: shell -- Replace ``TENANT_NAME`` with the name of the Tenant. -- Replace ``RELEASE:YYYY-MM-DDTHH-MM-SSZ`` with the specific release to use. - Specify ``minio/minio`` to use the latest stable version of MinIO. -- Replace ``TENANT_NAMESPACE`` with the namespace of the Tenant. + tenant.minio.min.io/my-tenant configured -See MinIO's `DockerHub Repository `__ for a list of available release tags. .. _minio-upgrade-tenant-helm: @@ -83,7 +139,7 @@ Upgrade the Tenant using the MinIO Helm Chart This procedure upgrades an existing MinIO Tenant using Helm Charts. -If you deployed the Tenant using the :ref:`MinIO Kubernetes Plugin `, use the :ref:`minio-upgrade-tenant-plugin` procedure instead. +If you deployed the Tenant using Kustomize, use the :ref:`minio-upgrade-tenant-kustomize` procedure instead. 1. Verify the existing MinIO Tenant installation. diff --git a/source/operations/installation.rst b/source/operations/installation.rst index 4e5f5b6a..1f768d3a 100644 --- a/source/operations/installation.rst +++ b/source/operations/installation.rst @@ -24,4 +24,4 @@ .. cond:: k8s and not (openshift or eks or gke or aks) - .. include:: /includes/k8s/deploy-operator.rst \ No newline at end of file + .. include:: /includes/k8s/deploy-operator.rst diff --git a/source/operations/server-side-encryption.rst b/source/operations/server-side-encryption.rst index fcfa0d4e..0ac00aab 100644 --- a/source/operations/server-side-encryption.rst +++ b/source/operations/server-side-encryption.rst @@ -27,7 +27,7 @@ keys for use with MinIO SSE. MinIO supports the following |KMS| as the central key store: -- :ref:`Hashicorp KeyVault ` +- :ref:`HashiCorp KeyVault ` - :ref:`AWS SecretsManager ` - :ref:`Google Cloud SecretManager ` - :ref:`Azure Key Vault ` diff --git a/source/operations/server-side-encryption/configure-minio-kes.rst b/source/operations/server-side-encryption/configure-minio-kes.rst index e69dc67a..45cce14a 100644 --- a/source/operations/server-side-encryption/configure-minio-kes.rst +++ b/source/operations/server-side-encryption/configure-minio-kes.rst @@ -18,7 +18,7 @@ Server-Side Object Encryption with KES .. |KMS| replace:: :abbr:`KMS (Key Management System)` .. |KES-git| replace:: :minio-git:`Key Encryption Service (KES) ` .. |KES| replace:: :abbr:`KES (Key Encryption Service)` -.. |rootkms| replace:: `Hashicorp Vault `__ +.. |rootkms| replace:: `HashiCorp Vault `__ .. |rootkms-short| replace:: Vault .. meta:: @@ -103,8 +103,8 @@ Prerequisites .. cond:: k8s - MinIO Kubernetes Operator and Plugin - ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + MinIO Kubernetes Operator + ~~~~~~~~~~~~~~~~~~~~~~~~~ .. include:: /includes/k8s/common-operator.rst :start-after: start-requires-operator-plugin @@ -145,8 +145,8 @@ Refer to the configuration instruction in the :kes-docs:`KES documentation <>` f - :kes-docs:`Azure KeyVault ` - :kes-docs:`Entrust KeyControl ` - :kes-docs:`Fortanix SDKMS ` -- :kes-docs:`Google Cloud Secret Manager ` -- :kes-docs:`Hashicorp Vault ` +- :kes-docs:`Google Cloud Secret Manager ` +- :kes-docs:`HashiCorp Vault ` - :kes-docs:`Thales CipherTrust Manager (formerly Gemalto KeySecure) ` diff --git a/source/reference/kubectl-minio-plugin.rst b/source/reference/kubectl-minio-plugin.rst deleted file mode 100644 index c48bd128..00000000 --- a/source/reference/kubectl-minio-plugin.rst +++ /dev/null @@ -1,100 +0,0 @@ -:orphan: - -.. _minio-kubectl-plugin: - -======================= -MinIO Kubernetes Plugin -======================= - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -Overview --------- - -.. admonition:: Current Stable Version is |operator-version-stable| - :class: note - - This reference documentation reflects |operator-version-stable| of the - MinIO Kubernetes Operator and :mc:`kubectl minio` plugin. - -The :mc:`kubectl minio` plugin brings native support for deploying MinIO tenants to Kubernetes clusters using the ``kubectl`` CLI. -Use :mc:`kubectl minio` to deploy a MinIO tenant with little to no interaction with ``YAML`` configuration files. - -.. image:: /images/minio-k8s.svg - :align: center - :width: 90% - :class: no-scaled-link - :alt: Kubernetes Orchestration with the MinIO Operator facilitates automated deployment of MinIO clusters. - -Installing :mc:`kubectl minio` implies installing the -:minio-git:`MinIO Kubernetes Operator `. - -.. _minio-plugin-installation: - -.. mc:: kubectl minio - -Installation ------------- - -The MinIO Kubernetes Plugin requires Kubernetes 1.19.0 or later. - -The following code downloads the latest stable version |operator-version-stable| of the MinIO Kubernetes Plugin and installs it to the system ``$PATH``. - - -.. tab-set:: - - .. tab-item:: krew - - This procedure uses the Kubernetes krew plugin manager for installing the MinIO Kubernetes Operator and Plugin. - - See the ``krew`` `installation documentation `__ for specific instructions. - - .. code-block:: shell - :class: copyable - - kubectl krew update - kubectl krew install minio - - .. tab-item:: shell - - .. code-block:: shell - :substitutions: - :class: copyable - - wget https://github.com/minio/operator/releases/download/v|operator-version-stable|/kubectl-minio_|operator-version-stable|_linux_amd64 -O kubectl-minio - chmod +x kubectl-minio - mv kubectl-minio /usr/local/bin/ - -You can access the plugin using the :mc:`kubectl minio` command. Run -the following command to verify installation of the plugin: - -.. code-block:: shell - :class: copyable - - kubectl minio version - - -Subcommands ------------ - -:mc:`kubectl minio` has the following subcommands: - -- :mc:`~kubectl minio init` -- :mc:`~kubectl minio proxy` -- :mc:`~kubectl minio tenant` -- :mc:`~kubectl minio delete` -- :mc:`~kubectl minio version` - -.. toctree:: - :titlesonly: - :hidden: - - /reference/kubectl-minio-plugin/kubectl-minio-init - /reference/kubectl-minio-plugin/kubectl-minio-proxy - /reference/kubectl-minio-plugin/kubectl-minio-tenant - /reference/kubectl-minio-plugin/kubectl-minio-delete - /reference/kubectl-minio-plugin/kubectl-minio-version diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-delete.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-delete.rst deleted file mode 100644 index 749bdfad..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-delete.rst +++ /dev/null @@ -1,84 +0,0 @@ - -.. _kubectl-minio-delete: - -======================== -``kubectl minio delete`` -======================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio delete - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-delete-desc - -Deletes the MinIO Operator along with all associated resources, including all MinIO Tenant instances in the :mc-cmd:`watched namespace `. - -.. end-kubectl-minio-delete-desc - -.. warning:: - - If the underlying Persistent Volumes (``PV``) were created with a reclaim policy of ``recycle`` or ``delete``, deleting the MinIO Tenant results in complete loss of all objects stored on the tenant. - - Ensure you have performed all due diligence in confirming the safety of any data on each Operator-managed MinIO Tenant prior to deletion. - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following example deletes a the MinIO Operator in the ``minio-operator`` namesapce and all its tenants: - - .. code-block:: shell - :class: copyable - - kubectl minio delete --namespace minio-operator - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - - kubectl minio delete \ - --namespace \ - [--force --dangerous] - -Flags ------ - -The command supports the following flags: - -.. mc-cmd:: --namespace - :required: - - The namespace of the operator to delete. - - Defaults to ``minio-operator``. - -.. mc-cmd:: --dangerous - :optional: - - Safety flag to confirm deletion of the MinIO Operator and all tenants with :mc-cmd:`~kubectl minio delete --force`. - - This operation is irreversible. - -.. mc-cmd:: --force - :optional: - - Deletes the MinIO Operator and all tenants without confirmation. - Requires the :mc-cmd:`~kubectl minio delete --dangerous` flag. - - This operation is irreversible. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst index 29e91904..902dd070 100644 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst +++ b/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst @@ -1,3 +1,4 @@ +:orphan: .. _kubectl-minio-init: diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst deleted file mode 100644 index 28cef8d2..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst +++ /dev/null @@ -1,85 +0,0 @@ - -.. _kubectl-minio-proxy: - -======================= -``kubectl minio proxy`` -======================= - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio proxy - -Description ------------ - -.. start-kubectl-minio-proxy-desc - -:mc-cmd:`kubectl minio proxy` creates a temporary proxy to forward traffic from the local host machine to the MinIO Operator Console. -The :ref:`Operator Console ` provides a rich user interface for :ref:`deploying and managing MinIO Tenants `. - -This command is an alternative to configuring `Ingress `__ to grant access to the Operator Console pods. - -.. end-kubectl-minio-proxy-desc - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. cond:: openshift - - .. versionchanged:: Operator 5.0.0 - - The ``kubectl minio proxy`` command now supports retrieving the JWT for use with OpenShift deployments. - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following command creates proxy to use to access the operator graphical user interface for the ``myminio`` namespace: - - .. code-block:: shell - :class: copyable - - kubectl minio proxy --namespace myminio - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - :class: copyable - - kubectl minio init \ - [--namespace] - -Flags ------ - -.. - Default values update frequently and can be found in the following files: - https://github.com/minio/operator/blob/master/kubectl-minio/cmd/init.go - https://github.com/minio/operator/blob/master/kubectl-minio/cmd/helpers/constants.go - - For minio/console, run ``kubectl minio init -o | grep minio/console`` - -The command supports the following flags: - -.. mc-cmd:: --namespace - :optional: - - The namespace for which to access the operator. - - .. cond:: not openshift - - Defaults to ``minio-operator``. - - .. cond:: openshift - - Defaults to ``openshift-operators``. \ No newline at end of file diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst deleted file mode 100644 index 657380cf..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst +++ /dev/null @@ -1,327 +0,0 @@ - -.. _kubectl-minio-tenant-create: - -=============================== -``kubectl minio tenant create`` -=============================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant create - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-tenant-create-desc - -:mc-cmd:`kubectl minio tenant create` adds a new MinIO tenant and associated resources to a Kubernetes cluster. -The :ref:`Operator Console ` provides a rich user interface for :ref:`deploying and managing MinIO Tenants `. - -:mc-cmd:`~kubectl minio tenant create` always uses the latest stable version of the :github:`MinIO Server ` and :github:`MinIO Console `. - -.. end-kubectl-minio-tenant-create-desc - -On success, the command returns the following: - -- The administrative username and password for the Tenant. - - .. important:: - - Store these credentials in a secure location, such as a password protected key manager. - MinIO does *not* show these credentials again. - -- The Service created for connecting to the MinIO Console. - The Console supports administrative operations on the Tenant, such as configuring Identity and Access Management (IAM) and bucket configurations. - -- The Service created for connecting to the MinIO Tenant. - Applications should use this service for performing operations against the MinIO Tenant. - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following example creates a MinIO Tenant in the namespace ``minio-tenant-1`` consisting of 4 MinIO servers with 8 drives each and a total capacity of 32Ti. - - .. code-block:: shell - :class: copyable - - kubectl minio tenant create \ - minio-tenant-1 \ - --servers 4 \ - --volumes 8 \ - --capacity 32Ti \ - --namespace minio-tenant-1 \ - --storage-class local-storage - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - - kubectl minio tenant create \ - TENANT_NAME \ - --capacity \ - --servers \ - --volumes | --volumes-per-server \ - [--interactive] \ - [--disable-tls] \ - [--enable-audit-logs] \ - [--enable-prometheus] \ - [--expose-console-service] \ - [--expose-minio-service] \ - [--image] \ - [--image-pull-secret] \ - [--kes-config] \ - [--kes-image] \ - [--namespace] \ - [--output] \ - [--pool] \ - [--storage-class] - - .. include:: /includes/common-minio-mc.rst - :start-after: start-minio-syntax - :end-before: end-minio-syntax - - -Flags ------ - -The command supports the following flags: - -.. mc-cmd:: --interactive - :optional: - - Offers command line prompts to request the information required to set up a new tenant. - This command is mutually exclusive of the other flags when creating a new tenant. - - When added, prompts ask for input for the following values: - - - Tenant name - - Total servers - - Total volumes - - Namespace - - Capacity - - Disable TLS - - Disable audit logs - - Disable prometheus - -.. mc-cmd:: TENANT_NAME - :required: - - The name of the MinIO tenant which the command creates. - The name *must* be unique in the :mc-cmd:`~kubectl minio tenant create --namespace`. - -.. mc-cmd:: --capacity - :required: - - Total raw capacity of the MinIO tenant, such as 16Ti. - Include a string that is a number and a standard storage capacity unit. - - The total capacity of the MinIO tenant. :mc:`kubectl minio` divides the capacity by the number of :mc-cmd:`~kubectl minio tenant create --volumes` to determine the amount of ``resources.requests.storage`` to set for each Persistent Volume Claim (``PVC``). - - If no Persistent Volumes (``PV``) can satisfy the requested storage, :mc:`kubectl minio tenant create` hangs and waits until the required storage exists. - -.. mc-cmd:: --servers - :required: - - The number of ``minio`` servers to deploy on the Kubernetes cluster. - - Ensure that the specified number of :mc-cmd:`~kubectl minio tenant create --servers` does *not* exceed the number of nodes in the Kubernetes cluster. - -.. mc-cmd:: --volumes - :required: - - Mutually exclusive with :mc-cmd:`~kubectl minio tenant create --volumes-per-server`. - Use either :mc-cmd:`~kubectl minio tenant create --volumes` or :mc-cmd:`~kubectl minio tenant create --volumes-per-server`. - - The total number of volumes in the new MinIO Tenant Pool. - :mc-cmd:`kubectl minio tenant create` generates one :kube-docs:`Persistent Volume Claim (PVC) ` for each volume. - - The number of volumes affects both the requested storage of each ``PVC`` *and* the number of ``PVCs`` to associate to each MinIO Pod in the cluster: - - - The command :mc:`kubectl minio` divides the :mc-cmd:`~kubectl minio tenant create --capacity` by the number of volumes to determine the amount of ``resources.requests.storage`` to set for each ``PVC``. - - - :mc:`kubectl minio` determines the number of ``PVCs`` to associate to each ``minio`` server by dividing :mc-cmd:`~kubectl minio tenant create --volumes` by :mc-cmd:`~kubectl minio tenant create --servers`. - - The command generates each ``PVC`` with Pod-specific selectors, such that each Pod only uses ``PVs`` that are locally-attached to the node running that Pod. - - If the specified number of volumes exceeds the number of unbound ``PVs`` available on the cluster, :mc:`kubectl minio tenant create` hangs and waits until the required ``PVs`` exist. - -.. mc-cmd:: --volumes-per-server - :required: - - Mutually exclusive with :mc-cmd:`~kubectl minio tenant create --volumes`. - Use either :mc-cmd:`~kubectl minio tenant create --volumes-per-server` or :mc-cmd:`~kubectl minio tenant create --volumes`. - - Number of volumes to use for each server in the pool. - - Similar to :mc-cmd:`~kubectl minio tenant create --volumes`, but instead of specifying the total number of volumes for all MinIO servers, associate ``--volumes-per-server`` volumes to each server. - - If the combined total number of volumes exceeds the number of unbound ``PVs`` available on the cluster, :mc:`kubectl minio tenant create` hangs and waits until the required ``PVs`` exist. - -.. mc-cmd:: --disable-tls - :optional: - - Disables automatic TLS certificate provisioning on the Tenant. - -.. mc-cmd:: --enable-audit-logs - :optional: - - .. include:: /includes/common/common-k8s-deprecation-audit-prometheus.rst - :start-after: start-deprecate-audit-logs - :end-before: end-deprecate-audit-logs - - Defaults to ``true``. - - Deploys the MinIO Tenant with a PostgreSQL Pod which, combined with an additional auto-deployed service, enables Audit Logging in the Tenant Console. - - You can control the configuration of the PostgreSQL pod using the following optional parameters: - - .. list-table:: - :header-rows: 1 - :widths: 40 60 - :width: 80% - - * - Option - - Description - - * - ``--audit-logs-disk-space `` - - Specify the amount of storage to provision for the PostgreSQL pod. - The Operator provisions a PVC requesting the specified amount of storage in gigabytes. - - Defaults to ``5`` - - If no Persistent Volume can meet the PVC request, the pod fails to deploy. - - * - ``--audit-logs-pg-image`` - - Specify the Docker image to use for deploying the PostgreSQL pod. - - * - ``--audit-logs-storage-class`` - - Specify the storage class to assign to the generated PVC for the PostgreSQL Pod. - - Specify ``false`` to deploy the Tenant without the PostgreSQL and Audit Logging Console feature. - -.. mc-cmd:: --enable-prometheus - :optional: - - .. include:: /includes/common/common-k8s-deprecation-audit-prometheus.rst - :start-after: start-deprecate-prometheus - :end-before: end-deprecate-prometheus - - Defaults to ``true``. - - Deploys the MinIO Tenant with a Prometheus pod which enables the :ref:`MinIO Console Metrics ` view. - - You can control the configuration of the Prometheus pod using the following optional parameters: - - .. list-table:: - :header-rows: 1 - :widths: 40 60 - :width: 80% - - * - Option - - Description - - * - ``--prometheus-disk-space `` - - Specify the amount of storage to provision for the Prometheus pod. - The Operator provisions a PVC requesting the specified amount of storage in gigabytes. - - Defaults to ``5``. - - * - ``--prometheus-image`` - - Specify the Docker image to use for deploying the Prometheus pod. - - * - ``--prometheus-storage-class`` - - Specify the storage class to assign to the generated PVC for the Prometheus pod. - - -.. mc-cmd:: --expose-console-service - :optional: - - Directs the Operator to configure the MinIO Tenant Console service with the :kube-docs:`LoadBalancer ` networking type. - For Kubernetes clusters configured with a global load balancer, this option allows the Console to request an external IP address automatically. - -.. mc-cmd:: --expose-minio-service - :optional: - - Directs the Operator to configure the MinIO API service with the :kube-docs:`LoadBalancer ` networking type. - For Kubernetes clusters configured with a global load balancer, this option allows the Console to request an external IP address automatically. - -.. mc-cmd:: --image - :optional: - - MinIO image to use for the tenant. - Defaults to the latest minio release. - -.. mc-cmd:: --image-pull-secret - :optional: - - The image secret to use for pulling MinIO. - -.. mc-cmd:: --kes-config - :optional: - - The name of the Kubernetes Secret which contains the MinIO Key Encryption Service (KES) configuration. - Required for enabling Server Side Encryption of objects (SSE-S3). - - For more, see the `Github documentation `__. - -.. mc-cmd:: --kes-image - :optional: - - .. versionadded:: v5.0.11 - - The KES image to use when deploying KES pods in the tenant. - - .. important:: - - You cannot downgrade KES images after deployment. - -.. mc-cmd:: --namespace - :optional: - - The namespace in which to create the MinIO Tenant and its associated resources. - - MinIO supports exactly *one* MinIO Tenant per namespace. - Create a unique namespace for each MinIO Tenant deployed into the cluster. - - Defaults to ``minio``. - -.. mc-cmd:: --output - :optional: - - Dry run the command and generate the ``YAML``. - - :mc-cmd:`~kubectl minio tenant create --output` does **not** create the MinIO Tenant. - Use ``kubectl apply -f `` to manually create the MinIO tenant using the generated file. - -.. mc-cmd:: --pool - :optional: - - Assign a name for the pool added for the tenant. - -.. mc-cmd:: --storage-class - :optional: - - The type of storage to use for this tenant. - - The name of the Kubernetes :kube-docs:`Storage Class ` to use when creating Persistent Volume Claims (``PVC``) for the MinIO Tenant. - The specified :mc-cmd:`~kubectl minio tenant create --storage-class` *must* match the ``storage-class`` of the Persistent Volumes (``PVs``) to which the ``PVCs`` should bind. - - MinIO strongly recommends creating a Storage Class that corresponds to locally-attached volumes on the host machines on which the Tenant deploys. - This ensures each pod can use locally-attached storage for maximum performance and throughput. - See the :ref:`Deploy MinIO Tenant ` tutorial for guidance on creating Storage Classes for supporting the MinIO Tenant. - - Defaults to ``default``. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-delete.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-delete.rst deleted file mode 100644 index ec6318b7..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-delete.rst +++ /dev/null @@ -1,99 +0,0 @@ - -.. _kubectl-minio-tenant-delete: - -=============================== -``kubectl minio tenant delete`` -=============================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant delete - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-tenant-delete-desc - -Deletes the MinIO Tenant and its associated resources. - -The delete behavior of each Persistent Volume Claims (``PVC``) generated by the Tenant depends on the :kube-docs:`Reclaim Policy ` of its bound Persistent Volume (``PV``): - -- For ``recycle`` or ``delete`` policies, the command deletes the ``PVC``. - -- For ``retain``, the command retains the ``PVC``. - -Deletion of the underlying ``PV``, whether automatic or manual, results in the loss of any objects stored on the MinIO Tenant. -Perform all due diligence in ensuring the safety of stored data *prior* to deleting the tenant. - -.. end-kubectl-minio-tenant-delete-desc - - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following example deletes a MinIO Tenant in the namespace ``minio-tenant-1``. - It keeps the namespace intact after deleting the tenant. - - .. code-block:: shell - :class: copyable - - kubectl minio tenant delete \ - minio-tenant-1 \ - --namespace minio-tenant-1 \ - --retain-namespace - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - - kubectl minio tenant delete \ - TENANT_NAME \ - --force \ - --namespace \ - [--retain-namespace] \ - - -Flags ------ - -The command supports the following flags: - -.. mc-cmd:: TENANT_NAME - :required: - - The name of the MinIO tenant which the command deletes. - -.. mc-cmd:: --force - :optional: - - Forces the deletion of the tenant. - -.. mc-cmd:: --namespace - :required: - - The namespace scope to access. - -.. mc-cmd:: --retain-namespace - :optional: - - Keeps the namespace after deleting the tenant. - - Omit to delete the namespace after deleting the tenant. - - .. warning:: - - Deleting a namespace deletes all resources associated to that namespace. \ No newline at end of file diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-expand.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-expand.rst deleted file mode 100644 index dec7248b..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-expand.rst +++ /dev/null @@ -1,156 +0,0 @@ - -.. _kubectl-minio-tenant-expand: - -=============================== -``kubectl minio tenant expand`` -=============================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant expand - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-tenant-expand-desc - -Extends the total capacity of a MinIO Tenant by adding a new Pool. -A Pool consists of an independent set of pods running the MinIO Server and MinIO Console. -The new pool uses the same MinIO Server and Console Docker images as the existing Tenant pool(s). - -.. end-kubectl-minio-tenant-expand-desc - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following example expands a MinIO Tenant with a Pool consisting of 4 MinIO servers with 8 drives each and a total additional capacity of 32Ti: - - .. code-block:: shell - :class: copyable - - kubectl minio tenant expand \ - minio-tenant-1 \ - --servers 4 \ - --volumes 8 \ - --capacity 32Ti \ - --namespace minio-tenant-1 \ - --storage-class local-storage - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - - kubectl minio tenant expand \ - TENANT_NAME \ - --capacity \ - --namespace \ - --servers \ - --volumes | --volumes-per-server \ - [--output] \ - [--pool] \ - [--storage-class] - - .. include:: /includes/common-minio-mc.rst - :start-after: start-minio-syntax - :end-before: end-minio-syntax - -Flags ------ - -The command supports the following flags: - -.. mc-cmd:: TENANT_NAME - :required: - - The name of the MinIO tenant to expand. - -.. mc-cmd:: --capacity - :optional: - - The total capacity of the new MinIO Tenant Pool. :mc:`kubectl minio` divides the capacity by the number of :mc-cmd:`~kubectl minio tenant expand --volumes` to determine the - amount of ``resources.requests.storage`` to set for each Persistent Volume Claim (``PVC``). - - If the existing Persistent Volumes (``PV``) can satisfy the requested storage, :mc:`kubectl minio tenant expand` hangs and waits until the required storage exists. - -.. mc-cmd:: --servers - :required: - - The number of ``minio`` servers to deploy in the new MinIO Tenant Pool. - - Ensure that the specified number of :mc-cmd:`~kubectl minio tenant expand --servers` does *not* exceed the number of available nodes in the Kubernetes cluster. - -.. mc-cmd:: --volumes - :required: - - Mutually exclusive with :mc-cmd:`~kubectl minio tenant expand --volumes-per-server`. - Use either :mc-cmd:`~kubectl minio tenant expand --volumes` or :mc-cmd:`~kubectl minio tenant expand --volumes-per-server`. - - The number of volumes in the new MinIO Tenant Pool. - :mc:`kubectl minio` generates one Persistent Volume Claim (``PVC``) for each volume. - - The number of volumes affects both the requested storage of each ``PVC`` *and* the number of ``PVCs`` to associate to each MinIO Pod in the new Pool: - - - The command :mc:`kubectl minio` divides the :mc-cmd:`~kubectl minio tenant expand --capacity` by the number of volumes to determine the amount of ``resources.requests.storage`` to set for each ``PVC``. - - - :mc:`kubectl minio` determines the number of ``PVCs`` to associate to each ``minio`` server by dividing :mc-cmd:`~kubectl minio tenant expand --volumes` by :mc-cmd:`~kubectl minio tenant expand --servers`. - - The command generates each ``PVC`` with Pod-specific selectors, such that each Pod only uses ``PVs`` that are locally-attached to the node running that Pod. - - If the specified number of volumes exceeds the number of unbound ``PVs`` available in the cluster, :mc:`kubectl minio tenant expand` hangs and waits until the required ``PVs`` exist. - -.. mc-cmd:: --volumes-per-server - :required: - - Mutually exclusive with :mc-cmd:`~kubectl minio tenant expand --volumes`. - Use either :mc-cmd:`~kubectl minio tenant expand --volumes-per-server` or :mc-cmd:`~kubectl minio tenant expand --volumes`. - - Number of volumes to use for each server in the pool. - - Similar to :mc-cmd:`~kubectl minio tenant expand --volumes`, but instead of specifying the total number of volumes for all MinIO servers, associate ``--volumes-per-server`` volumes to each server. - - If the combined total number of volumes exceeds the number of unbound ``PVs`` available on the cluster, :mc:`kubectl minio tenant expand` hangs and waits until the required ``PVs`` exist. - -.. mc-cmd:: --namespace - :optional: - - The namespace in which to create the new MinIO Tenant Pool. - The namespace *must* match that of the MinIO Tenant being extended. - - Defaults to ``minio``. - -.. mc-cmd:: --output - :optional: - - Outputs the generated ``YAML`` objects to ``STDOUT`` for further customization. - - :mc-cmd:`~kubectl minio tenant expand --output` does **not** create the new MinIO Tenant Pool. - Use ``kubectl apply -f `` to manually create the MinIO tenant using the generated file. - -.. mc-cmd:: --pool - :optional: - - The name to assign to the pool created for this expansion. - -.. mc-cmd:: --storage-class - :optional: - - The name of the Kubernetes :kube-docs:`Storage Class ` to use when creating Persistent Volume Claims (``PVC``) for the new MinIO Tenant Pool. - The specified :mc-cmd:`~kubectl minio tenant expand --storage-class` *must* match the ``storage-class`` of the Persistent Volumes (``PVs``) to which the ``PVCs`` should bind. - - MinIO strongly recommends creating a Storage Class that corresponds to locally-attached volumes on the host machines on which the Tenant deploys. - This ensures each pod can use locally-attached storage for maximum performance and throughput. - See the :ref:`Deploy MinIO Tenant ` tutorial for guidance on creating Storage Classes for supporting the MinIO Tenant. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-info.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-info.rst deleted file mode 100644 index 75d53af1..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-info.rst +++ /dev/null @@ -1,105 +0,0 @@ - -.. _kubectl-minio-tenant-info: - -============================= -``kubectl minio tenant info`` -============================= - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant info - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-tenant-info-desc - -Displays information on a MinIO Tenant, including but not limited to: - -- The total capacity of the Tenant -- The version of MinIO server and MinIO Console running on the Tenant -- The configuration of each Pool in the Tenant. -- The root user credentials for the Tenant. - -.. end-kubectl-minio-tenant-info-desc - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following example retrieves the information of the MinIO Tenant ``minio-tenant-1`` in the namespace ``minio-namespace-1``. - - .. code-block:: shell - :class: copyable - - kubectl minio tenant info \ - minio-tenant-1 \ - --namespace minio-namespace-1 - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - - kubectl minio tenant info \ - TENANT_NAME \ - --namespace - - -Flags ------ - -The command supports the following flag: - -.. mc-cmd:: --namespace - :optional: - - The namespace in which to look for the MinIO Tenant. - - Defaults to ``minio``. - - -Example -------- - -Display Tenant Details -~~~~~~~~~~~~~~~~~~~~~~ - -The following command outputs information for the Tenant ``minio-tenant`` in the namespace ``minio-ns``: - -.. code-block:: shell - :class: copyable - - kubectl minio tenant info \ - minio-tenant \ - --namespace minio-ns - -The output resembles the following: - -.. code-block:: shell - - Tenant 'minio-tenant', Namespace 'minio-ns', Total capacity 16 GiB - - Current status: Initialized - MinIO version: minio/minio:RELEASE.2023-06-23T20-26-00Z - MinIO service: minio/ClusterIP (port 443) - Console service: minio-tenant-console/ClusterIP (port 9443) - - POOL SERVERS VOLUMES(SERVER) CAPACITY(VOLUME) - 0 4 1 4.0 GiB - - MinIO Root User Credentials: - MINIO_ROOT_USER="root_user" - MINIO_ROOT_PASSWORD="root_password" diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-list.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-list.rst deleted file mode 100644 index 6aca9a93..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-list.rst +++ /dev/null @@ -1,45 +0,0 @@ - -.. _kubectl-minio-tenant-list: - -============================= -``kubectl minio tenant list`` -============================= - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant list - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-tenant-list-desc - -Displays a list of all of the tenants managed by the MinIO Operator. - -.. end-kubectl-minio-tenant-list-desc - -The output includes information for each tenant similar to the following: - -- Tenant name -- Tenant's namespace -- Total capacity -- Current status -- MinIO version - -Syntax ------- - -The command has the following syntax: - -.. code-block:: shell - :class: copyable - - kubectl minio tenant list diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-report.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-report.rst deleted file mode 100644 index 26b2edf7..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-report.rst +++ /dev/null @@ -1,78 +0,0 @@ - -.. _kubectl-minio-tenant-report: - -=============================== -``kubectl minio tenant report`` -=============================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant report - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-tenant-report-desc - -Saves pod logs from the MinIO Tenant and its associated resources. - -.. end-kubectl-minio-tenant-report-desc - -The logs output to a zip archive file. - -When unzipped, the contents include three files for each pool: - -- JSON formatted file listing events -- JSON formatted file listing the status -- Human readable log file - -The folder also contains the yaml file for the tenant in ``TENANT_NAME.yaml`` - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following example creates a MinIO Tenant in the namespace ``minio-tenant-1`` consisting of 4 MinIO servers with 8 drives each and a total capacity of 32Ti. - - .. code-block:: shell - :class: copyable - - kubectl minio tenant report \ - TENANT1 \ - --namespace minio-namespace - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - - kubectl minio tenant report \ - TENANT_NAME \ - --namespace - -Flags ------ - -The command supports the following flags: - -.. mc-cmd:: TENANT_NAME - :required: - - The name of the MinIO tenant to expand. - -.. mc-cmd:: --namespace - :optional: - - The namespace in which to look for the MinIO Tenant. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-upgrade.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-upgrade.rst deleted file mode 100644 index f5a09772..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-upgrade.rst +++ /dev/null @@ -1,90 +0,0 @@ - -.. _kubectl-minio-tenant-upgrade: - -================================ -``kubectl minio tenant upgrade`` -================================ - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant upgrade - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-tenant-upgrade-desc - -Upgrades the ``minio`` server container image used by the MinIO Tenant. - -.. end-kubectl-minio-tenant-upgrade-desc - -.. important:: - - MinIO upgrades the image used by all pods in the Tenant at once. - Applications typically transparently retry operations against the MinIO Tenant, such that there should be no perceived downtime. - - Test all upgrades in a staging environment, such as a separate MinIO Tenant, before applying to production tenants. - -Syntax ------- - -.. tab-set:: - - .. tab-item:: EXAMPLE - - The following example expands a MinIO Tenant with a Pool consisting of 4 MinIO servers with 8 drives each and a total additional capacity of 32Ti: - - .. code-block:: shell - :class: copyable - :substitutions: - - kubectl minio tenant upgrade \ - minio-tenant-1 \ - --image quay.io/minio/minio:|minio-latest| - - .. tab-item:: SYNTAX - - The command has the following syntax: - - .. code-block:: shell - - kubectl minio tenant upgrade - TENANT_NAME \ - --image \ - --namespace \ - [--output] - -Flags ------ - -The command supports the following flags: - -.. mc-cmd:: TENANT_NAME - :required: - - The name of the MinIO tenant to upgrade. - -.. mc-cmd:: --image - :required: - - The container image to use for upgrading the MinIO Tenant. - -.. mc-cmd:: --namespace - :optional: - - The namespace in which to look for the MinIO Tenant. - - Defaults to ``minio``. - -.. mc-cmd:: --output - :optional: - - Displays the generated ``YAML`` objects, but does not upgrade the tenant. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant.rst deleted file mode 100644 index 2f922576..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant.rst +++ /dev/null @@ -1,52 +0,0 @@ - -.. _kubectl-minio-tenant: - -======================== -``kubectl minio tenant`` -======================== - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio tenant - -Description ------------ - -.. start-kubectl-minio-tenant-desc - -:mc-cmd:`kubectl minio tenant` creates and manages tenants for the MinIO Operator. - -.. end-kubectl-minio-tenant-desc - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -Subcommands ------------ - -The :mc-cmd:`kubectl minio tenant` command includes the following subcommands: - -- :mc-cmd:`~kubectl minio tenant create` -- :mc-cmd:`~kubectl minio tenant list` -- :mc-cmd:`~kubectl minio tenant info` -- :mc-cmd:`~kubectl minio tenant expand` -- :mc-cmd:`~kubectl minio tenant report` -- :mc-cmd:`~kubectl minio tenant upgrade` -- :mc-cmd:`~kubectl minio tenant delete` - -.. toctree:: - :titlesonly: - :hidden: - - /reference/kubectl-minio-plugin/kubectl-minio-tenant-create - /reference/kubectl-minio-plugin/kubectl-minio-tenant-delete - /reference/kubectl-minio-plugin/kubectl-minio-tenant-expand - /reference/kubectl-minio-plugin/kubectl-minio-tenant-info - /reference/kubectl-minio-plugin/kubectl-minio-tenant-list - /reference/kubectl-minio-plugin/kubectl-minio-tenant-report - /reference/kubectl-minio-plugin/kubectl-minio-tenant-upgrade \ No newline at end of file diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-version.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-version.rst deleted file mode 100644 index d3706d06..00000000 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-version.rst +++ /dev/null @@ -1,37 +0,0 @@ -.. _kubectl-minio-version: - -========================= -``kubectl minio version`` -========================= - -.. default-domain:: minio - -.. contents:: Table of Contents - :local: - :depth: 2 - -.. mc:: kubectl minio version - - -Description ------------ - -.. include:: /includes/facts-kubectl-plugin.rst - :start-after: start-kubectl-minio-requires-operator-desc - :end-before: end-kubectl-minio-requires-operator-desc - -.. start-kubectl-minio-version-desc - -Displays the version number for the currently installed ``kubectl minio`` plugin. - -.. end-kubectl-minio-version-desc - -Syntax ------- - -The command has the following syntax: - -.. code-block:: shell - :class: copyable - - kubectl minio version diff --git a/source/reference/minio-mc.rst b/source/reference/minio-mc.rst index 23d67e12..5229a60d 100644 --- a/source/reference/minio-mc.rst +++ b/source/reference/minio-mc.rst @@ -460,7 +460,7 @@ Configuration File certain kinds of information, such as the :mc-cmd:`aliases ` for each configured S3-compatible service. -For Linux and OSX, the default configuration file location is +For Linux and macOS, the default configuration file location is ``~/.mc/config.json``. For Windows, :mc-cmd:`mc` attempts to construct a default file path by trying @@ -482,7 +482,7 @@ Certificates The MinIO Client stores certificates and CAs for deployments to the following paths: -Linux, MacOS, and other Unix-like systems: +Linux, macOS, and other Unix-like systems: .. code-block:: shell diff --git a/source/reference/minio-server/minio-server.rst b/source/reference/minio-server/minio-server.rst index 6a42db67..c763d152 100644 --- a/source/reference/minio-server/minio-server.rst +++ b/source/reference/minio-server/minio-server.rst @@ -284,7 +284,7 @@ The command accepts the following arguments: Omit to use the default directory paths: - - Linux/OSX: ``${HOME}/.minio/certs`` + - Linux/macOS: ``${HOME}/.minio/certs`` - Windows: ``%%USERPROFILE%%\.minio\certs``. See :ref:`minio-TLS` for more information on TLS/SSL connectivity.