diff --git a/source/_static/scss/includes/_reset.scss b/source/_static/scss/includes/_reset.scss index fc01fdee..66c28507 100644 --- a/source/_static/scss/includes/_reset.scss +++ b/source/_static/scss/includes/_reset.scss @@ -299,7 +299,6 @@ ul { list-style-type: disc; } - // ---------------------- // Misc // ---------------------- @@ -316,4 +315,16 @@ abbr, acronym { dt:target, span.highlighted { background-color: transparent; +} + +// ---------------------- +// Container - Procedure +// ---------------------- + +.container.procedure { + padding: 0px; + + > ol > li > p:first-of-type { + font-weight: bold; + } } \ No newline at end of file diff --git a/source/images/k8s/operator-manage-tenant-update-minio-version.png b/source/images/k8s/operator-manage-tenant-update-minio-version.png new file mode 100644 index 00000000..bb3b3b12 Binary files /dev/null and b/source/images/k8s/operator-manage-tenant-update-minio-version.png differ diff --git a/source/includes/k8s/deploy-operator.rst b/source/includes/k8s/deploy-operator.rst index 7e0eb64c..9919f847 100644 --- a/source/includes/k8s/deploy-operator.rst +++ b/source/includes/k8s/deploy-operator.rst @@ -216,10 +216,8 @@ Operator Console. You can deploy a new :ref:`MinIO Tenant ` from the Operator Dashboard. -.. uncomment this block when upgrade operator procedure is complete +.. toctree:: + :titlesonly: + :hidden: - .. toctree:: - :titlesonly: - :hidden: - - /operations/install-deploy-manage/upgrade-minio-operator \ No newline at end of file + /operations/install-deploy-manage/upgrade-minio-operator \ No newline at end of file diff --git a/source/includes/k8s/install-minio-kubectl-plugin.rst b/source/includes/k8s/install-minio-kubectl-plugin.rst index b20d1762..aa908e34 100644 --- a/source/includes/k8s/install-minio-kubectl-plugin.rst +++ b/source/includes/k8s/install-minio-kubectl-plugin.rst @@ -36,7 +36,7 @@ You can install the MinIO plugin using either the Kubernetes Krew plugin manager :substitutions: :class: copyable - curl https://github.com/minio/operator/releases/download/|operator-version-stable|/kubectl-minio_|operator-version-stable|_linux_amd64 -o kubectl-minio + curl https://github.com/minio/operator/releases/download/v|operator-version-stable|/kubectl-minio_|operator-version-stable|_linux_amd64 -o kubectl-minio chmod +x kubectl-minio mv kubectl-minio /usr/local/bin/ diff --git a/source/operations/install-deploy-manage/upgrade-minio-operator.rst b/source/operations/install-deploy-manage/upgrade-minio-operator.rst index 68763092..26320d23 100644 --- a/source/operations/install-deploy-manage/upgrade-minio-operator.rst +++ b/source/operations/install-deploy-manage/upgrade-minio-operator.rst @@ -1,4 +1,3 @@ -:orphan: .. _minio-k8s-upgrade-minio-operator: ====================== @@ -11,6 +10,321 @@ Upgrade MinIO Operator :local: :depth: 1 +You can upgrade the MinIO Operator at any time without impacting your managed MinIO Tenants. -This page is currently under active redevelopment. -We will restore it to the TOC once that work is complete. \ No newline at end of file +As part of the upgrade process, the Operator may update and restart Tenants to support changes to the MinIO Custom Resource Definition (CRD). +These changes require no action on the part of any operator or administrator, and do not impact Tenant operations. + +The following table lists the upgrade paths from previous versions of the MinIO Operator: + +.. list-table:: + :header-rows: 1 + :widths: 40 40 + :width: 100% + + * - Current Version + - Supported Upgrade Target + + * - 4.2.3 and Later + - |operator-version-stable| + + * - 4.0.0 through 4.2.2 + - 4.2.3 + + * - 3.X.X + - 4.2.2 + +.. _minio-k8s-upgrade-minio-operator-procedure: + +Upgrade MinIO Operator 4.2.3 and Later to |operator-version-stable| +------------------------------------------------------------------- + +.. admonition:: Prerequisites + :class: note + + This procedure requires the following: + + - You have an existing MinIO Operator deployment running 4.2.3 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|. + +.. 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. + + #. 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.1", + "imagePullPolicy": "IfNotPresent", + "name": "minio-operator" + } + + #. Download the Latest Stable Version of the MinIO Kubernetes Plugin + + .. include:: /includes/k8s/install-minio-kubectl-plugin.rst + + #. 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 + + #. Validate the Operator upgrade + + You can check the Operator version by reviewing the object specification for an Operator Pod using a previous step. + + Use :mc-cmd:`kubectl minio proxy` to access the Operator Console and confirm the status of managed Tenants: + + .. code-block:: shell + :class: copyable + + kubectl minio proxy + +.. _minio-k8s-upgrade-minio-operator-4.2.2-procedure: + +Upgrade MinIO Operator 4.0.0 through 4.2.2 to 4.2.3 +--------------------------------------------------- + +.. admonition:: Prerequisites + :class: note + + This procedure assumes that: + + - You have an existing MinIO Operator deployment running any release from 4.0.0 through 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 + +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. + + #. Check the Security Context for each Tenant Pool + + Use the following command to validate the specification for each managed MinIO Tenant: + + .. code-block:: shell + :class: copyable + + kubectl get tenants -n -o yaml + + If the ``spec.pools.securityContext`` field does not exist for a Tenant, the tenant pods likely run as root. + + As part of the 4.2.3 and later series, pods run with a limited permission set enforced as part of the Operator upgrade. + 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 + :class: copyable + + securityContext: + runAsUser: 0 + runAsGroup: 0 + runAsNonRoot: false + fsGroup: 0 + + You can use the following command to edit the tenant and apply the changes: + + .. code-block:: shell + + kubectl edit tenants -n + # Modify the securityContext as needed + + See :kube-docs:`Pod Security Standards ` for more information on Kubernetes Security Contexts. + + #. Upgrade to Operator 4.2.3 + + 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 + :class: copyable + + 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 + + Check the Operator and MinIO Tenant namespaces to ensure all pods and services started successfully. + + For example: + + .. code-block:: shell + :class: copyable + + kubectl get all -n minio-operator + + kubectl get pods -l "v1.min.io/tenant" --all-namespaces + + #. Upgrade to |operator-version-stable| + + Follow the :ref:`minio-k8s-upgrade-minio-operator-procedure` procedure to upgrade to the latest stable Operator version. + +Upgrade MinIO Operator 3.0.0 through 3.0.29 to 4.2.2 +---------------------------------------------------- + +.. admonition:: Prerequisites + :class: note + + This procedure assumes that: + + - You have an existing MinIO Operator deployment running 3.X.X + - 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 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. + + 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. + + #. Validate the Tenant ``tenant.spec.zones`` values + + Use the following command to validate the specification for each managed MinIO Tenant: + + .. code-block:: shell + :class: copyable + + kubectl get tenants -n -o yaml + + - Ensure each ``tenant.spec.zones`` element has a ``name`` field set to the name for that zone. + Each zone must have a unique name for that Tenant, such as ``zone-0`` and ``zone-1`` for the first and second zones respectively. + + - Ensure each ``tenant.spec.zones`` has an explicit ``securityContext`` describing the permission set with which pods run in the cluster. + + The following example tenant YAML fragment sets the specified fields: + + .. code-block:: yaml + + image: "minio/minio:$(LATEST-VERSION)" + ... + zones: + - servers: 4 + name: "zone-0" + volumesPerServer: 4 + volumeClaimTemplate: + metadata: + name: data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Ti + securityContext: + runAsUser: 0 + runAsGroup: 0 + runAsNonRoot: false + fsGroup: 0 + - servers: 4 + name: "zone-1" + volumesPerServer: 4 + volumeClaimTemplate: + metadata: + name: data + spec: + accessModes: + - ReadWriteOnce + resources: + requests: + storage: 1Ti + securityContext: + runAsUser: 0 + runAsGroup: 0 + runAsNonRoot: false + fsGroup: 0 + + You can use the following command to edit the tenant and apply the changes: + + .. code-block:: shell + + kubectl edit tenants -n + + #. Upgrade to Operator 4.2.2 + + Download the MinIO Kubernetes Plugin 4.2.2 and use it to upgrade the Operator. + Open https://github.com/minio/operator/releases/tag/v4.2.2 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 + :class: copyable + + wget https://github.com/minio/operator/releases/download/v4.2.3/kubectl-minio_4.2.2_linux_amd64 -o kubectl-minio_4.2.2 + chmod +x kubectl-minio_4.2.2 + + ./kubectl-minio_4.2.2 init + + #. Validate all Tenants and Operator pods + + Check the Operator and MinIO Tenant namespaces to ensure all pods and services started successfully. + + For example: + + .. code-block:: shell + :class: copyable + + kubectl get all -n minio-operator + + kubectl get pods -l "v1.min.io/tenant" --all-namespaces + + #. Upgrade to 4.2.3 + + Follow the :ref:`minio-k8s-upgrade-minio-operator-4.2.2-procedure` procedure to upgrade to Operator 4.2.3. + You can then upgrade to |operator-version-stable|. diff --git a/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst b/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst index 5f955f6e..873598a8 100644 --- a/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst +++ b/source/reference/kubectl-minio-plugin/kubectl-minio-init.rst @@ -18,11 +18,13 @@ Description .. start-kubectl-minio-init-desc -The :mc:`kubectl minio init` command initializes the MinIO Operator. -:mc:`kubectl minio init` requires the operator for core functionality. +The :mc:`kubectl minio init` command initialize the MinIO Operator. .. end-kubectl-minio-init-desc +If the Kubernetes cluster has an existing MinIO Operator installation, this command upgrades the Operator to match the MinIO plugin version. +For more information on upgrading the MinIO Operator, see :ref:`minio-k8s-upgrade-minio-operator`. + Syntax ------ @@ -30,17 +32,12 @@ Syntax .. tab-item:: EXAMPLE - The following command initializes a new MinIO Operator deployment using operator v4.4.22, on the ``minio-operator`` namespace, using the cluster domain of ``cluster.local`` and watching the default namespace.: + The following command initializes a new MinIO Operator deployment running |operator-version-stable|. .. code-block:: shell :class: copyable - kubectl minio init \ - --image=minio/operator:v4.4.22 \ - --namespace=minio-operator \ - --cluster-domain=cluster.local \ - --namespace-to-watch=default \ - --image-pull-secret= + kubectl minio init .. tab-item:: SYNTAX