Doc updates related to Operator v5.0.0 (#837)

Updates docs for most changes through v5.0.4.
Does not have changes related to sidecar containers.

Partially addresses #791

Staged: http://192.241.195.202:9000/staging/operator-5.0.0/index.html

source/operations/install-deploy-manage/deploy-minio-tenant.rst

@@ -567,7 +567,7 @@ The :guilabel:`Security` section displays TLS certificate settings for the MinIO
 
 .. _create-tenant-encryption-section:
 
-1) The :guilabel:`Encryption` Section
+8) The :guilabel:`Encryption` Section
 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
 
 The :guilabel:`Encryption` section displays the :ref:`Server-Side Encryption (SSE) <minio-sse>` settings for the MinIO Tenant. 
@@ -607,7 +607,7 @@ Enabling SSE also creates :minio-git:`MinIO Key Encryption Service <kes>` pods i
    :start-after: start-deprecate-audit-logs
    :end-before: end-deprecate-audit-logs
 
-.. versionchanged:: Console 0.23.1
+.. versionchanged:: Console 0.23.1 and Operator 5.0.0
 
    New tenants have Audit Logs :guilabel:`Disabled` by default.
 
@@ -648,7 +648,7 @@ Enabling SSE also creates :minio-git:`MinIO Key Encryption Service <kes>` pods i
    :start-after: start-deprecate-prometheus
    :end-before: end-deprecate-prometheus
 
-.. versionchanged:: Console 0.23.1
+.. versionchanged:: Console 0.23.1 and Operator 5.0.0
 
    New tenants have monitoring :guilabel:`Disabled` by default.
 

source/operations/install-deploy-manage/minio-operator-console.rst

@@ -33,8 +33,7 @@ Connect to the Operator Console
 Tenant Management
 -----------------
 
-The MinIO Operator Console supports deploying, managing, and monitoring 
+The MinIO Operator Console supports deploying, managing, and monitoring MinIO Tenants on the Kubernetes cluster.
-MinIO Tenants on the Kubernetes cluster.
 
 .. image:: /images/k8s/operator-dashboard.png
    :align: center
@@ -42,22 +41,27 @@ MinIO Tenants on the Kubernetes cluster.
    :class: no-scaled-link
    :alt: MinIO Operator Console
 
-You can :ref:`deploy a MinIO Tenant <minio-k8s-deploy-minio-tenant>` through the 
+You can :ref:`deploy a MinIO Tenant <minio-k8s-deploy-minio-tenant>` through the Operator Console.
-Operator Console.
 
-The Operator Console automatically detects any MinIO Tenants 
+The Operator Console automatically detects MinIO Tenants deployed on the cluster when provisioned through the Operator Console, the :ref:`MinIO Kubernetes Plugin <minio-k8s-deploy-minio-tenant-commandline>`, Helm, or Kustomize.
-deployed on the cluster, whether provisioned through the Operator Console 
-or through the :ref:`MinIO Kubernetes Plugin <minio-k8s-deploy-minio-tenant-commandline>`.
 
 Select a listed tenant to open an in-browser view of that tenant's MinIO Console. 
 You can use this view to directly manage, modify, expand, upgrade, and delete the tenant through the Operator UI.
 
+.. versionadded:: Operator 5.0.0
+
+   You can download a Log Report for a tenant from the Pods summary screen.
+
+   The report downloads as ``<tenant-name>-report.zip``.
+   The ZIP archive contains status, events, and log information for each pool on the deployment.
+   The archive also includes a summary yaml file describing the deployment.
+
+   |subnet| users can upload this file for analysis by MinIO Engineers.
+
 Tenant Registration
 -------------------
 
-.. versionchanged:: 0.19.5
+|subnet| users relying on the commercial license should register your MinIO tenants to your SUBNET account, which can be done through the Operator Console.
-
-   You can register your MinIO tenants with your |SUBNET| account using the Operator Console.
 
 .. image:: /images/k8s/operator-console-register.png
    :align: center

