Update Operator documentation based on kubectl-minio plugin (#219)

minio · Aug 31, 2020 · 97cc990 · 97cc990
1 parent dcefedf
commit 97cc990
Show file tree

Hide file tree

Showing 21 changed files with 495 additions and 543 deletions.
diff --git a/README.md b/README.md
@@ -1,68 +1,82 @@
-# MinIO Operator Guide [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/k8s-operator.svg?maxAge=604800)](https://hub.docker.com/r/minio/k8s-operator)
+# MinIO Operator [![Docker Pulls](https://img.shields.io/docker/pulls/minio/k8s-operator.svg?maxAge=604800)](https://hub.docker.com/r/minio/k8s-operator)
 
-MinIO is a high performance distributed object storage server, designed for large-scale private cloud infrastructure. MinIO is designed in a cloud-native manner to scale sustainably in multi-tenant environments. Orchestration platforms like Kubernetes provide perfect launchpad for MinIO to scale.
+MinIO Operator brings native support for [MinIO](https://github.com/minio/minio), [Graphical Console](https://github.com/minio/console), and [Encryption](https://github.com/minio/kes) to Kubernetes. This document explains how to get started with MinIO Operator using `kubectl minio` plugin.
 
-MinIO-Operator brings native MinIO, [Console](https://github.com/minio/console), and [KES](https://github.com/minio/kes) support to Kubernetes. MinIO-Operator currently supports following features:
+## Prerequisites
 
-| Feature                 | Reference Document |
-|-------------------------|--------------------|
-| Create and delete highly available distributed MinIO clusters  | [Create a MinIO Tenant](https://github.com/minio/operator#create-a-minio-tenant). |
-| TLS Configuration  | [TLS for MinIO Tenant](https://github.com/minio/operator/blob/master/docs/tls.md). |
-| Expand an existing MinIO cluster | [Expand a MinIO Cluster](https://github.com/minio/operator/blob/master/docs/adding-zones.md). |
-| Use a custom template for hostname discovery | [Custom Hostname Discovery](https://github.com/minio/operator/blob/master/docs/custom-name-templates.md). |
-| Use PodSecurityPolicy for MinIO Pods | [Apply PodSecurityPolicy](https://github.com/minio/operator/blob/master/docs/pod-security-policy.md). |
-| Deploy Console with MinIO cluster  | [Deploy MinIO Tenant with Console](https://github.com/minio/operator/blob/master/docs/console.md). |
-| Deploy KES with MinIO cluster  | [Deploy MinIO Tenant with KES](https://github.com/minio/operator/blob/master/docs/kes.md). |
+- Kubernetes >= v1.17.0.
+- Create PVs. We recommend [direct CSI driver](https://github.com/minio/operator/blob/master/docs/using-direct-csi.md) for PV creation.
+- Install [`kubectl minio` plugin](https://github.com/minio/operator/tree/master/kubectl-minio#install-plugin).
 
-## Getting Started
+## Operator Setup
 
-### Prerequisites
+MinIO Operator offers MinIO Tenant creation, management, upgrade, zone addition and more. Operator is meant to control and manage multiple MinIO Tenants.
 
-- Kubernetes version v1.17.0 and above for compatibility. MinIO Operator uses `k8s/client-go` v0.18.0.
-- `kubectl` configured to refer to a Kubernetes cluster.
-- Create the required PVs using [direct CSI driver](https://github.com/minio/operator/blob/master/docs/using-direct-csi.md).
-- Optional: `kustomize` installed as [explained here](https://github.com/kubernetes-sigs/kustomize/blob/master/docs/INSTALL.md#installation).
+To get started, create the MinIO Operator deployment. This is a _one time_ process.
 
-### Create Operator Deployment
+```sh
+kubectl minio operator create
+```
 
-To start MinIO-Operator with default configuration, use the `kubectl apply -k` on this repository.
+Once the MinIO Operator is created, proceed with Tenant creation.
 
-```bash
-kubectl apply -k github.com/minio/operator
-```
+## Tenant Setup
+
+A Tenant is a MinIO cluster created and managed by the Operator.
+
+### Step 1: Create Tenant Namespace
 
-Advanced users can leverage [kustomize](https://github.com/kubernetes-sigs/kustomize) to customize operator configuration via overlays.
+Before creating a Tenant, please create the namespace where this Tenant will reside.
 
-```bash
-git clone https://github.com/minio/operator
-kustomize build | kubectl apply -f -
+For logical isolation, Operator allows a single Tenant per Kubernetes Namespace.
+
+```sh
+kubectl create ns tenant1-ns
 ```
 
-### Create a MinIO Tenant
+### Step 2: Create Secret for Tenant Credentials
+
+Next, create the Kubernetes secret that encapsulates root credentials for MinIO Tenant. Please ensure to create secret object with literals `accesskey` and `secretkey`.
 
-Once MinIO-Operator deployment is running, you can create MinIO Tenants using the below command
+Remember to change `YOUR-ACCESS-KEY` and `YOUR-SECRET-KEY` to actual values.
 
+```sh
+kubectl create secret generic tenant1-secret --from-literal=accesskey=YOUR-ACCESS-KEY --from-literal=secretkey=YOUR-SECRET-KEY --namespace tenant1-ns
 ```
-kubectl apply -f https://raw.githubusercontent.com/minio/operator/master/examples/tenant.yaml
+
+Note that the access key and secret key provided here is authorized to perform _all_ operations on the Tenant.
+
+### Step 3: Create MinIO Tenant
+
+We can create the Tenant now. Before that, please ensure you have requisite nodes and drives in place and relevant PVs are created. In below example, we ask MinIO Operator to create a Tenant with 4 nodes, 16 volumes, and 16 Ti total raw capacity (4 volumes of 1 Ti per node). This means you need to have 4 PVCs of 1 Ti each, per node, and total of 4 nodes, before attempting to create the MinIO Tenant.
+
+We recommend [direct CSI driver](https://github.com/minio/operator/blob/master/docs/using-direct-csi.md) to create PVs.
+
+```sh
+kubectl minio tenant create --name tenant1 --secret tenant1-secret --servers 4 --volumes 16 --capacity 16Ti --namespace tenant1-ns --storageclass direct.csi.min.io
 ```
 
-### Access Tenant via Service
+## Post Tenant Creation
+
+### Expanding a Tenant
 
-Add an [external service](https://kubernetes.io/docs/concepts/services-networking/service/) in Tenant definition to enable Service based access to the Tenant pods. Refer [the example here](https://github.com/minio/operator/blob/master/examples/tenant.yaml?raw=true) for details on how to setup service based access for Tenant pods.
+You can add capacity to the tenant using `kubectl minio` plugin, like this
+
+```
+kubectl minio tenant volumes add --name tenant1 --servers 8 --volumes 32 --capacity 32Ti --namespace tenant1-ns
+```
 
-### Environment variables
+This will add 32 drives spread uniformly over 8 servers to the tenant `tenant1`, with additional capacity of 32Ti. Read more about [tenant expansion here](https://github.com/minio/operator/blob/master/docs/expansion.md).
 
-These variables may be passed to operator Deployment in order to modify some of its parameters
+## License
 
-| Name                | Default | Description                                                                                                                   |
-| ---                 | ---     | ---                                                                                                                           |
-| `CLUSTER_DOMAIN`    | `cluster.local` | Cluster Domain of the Kubernetes cluster |
-| `WATCHED_NAMESPACE` | `-` | If set, the operator will watch for Tenant (tenant.minio.min.io) resources in specified namespace only. If empty, operator will watch all namespaces. |
+Use of MinIO Operator is governed by the GNU AGPLv3 or later, found in the [LICENSE](./LICENSE) file.
 
 ## Explore Further
 
-- [MinIO Erasure Code QuickStart Guide](https://docs.min.io/docs/minio-erasure-code-quickstart-guide)
-- [Use `mc` with MinIO Server](https://docs.min.io/docs/minio-client-quickstart-guide)
-- [Use `aws-cli` with MinIO Server](https://docs.min.io/docs/aws-cli-with-minio)
-- [The MinIO documentation website](https://docs.min.io)
-- Expose MinIO via Istio: Istio >= 1.4 has support for headless Services, so instead of creating an explicit `Service` for the created MinIO Tenant, you can also directly target the headless Service that is created by the operator. Use [Istio Ingress Gateway](https://istio.io/latest/docs/tasks/traffic-management/ingress/ingress-control/) to configure Istio to expose the MinIO service outside of the service mesh.
+- [Create a MinIO Tenant](https://github.com/minio/operator#create-a-minio-instance).
+- [TLS for MinIO Tenant](https://github.com/minio/operator/blob/master/docs/tls.md).
+- [Custom Hostname Discovery](https://github.com/minio/operator/blob/master/docs/custom-name-templates.md).
+- [Apply PodSecurityPolicy](https://github.com/minio/operator/blob/master/docs/pod-security-policy.md).
+- [Deploy MinIO Tenant with Console](https://github.com/minio/operator/blob/master/docs/console.md).
+- [Deploy MinIO Tenant with KES](https://github.com/minio/operator/blob/master/docs/kes.md).
diff --git a/docs/adding-zones.md b/docs/adding-zones.md
diff --git a/docs/console.md b/docs/console.md
@@ -1,21 +1,30 @@
-# MinIO Operator Console Configuration
-
-[![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
-[![Docker Pulls](https://img.shields.io/docker/pulls/minio/k8s-operator.svg?maxAge=604800)](https://hub.docker.com/r/minio/k8s-operator)
+# Console Configuration [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/k8s-operator.svg?maxAge=604800)](https://hub.docker.com/r/minio/k8s-operator)
 
 This document explains how to enable Console with MinIO Operator.
 
 ## Getting Started
 
 ### Prerequisites
 
-- MinIO Operator up and running as explained in the [document here](https://github.com/minio/operator#create-operator-and-related-resources).
+- MinIO Operator up and running as explained in the [document here](https://github.com/minio/operator#operator-setup).
+- Install [`kubectl minio` plugin](https://github.com/minio/operator/tree/master/kubectl-minio#install-plugin).
+
+### Create MinIO Tenant
+
+Use `kubectl minio` plugin to create the MinIO tenant with console enabled:
+
+```
+kubectl create ns tenant1-ns
+kubectl create secret generic tenant1-secret --from-literal=accesskey=YOUR-ACCESS-KEY --from-literal=secretkey=YOUR-SECRET-KEY --namespace tenant1-ns
+kubectl create -f https://raw.githubusercontent.com/minio/operator/master/examples/console-secret.yaml --namespace tenant1-ns
+kubectl minio tenant create --name tenant1 --secret tenant1-secret --servers 4 --volumes 16 --capacity 16Ti --namespace tenant1-ns --console-secret console-secret
+```
 
-### Enable Console Configuration
+## Console Configuration
 
-Console Configuration is a part of Tenant yaml file. Check the sample file [available here](https://raw.githubusercontent.com/minio/operator/master/examples/tenant-console.yaml). The config offers below options
+Console Configuration is a part of Tenant yaml file. Check the sample file [available here](https://raw.githubusercontent.com/minio/operator/master/examples/tenant.yaml). The config offers below options
 
-#### Console Fields
+### Console Fields
 
 | Field                 | Description |
 |-----------------------|-------------|
@@ -24,30 +33,3 @@ Console Configuration is a part of Tenant yaml file. Check the sample file [avai
 | spec.console.replicas | Number of MinIO Console pods to be created. |
 | spec.console.consoleSecret | Use this secret to assign console credentials to Tenant. |
 | spec.console.metadata | This allows a way to map metadata to the console container. Internally `metadata` is a struct type as [explained here](https://godoc.org/k8s.io/apimachinery/pkg/apis/meta/v1#ObjectMeta). |
-
-### Create MinIO Instance
-
-Once you have updated the yaml file per your requirement, use `kubectl` to create the MinIO instance like
-
-```
-kubectl create -f examples/tenant-console.yaml
-```
-
-Alternatively, you can deploy the example like this
-
-```
-kubectl create -f https://raw.githubusercontent.com/minio/operator/master/examples/tenant-console.yaml
-```
-
-Above example file uses CSR for self signed certificate generation. MinIO requires one certificates/key pair 
-
-- X.509 certificate for the MinIO server and the corresponding private key.
-
-Accordingly, you'll need to approve the CSR request, using below approach
-
-```
-kubectl get csr
-kubectl certificate approve <csr-name>
-```
-
-Once all the CSRs are approved, MinIO Operator will deploy Console Pods and start MinIO Server with Console integration.
diff --git a/docs/custom-name-templates.md b/docs/custom-name-templates.md
@@ -1,28 +1,24 @@
-# Custom Hostname Discovery
+# Custom Hostname Discovery [![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io) [![Docker Pulls](https://img.shields.io/docker/pulls/minio/k8s-operator.svg?maxAge=604800)](https://hub.docker.com/r/minio/k8s-operator)
 
-[![Slack](https://slack.min.io/slack?type=svg)](https://slack.min.io)
-[![Docker Pulls](https://img.shields.io/docker/pulls/minio/k8s-operator.svg?maxAge=604800)](https://hub.docker.com/r/minio/k8s-operator)
-
-This document explains how to control the names used for host discovery.  This allows us to discover hosts using external name services, which is useful for serving with trusted certificates.
+This document explains how to control the names used for host discovery. This allows us to discover hosts using external name services, which is useful for serving with trusted certificates.
 
 ## Getting Started
 
-Assuming you have a MinIO cluster with single zone, `zone-0` with 4 drives (as shown in [examples](https://github.com/minio/operator/tree/master/examples)). You can dd a new zone `zone-1` with 4 drives using `kubectl patch` command.
-
-The example cluster is named minio, so the four servers will be called `minio-0`, `minio-1`, `minio-2`, and `minio-3`.  If all of your hosts are available at the domain `example.com` then you can use the `--hosts-template` flag to update discovery:
+If MinIO Tenant is named `tenant1`, then the four servers will be called `tenant1-zone-0-0`, `tenant1-zone-0-1`, `tenant1-zone-0-2`, and `tenant1-zone-0-3`.  If all of your hosts are available at the domain `example.com` then you can use the `--hosts-template` flag in [MinIO Operator Deployment yaml](https://github.com/minio/operator/blob/master/minio-operator.yaml) to update discovery. This will generate the discovery string `tenant1-zone-0-{0...3}.example.com`.
 
-```
+```yaml
   containers:
   - command:
     - /operator
     - --hosts-template
     - '{{.StatefulSet}}-{{.Ellipsis}}.example.com'
 ```
 
-This will generate the discovery string `minio-{0...3}.example.com`.  The following fields are available
+The following fields can be configured:
+
 | Field                 | Description |
 |-----------------------|-------------|
-| StatefulSet | The name of the instance StatefulSet (e.g. `minio`). |
+| StatefulSet | The name of the tenant StatefulSet (e.g. `minio`). |
 | CIService | The name of the service provided in `spec.serviceName`. |
 | HLService | The name of the headless service that is generated (e.g. `minio-hl-service`) |
 | Ellipsis | `{0...N-1}` the per-zone host numbers. |