diff --git a/.gitignore b/.gitignore index 20a27003..ad644488 100644 --- a/.gitignore +++ b/.gitignore @@ -11,4 +11,4 @@ objects.inv output.log .DS_Store source/conf.py -package-lock.json \ No newline at end of file +package-lock.json diff --git a/Makefile b/Makefile index 768266f6..5d101cab 100644 --- a/Makefile +++ b/Makefile @@ -57,6 +57,7 @@ macos: k8s: @cp source/default-conf.py source/conf.py + @make sync-operator-version @make sync-minio-version @make sync-kes-version @$(SPHINXBUILD) -M html "$(SOURCEDIR)" "$(BUILDDIR)/$(GITDIR)/$@" $(SPHINXOPTS) $(O) -t $@ @@ -67,9 +68,7 @@ sync-operator-version: $(shell wget -O /tmp/downloads-operator.json https://api.github.com/repos/minio/operator/releases/latest) $(eval OPERATOR = $(shell cat /tmp/downloads-operator.json | jq '.tag_name[1:]')) - @echo "Replacing variables" - - @cp source/default-conf.py source/conf.py + @echo "Updating Operator to ${OPERATOR}" @case "${kname}" in \ "Darwin") \ @@ -102,8 +101,6 @@ sync-minio-version: @$(eval RPM = $(shell cat /tmp/downloads-minio.json | jq '.Linux."MinIO Server".amd64.RPM.download')) @$(eval MINIO = $(shell curl --retry 10 -Ls -o /dev/null -w "%{url_effective}" https://github.com/minio/minio/releases/latest | sed "s/https:\/\/github.com\/minio\/minio\/releases\/tag\///")) - @cp source/default-conf.py source/conf.py - @$(eval kname = $(shell uname -s)) @case "${kname}" in \ @@ -119,6 +116,13 @@ sync-minio-version: ;; \ esac + @if [ "$(shell git diff --name-only | grep 'conf.py')" == "" ]; then \ + echo "MinIO Server Version already latest"; \ + else \ + echo "New MinIO Server Version available ${MINIO}" ; \ + #git add source/conf.py && git commit -m "Updating MinIO server to ${MINIO}"; \ + fi + sync-java-docs: @echo "Retrieving Java docs from github.com/minio/minio-java" @$(eval LATEST = $(shell wget -q https://api.github.com/repos/minio/minio-java/releases/latest -O - | jq -r '.tag_name')) diff --git a/README.md b/README.md index 397905ce..fd0fbb89 100644 --- a/README.md +++ b/README.md @@ -31,9 +31,16 @@ static HTML pages using ReSTructured Text (rST). 3. Run `pip install -r requirements.txt` to setup the Python environment. -4. Run `make stage` +4. Run `make` to see the available build targets: + + - `make linux` + - `make macos` + - `make windows` + - `make k8s` -5. Open your browser to http://localhost:8000 to view the staged output. +5. Use `python -m http.server --directory build/GIT_BRANCH//html` + + Open your browser to http://localhost:8000 to view the staged output. ### MacOS @@ -49,12 +56,23 @@ static HTML pages using ReSTructured Text (rST). 5. Run `npm run build` -6. Run `make stage` +6. Run `make` to see the available build targets: + + - `make linux` + - `make macos` + - `make windows` + - `make k8s` -7. Open your browser to http://localhost:8000 to view the staged output. +7. Use `python -m http.server --directory build/GIT_BRANCH//html` + + Open your browser to http://localhost:8000 to view the staged output. ### Windows +Note: The MinIO Docs builder is designed around the Makefile. +Windows users may have issues in build output. +Consider running Sphinx in a virtual machine or Windows Subsystem for Linux. + Prereq: - Checkout the MinIO docs repository using your preferred `git` method @@ -84,12 +102,22 @@ All instructions use PowerShell running as an administrator. `npm run build` 8. Build the docs - `sphinx-build -M html source\ build\master -n` + `sphinx-build -M html source\ build\GITBRANCH\TAG\ -n -t TAG` + + Replace `TAG` with one of the following supported values: + + - `k8s` + - `linux` + - `macos` + - `windows` + 9. Start the http server - `python -m http.server --directory build\master\html` + `python -m http.server --directory build\GITBRANCH\TAG\html` 10. View the staged output in a browser by going to `localhost:8000` +License +------- This project is licensed under a [Creative Commons Attribution 4.0 International License](https://creativecommons.org/licenses/by/4.0/legalcode). diff --git a/requirements.txt b/requirements.txt index 0cffb722..cab7f87d 100644 --- a/requirements.txt +++ b/requirements.txt @@ -6,4 +6,4 @@ sphinx-markdown-tables == 0.0.15 Sphinx-Substitution-Extensions == 2020.9.30.0 sphinx-togglebutton === 0.3.0 sphinxcontrib-images === 0.9.4 -myst-parser === 0.16.1 \ No newline at end of file +myst-parser === 0.18.0 \ No newline at end of file diff --git a/source/_static/js/main.js b/source/_static/js/main.js index 2293659d..63ee9c11 100644 --- a/source/_static/js/main.js +++ b/source/_static/js/main.js @@ -69,7 +69,7 @@ function renderPersonas() { for (i=0; i`__ .. |kes-tag| replace:: `KESLATEST `__ .. |kes-stable| replace:: KESLATEST -.. |operator-version-stable| replace:: OPERATOR - .. |minio-tag| replace:: `MINIOLATEST `__ .. |minio-latest| replace:: MINIOLATEST .. |minio-rpm| replace:: RPMURL @@ -262,6 +262,7 @@ rst_prolog = """ .. |SNSD| replace:: :abbr:`SNSD (Single-Node Single-Drive)` .. |SNMD| replace:: :abbr:`SNMD (Single-Node Multi-Drive)` .. |MNMD| replace:: :abbr:`MNMD (Multi-Node Multi-Drive)` +.. |operator-version-stable| replace:: OPERATOR """ diff --git a/source/images/k8s/operator-dashboard.png b/source/images/k8s/operator-dashboard.png new file mode 100644 index 00000000..f8c9d3cb Binary files /dev/null and b/source/images/k8s/operator-dashboard.png differ diff --git a/source/images/k8s/operator-manage-tenant.png b/source/images/k8s/operator-manage-tenant.png new file mode 100644 index 00000000..b15ff0a2 Binary files /dev/null and b/source/images/k8s/operator-manage-tenant.png differ diff --git a/source/images/k8s/operator-tenant-view.png b/source/images/k8s/operator-tenant-view.png new file mode 100644 index 00000000..fc2326a4 Binary files /dev/null and b/source/images/k8s/operator-tenant-view.png differ diff --git a/source/includes/k8s/deploy-operator.rst b/source/includes/k8s/deploy-operator.rst index f3cd3766..ac9f1aa9 100644 --- a/source/includes/k8s/deploy-operator.rst +++ b/source/includes/k8s/deploy-operator.rst @@ -1,4 +1,5 @@ .. _minio-operator-installation: +.. _deploy-operator-kubernetes: ========================= Deploy the MinIO Operator @@ -10,7 +11,212 @@ Deploy the MinIO Operator :local: :depth: 1 -STUB - to be filled in +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 MinIO Operator installs a :kube-docs:`Custom Resource Document (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. + +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 <>`. + +Prerequisites +------------- + +Kubernetes Version 1.19.0 +~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +``kubectl`` Configuration +~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +Kubernetes TLS Certificate API +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The MinIO Operator automatically generates TLS Certificate Signing Requests +(CSR) and uses the Kubernetes ``certificates.k8s.io`` +:kube-docs:`TLS certificate management API +` to create signed TLS certificates. + +The MinIO Operator therefore *requires* that the Kubernetes +``kube-controller-manager`` configuration include the following +:kube-docs:`configuration settings +`: + +- ``--cluster-signing-key-file`` - Specify the PEM-encoded RSA or ECDSA private + key used to sign cluster-scoped certificates. + +- ``--cluster-signing-cert-file`` - Specify the PEM-encoded x.509 Certificate + Authority certificate used to issue cluster-scoped certificates. + +The Operator cannot complete initialization if the Kubernetes cluster is +not configured to respond to a generated CSR. Certain Kubernetes +providers do not specify these configuration values by default. + +To verify whether the ``kube-controller-manager`` has the required +settings, use the following command. Replace ``$CLUSTER-NAME`` with the name +of the Kubernetes cluster: + +.. code-block:: shell + :class: copyable + + kubectl get pod kube-controller-manager-$CLUSTERNAME-control-plane \ + -n kube-system -o yaml + +Confirm that the output contains the highlighted lines. The output of +the example command above may differ from the output in your terminal: + +.. code-block:: shell + :emphasize-lines: 12,13 + + spec: + containers: + - command: + - kube-controller-manager + - --allocate-node-cidrs=true + - --authentication-kubeconfig=/etc/kubernetes/controller-manager.conf + - --authorization-kubeconfig=/etc/kubernetes/controller-manager.conf + - --bind-address=127.0.0.1 + - --client-ca-file=/etc/kubernetes/pki/ca.crt + - --cluster-cidr=10.244.0.0/16 + - --cluster-name=my-cluster-name + - --cluster-signing-cert-file=/etc/kubernetes/pki/ca.crt + - --cluster-signing-key-file=/etc/kubernetes/pki/ca.key + ... + +.. important:: + + The MinIO Operator automatically generates TLS certificates for all + MinIO Tenant pods using the specified Certificate Authority (CA). + Clients external to the Kubernetes cluster must trust the + Kubernetes cluster CA to connect to the MinIO Operator or MinIO Tenants. + + Clients which cannot trust the Kubernetes cluster CA can try disabling TLS + validation for connections to the MinIO Operator or a MinIO Tenant. + + Alternatively, you can generate x.509 TLS certificates signed by a known + and trusted CA and pass those certificates to MinIO Tenants. + See :ref:`minio-tls-user-generated` for more complete documentation. + +Procedure +--------- + +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. + +.. 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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Run the :mc:`kubectl minio proxy` command to temporarily forward traffic from +the :ref:`MinIO Operator Console ` service to your +local machine: + +.. code-block:: shell + :class: copyable + + kubectl minio proxy + +The command output includes a JWT token you must use to log 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. .. toctree:: :titlesonly: diff --git a/source/includes/k8s/deploy-tenant-requirements.rst b/source/includes/k8s/deploy-tenant-requirements.rst new file mode 100644 index 00000000..e0a89a50 --- /dev/null +++ b/source/includes/k8s/deploy-tenant-requirements.rst @@ -0,0 +1,44 @@ +.. start-local-persistent-volume + +.. code-block:: yaml + :class: copyable + :emphasize-lines: 4, 12, 14, 22 + + apiVersion: v1 + kind: PersistentVolume + metadata: + name: + spec: + capacity: + storage: 1Ti + volumeMode: Filesystem + accessModes: + - ReadWriteOnce + persistentVolumeReclaimPolicy: Retain + storage-class: + local: + path: + nodeAffinity: + required: + nodeSelectorTerms: + - matchExpressions: + - key: kubernetes.io/hostname + operator: In + values: + - + +.. end-local-persistent-volume + +.. start-storage-class + +.. code-block:: yaml + :class: copyable + + apiVersion: storage.k8s.io/v1 + kind: StorageClass + metadata: + name: minio-local-storage + provisioner: kubernetes.io/no-provisioner + volumeBindingMode: WaitForFirstConsumer + +.. end-storage-class diff --git a/source/includes/k8s/install-minio-kubectl-plugin.rst b/source/includes/k8s/install-minio-kubectl-plugin.rst new file mode 100644 index 00000000..aa908e34 --- /dev/null +++ b/source/includes/k8s/install-minio-kubectl-plugin.rst @@ -0,0 +1,76 @@ +You can install the MinIO plugin using either the Kubernetes Krew plugin manager or manually by downloading and installing the plugin binary to your local host: + +.. tab-set:: + + .. tab-item:: 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 Krew to install the MinIO ``kubectl`` plugin using the following commands: + + .. code-block:: shell + :class: copyable + + kubectl krew update + kubectl krew install 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: + + .. 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 + + kubectl minio version + + The output should display the Operator version as |operator-version-stable|. + + .. 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: + + .. 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 + + kubectl minio version + + The output should display the Operator version as |operator-version-stable|. \ No newline at end of file diff --git a/source/includes/k8s/quickstart.rst b/source/includes/k8s/quickstart.rst index 33ad8234..de4ced8a 100644 --- a/source/includes/k8s/quickstart.rst +++ b/source/includes/k8s/quickstart.rst @@ -10,7 +10,7 @@ Quickstart for Kubernetes This procedure deploys a Single-Node Single-Drive MinIO server onto |OS| for early development and evaluation of MinIO Object Storage and its S3-compatible API layer. -Use the :ref:`MinIO Opreator ` to deploy and manage production-ready MinIO tenants on Kubernetes. +Use the :ref:`MinIO Operator ` to deploy and manage production-ready MinIO tenants on Kubernetes. Prerequisites ------------- diff --git a/source/index.rst b/source/index.rst index 96e20eab..79f9dd66 100644 --- a/source/index.rst +++ b/source/index.rst @@ -103,7 +103,6 @@ without validating their usage do so at their own risk. /developers/security-token-service /reference/minio-mc /reference/minio-mc-admin - /reference/minio-server/minio-server /reference/kubectl-minio-plugin .. cond:: linux or macos or windows diff --git a/source/operations/concepts.rst b/source/operations/concepts.rst index d8f172d7..ad6c7c48 100644 --- a/source/operations/concepts.rst +++ b/source/operations/concepts.rst @@ -71,12 +71,12 @@ Deployment Architecture .. _minio-intro-server-pool: :ref:`Server Pool ` - A set of MinIO :mc-cmd:`minio server` nodes which pool their drives and + A set of MinIO :mc:`minio server` nodes which pool their drives and resources for supporting object storage/retrieval requests. Server pools support horizontal expansion for MinIO deployments. The :mc-cmd:`~minio server HOSTNAME` argument passed to the - :mc-cmd:`minio server` command represents a Server Pool: + :mc:`minio server` command represents a Server Pool: .. code-block:: shell @@ -89,7 +89,7 @@ Deployment Architecture MinIO requires starting each :mc:`minio server` in the set with the same startup command to enable awareness of all set peers. - See :mc-cmd:`minio server` for complete syntax and usage. + See :mc:`minio server` for complete syntax and usage. MinIO calculates the size and number of Erasure Sets in the Server Pool based on the total number of drives in the set *and* the number of :mc:`minio` @@ -100,7 +100,7 @@ Deployment Architecture :ref:`Cluster ` The whole MinIO deployment consisting of one or more Server Pools. Each :mc-cmd:`~minio server HOSTNAME` argument passed to the - :mc-cmd:`minio server` command represents one Server Pool: + :mc:`minio server` command represents one Server Pool: .. code-block:: shell diff --git a/source/operations/deploy-manage-tenants.rst b/source/operations/deploy-manage-tenants.rst index 7bba9fd3..41261181 100644 --- a/source/operations/deploy-manage-tenants.rst +++ b/source/operations/deploy-manage-tenants.rst @@ -10,16 +10,32 @@ Deploy and Manage MinIO Tenants :local: :depth: 1 -STUB - to be filled in +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. -.. Following link is for K8s only -.. _deploy-minio-distributed-prereqs-storage: +The following tutorials provide steps for tenant management via the Operator Console and MinIO Kubernetes Plugin: -Tenant Requirements -------------------- +.. list-table:: + :stub-columns: 1 + :widths: 40 60 + :width: 100% -STUB - to be filled in + * - :ref:`minio-k8s-deploy-minio-tenant` + - Deploy a new MinIO Tenant onto the Kubernetes cluster. + * - :ref:`minio-k8s-modify-minio-tenant` + - Modify the configuration or topology settings of a MinIO Tenant. + + * - :ref:`minio-k8s-upgrade-minio-tenant` + - Upgrade the MinIO Server version used by a MinIO Tenant. + + * - :ref:`minio-k8s-expand-minio-tenant` + - Increase the available storage capacity of an existing MinIO Tenant. + + * - :ref:`minio-k8s-delete-minio-tenant` + - Delete an existing MinIO Tenant. + + * - :ref:`minio-site-replication-overview` + - Configure two or more MinIO Tenants as peers for MinIO Site Replication .. toctree:: :titlesonly: @@ -31,4 +47,4 @@ STUB - to be filled in /operations/install-deploy-manage/expand-minio-tenant /operations/install-deploy-manage/delete-minio-tenant /operations/install-deploy-manage/multi-site-replication - /operations/install-deploy-manage/minio-operator-console \ No newline at end of file + /operations/install-deploy-manage/minio-operator-console diff --git a/source/operations/install-deploy-manage/delete-minio-tenant.rst b/source/operations/install-deploy-manage/delete-minio-tenant.rst index 8a46092b..d700270d 100644 --- a/source/operations/install-deploy-manage/delete-minio-tenant.rst +++ b/source/operations/install-deploy-manage/delete-minio-tenant.rst @@ -10,5 +10,43 @@ Delete a MinIO Tenant :local: :depth: 1 +Prerequisites +------------- -Stub: TODO \ No newline at end of file +MinIO Kubernetes Operator and Plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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|. + +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. + +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``. + +.. warning:: + + 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. + +.. code-block:: shell + :class: copyable + + kubectl minio tenant delete TENANT_NAME \ + --namespace TENANT_NAMESPACE + +- Replace ``TENANT_NAME`` with the name of the Tenant. +- Replace ``TENANT_NAMESPACE`` with the namespace of the Tenant. + +The command includes a confirmation prompt that requires explicit approval of the delete operation. diff --git a/source/operations/install-deploy-manage/deploy-minio-tenant.rst b/source/operations/install-deploy-manage/deploy-minio-tenant.rst index 7b0bd924..968bfe6e 100644 --- a/source/operations/install-deploy-manage/deploy-minio-tenant.rst +++ b/source/operations/install-deploy-manage/deploy-minio-tenant.rst @@ -1,11 +1,8 @@ -.. _minio-k8s-deploy-minio-tenant: - -.. _deploy-minio-tenant: - - .. The following label handles links from content to distributed MinIO in K8s context .. _deploy-minio-distributed: +.. _minio-k8s-deploy-minio-tenant: + ===================== Deploy a MinIO Tenant ===================== @@ -14,7 +11,566 @@ Deploy a MinIO Tenant .. contents:: Table of Contents :local: - :depth: 1 + :depth: 2 +This procedure documents deploying a MinIO Tenant using the MinIO Operator Console. -Stub: TODO \ No newline at end of file +.. image:: /images/k8s/operator-dashboard.png + :align: center + :width: 70% + :class: no-scaled-link + :alt: MinIO Operator Console + +The Operator Console provides a rich user interface for deploying and managing MinIO Tenants on Kubernetes infrastructure. +Installing the MinIO :ref:`Kubernetes Operator ` automatically installs and configures the Operator Console. + +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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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|. + +See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator. + +.. include:: /includes/k8s/install-minio-kubectl-plugin.rst + +Kubernetes Version 1.19.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+. + +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. + +Locally Attached Drives +~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO *strongly recommends* using locally attached drives on each node intended +to support the MinIO Tenant. MinIO’s strict read-after-write and +list-after-write consistency model requires local disk filesystems (xfs, ext4, +etc.). MinIO also shows best performance with locally-attached drives. + +MinIO automatically generates :kube-docs:`Persistent Volume Claims (PVC) +` as part of +deploying a MinIO Tenant. The Operator generates one PVC for each volume in the +tenant *plus* two PVC to support collecting Tenant Metrics and logs. For +example, deploying a Tenant with 16 volumes requires 18 (16 + 2) ``PV``. + +This procedure uses the MinIO :minio-git:`DirectPV ` driver to +automatically provision Persistent Volumes from locally attached drives to +support the generated PVC. See the :minio-git:`DirectPV Documentation +` for installation and configuration +instructions. + +For clusters which cannot deploy MinIO DirectPV, +:kube-docs:`Local Persistent Volumes `. + +The following tabs provide example YAML objects for a local persistent +volume and a supporting +:kube-docs:`StorageClass `: + +.. tab-set:: + + .. tab-item:: Local Persistent Volume + + The following YAML describes a :kube-docs:`Local Persistent Volume + `: + + .. include:: /includes/k8s/deploy-tenant-requirements.rst + :start-after: start-local-persistent-volume + :end-before: end-local-persistent-volume + + Replace values in brackets ```` with the appropriate + value for the local drive. + + .. tab-item:: Storage Class + + The following YAML describes a + :kube-docs:`StorageClass ` that + meets the requirements for a MinIO Tenant: + + .. include:: /includes/k8s/deploy-tenant-requirements.rst + :start-after: start-storage-class + :end-before: end-storage-class + + The storage class *must* have ``volumeBindingMode: WaitForFirstConsumer``. + Ensure all Persistent Volumes provisioned to support the MinIO Tenant + use this storage class. + +Procedure (Operator Console) +---------------------------- + +1) Access the MinIO Operator Console +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward +traffic between the local host machine and the MinIO Operator Console: + +.. 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:9090 + + Current JWT to login: TOKEN + +Open your browser to the specified URL and enter the JWT Token into the +login page. You should see the :guilabel:`Tenants` page: + +.. image:: /images/k8s/operator-dashboard.png + :align: center + :width: 70% + :class: no-scaled-link + :alt: MinIO Operator Console + +Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant. + +2) Complete the Tenant :guilabel:`Setup` +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :guilabel:`Setup` pane displays core configuration settings for the +MinIO Tenant. + +Settings marked with an asterisk :guilabel:`*` are *required*: + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - Field + - Description + + * - :guilabel:`Name` + - The name of the MinIO Tenant + + * - :guilabel:`Namespace` + - The Kubernetes Namespace in which to deploy the tenant. You can create + the namespace by selecting the plus :guilabel:`+` icon if it does not + exist. + + The Operator supports at most *one* MinIO Tenant per namespace. + + * - :guilabel:`Storage Class` + - Specify the Kubernetes Storage Class the Operator uses when generating + Persistent Volume Claims for the Tenant. + + This procedure assumes using the :minio-git:`DirectPV ` + storage class ``directpv-min-io``. See the + :minio-git:`DirectPV Documentation ` + for installation and configuration instructions. + + * - :guilabel:`Number of 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. Use + the :guilabel:`Pod Placement` pane to modify the pod scheduling + settings for the Tenant. + + * - :guilabel:`Number of 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. The Operator generates an equal + number of PVC *plus two* for supporting Tenant services (Metrics and + Log Search). + + The specified :guilabel:`Storage Class` *must* correspond to a set of + Persistent Volumes sufficient in number to match each generated PVC. + + * - :guilabel:`Total Size` + - The total raw storage size for the Tenant. Specify both the total + storage size *and* the :guilabel:`Unit` of that storage. All storage + units are in SI values, e.g. Gi = GiB = 1024\ :sup:`3` bytes. + + The Operator displays the :guilabel:`Drive Capacity` under the + :guilabel:`Resource Allocation` section. The Operator sets this value + as the requested storage capacity in each generated PVC. + + 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. See :ref:`minio-k8s-production-considerations-memory` for guidance + on setting this value. + + 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. + + 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. + +3) The :guilabel:`Configure` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :guilabel:`Configure` section displays optional configuration settings for +the MinIO Tenant and its supporting services. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - Field + - Description + + * - :guilabel:`Expose Services` + - The MinIO Operator by default directs the MinIO Tenant services to + request an externally accessible IP address from the Kubernetes cluster + Load Balancer if one is available. + + Most public cloud Kubernetes infrastructures include a global Load + Balancer which meets this requirements. Other Kubernetes distributions + *may* include a load balancer that can respond to these requests. + + You can direct the Tenant to not make this request by toggling the + option to :guilabel:`Off` for the MinIO Service and Console Service. + + * - :guilabel:`Override Tenant Defaults` + - The MinIO Operator sets the Kubernetes Security Context for pods to + a default of ``1000`` for User, Group, and FsGroup. MinIO runs the + pod using the ``root`` user. + + You can modify the Security Context to direct MinIO to run using a + different User, Group, or FsGroup ID. You can also direct MinIO to not + run as the Root user. + + * - :guilabel:`Override Log Search Defaults` + - 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, or FsGroup ID. 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 Log Search service. + + * - :guilabel:`Override Prometheus Search Defaults` + - The MinIO Operator deploys a Prometheus service to support detailed + metrics in the MinIO Tenant Console. + + You can modify the Security Context to run the associated pod commands + using a different User, Group, or FsGroup ID. 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. + +4) The :guilabel:`Images` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :guilabel:`Images` section displays container image settings used by the +MinIO Tenant. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - Field + - Description + + * - :guilabel:`MinIO's Image` + - 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. + +5) The :guilabel:`Pod Placement` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :guilabel:`Pod Placement` section displays pod scheduler settings for the +MinIO Tenant. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - Field + - Description + + * - :guilabel:`None` + - Disables pod scheduling constraints for the tenant. This allows + Kubernetes to schedule multiple Tenant pods onto the same node. + + This may decrease resiliency, as a single Kubernetes worker can host + multiple MinIO pods. If that worker is down or lost, objects + may also be unavailable or lost. + + Consider using this setting only in early development or sandbox + environments with a limited number of worker nodes. + + * - :guilabel:`Default (Pod Anti-Affinity)` + - Directs the Operator to set anti-affinity settings such that no + Kubernetes worker can host more than one MinIO server pod for this + Tenant. + + * - :guilabel:`Node Selector` + - Directs the operator to set a Node Selector such that pods only deploy + onto Kubernetes workers whose labels match the selector. + +6) The :guilabel:`Identity Provider` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :guilabel:`Identity Provider` section displays +the :ref:`Identity Provider ` +settings for the MinIO Tenant. This includes configuring an external IDP such as +:ref:`OpenID ` or +:ref:`Active Directory / LDAP `. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - Field + - Description + + * - :guilabel:`Built-In` + - Configure additional internal MinIO users for the Operator to create + as part of deploying the Tenant. + + * - :guilabel:`OpenID` + - Configure an OpenID Connect-compatible servce as an external Identity + Provider (e.g. Keycloak, Okta, Google, Facebook, Dex) to manage MinIO + users. + + * - :guilabel:`Active Directory` + - Configure an Active Directory or OpenLDAP service as the external + Identity Provider to manage MinIO users. + +7) The :guilabel:`Security` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :guilabel:`Security` section displays TLS certificate settings +for the MinIO Tenant. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - Field + - Description + + * - :guilabel:`Enable TLS` + - Enable or disable TLS for the MinIO Tenant. + + * - :guilabel:`Enable 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. + + * - :guilabel:`Custom Certificates` + - Specify one or more custom TLS certificates for use by the MinIO Tenant. + + MinIO supports Server Name Indication (SNI) such that the Tenant can + select the appropriate TLS certificate based on the request hostname + and the certificate Subject Alternative Name. + + MinIO also supports specifying Certificate Authority certificates for + validating client certificates minted by that CA. + +8) The :guilabel:`Encryption` Section +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The :guilabel:`Encryption` section displays the +:ref:`Server-Side Encryption ` settings for the MinIO Tenant. + +Enabling SSE also deploys a MinIO :minio-git:`KES ` service in the +Tenant to faciliate SSE operations. + +.. list-table:: + :header-rows: 1 + :widths: 30 70 + :width: 100% + + * - Field + - Description + + * - :guilabel:`Vault` + - 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:`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. + + * - :guilabel:`Azure` + - Configure `Azure Key Vault + `__ + as the external KMS for storing root encryption keys. See + :ref:`minio-sse-azure` for guidance on the displayed fields. + +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. Copy these credentials to a secure location. + +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. + +.. image:: /images/k8s/operator-tenant-view.png + :align: center + :width: 70% + :class: no-scaled-link + :alt: Tenant View + +Each tab provides additional details or configuration options for the +MinIO Tenant. + +- :guilabel:`METRICS` - Displays metrics collected from the MinIO Tenant. +- :guilabel:`SECURITY` - Provides TLS-related configuration options. +- :guilabel:`POOLS` - Supports expanding the tenant by adding more Server Pools. +- :guilabel:`LICENSE` - Enter your `SUBNET `__ + license. + +10) Connect to the Tenant +~~~~~~~~~~~~~~~~~~~~~~~~~ + +The MinIO Operator creates services for the MinIO Tenant. 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. See the Kubernetes +documentation on :kube-docs:`Publishing Services (ServiceTypes) +` and +:kube-docs:`Ingress ` for more complete +information on configuring external access to services. + +You can temporarily expose each service using the +``kubectl port-forward`` utility. Run the following examples to forward +traffic from the local host running ``kubectl`` to the services running inside +the Kubernetes cluster. + +.. tab-set:: + + .. tab-item:: MinIO Tenant + + .. code-block:: shell + :class: copyable + + kubectl port-forward service/minio 443:443 + + .. tab-item:: MinIO Console + + .. code-block:: shell + :class: copyable + + kubectl port-forward service/minio-tenant-1-console 9443:9443 + +.. _minio-k8s-deploy-minio-tenant-commandline: + +Procedure (CLI) +--------------- + +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. + +You can also use this procedure to generate a Kubernetes ``YAML``-formatted resource document for further customization. + +STUB \ No newline at end of file diff --git a/source/operations/install-deploy-manage/expand-minio-tenant.rst b/source/operations/install-deploy-manage/expand-minio-tenant.rst index 28d5ea85..aaff8d3c 100644 --- a/source/operations/install-deploy-manage/expand-minio-tenant.rst +++ b/source/operations/install-deploy-manage/expand-minio-tenant.rst @@ -11,4 +11,131 @@ Expand a MinIO Tenant :depth: 1 -Stub: TODO \ No newline at end of file +This procedure documents expanding the available storage capacity of an existing MinIO tenant by deploying an additional pool of MinIO pods in the Kubernetes infrastructure. + +Prerequisites +------------- + +MinIO Kubernetes Operator and Plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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|. + +See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator. + +.. include:: /includes/k8s/install-minio-kubectl-plugin.rst + +Available Worker Nodes +~~~~~~~~~~~~~~~~~~~~~~ + +MinIO deploys additional :mc:`minio server ` pods as part of the new Tenant pool. +The Kubernetes cluster *must* have sufficient available worker nodes on which to schedule the new pods. + +The MinIO Operator provides configurations for controlling pod affinity and anti-affinity to direct scheduling to specific workers. + +Locally Attached Drives +~~~~~~~~~~~~~~~~~~~~~~~ + +MinIO *strongly recommends* using locally attached drives on each node intended to support the new tenant pool to ensure optimal performance. +MinIO’s strict read-after-write and list-after-write consistency model requires local disk filesystems (xfs, ext4, etc.). + +MinIO automatically generates :kube-docs:`Persistent Volume Claims (PVC) ` as part of deploying a MinIO Tenant. +The Operator generates one PVC for each volume in the new pool. + +This procedure uses the MinIO :minio-git:`DirectPV ` driver to automatically provision Persistent Volumes from locally attached drives to support the generated PVC. +See the :minio-git:`DirectPV Documentation ` for installation and configuration instructions. + +For clusters which cannot deploy MinIO DirectPV, :kube-docs:`Local Persistent Volumes `. + +The following tabs provide example YAML objects for a local persistent volume and a supporting :kube-docs:`StorageClass `: + +.. tab-set:: + + .. tab-item:: Local Persistent Volume + + The following YAML describes a :kube-docs:`Local Persistent Volume `: + + .. include:: /includes/k8s/deploy-tenant-requirements.rst + :start-after: start-local-persistent-volume + :end-before: end-local-persistent-volume + + Replace values in brackets ```` with the appropriate value for the local drive. + + .. tab-item:: Storage Class + + The following YAML describes a :kube-docs:`StorageClass ` that meets the requirements for a MinIO Tenant: + + .. include:: /includes/k8s/deploy-tenant-requirements.rst + :start-after: start-storage-class + :end-before: end-storage-class + + The storage class *must* have ``volumeBindingMode: WaitForFirstConsumer``. + Ensure all Persistent Volumes provisioned to support the MinIO Tenant use this storage class. + +Procedure (CLI) +--------------- + +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: + +.. 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 + + * - :mc-cmd:`minio-tenant-1 ` + - The name of the MinIO Tenant which the command expands with the new pool. + + * - :mc-cmd:`~kubectl minio tenant expand --servers` + - The number of ``minio`` servers to deploy in the new Tenant Pool across + the Kubernetes cluster. + + * - :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``. + + * - :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``. + + * - :mc-cmd:`~kubectl minio tenant expand --storage-class` + - The Kubernetes ``StorageClass`` to use when creating each PVC. + + * - :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 diff --git a/source/operations/install-deploy-manage/minio-operator-console.rst b/source/operations/install-deploy-manage/minio-operator-console.rst index 0b00718a..fb4fc876 100644 --- a/source/operations/install-deploy-manage/minio-operator-console.rst +++ b/source/operations/install-deploy-manage/minio-operator-console.rst @@ -4,4 +4,81 @@ MinIO Operator Console ====================== -stub \ No newline at end of file +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +The Operator Console provides a rich user interface for deploying and +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 + :align: center + :width: 70% + :class: no-scaled-link + :alt: MinIO Operator Console + +This page summarizes the functions available with the MinIO Operator Console. + +Use the :mc-cmd:`kubectl minio proxy` command to temporarily forward +traffic between the local host machine and the MinIO Operator Console: + +.. 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:9090 + + Current JWT to login: TOKEN + +Open your browser to the specified URL and enter the JWT Token into the +login page. + +Tenant Management +----------------- + +The MinIO Operator Console supports deploying, managing, and monitoring +MinIO Tenants on the Kubernetes cluster. + +.. image:: /images/k8s/operator-dashboard.png + :align: center + :width: 70% + :class: no-scaled-link + :alt: MinIO Operator Console + +You can :ref:`deploy a MinIO Tenant ` through the +Operator Console. + +The Operator Console automatically detects any MinIO Tenants +deployed on the cluster, whether provisioned through the Operator Console +or through the :ref:`MinIO Kubernetes Plugin `. + +For each listed tenant, select :guilabel:`MANAGE` to open an in-browser +view of that tenant's MinIO Console. You can use this view to directly manage +the tenant through the Operator UI. + +.. image:: /images/k8s/operator-manage-tenant.png + :align: center + :width: 70% + :class: no-scaled-link + :alt: MinIO Operator Tenant Console + +Select :guilabel:`VIEW` to view the Tenant details and configurations. +You can modify, expand, upgrade, and delete the Tenant from this view. + +.. image:: /images/k8s/operator-tenant-view.png + :align: center + :width: 70% + :class: no-scaled-link + :alt: MinIO Operator Tenant View + diff --git a/source/operations/install-deploy-manage/upgrade-minio-tenant.rst b/source/operations/install-deploy-manage/upgrade-minio-tenant.rst index 38973879..e195b59f 100644 --- a/source/operations/install-deploy-manage/upgrade-minio-tenant.rst +++ b/source/operations/install-deploy-manage/upgrade-minio-tenant.rst @@ -10,5 +10,57 @@ Upgrade a MinIO Tenant :local: :depth: 1 +Prerequisites +------------- -Stub: TODO \ No newline at end of file +MinIO Kubernetes Operator and Plugin +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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|. + +See :ref:`deploy-operator-kubernetes` for complete documentation on deploying the MinIO Operator. + +.. include:: /includes/k8s/install-minio-kubectl-plugin.rst + +Procedure (CLI) +--------------- + +This procedure documents upgrading pods running on a MinIO Tenant. + +1) Validate the Active MinIO Version +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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 TENANT_NAME \ + --namespace TENANT_NAMESPACE + +- Replace ``TENANT_NAME`` with the name of the Tenant. +- Replace ``TENANT_NAMESPACE`` with the namespace of the Tenant. + +The output includes the version of the MinIO Server used by all Pods in the Tenant. + +2) Upgrade the MinIO Tenant +~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +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. + +.. code-block:: shell + :class: copyable + + kubectl minio tenant upgrade TENANT_NAME \ + --image minio:minio:RELEASE:YYYY-MM-DDTHH-MM-SSZ \ + --namespace TENANT_NAMESPACE + +- 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. + +See MinIO's `DockerHub Repository `__ for a list of available release tags. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst index 2b96cf21..d5bd6d1d 100644 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst +++ b/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst @@ -19,7 +19,7 @@ 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 `. +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. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst index 7eed816c..4b052ac4 100644 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst +++ b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst @@ -23,7 +23,7 @@ Description .. 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 `. +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 `. @@ -186,6 +186,6 @@ The command supports the following flags: 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. + 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-expand.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-expand.rst index 1d8770a1..7f39c174 100644 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-expand.rst +++ b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-expand.rst @@ -128,4 +128,4 @@ The command supports the following flags: 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. \ No newline at end of file + See the :ref:`Deploy MinIO Tenant ` tutorial for guidance on creating Storage Classes for supporting the MinIO Tenant. \ No newline at end of file