source/operations/install-deploy-manage/upgrade-minio-operator.rst

@@ -25,9 +25,12 @@ The following table lists the upgrade paths from previous versions of the MinIO
    * - Current Version
      - Supported Upgrade Target
 
-   * - 4.2.3 and Later
+   * - 4.5.8 or later
      - |operator-version-stable| 
 
+   * - 4.2.3 to 4.5.7
+     - 4.5.8
+   
    * - 4.0.0 through 4.2.2
      - 4.2.3
 
@@ -36,7 +39,7 @@ The following table lists the upgrade paths from previous versions of the MinIO
 
 .. _minio-k8s-upgrade-minio-operator-procedure:
 
-Upgrade MinIO Operator 4.2.3 and Later to |operator-version-stable|
+Upgrade MinIO Operator 4.5.8 and Later to |operator-version-stable|
 -------------------------------------------------------------------
 
 .. admonition:: Prerequisites
@@ -44,13 +47,163 @@ Upgrade MinIO Operator 4.2.3 and Later to |operator-version-stable|
 
    This procedure requires the following:
 
-   - You have an existing MinIO Operator deployment running 4.2.3 or later
+   - You have an existing MinIO Operator deployment running 4.5.8 or later
    - Your Kubernetes cluster runs 1.19.0 or later
    - Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster
 
-This procedure upgrades the MinIO Operator from any 4.2.3 or later release to |operator-version-stable|.
+This procedure upgrades the MinIO Operator from any 4.5.8 or later release to |operator-version-stable|.
 
