Documentation

Documentation

Deploy a MinIO Tenant

This procedure documents deploying a MinIO Tenant through OpenShift 4.7+ using the OpenShift Web Console and the MinIO Kubernetes Operator.

MinIO Operator Console

The MinIO Operator supports only the Distributed (Multi-Node Multi-Drive) MinIO topology. You can use basic Kubernetes YAML resource definitions to deploy Single-Node Single-Drive and Single-Node Multi-Drive topologies for local testing and evaluation as necessary.

The Operator Console provides a rich user interface for deploying and managing MinIO Tenants on Kubernetes infrastructure. Installing the MinIO 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 Kubernetes Documentation.

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 4.5.5.

See Deploy the MinIO Operator for complete documentation on deploying the MinIO Operator.

You can install the MinIO Kubernetes plugin by downloading and installing the plugin binary to your local host:

You can download the MinIO kubectl plugin to your local system path. The oc CLI automatically discovers and runs compatible plugins.

The following code downloads the latest stable version 4.5.5 of the MinIO Kubernetes plugin and installs it to the system path:

curl https://github.com/minio/operator/releases/download/v4.5.5/kubectl-minio_4.5.5_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:

oc minio version

The output should display the Operator version as 4.5.5.

You can download the MinIO kubectl plugin to your local system path. The oc CLI automatically discovers and runs compatible plugins.

The following PowerShell command downloads the latest stable version 4.5.5 of the MinIO Kubernetes plugin and installs it to the system path:

Invoke-WebRequest -Uri "https://github.com/minio/operator/releases/download/v4.5.5/kubectl-minio_4.5.5_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:

oc minio version

The output should display the Operator version as 4.5.5.

OpenShift 4.7+ and oc CLI Tool

This procedure assumes installation of the MinIO Operator using the OpenShift 4.7+ and the OpenShift OperatorHub.

This procedure assumes your local machine has the OpenShift oc CLI tool installed and configured for access to the OpenShift Cluster. Download and Install the OpenShift CLI oc for use in this procedure.

See Deploy MinIO Operator on RedHat OpenShift for more complete instructions.

Check Security Context Constraints

The MinIO Operator deploys pods using the following default Security Context per pod:

securityContext:
  runAsUser: 1000
  runAsGroup: 1000
  runAsNonRoot: true
  fsGroup: 1000

Certain OpenShift Security Context Constraints limit the allowed UID or GID for a pod such that MinIO cannot deploy the Tenant successfully. Ensure that the Project in which the Operator deploys the Tenant has sufficient SCC settings that allow the default pod security context. You can alternatively modify the tenant security context settings during deployment.

The following command returns the optimal value for the securityContext:

oc get namespace <namespace> \
-o=jsonpath='{.metadata.annotations.openshift\.io/sa\.scc\.supplemental-groups}{"\n"}'

The command returns output similar to the following:

1056560000/10000

Take note of this value before the slash for use in this procedure.

Persistent Volumes

MinIO can use any Kubernetes Persistent Volume (PV) that supports the ReadWriteOnce access mode. MinIO’s consistency guarantees require the exclusive storage access that ReadWriteOnce provides.

For Kubernetes clusters where nodes have Direct Attached Storage, MinIO strongly recommends using the DirectPV CSI driver. DirectPV provides a distributed persistent volume manager that can discover, format, mount, schedule, and monitor drives across Kubernetes nodes. DirectPV addresses the limitations of manually provisioning and monitoring local persistent volumes.

Deploy a Tenant using the MinIO Operator Console

To deploy a tenant from the MinIO Operator Console, complete the following steps in order:

1) Access the MinIO Operator Console

2) Complete the Tenant Setup

3) The Configure Section

4) The Images Section

5) The Pod Placement Section

6) The Identity Provider Section

7) The Security Section

1) The Encryption Section

9) Audit Log Settings

10) Deploy and View the Tenant

11) Connect to the Tenant

12) Forward Ports

1) Access the MinIO Operator Console

Use the oc minio proxy command to temporarily forward traffic between the local host machine and the MinIO Operator Console:

oc minio proxy

The command returns output similar to the following:

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 Tenants page:

MinIO Operator Console

Click the + Create Tenant to start creating a MinIO Tenant.

2) Complete the Tenant Setup

The Setup pane displays core configuration settings for the MinIO Tenant.

Settings marked with an asterisk * are required:

Field

Description

Name

The name of the MinIO Tenant

Namespace

The Kubernetes Namespace in which to deploy the tenant. You can create the namespace by selecting the plus + icon if it does not exist.

The Operator supports at most one MinIO Tenant per namespace.

Storage Class

Specify the Kubernetes Storage Class the Operator uses when generating Persistent Volume Claims for the Tenant.

Ensure the specified storage class has sufficient available Persistent Volume resources to match each generated Persistent Volume Claim.

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 Pod Placement pane to modify the pod scheduling settings for the Tenant.

Number of Drives per Server

The number of storage volumes (Persistent Volume Claims) the Operator requests per Server.

The Operator displays the Total Volumes under the Resource Allocation section. The Operator generates an equal number of PVC plus two for supporting Tenant services (Metrics and Log Search).

