docs/source/includes/k8s/steps-deploy-tenant-cli.rst

Deploy a MinIO Tenant using the Command Line

The kubectl minio tenant create command supports creating a MinIO Tenant in your Kubernetes cluster. The command requires that the cluster have a functional MinIO Operator installation.

To deploy a tenant from the command line, complete the following steps:

create-tenant-cli-determine-settings-required-options

create-tenant-cli-determine-additional-options

create-tenant-cli-enter-command

create-tenant-cli-record-access-info

create-tenant-cli-access-tenant-console

create-tenant-cli-forward-ports

1) Determine Values for Required Settings

The kubectl minio tenant create command requires several configuration settings. Determine the values for all required settings.

Required Settings

The command requires values for each of the items in this table.

Setting	Description
~kubectl minio tenant create TENANT_NAME	The name to use for the new tenant.
~kubectl minio tenant create --capacity	The total raw storage size for the Tenant across all volumes. Specify both the total storage size and the Unit of that storage. All storage units are in SI values, e.g. Gi = GiB = 10243 bytes. For example, 16 Ti for 16 Tebibytes.
~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.
~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.
~kubectl minio tenant create --namespace	Each MinIO tenant requires its own namespace. Specify a namespace with the ~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 <new_namespace> to add one.
~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 ~kubectl minio tenant create --storage-class flag. The specified ~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.

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

kubectl minio tenant create miniotenant          \
                            --capacity 16Ti      \
                            --servers 4          \
                            --volumes 16         \
                            --namespace minio    \
                            --storage-class warm

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 kubectl minio tenant create command:

Setting	Description
~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 ~kubectl minio tenant create --image flag. See the MinIO Quay or the MinIO DockerHub repositories for a list of valid tags.
~kubectl minio tenant create --image-pull-secret	If using a custom container registry, specify the secret to use when pulling the minio image. Use ~kubectl minio tenant create --image-pull-secret to specify the secret.
~kubectl minio tenant create --kes-config	Configure a Key Encrption Service (KES) <kes> Use the ~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 KES <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 ~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 <FILE> to manually create the MinIO tenant using the file.

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,

Key ecnryption file

minio-secret

Storage class

warm

kubectl minio tenant create                                \
                     minio1                                \
                     --capacity 16Ti                       \
                     --servers 4                           \
                     --volumes 16                          \
                     --namespace miniotenantspace          \
                     --image |minio-latest|  \
                     --kes-config minio-kes-secret         \
                     --storage-class warm

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.

5) Access the Tenant's MinIO Console

To access the MinIO Console <minio-console> for the tenant, forward the tenant's port.

• If necessary, run kubectl get svc -n <namespace> to retrieve the tenant's port number.

• Run the following to forward the tenant's port and access it from a browser:

  kubectl port-forward svc/<tenant-name>-console -n <tenant-namespace> <localport>:<tenantport>

  • Replace <tenant-name> with the name of your tenant.
  • Replace <tenant-namespace> with the namespace the tenant exists in.
  • Replace <localport> with the port number to use on your local machine to access the tenant's MinIO Console.
  • Replace <tenantport> with the port number the MinIO Operator assigned to the tenant.

• Go to https://127.0.0.1:<localport> to Access the tenant's MinIO Console.

  Replace <localport> 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.

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.

MinIO Tenant

kubectl port-forward service/minio 443:443

MinIO Console

kubectl port-forward service/minio-tenant-1-console 9443:9443