From 79e342b6d467002cc90d14c2ee8002fa5124b1f6 Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Fri, 17 Jun 2022 16:53:14 -0500 Subject: [PATCH] Adding create tenant CLI tutorial for K8s docs to the deploy tenant file. --- Makefile | 14 +- source/includes/k8s/deploy-operator.rst | 2 +- .../deploy-minio-multi-node-multi-drive.rst | 2 +- .../deploy-minio-tenant.rst | 618 ++++++++++++------ .../kubectl-minio-tenant-create.rst | 4 +- 5 files changed, 442 insertions(+), 198 deletions(-) diff --git a/Makefile b/Makefile index 5d101cab..882d223f 100644 --- a/Makefile +++ b/Makefile @@ -68,6 +68,8 @@ 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:]')) + @$(eval kname = $(shell uname -s)) + @echo "Updating Operator to ${OPERATOR}" @case "${kname}" in \ @@ -116,12 +118,12 @@ 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 +# @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" diff --git a/source/includes/k8s/deploy-operator.rst b/source/includes/k8s/deploy-operator.rst index ac9f1aa9..16dbfd4a 100644 --- a/source/includes/k8s/deploy-operator.rst +++ b/source/includes/k8s/deploy-operator.rst @@ -123,7 +123,7 @@ the example command above may differ from the output in your terminal: 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. + See :ref:`minio-tls` for more complete documentation. Procedure --------- diff --git a/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst b/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst index c9b05c17..491a89c8 100644 --- a/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst +++ b/source/operations/install-deploy-manage/deploy-minio-multi-node-multi-drive.rst @@ -488,7 +488,7 @@ for use by based on the total network bandwidth supported by the host: * - 100GbE - 64 vCPU per pod. - +.. _minio-k8s-production-considerations-memory: Memory Allocation ~~~~~~~~~~~~~~~~~ diff --git a/source/operations/install-deploy-manage/deploy-minio-tenant.rst b/source/operations/install-deploy-manage/deploy-minio-tenant.rst index 968bfe6e..1af03e88 100644 --- a/source/operations/install-deploy-manage/deploy-minio-tenant.rst +++ b/source/operations/install-deploy-manage/deploy-minio-tenant.rst @@ -11,7 +11,7 @@ Deploy a MinIO Tenant .. contents:: Table of Contents :local: - :depth: 2 + :depth: 1 This procedure documents deploying a MinIO Tenant using the MinIO Operator Console. @@ -110,14 +110,39 @@ volume and a supporting Ensure all Persistent Volumes provisioned to support the MinIO Tenant use this storage class. -Procedure (Operator Console) ----------------------------- +Procedure (MinIO Operator Console) +---------------------------------- + +To deploy a tenant from the MinIO Operator Console, complete the following steps in order: + +:ref:`create-tenant-access-minio-operator-console` + +:ref:`create-tenant-complete-tenant-setup` + +:ref:`create-tenant-configure-section` + +:ref:`create-tenant-images-section` + +:ref:`create-tenant-pod-placement-section` + +:ref:`create-tenant-identity-provider-section` + +:ref:`create-tenant-security-section` + +:ref:`create-tenant-encryption-section` + +:ref:`create-tenant-deploy-view-tenant` + +:ref:`create-tenant-connect-tenant` + +:ref:`create-tenant-operator-forward-ports` + +.. _create-tenant-access-minio-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: +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 @@ -134,8 +159,8 @@ The command returns output similar to the following: 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: +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 @@ -145,11 +170,12 @@ login page. You should see the :guilabel:`Tenants` page: Click the :guilabel:`+ Create Tenant` to start creating a MinIO Tenant. +.. _create-tenant-complete-tenant-setup: + 2) Complete the Tenant :guilabel:`Setup` ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :guilabel:`Setup` pane displays core configuration settings for the -MinIO Tenant. +The :guilabel:`Setup` pane displays core configuration settings for the MinIO Tenant. Settings marked with an asterisk :guilabel:`*` are *required*: @@ -165,80 +191,64 @@ Settings marked with an asterisk :guilabel:`*` are *required*: - 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 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. + - 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. + 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. + 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 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 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. + 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 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. :math:`Gi = GiB = 1024^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 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. + 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. + - 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. + 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. + 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. +While all subsequent sections are *optional*, MinIO recommends reviewing them prior to deploying the Tenant. + +.. _create-tenant-configure-section: 3) The :guilabel:`Configure` Section ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :guilabel:`Configure` section displays optional configuration settings for -the MinIO Tenant and its supporting services. +The :guilabel:`Configure` section displays optional configuration settings for the MinIO Tenant and its supporting services. .. list-table:: :header-rows: 1 @@ -249,53 +259,42 @@ the MinIO Tenant and its supporting services. - 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. + - 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. + 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. + 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. + - 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. + 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. + - 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 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. + 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. + - 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 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. + You can also modify the storage class and requested capacity associated to the PVC generated to support the Prometheus service. + +.. _create-tenant-images-section: 4) The :guilabel:`Images` Section ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :guilabel:`Images` section displays container image settings used by the -MinIO Tenant. +The :guilabel:`Images` section displays container image settings used by the MinIO Tenant. .. list-table:: :header-rows: 1 @@ -306,11 +305,8 @@ MinIO Tenant. - 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. + - 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. @@ -320,21 +316,20 @@ MinIO Tenant. * - | :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 + - 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. + - The container images to use for starting the Prometheus service supporting the Log Search API. + +.. _create-tenant-pod-placement-section: 5) The :guilabel:`Pod Placement` Section ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :guilabel:`Pod Placement` section displays pod scheduler settings for the -MinIO Tenant. +The :guilabel:`Pod Placement` section displays pod scheduler settings for the MinIO Tenant. .. list-table:: :header-rows: 1 @@ -345,33 +340,27 @@ MinIO Tenant. - Description * - :guilabel:`None` - - Disables pod scheduling constraints for the tenant. This allows - Kubernetes to schedule multiple Tenant pods onto the same node. + - 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. + 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. + 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. + - 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. + - Directs the operator to set a Node Selector such that pods only deploy onto Kubernetes workers whose labels match the selector. + +.. _create-tenant-identity-provider-section: 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 `. +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 @@ -382,23 +371,20 @@ settings for the MinIO Tenant. This includes configuring an external IDP such as - Description * - :guilabel:`Built-In` - - Configure additional internal MinIO users for the Operator to create - as part of deploying the Tenant. + - 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. + - 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. + - Configure an Active Directory or OpenLDAP service as the external Identity Provider to manage MinIO users. + +.. _create-tenant-security-section: 7) The :guilabel:`Security` Section ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :guilabel:`Security` section displays TLS certificate settings -for the MinIO Tenant. +The :guilabel:`Security` section displays TLS certificate settings for the MinIO Tenant. .. list-table:: :header-rows: 1 @@ -412,30 +398,25 @@ for the MinIO Tenant. - 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. + - 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. + 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 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. + MinIO also supports specifying Certificate Authority certificates for validating client certificates minted by that CA. + +.. _create-tenant-encryption-section: 8) The :guilabel:`Encryption` Section ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :guilabel:`Encryption` section displays the -:ref:`Server-Side Encryption ` settings for the MinIO Tenant. +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. +Enabling SSE also deploys a MinIO :minio-git:`KES ` service in the Tenant to faciliate SSE operations. .. list-table:: :header-rows: 1 @@ -446,42 +427,35 @@ Tenant to faciliate SSE operations. - 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. + - 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. + - 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. + - 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. + - Configure `Azure Key Vault `__ as the external KMS for storing root encryption keys. + See :ref:`minio-sse-azure` for guidance on the displayed fields. + +.. _create-tenant-deploy-view-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. Copy these credentials to a secure location. +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. +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. +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 @@ -489,20 +463,20 @@ its details. :class: no-scaled-link :alt: Tenant View -Each tab provides additional details or configuration options for the -MinIO Tenant. +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. +- :guilabel:`LICENSE` - Enter your `SUBNET `__ license. + +.. _create-tenant-connect-tenant: 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: +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 @@ -519,33 +493,32 @@ The MinIO Operator creates services for the MinIO Tenant. Use the 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 ``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 ``*-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. +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 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. +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. +.. _create-tenant-operator-forward-ports: + +11) Forward Ports +~~~~~~~~~~~~~~~~~ + +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:: @@ -565,12 +538,281 @@ the Kubernetes cluster. .. _minio-k8s-deploy-minio-tenant-commandline: -Procedure (CLI) ---------------- +Procedure (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. -You can also use this procedure to generate a Kubernetes ``YAML``-formatted resource document for further customization. +To deploy a tenant from the command line, complete the following steps: -STUB \ No newline at end of file +: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` + +:ref:`create-tenant-cli-forward-ports` + +.. _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 +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +To access the :ref:`MinIO Console ` for the tenant, forward the tenant's port. + +- If necessary, run ``kubectl get svc -n `` to retrieve the tenant's port number. +- Run the following to forward the tenant's port and access it from a browser: + + .. code-block:: shell + :class: copyable + + kubectl port-forward svc/-console -n : + + - Replace ```` with the name of your tenant. + - Replace ```` with the namespace the tenant exists in. + - Replace ```` with the port number to use on your local machine to access the tenant's MinIO Console. + - Replace ```` with the port number the MinIO Operator assigned to the tenant. + +- Go to ``https://127.0.0.1:`` to Access the tenant's MinIO Console. + + Replace ```` with the port number you used when forwarding the tenant's port. + +- Login with the username and password shown in the tenant creation output and recorded in step 4 above. + +.. _create-tenant-cli-forward-ports: + +6) Forward Ports +~~~~~~~~~~~~~~~~ + +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 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 4b052ac4..8384b62f 100644 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst +++ b/source/reference/kubectl-minio-plugin/kubectl-minio-tenant-create.rst @@ -101,7 +101,7 @@ The command supports the following flags: 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``). + 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. @@ -123,7 +123,7 @@ The command supports the following flags: - 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 ``PVC`` to associate to each ``minio`` server by dividing :mc-cmd:`~kubectl minio tenant create --volumes` by :mc-cmd:`~kubectl minio tenant create --servers`. + - :mc:`kubectl minio` determines the number of ``PVC`` 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 ``PV`` that are locally-attached to the node running that Pod.