The specified Storage Class must correspond to a set of Persistent Volumes sufficient in number to match each generated PVC.

Total Size

The total raw storage size for the Tenant. Specify both the total storage size and the Unit of that storage. All storage units are in SI values, e.g. \(Gi = GiB = 1024^3\) bytes.

The Operator displays the Drive Capacity under the:guilabel:Resource Allocation section. The Operator sets this value as the requested storage capacity in each generated PVC.

The specified Storage Class must correspond to a set of Persistent Volumes sufficient in capacity to match each generated PVC.

Memory per Node [Gi]

Specify the total amount of memory (RAM) to allocate per MinIO server pod. See Memory for guidance on setting this value.

The Kubernetes cluster must have worker nodes with sufficient free RAM to match the pod request.

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 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 Erasure Coding for more complete documentation.

Select 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 Configure Section

The Configure section displays optional configuration settings for the MinIO Tenant and its supporting services.

Field

Description

Expose MinIO Service

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 to access the tenant.

Most public cloud Kubernetes infrastructures include a global Load Balancer which meets this requirement. Other Kubernetes distributions may include a load balancer that can respond to these requests.

Expose Console Service

Select whether the Tenant should request an IP address from the Load Balancer to access the Tenant’s Console.

Most public cloud Kubernetes infrastructures include a global Load Balancer which meets this requirement. Other Kubernetes distributions may include a load balancer that can respond to these requests.

Set Custom Domains

Toggle on to customize the domains allowed to access the tenant’s console and other tenant services.

Security Context

The MinIO Operator sets the Kubernetes Security Context for pods to a default of 1000 for User, Group, and FsGroup. The FSGroupChangePolicy defaults to Always. MinIO does not run the pod using the root user.

You can modify the Security Context to direct MinIO to run using a different User, Group,FsGroup ID, and FSGroupChangePolicy. You can also direct MinIO to run as the Root user.

Important

If your OpenShift cluster enforces Security Context Constraints , ensure you set the Tenant constraints appropriately such that pods can start and run normally.

Additional Environment Variables

Enter any additional the key:value pairs to use as environment variables for the tenant.

4) The Images Section

The Images section displays container image settings used by the MinIO Tenant.

Field

Description

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.

Log Search API’s Image

The container image to use for MinIO Log Search API.

KES Image

The container image to use for MinIO KES.

Log Search Postgres Image
Log Search Postgres Init Image

The container images to use for starting the PostgreSQL service supporting the Log Search API

Prometheus Image
Prometheus Sidecar Image
Prometheus Init Image

The container images to use for starting the Prometheus service supporting the Log Search API.

5) The Pod Placement Section

The Pod Placement section displays pod scheduler settings for the MinIO Tenant.

Field

Description

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.

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.

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 Identity Provider Section

The Identity Provider section displays the Identity Provider settings for the MinIO Tenant. This includes configuring an external IDP such as OpenID or Active Directory / LDAP.

Field

Description

Built-In

Configure additional internal MinIO users for the Operator to create as part of deploying the Tenant.

OpenID

Configure an OpenID Connect-compatible service as an external Identity Provider (e.g. Keycloak, Okta, Google, Facebook, Dex) to manage MinIO users.

Active Directory

Configure an Active Directory or OpenLDAP service as the external Identity Provider to manage MinIO users.

7) The Security Section

The Security section displays TLS certificate settings for the MinIO Tenant.

Field

Description

Enable TLS

Enable or disable TLS for the MinIO Tenant.

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.

Custom Certificates

When enabled, you can upload custom TLS certificates for MinIO to use for server and client credentials.

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 uploading Certificate Authority certificates for validating client certificates minted by that CA.

1) The Encryption Section

The Encryption section displays the Server-Side Encryption (SSE) settings for the MinIO Tenant.

Enabling SSE also creates MinIO Key Encryption Service pods in the Tenant to facilitate SSE operations.

Field

Description

Vault

Configure Hashicorp Vault as the external KMS for storing root encryption keys. See Server-Side Object Encryption with Hashicorp Vault Root KMS for guidance on the displayed fields.

AWS

Configure AWS Secrets Manager as the external KMS for storing root encryption keys. See Server-Side Object Encryption with AWS Secrets Manager Root KMS for guidance on the displayed fields.

GCP

Configure Google Cloud Platform Secret Manager as the external KMS for storing root encryption keys. See Server-Side Object Encryption with GCP Secret Manager Root KMS for guidance on the displayed fields.

Azure

Configure Azure Key Vault as the external KMS for storing root encryption keys. See Server-Side Object Encryption with Azure Key Vault Root KMS for guidance on the displayed fields.

9) Audit Log Settings

Field

Description

Log Search Storage Class

Select the storage class and requested capacity associated to the PVC generated to support audit logging.

Storage Size

Specify the amount of size of storage to make available for audit logging.

SecurityContext for LogSearch

The MinIO Operator deploys a Log Search service (SQL Database and Log Search API) to support Audit Log search in the MinIO Tenant Console.

