From 8a71c3a86a67d4af428ccbda700a564a5411178f Mon Sep 17 00:00:00 2001 From: Daryl White <53910321+djwfyi@users.noreply.github.com> Date: Thu, 27 Apr 2023 17:11:28 -0500 Subject: [PATCH] Doc updates related to Opeartor v5.0.0 Partially addresses #791 --- .../deploy-minio-tenant.rst | 6 +- .../minio-operator-console.rst | 24 +-- .../upgrade-minio-operator.rst | 143 +++++++++++++++++- source/reference/kubectl-minio-plugin.rst | 65 ++++++++ .../kubectl-minio-proxy.rst | 15 +- 5 files changed, 235 insertions(+), 18 deletions(-) diff --git a/source/operations/install-deploy-manage/deploy-minio-tenant.rst b/source/operations/install-deploy-manage/deploy-minio-tenant.rst index adf421b4..e4d874c2 100644 --- a/source/operations/install-deploy-manage/deploy-minio-tenant.rst +++ b/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) ` settings for the MinIO Tenant. @@ -607,7 +607,7 @@ Enabling SSE also creates :minio-git:`MinIO Key Encryption Service ` 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 ` 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. diff --git a/source/operations/install-deploy-manage/minio-operator-console.rst b/source/operations/install-deploy-manage/minio-operator-console.rst index 74edc334..ceb5083a 100644 --- a/source/operations/install-deploy-manage/minio-operator-console.rst +++ b/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 -MinIO Tenants on the Kubernetes cluster. +The MinIO Operator Console supports deploying, managing, and monitoring 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 ` through the -Operator Console. +You can :ref:`deploy a MinIO Tenant ` through the Operator Console. -The Operator Console automatically detects any MinIO Tenants -deployed on the cluster, whether provisioned through the Operator Console -or through the :ref:`MinIO Kubernetes Plugin `. +The Operator Console automatically detects any MinIO Tenants deployed on the cluster, whether provisioned through the Operator Console or through the :ref:`MinIO Kubernetes Plugin `. 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 ``-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. + + If subscribed, you can upload this file to :ref:`SUBNET ` for analysis by MinIO Engineers. + Tenant Registration ------------------- -.. versionchanged:: 0.19.5 - - You can register your MinIO tenants with your |SUBNET| account using 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 diff --git a/source/operations/install-deploy-manage/upgrade-minio-operator.rst b/source/operations/install-deploy-manage/upgrade-minio-operator.rst index b58a9b50..5c97c934 100644 --- a/source/operations/install-deploy-manage/upgrade-minio-operator.rst +++ b/source/operations/install-deploy-manage/upgrade-minio-operator.rst @@ -25,8 +25,11 @@ The following table lists the upgrade paths from previous versions of the MinIO * - Current Version - Supported Upgrade Target - * - 4.2.3 and Later - - |operator-version-stable| + * - 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,7 +47,139 @@ 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.5.8 or later release to |operator-version-stable|. + +Breaking changes +~~~~~~~~~~~~~~~~ + +The following changes apply for Operator v5.0.0 or later: + +- The Operator's Graphical User Interface now comes bundled with the same container as the Operator. +- The ``.spec.s3`` field is replaced by the ``.spec.features`` field. +- The ``.spec.credsSecret`` field is replaced by the ``.spec.configuration`` field. + + This secret should hold all the environment variables for the MinIO deployment that contain sensitive information and should not show in ``.spec.env``. +- 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 CR 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. + +.. container:: procedure + + 1. Back up deployments + + .. 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 you are upgrading. + - Replace ``mynamespace`` with the namespace for the tenant you are upgrading. + + 2. Remove ``.metadata.ownerReferences`` for all backed up files + + 3. *(Optional)* To continue using Log Search API and Prometheus, add the following variables to ``.spec.env`` + + .. code-block:: shell + :class: copyable + + - name: MINIO_LOG_QUERY_AUTH_TOKEN + valueFrom: + secretKeyRef: + key: MINIO_LOG_QUERY_AUTH_TOKEN + name: -log-secret + - name: MINIO_LOG_QUERY_URL + value: http://-log-search-api:8080 + - name: MINIO_PROMETHEUS_JOB_ID + value: minio-job + - name: MINIO_PROMETHEUS_URL + value: http://-prometheus-hl-svc:9090 + + - Replace ```` with the name of your tenant. + + 4. *(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. + + 5. 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 ``. + + 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" + } + + 6. Download the Latest Stable Version of the MinIO Kubernetes Plugin + + .. include:: /includes/k8s/install-minio-kubectl-plugin.rst + + 7. 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 + + 8. 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 +--------------------------------------------------- + +.. admonition:: Prerequisites + :class: note + + 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 diff --git a/source/reference/kubectl-minio-plugin.rst b/source/reference/kubectl-minio-plugin.rst index c48bd128..a5f2e381 100644 --- a/source/reference/kubectl-minio-plugin.rst +++ b/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 ` uses the following environment variables during startup to set configuration settings. + + +.. 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 the 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 value 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 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: diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst index d5bd6d1d..28cef8d2 100644 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst +++ b/source/reference/kubectl-minio-plugin/kubectl-minio-proxy.rst @@ -29,6 +29,12 @@ This command is an alternative to configuring `Ingress