-.. container:: procedure
+Tenant Custom Resource Definition Changes
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The following changes apply for Operator v5.0.0 or later:
+
+- The ``.spec.s3`` field is replaced by the ``.spec.features`` field.
+- The ``.spec.credsSecret`` field is replaced by the ``.spec.configuration`` field.
+
+  The ``.spec.credsSecret`` should hold all the environment variables for the MinIO deployment that contain sensitive information and should not show in ``.spec.env``.
+  This change impacts the Tenant :abbr:`CRD <CustomResourceDefinition>` and only impacts users editing a tenant YAML directly, such as through Helm or Kustomize.
+- Both the **Log Search API** (``.spec.log``) and **Prometheus** (``.spec.prometheus``) deployments have been removed.
+  However, existing deployments are left running as standalone deployments / statefulsets with no connection to the Tenant CR.
+  If the Tenant CRD is deleted, this does not cascade to the log or Prometheus deployments.
+
+  .. important::
+
+     MinIO recommends that you create a yaml file to manage these deployments going forward.
+
+Log Search and Prometheus
+~~~~~~~~~~~~~~~~~~~~~~~~~
+
+The latest releases of Operator remove Log Search and Prometheus from included Operator tools.
+The following steps back up the existing yaml files, perform some clean up, and provide steps to continue using either or both of these functions.
+
+1. Back up Prometheus and Log Search yaml files.
+
+   .. code-block:: shell
+      :class: copyable
+
+      export TENANT_NAME=myminio
+      export NAMESPACE=mynamespace
+      kubectl -n $NAMESPACE get secret $TENANT_NAME-log-secret -o yaml > $TENANT_NAME-log-secret.yaml
+      kubectl -n $NAMESPACE get cm $TENANT_NAME-prometheus-config-map -o yaml > $TENANT_NAME-prometheus-config-map.yaml
+      kubectl -n $NAMESPACE get sts $TENANT_NAME-prometheus -o yaml > $TENANT_NAME-prometheus.yaml
+      kubectl -n $NAMESPACE get sts $TENANT_NAME-log -o yaml > $TENANT_NAME-log.yaml
+      kubectl -n $NAMESPACE get deployment $TENANT_NAME-log-search-api -o yaml > $TENANT_NAME-log-search-api.yaml
+      kubectl -n $NAMESPACE get svc $TENANT_NAME-log-hl-svc -o yaml > $TENANT_NAME-log-hl-svc.yaml
+      kubectl -n $NAMESPACE get svc $TENANT_NAME-log-search-api -o yaml > $TENANT_NAME-log-search-api.yaml
+      kubectl -n $NAMESPACE get svc $TENANT_NAME-prometheus-hl-svc -o yaml > $TENANT_NAME-prometheus-hl-svc.yaml
+
+   - Replace ``myminio`` with the name of the tenant on the operator deployment you are upgrading.
+   - Replace ``mynamespace`` with the namespace for the tenant on the operator deployment you are upgrading.
+
+   Repeat for each tenant.
+
+2. Remove ``.metadata.ownerReferences`` for all backed up files for all tenants.
+
+3. *(Optional)* To continue using Log Search API and Prometheus, add the following variables to the tenant's yaml specification file under ``.spec.env``
+
+   Use the following command to edit a tenant:
+
+   .. code-block:: shell
+      :class: copyable
+
+      kubectl edit tenants <TENANT-NAME> -n <TENANT-NAMESPACE>
+
+   - Replace ``<TENANT-NAME>`` with the name of the tenant to modify.
+   - Replace ``<TENANT-NAMESPACE>`` with the namespace of the tenant you are modifying.
+
+   Add the following values under ``.spec.env`` in the file:
+
+   .. code-block:: yaml
+      :class: copyable
+
+      - name: MINIO_LOG_QUERY_AUTH_TOKEN
+        valueFrom:
+          secretKeyRef:
+            key: MINIO_LOG_QUERY_AUTH_TOKEN
+            name: <TENANT_NAME>-log-secret
+      - name: MINIO_LOG_QUERY_URL
+        value: http://<TENANT_NAME>-log-search-api:8080
+      - name: MINIO_PROMETHEUS_JOB_ID
+        value: minio-job
+      - name: MINIO_PROMETHEUS_URL
+        value: http://<TENANT_NAME>-prometheus-hl-svc:9090
+
+   - Replace ``<TENANT_NAME>`` in the ``name`` or ``value`` lines with the name of your tenant.
+
+Upgrade Operator to |operator-version-stable|
+~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+
+1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version.
+ 
+   Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements.
+   Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants.
+   See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants.
+
+2. Verify the existing Operator installation.
+   Use ``kubectl get all -n minio-operator`` to verify the health and status of all Operator pods and services.
+   
+   If you installed the Operator to a custom namespace, specify that namespace as ``-n <NAMESPACE>``.
+
+   You can verify the currently installed Operator version by retrieving the object specification for an operator pod in the namespace.
+   The following example uses the ``jq`` tool to filter the necessary information from ``kubectl``:
+
+   .. code-block:: shell
+      :class: copyable
+
+      kubectl get pod -l 'name=minio-operator' -n minio-operator -o json | jq '.items[0].spec.containers'
+   
+   The output resembles the following:
+   
+   .. code-block:: json
+      :emphasize-lines: 8-10
+
+      {
+         "env": [
+            {
+               "name": "CLUSTER_DOMAIN",
+               "value": "cluster.local"
+            }
+         ],
+         "image": "minio/operator:v4.5.8",
+         "imagePullPolicy": "IfNotPresent",
+         "name": "minio-operator"
+      }
+
+3. Download the Latest Stable Version of the MinIO Kubernetes Plugin
+
+   .. include:: /includes/k8s/install-minio-kubectl-plugin.rst
+
+4. Run the initialization command to upgrade the Operator
+
+   Use the :mc-cmd:`kubectl minio init` command to upgrade the existing MinIO Operator installation
+
+   .. code-block:: shell
+      :class: copyable
+
+      kubectl minio init
+
+5. Validate the Operator upgrade
+
+   You can check the Operator version by reviewing the object specification for an Operator Pod using a previous step.
+   .. include:: /includes/common/common-k8s-connect-operator-console.rst
+
+Upgrade MinIO Operator 4.2.3 through 4.5.7 to 4.5.8
+---------------------------------------------------
+
+Prerequisites
+~~~~~~~~~~~~~
+
+This procedure requires the following:
+
+- You have an existing MinIO Operator deployment running 4.2.3 through 4.5.7
+- Your Kubernetes cluster runs 1.19.0 or later
+- Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster
+
+Procedure
+~~~~~~~~~
+
+This procedure upgrades the MinIO Operator from any 4.2.3 or later release to |operator-version-stable|.
 
 1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version.
 