You can modify the Security Context to run the associated pod commands using a different User, Group, FsGroup, or FSGroupChangePolicy. You can also direct the pod to not run commands as the Root user.

SecurityContext for PostgreSQL

The MinIO Operator deploys a PostgreSQL database to support logging services.

You can modify the Security Context to run the associated pod commands using a different User, Group, FsGroup, or FSGroupChangePolicy. You can also direct the pod to not run commands as the Root user.

You can also modify the storage class and requested capacity associated to the PVC generated to support the Prometheus service.

10) Deploy and View the Tenant

Select 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 Tenants view. The State column updates throughout the deployment process.

Tenant deployment can take several minutes to complete. Once the State reads as Initialized, click the Tenant to view its details.

Tenant View

Each tab provides additional details or configuration options for the MinIO Tenant.

  • METRICS - Displays metrics collected from the MinIO Tenant.

  • SECURITY - Provides TLS-related configuration options.

  • POOLS - Supports expanding the tenant by adding more Server Pools.

  • LICENSE - Enter your SUBNET license.

11) Connect to the Tenant

The MinIO Operator creates services for the MinIO Tenant.

Use the oc get svc -n TENANT-PROJECT command to review the deployed services:

oc get svc -n minio-tenant-1
NAME                               TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
minio                              LoadBalancer   10.97.114.60     <pending>     443:30979/TCP    2d3h
minio-tenant-1-console             LoadBalancer   10.106.103.247   <pending>     9443:32095/TCP   2d3h
minio-tenant-1-hl                  ClusterIP      None             <none>        9000/TCP         2d3h
minio-tenant-1-log-hl-svc          ClusterIP      None             <none>        5432/TCP         2d3h
minio-tenant-1-log-search-api      ClusterIP      10.103.5.235     <none>        8080/TCP         2d3h
minio-tenant-1-prometheus-hl-svc   ClusterIP      None             <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 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 OpenShift documentation on Route or Ingress for more complete information on configuring external access to services.

12) Forward Ports

You can temporarily expose each service using the oc port-forward utility. Run the following examples to forward traffic from the local host running oc to the services running inside the Kubernetes cluster.

oc port-forward service/minio 443:443
oc port-forward service/minio-tenant-1-console 9443:9443

Deploy a Tenant using the OpenShift Web Console

1) Access the MinIO Operator Interface

You can find the MinIO Operator Interface from the Operators left-hand navigation header.

  1. Go to Operators, then Installed Operators.

  2. For the Project dropdown, select openshift-operators.

  3. Select MinIO Operators from the list of installed operators.

Click Create Tenant to begin the Tenant Creation process.

2) Create the Tenant

The Form View provides a user interface for configuring the new MinIO Tenant.

OpenShift Tenant Creation UI View
  • Ensure the Tenant Secret -> Name is set to the name of the MinIO Root User Kubernetes Secret created as part of the prerequisites.

  • Ensure the Console -> Console Secret -> Name is set to the name of the MinIO Console Kubernetes Secret created as part of the prerequisites.

You can also use the YAML view to perform more granular configuration of the MinIO Tenant. Refer to the MinIO Custom Resource Definition Documentation for guidance on setting specific fields. MinIO also publishes examples for additional guidance in creating custom Tenant YAML objects. Note that the OperatorHub YAML view supports creating only the MinIO Tenant object. Do not specify any other objects as part of the YAML input.

OpenShift Tenant Creation UI View

Changes to one view are reflected in the other. For example, you can make modifications in the YAML View and see those changes in the Form View.

Security Context Configuration

If your OpenShift cluster Security Context Configuration restricts the supported pod security contexts, open the YAML View and locate the spec.pools[n].securityContext and spec.console.securityContext objects. Modify the securityContext settings to use a supported UID based on the SCC of your OpenShift Cluster.

Click Create to create the MinIO Tenant using the specified configuration. Use the credentials specified as part of the MinIO Root User secret to access the MinIO Server.

3) Connect to the Tenant

The MinIO Operator creates services for the MinIO Tenant. Use the oc get svc -n NAMESPACE command to review the deployed services:

oc get svc -n minio-tenant-1
NAME                               TYPE           CLUSTER-IP       EXTERNAL-IP   PORT(S)          AGE
minio                              LoadBalancer   10.97.114.60     <pending>     443:30979/TCP    2d3h
minio-tenant-1-console             LoadBalancer   10.106.103.247   <pending>     9443:32095/TCP   2d3h
minio-tenant-1-hl                  ClusterIP      None             <none>        9000/TCP         2d3h
minio-tenant-1-log-hl-svc          ClusterIP      None             <none>        5432/TCP         2d3h
minio-tenant-1-log-search-api      ClusterIP      10.103.5.235     <none>        8080/TCP         2d3h
minio-tenant-1-prometheus-hl-svc   ClusterIP      None             <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 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 Publishing Services (ServiceTypes) and Ingress for more complete information on configuring external access to services.

4) Forward Ports

You can temporarily expose each service using the oc port-forward utility. Run the following examples to forward traffic from the local host running oc to the services running inside the Kubernetes cluster.

oc port-forward service/minio 443:443
oc port-forward service/minio-tenant-1-console 9443:9443