@@ -115,8 +268,8 @@ This procedure upgrades the MinIO Operator from any 4.2.3 or later release to |o
 Upgrade MinIO Operator 4.0.0 through 4.2.2 to 4.2.3
 ---------------------------------------------------
 
-.. admonition:: Prerequisites
+Prerequisites
-   :class: note
+~~~~~~~~~~~~~
 
 This procedure assumes that:
 
@@ -124,17 +277,17 @@ Upgrade MinIO Operator 4.0.0 through 4.2.2 to 4.2.3
 - Your Kubernetes cluster runs 1.19.0 or later
 - Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster
 
+Procedure
+~~~~~~~~~
+
 This procedure covers the necessary steps to upgrade a MinIO Operator deployment running any release from 4.0.0 through 4.2.2 to 4.2.3.
 You can then perform :ref:`minio-k8s-upgrade-minio-operator-procedure` to complete the upgrade to |operator-version-stable|.
 
 There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-version-stable|.
 
-.. container:: procedure
-
 1. *(Optional)* Update each MinIO Tenant to the latest stable MinIO Version.
 
    Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements.
-
    Test upgrades in a lower environment such as a Dev or QA Tenant, before applying to your production Tenants.
 
    See :ref:`minio-k8s-upgrade-minio-tenant` for a procedure on upgrading MinIO Tenants.
@@ -154,7 +307,7 @@ There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-ver
    However, Tenants running pods as root may fail to start due to the security context mismatch.
    You can set an explicit Security Context that allows pods to run as root for those Tenants:
 
-      .. code-block:: shell
+   .. code-block:: yaml
       :class: copyable
 
       securityContext:
@@ -176,6 +329,7 @@ There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-ver
 
    Download the MinIO Kubernetes Plugin 4.2.3 and use it to upgrade the Operator.
    Open https://github.com/minio/operator/releases/tag/v4.2.3 in a browser and download the binary that corresponds to your local host OS.
+
    For example, Linux hosts running an Intel or AMD processor can run the following commands:
 
    .. code-block:: shell
@@ -183,7 +337,6 @@ There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-ver
 
       wget https://github.com/minio/operator/releases/download/v4.2.3/kubectl-minio_4.2.3_linux_amd64 -o kubectl-minio_4.2.3
       chmod +x kubectl-minio_4.2.3
-
       ./kubectl-minio_4.2.3 init
 
 #. Validate all Tenants and Operator pods
@@ -196,7 +349,6 @@ There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-ver
       :class: copyable
 
       kubectl get all -n minio-operator
-
       kubectl get pods -l "v1.min.io/tenant" --all-namespaces
 
 #. Upgrade to |operator-version-stable|
@@ -206,8 +358,8 @@ There is no direct upgrade path for 4.0.0 - 4.2.2 installations to |operator-ver
 Upgrade MinIO Operator 3.0.0 through 3.0.29 to 4.2.2
 ----------------------------------------------------
 
-.. admonition:: Prerequisites
+Prerequisites
-   :class: note
+~~~~~~~~~~~~~
 
 This procedure assumes that:
 
@@ -215,13 +367,14 @@ Upgrade MinIO Operator 3.0.0 through 3.0.29 to 4.2.2
 - Your Kubernetes cluster runs 1.19.0 or later
 - Your local host has ``kubectl`` installed and configured with access to the Kubernetes cluster
 
+Procedure
+~~~~~~~~~
+
 This procedure covers the necessary steps to upgrade a MinIO Operator deployment running any release from 3.0.0 through 3.2.9 to 4.2.2.
 You can then perform :ref:`minio-k8s-upgrade-minio-operator-4.2.2-procedure`, followed by :ref:`minio-k8s-upgrade-minio-operator-procedure`.
 
 There is no direct upgrade path from a 3.X.X series installation to |operator-version-stable|.
 
-.. container:: procedure
-
 1. (Optional) Update each MinIO Tenant to the latest stable MinIO Version.
 
    Upgrading MinIO regularly ensures your Tenants have the latest features and performance improvements.

source/reference/kubectl-minio-plugin.rst

@@ -89,6 +89,71 @@ Subcommands
 - :mc:`~kubectl minio delete`
 - :mc:`~kubectl minio version`
 
+Environment Variables
+---------------------
+
+The :ref:`MinIO Operator <minio-operator-installation>` uses the following environment variables during startup to set configuration settings.
+Configure these variables on the machine running the kubectl plugin.
+
+.. envvar:: MINIO_OPERATOR_CERTIFICATES_VERSION
+
+   Specifies the certificate API version to use.
+
+   Valid values are ``v1`` or ``v1beta1``.
+
+   When not specified, the default is the API Kubernetes provides.
+
+.. envvar:: MINIO_OPERATOR_RUNTIME
+
+   Specify the type of runtime to use.
+
+   Valid values are ``EKS``, ``Rancher``, or ``OpenShift``.
+   Leave blank if none of the options apply.
+
+   When set as ``EKS``, the :envvar:`MINIO_OPERATOR_CSR_SIGNER_NAME` must be ``beta.eks.amazonaws.com/app-serving``.
+
+.. envvar:: MINIO_OPERATOR_CSR_SIGNER_NAME
+
+   Override the default signer for certificate signing requests (CSRs).
+
+   When not specified, the default value is ``kubernetes.io/kubelet-serving``.
+
+.. envvar:: OPERATOR_CERT_PASSWD
+   
+   *Optional*
+
+   The password Operator should use to decrypt the private key in the TLS certificate for Operator.
+
+.. envvar:: MINIO_OPERATOR_DEPLOYMENT_NAME
+
+   Specifies the namespace to create and use for Operator
+
+   When not specified, the default value is ``minio-operator``.
+
+.. envvar:: OPERATOR_STS_ENABLED
+
+   Toggle STS Service ``on`` or ``off``.
+
+   When not specified, the default value is ``off``.
+
+.. envvar:: MINIO_CONSOLE_DEPLOYMENT_NAME
+
+   The name to use for the Operator Console.
+
+   When not specified, the default value is ``operator``.
+
+.. envvar:: OPERATOR_CONSOLE_TLS_ENABLE
+
+   Toggle Console TLS service ``on`` or ``off``.
+
+   When not specified, the default value is ``off``.
+
+.. envvar:: WATCHED_NAMESPACE
+
+   A comma-separated list of the namespace(s) Operator should watch for tenants.
+   
+   When not specified, the default value is ``""`` to watch all namespaces.
+
 .. toctree::
    :titlesonly:
    :hidden:

source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst

@@ -29,6 +29,12 @@ This command is an alternative to configuring `Ingress <https://kubernetes.io/do
    :start-after: start-kubectl-minio-requires-operator-desc
    :end-before: end-kubectl-minio-requires-operator-desc
 
+.. cond:: openshift
+
+   .. versionchanged:: Operator 5.0.0
+
+      The ``kubectl minio proxy`` command now supports retrieving the JWT for use with OpenShift deployments.
+
 Syntax
 ------
 
@@ -69,4 +75,11 @@ The command supports the following flags:
    :optional:
 
    The namespace for which to access the operator.
+
+   .. cond:: not openshift
+   
       Defaults to ``minio-operator``.
+
+   .. cond:: openshift
+
+      Defaults to ``openshift-operators``.