diff --git a/requirements.txt b/requirements.txt index 2ac67f23..a44495f8 100644 --- a/requirements.txt +++ b/requirements.txt @@ -2,4 +2,5 @@ sphinx == 3.1.2 sphinx-copybutton == 0.2.12 git+https://github.com/ravindk89/sphinx-tabs recommonmark == 0.6.0 -sphinx-markdown-tables == 0.0.15 \ No newline at end of file +sphinx-markdown-tables == 0.0.15 +Sphinx-Substitution-Extensions == 2020.9.30.0 \ No newline at end of file diff --git a/source/conf.py b/source/conf.py index fae11481..ebb0259c 100644 --- a/source/conf.py +++ b/source/conf.py @@ -42,6 +42,8 @@ extensions = [ 'sphinx_tabs.tabs', 'recommonmark', 'sphinx_markdown_tables', + 'sphinx-prompt', + 'sphinx_substitution_extensions' ] # -- External Links @@ -53,7 +55,7 @@ extlinks = { 'kube-docs' : ('https://kubernetes.io/docs/%s', ''), 'minio-git' : ('https://github.com/minio/%s',''), 'github' : ('https://github.com/%s',''), - 'kube-api' : ('https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.18/%s',''), + 'kube-api' : ('https://kubernetes.io/docs/reference/generated/kubernetes-api/v1.19/%s',''), 'aws-docs' : ('https://docs.aws.amazon.com/%s',''), 's3-docs' : ('https://docs.aws.amazon.com/AmazonS3/latest/dev/%s',''), 's3-api' : ('https://docs.aws.amazon.com/AmazonS3/latest/API/%s',''), @@ -110,8 +112,14 @@ html_title = 'MinIO Documentation' rst_epilog = """ -.. |minio-operator-release| replace:: ``minio/k8s-operator:v3.0.27`` +.. |minio-operator-release| replace:: ``minio/k8s-operator:v3.0.28`` .. |minio-server-release| replace:: ``minio/minio:RELEASE.2020-10-03T02-19-42Z`` +""" + +rst_prolog = """ + +.. |minio-operator-latest-version| replace:: v3.0.28 + """ \ No newline at end of file diff --git a/source/includes/common-minio-kubernetes.rst b/source/includes/common-minio-kubernetes.rst new file mode 100644 index 00000000..d5717c7a --- /dev/null +++ b/source/includes/common-minio-kubernetes.rst @@ -0,0 +1,83 @@ +.. default-domain:: minio + +.. start-kubeapi-customresourcedefinition + +See the Kubernetes API reference on +:kube-api:`CustomResourceDefinition +<#customresourcedefinition-v1-apiextensions-k8s-io>` objects for more complete +documentation on this field. + +.. end-kubeapi-customresourcedefinition + +.. start-kubeapi-objectmeta + +See the Kubernetes API reference on :kube-api:`ObjectMeta <#objectmeta-v1-meta>` +objects for more complete documentation on this field. + +.. end-kubeapi-objectmeta + +.. start-kubeapi-envvar + +See the Kubernetes API reference on :kube-api:`EnvVar<#envvar-v1-core>` objects +for more complete documentation on this field. + +.. end-kubeapi-envvar + +.. start-kubeapi-nodeselector + +See the Kubernetes API reference on +:kube-api:`NodeSelector <#nodeselector-v1-core>` objects for more complete +documentation on this field. + +.. end-kubeapi-nodeselector + +.. start-kubeapi-resources + +See the Kubernetes API reference on :kube-api:`ResourceRequirements +<#resourcerequirements-v1-core>` objects for more complete documentation on +this field. + +.. end-kubeapi-resources + +.. start-kubeapi-securitycontext + +See the Kubernetes API reference on :kube-api:`PodSecurityContext +<#podsecuritycontext-v1-core>` for more complete documentation on this field. + +.. end-kubeapi-securitycontext + +.. start-kubeapi-podmanagementpolicy + +See the Kubernetes API reference on :kube-api:`StatefulSetSpec +<#statefulsetspec-v1-apps>` for more complete documentation on this field. + +.. end-kubeapi-podmanagementpolicy + +.. start-kubeapi-priorityclassname + +See the Kubernetes API reference on :kube-api:`PodSpec <#podspec-v1-core>` +for more complete documentation on this field. + +.. end-kubeapi-priorityclassname + +.. start-kubeapi-affinity + +See the Kubernetes API reference on :kube-api:`Affinity <#affinity-v1-core>` +for more complete documentation on this field. + +.. end-kubeapi-affinity + +.. start-kubeapi-tolerations + +See the Kubernetes API reference on :kube-api:`Toleration <#toleration-v1-core>` +for more complete documentation on this field. + +.. end-kubeapi-toleartions + +.. start-kubeapi-persistentvolumeclaimspec + +See the Kubernetes API reference on +:kube-api:`PersistentVolumeClaimSpec <#persistentvolumeclaimspec-v1-core>` +for more complete documentation on this field. + +.. end-kubeapi-persistentvolumeclaimspec \ No newline at end of file diff --git a/source/kubernetes/minio-kubernetes-overview.rst b/source/kubernetes/minio-kubernetes-overview.rst index f4c57ba3..f3756dda 100644 --- a/source/kubernetes/minio-kubernetes-overview.rst +++ b/source/kubernetes/minio-kubernetes-overview.rst @@ -871,4 +871,10 @@ Delete a MinIO Tenant The namespace in which to look for the MinIO Tenant. - Defaults to ``minio``. \ No newline at end of file + Defaults to ``minio``. + +.. toctree:: + :hidden: + :titlesonly: + + /kubernetes/minio-operator-reference \ No newline at end of file diff --git a/source/kubernetes/minio-operator-reference.rst b/source/kubernetes/minio-operator-reference.rst index 5bf40495..8212cea8 100644 --- a/source/kubernetes/minio-operator-reference.rst +++ b/source/kubernetes/minio-operator-reference.rst @@ -27,10 +27,38 @@ and managing MinIO Tenants. Deploying the MinIO Operator ---------------------------- -You can use :github:`kustomize ` to deploy the -MinIO Operator to a Kubernetes cluster: +The following operations deploy the MinIO operator using ``kustomize`` +templates. Users who would prefer a more simplified deployment experience +that does *not* require familiarity with ``kustomize`` should use the +:ref:`minio-kubernetes` for deploying and managing MinIO Tenants. + +.. tabs:: + + .. tab:: ``kubectl`` + + Use the following command to deploy the MinIO Operator using + ``kubectl`` and ``kustomize`` templates: + + .. code-block:: + :class: copyable + :substitutions: + + kubectl apply -k github.com/minio/operator/\?ref\=|minio-operator-latest-version| + + .. tab:: ``kustomize`` + + + Use :github:`kustomize ` to deploy the + MinIO Operator using ``kustomize`` templates: + + .. code-block:: + :class: copyable + :substitutions: + + kustomize build github.com/minio/operator/\?ref\=|minio-operator-latest-version| \ + > minio-operator-|minio-operator-latest-version|.yaml + - MinIO Tenant Object ------------------- @@ -40,7 +68,7 @@ following resources: - 4 :mc:`minio` server processes. - 4 Volumes per server. -- 2 MinIO Console Service (MCS) proccesses. +- 2 MinIO Console Service (MCS) processes. .. ToDo : - 2 MinIO Key Encryption Service (KES) processes. @@ -96,8 +124,8 @@ following resources: volumesPerServer: 4 -MinIO Specification Syntax --------------------------- +MinIO Operator ``YAML`` Reference +--------------------------------- The MinIO Operator adds a :kube-api:`CustomResourceDefinition @@ -106,96 +134,1088 @@ Kubernetes Object API to support creating MinIO ``Tenant`` objects. .. tabs:: - .. tab:: ``Tenant`` Object Overview + .. tab:: All Top-Level Fields The following ``YAML`` block describes a MinIO Tenant object and its top-level fields. - .. code-block:: yaml + .. parsed-literal:: - apiVersion: minio.min.io/v1 - kind: Tenant - metadata: - name: minio - labels: + :kubeconf:`apiVersion`: minio.min.io/v1 + :kubeconf:`kind`: Tenant + :kubeconf:`metadata`: + :kubeconf:`~metadata.name`: minio + :kubeconf:`~metadata.namespace`: + :kubeconf:`~metadata.labels`: app: minio - annotations: + :kubeconf:`~metadata.annotations`: prometheus.io/path: prometheus.io/port: "" prometheus.io/scrape: "" - spec: + :kubeconf:`spec`: + :kubeconf:`~spec.certConfig`: + :kubeconf:`~spec.console`: + :kubeconf:`~spec.credsSecret`: + :kubeconf:`~spec.env`: + :kubeconf:`~spec.externalCertSecret`: + :kubeconf:`~spec.externalClientCertSecret`: + :kubeconf:`~spec.image`: minio/minio:latest + :kubeconf:`~spec.imagePullPolicy`: IfNotPresent + :kubeconf:`~spec.kes`: + :kubeconf:`~spec.mountPath`: + :kubeconf:`~spec.podManagementPolicy`: + :kubeconf:`~spec.priorityClassName`: + :kubeconf:`~spec.requestAutoCert`: + :kubeconf:`~spec.s3`: + :kubeconf:`~spec.securityContext`: + :kubeconf:`~spec.serverSet`: + :kubeconf:`~spec.serviceAccountName`: + :kubeconf:`~spec.subPath`: + :kubeconf:`~spec.serverSet`: - certConfig: - console: - credsSecret: - env: - externalCertSecret: - externalClientCertSecret: - image: minio/minio:latest - imagePullPolicy: IfNotPresent - kes: - mountPath: - podManagementPolicy: - priorityClassName: - requestAutoCert: - s3: - securityContext: - serviceAccountName: - subPath: - zones: - - Select the - :guilabel:`YAML Field Description` tab for a more detailed description of - each field. + .. tab:: Minimum Required Fields - .. tab:: YAML Field Description + Minimum Required Fields - The following table describes each top-level field in the MinIO Tenant - object. + .. parsed-literal:: - .. list-table:: - :header-rows: 1 - :widths: 30 10 60 - :width: 100% - - * - Field - - - | Required / - | Recommended / - | Optional - - - Description - - * - foo - - bar - - baz - - Select the :guilabel:`Tenant Object Description` tab - for an example of the YAML object file. + :kubeconf:`apiVersion`: minio.min.io/v1 + :kubeconf:`kind`: Tenant + :kubeconf:`metadata`: + :kubeconf:`~metadata.name`: minio + :kubeconf:`~metadata.labels`: + app: minio + :kubeconf:`spec`: + :kubeconf:`~spec.serverSet` : + - :kubeconf:`~spec.serverSet.servers` : + :kubeconf:`~spec.serverSet.volumeClaimTemplate`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.accessModes`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.resources`: + requests: + storage: + :kubeconf:`~spec.serverSet.volumesPerServer`: + + +Core Fields +~~~~~~~~~~~ + +The following fields describe the core settings used to deploy a MinIO Tenant. + +.. parsed-literal:: + + :kubeconf:`apiVersion`: minio.min.io/v1 + :kubeconf:`kind`: Tenant + :kubeconf:`metadata`: + :kubeconf:`~metadata.name`: + :kubeconf:`~metadata.namespace`: + :kubeconf:`~metadata.labels`: + app: minio + :kubeconf:`~metadata.annotations`: + - prometheus.io/path: + - prometheus.io/port: + - prometheus.io/scrape: + :kubeconf:`spec`: + :kubeconf:`~spec.credsSecret`: + :kubeconf:`~spec.env`: + + :kubeconf:`~spec.serverSet`: + - :kubeconf:`~spec.serverSet.affinity`: + :kubeconf:`~spec.serverSet.name`: + :kubeconf:`~spec.serverSet.nodeSelector`: + :kubeconf:`~spec.serverSet.resources`: + :kubeconf:`~spec.serverSet.servers`: + :kubeconf:`~spec.serverSet.tolerations`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate`: + :kubeconf:`~spec.serverSet.volumesPerServer`: + +.. kubeconf:: apiVersion + + *Required* + + The API Version of the MinIO Tenant Object. + + Specify ``minio.min.io/v1``. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-customresourcedefinition + :end-before: end-kubeapi-customresourcedefinition + +.. kubeconf:: kind + + *Required* + + The REST resource the object represents. Specify ``Tenant``. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-customresourcedefinition + :end-before: end-kubeapi-customresourcedefinition + +.. kubeconf:: metadata + + The root field for describing metadata related to the Tenant object. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-objectmeta + :end-before: end-kubeapi-objectmeta + +.. kubeconf:: metadata.name + + *Required* + + The name of the Tenant resource. The name *must* be unique within the + target namespace. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-objectmeta + :end-before: end-kubeapi-objectmeta + +.. kubeconf:: metadata.namespace + + *Required* + + The namespace in which Kubernetes deploys the Tenant resource. + Omit to use the "Default" namespace. MinIO recommends creating a namespace + for each MinIO Tenant deployed in the Kubernetes cluster. + +.. kubeconf:: metadata.labels + + The Kubernetes :kube-docs:`labels + ` to apply to the + MinIO Tenant Object. + + Specify *at minimum* the following key-value pair: + + .. code-block:: yaml + :class: copyable + + metadata: + labels: + app: minio + +.. kubeconf:: metadata.annotations + + One or more Kubernetes :kube-docs:`annotations ` to + associate with the MinIO Tenant Object. + + MinIO Tenants support the following annotations: + + - ``prometheus.io/path: `` + + - ``prometheus.io/port: `` + + - ``prometheus.io/scrape: `` + +.. kubeconf:: spec + + The root field for the MinIO Tenant Specification. + +.. kubeconf:: spec.credsSecret + + The Kubernetes secret containing values to use for setting the MinIO access + key (:envvar:`MINIO_ACCESS_KEY`) and secret key (:envvar:`MINIO_SECRET_KEY`). + The MinIO Operator automatically generates the secret along with values for + the access and secret key if this field is omitted. + + Specify an object where the ``name`` field contains the name of the + Kubernetes secret to use: + + .. code-block:: yaml + + spec: + credsSecret: + name: minio-secret + + The Kubernetes secret should contain the following values: + + - ``data.accesskey`` - the Access Key for each :mc:`minio` server in the + Tenant. + + - ``data.secretkey`` - the Secret Key for each :mc:`minio` server in the + Tenant. + +.. kubeconf:: spec.env + + The environment variables available for use by the MinIO Tenant. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-envvar + :end-before: end-kubeapi-envvar + + +.. kubeconf:: spec.mountPath + + *Optional* + + The mount path for Persistent Volumes bound to :mc:`minio` pods in the + MinIO Tenant. + + Defaults to ``/export``. + + + +.. kubeconf:: spec.s3 + + *Optional* + + The S3-related features enabled on the MinIO Tenant. + + Specify any of the following supported features as part of the + :kubeconf:`~spec.s3` object: + + - ``bucketDNS: `` - specify ``true`` to enable DNS lookup of + buckets on the MinIO Tenant. + + + +.. kubeconf:: spec.subPath + + *Optional* + + The sub path appended to the :kubeconf:`spec.mountPath`. The resulting + full path is the directory in which MinIO stores data. + + For example, given a :kubeconf:`~spec.mountPath` of ``export`` and + a :kubeconf:`~spec.subPath` of ``minio``, the full mount path is + ``export/minio``. + + Defaults to empty (``""``). + +.. kubeconf:: spec.serverSet + + *Required* + + The configuration for each MinIO Server Set deployed in the MinIO Tenant. A + Server Set consists of one or more :mc:`minio` servers. + + Each element in the :kubeconf:`~spec.serverSet` array is an object that *must* + contain the following fields: + + - :kubeconf:`~spec.serverSet.servers` + - :kubeconf:`~spec.serverSet.volumeClaimTemplate` + - :kubeconf:`~spec.serverSet.volumesPerServer` + + :kubeconf:`~spec.serverSet` must have *at least* one element in the array. + +.. kubeconf:: spec.serverSet.affinity + + *Optional* + + The configuration for node affinity, pod affinity, and pod anti-affinity + applied to each pod in the Server Set. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-affinity + :end-before: end-kubeapi-affinity + +.. kubeconf:: spec.serverSet.name + + *Optional* + + The name of the MinIO Server Set object. + + The MinIO Operator automatically generates the Server Set + name if this field is omitted. + +.. kubeconf:: spec.serverSet.nodeSelector + + *Optional* + + The filter to apply when selecting which node or nodes on which to + deploy each pod in the Server Set. See the Kubernetes documentation on + :kube-docs:`Assigning Pods to Nodes + ` for more information. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-nodeselector + :end-before: end-kubeapi-nodeselector + +.. kubeconf:: spec.serverSet.resources + + *Optional* + + The :kube-docs:`resources + ` each pod in the + Server Set requests. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-resources + :end-before: end-kubeapi-resources + +.. kubeconf:: spec.serverSet.servers + + *Required* + + The number of :mc:`minio` pods to deploy in the Zone. + + The minimum number of servers is ``2``. MinIO recommends + a minimum of ``4`` servers for optimal availability and + distribution of data in the Server Set. + +.. kubeconf:: spec.serverSet.tolerations + + *Optional* + + The :kube-docs:`Tolerations + ` applied to pods + deployed in the Server Set. + +.. kubeconf:: spec.serverSet.volumeClaimTemplate + :noindex: + + *Required* + + The configuration template to apply to each Persistent Volume Claim (``PVC``) + created as part of the Server Set. + + See :kubeconf:`spec.serverSet.volumeClaimTemplate` for more complete + documentation on the full specification of the ``volumeClaimTemplate`` + object. + + The MinIO Operator calculates the number of ``PVC`` to generate by + multiplying :kubeconf:`spec.serverSet.volumesPerServer` by + :kubeconf:`spec.serverSet.servers`. + +.. kubeconf:: spec.serverSet.volumesPerServer + + *Required* + + The number of Persistent Volume Claims (``PVC``) to create for each + :kubeconf:`server ` in the Server Set. + + The total number of volumes in the Server Set *must* be greater than + 4. Specifically: + + .. parsed-literal:: + + :kubeconf:`~spec.serverSet.servers` X :kubeconf:`~spec.serverSet.volumesPerServer` > 4 + + The MinIO Operator calculates the number of ``PVC`` to generate by + multiplying :kubeconf:`spec.serverSet.volumesPerServer` by + :kubeconf:`spec.serverSet.servers`. + +Volume Claim Template +~~~~~~~~~~~~~~~~~~~~~ + +The following fields describe the template used to generate Persistent Volume +Claims (``PVC``) for use in the MinIO Tenant. + +.. parsed-literal:: + + spec: + serverSet: + - :kubeconf:`~spec.serverSet.volumeClaimTemplate` + :kubeconf:`~spec.serverSet.volumeClaimTemplate.apiVersion`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.kind`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.metadata`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.accessModes`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.dataSource`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.resources`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.selector`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.storageClassName`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.volumeMode`: + :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.volumeName`: + status: + +.. kubeconf:: spec.serverSet.volumeClaimTemplate + + *Required* + + The configuration template to apply to each Persistent Volume Claim (``PVC``) + created as part of a :kubeconf:`Server Set `. The + :kubeconf:`~spec.serverSet.volumeClaimTemplate` dictates which Persistent Volumes + (``PV``) the generated ``PVC`` can bind to. + + The :kubeconf:`~spec.serverSet.volumeClaimTemplate` *requires* at minimum + the following fields: + + - :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.resources` + - :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.accessModes` + + The MinIO Operator calculates the number of ``PVC`` to generate by + multiplying :kubeconf:`spec.serverSet.volumesPerServer` by + :kubeconf:`spec.serverSet.servers`. + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.apiVersion + + *Optional* + + The API Version of the :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + + Specify ``minio.min.io/v1``. + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.kind + + *Optional* + + The REST resource the object represents. + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.metadata + + *Optional* + + The metadata for the :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-objectmeta + :end-before: end-kubeapi-objectmeta + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec + + The specification applied to each Persistent Volume Claim (``PVC``) created + using the :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-persistentvolumeclaimspec + :end-before: end-kubeapi-persistentvolumeclaimspec + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec.accessModes + + *Required* + + The desired :kube-docs:`access mode + ` for each Persistent + Volume Claim (``PVC``) created using the + :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-persistentvolumeclaimspec + :end-before: end-kubeapi-persistentvolumeclaimspec + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec.dataSource + + *Optional* + + The data source to use for each Persistent Volume Claim (``PVC``) + created using the :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-persistentvolumeclaimspec + :end-before: end-kubeapi-persistentvolumeclaimspec + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec.resources + + *Required* + + The resources requested by each Persistent Volume Claim (``PVC``) created + using the :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + + The :kubeconf:`~spec.serverSet.volumeClaimTemplate.spec.resources` object + *must* include a ``requests.storage`` object: + + .. code-block:: yaml + + spec: + serverSet: + - name: minio-server-set-1 + volumeClaimTemplate: + spec: + resources: + requests: + storage: + + The following table lists the supported units for the ``storage`` capacity. + + .. list-table:: + :header-rows: 1 + :widths: 20 80 + :width: 100% + + * - Suffix + - Unit Size + + * - ``k`` + - KB (Kilobyte, 1000 Bytes) + + * - ``m`` + - MB (Megabyte, 1000 Kilobytes) + + * - ``g`` + - GB (Gigabyte, 1000 Megabytes) + + * - ``t`` + - TB (Terrabyte, 1000 Gigabytes) + + * - ``ki`` + - KiB (Kibibyte, 1024 Bites) + + * - ``mi`` + - MiB (Mebibyte, 1024 Kibibytes) + + * - ``gi`` + - GiB (Gibibyte, 1024 Mebibytes) + + * - ``ti`` + - TiB (Tebibyte, 1024 Gibibytes) + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-persistentvolumeclaimspec + :end-before: end-kubeapi-persistentvolumeclaimspec + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec.selector + + *Optional* + + The selector logic to apply when querying available Persistent Volumes + (``PV``) for binding to the Persistent Volume Claim (``PVC``). + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-persistentvolumeclaimspec + :end-before: end-kubeapi-persistentvolumeclaimspec + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec.storageClassName + + *Optional* + + The storage class to apply to each Persistent Volume Claim (``PVC``) + created using the :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-persistentvolumeclaimspec + :end-before: end-kubeapi-persistentvolumeclaimspec + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec.volumeMode + + *Optional* + + The type of Persistent Volume (``PV``) required by the claim. + Defaults to ``Filesystem`` if omitted. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-persistentvolumeclaimspec + :end-before: end-kubeapi-persistentvolumeclaimspec + +.. kubeconf:: spec.serverSet.volumeClaimTemplate.spec.volumeName + + *Optional* + + The name to apply to each Persistent Volume Claim (``PVC``) created + using the :kubeconf:`~spec.serverSet.volumeClaimTemplate`. + +MinIO Docker Image +~~~~~~~~~~~~~~~~~~ + +The following fields describe the Docker settings used by the +MinIO Tenant. + +.. parsed-literal:: + + spec: + :kubeconf:`~spec.image`: + :kubeconf:`~spec.imagePullPolicy`: + :kubeconf:`~spec.imagePullSecret`: + +.. kubeconf:: spec.image + + The Docker image to use for the :mc:`minio` server process. + + Defaults to the latest stable release of ``minio:minio`` if omitted. + +.. kubeconf:: spec.imagePullPolicy + + The Docker pull policy to use for the specified :kubeconf:`spec.image`. + + Specify one of the following values: + + - ``Always`` - Always pull the image. + + - ``Never`` - Never pull the image. + + - ``IfNotPresent`` - Pull the image if not already present. + + Defaults to ``IfNotPresent`` if omitted. + +.. kubeconf:: spec.imagePullSecret + + The secret to use for pulling images from private Docker repositories. + + +Transport Layer Encryption (TLS) +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following fields describe the Transport Layer Encryption (TLS) settings +of a MinIO Tenant, including automatic TLS certificate generation. + +.. parsed-literal:: + + spec: + :kubeconf:`~spec.requestAutoCert`: + :kubeconf:`~spec.certConfig`: + :kubeconf:`~spec.certConfig.commonName`: + :kubeconf:`~spec.certConfig.dnsNames`: + :kubeconf:`~spec.certConfig.organizationName`: + :kubeconf:`~spec.externalCertSecret`: + - name: + type: kubernetes.io/tls + :kubeconf:`~spec.externalClientCertSecret`: + name: + type: kubernetes.io/tls + +.. kubeconf:: spec.requestAutoCert + + *Optional* + + Specify ``true`` to enable automatic TLS certificate generation and + signing using the Kubernetes ``certificates.k8s.io`` API. The MinIO Operator + generates *self-signed* x.509 certificates. + + See the Kubernetes documentation on + :kube-docs:`Manage TLS Certificates in a Cluster + ` for more information. + + This field is **mutually exclusive** with + :kubeconf:`spec.externalCertSecret`. + +.. kubeconf:: spec.certConfig + + *Optional* + + The configuration settings to use when auto-generating x.509 certificates for + TLS encryption. + + Omit to allow the MinIO Operator to generate required fields in + each auto-generate x.509 certificates. + + If :kubeconf:`spec.requestAutoCert` is ``false`` or omitted, this field has + no effect. + +.. kubeconf:: spec.certConfig.commonName + + *Optional* + + The x.509 Common Name to use when generating x.509 certificates for TLS + encryption. Use wildcard patterns when constructing the ``commonName`` + to ensure the generated certificates match the Kubernetes-generated + DNS names of Tenant resources. See the Kubernetes documentation on + :kubedocs:`DNS for Services and Pods + ` for more information on + Kubernetes DNS. + + If :kubeconf:`spec.requestAutoCert` is ``false`` or omitted, this field has + no effect. + +.. kubeconf:: spec.certConfig.dnsNames + + *Optional* + + The DNS names to use when generating x.509 certificates for TLS encryption. + + If :kubeconf:`spec.requestAutoCert` is ``false`` or omitted, this field has + no effect. + +.. kubeconf:: spec.certConfig.organizationName + + *Optional* + + The x.509 Organization Name to use when generating x.509 certificates for + TLS encryption. + + If :kubeconf:`spec.requestAutoCert` is ``false`` or omitted, this field has + no effect. + +.. kubeconf:: spec.externalCertSecret + + *Optional* + + One or more Kubernetes secrets that contain custom TLS certificate and + private key pairs. Use this field for specifying certificates signed by + a Certificate Authority (CA) of your choice. + + Each item in the array contains an object where: + + - ``names`` specifies the name of the Kubernetes secret, and + - ``types`` specifies ``kubernetes.io/tls`` + + Use wildcard patterns when constructing the DNS-related fields + to ensure the generated certificates match the Kubernetes-generated + DNS names of Tenant resources. See the Kubernetes documentation on + :kubedocs:`DNS for Services and Pods + ` for more information on + Kubernetes DNS. + + .. code-block:: yaml + + spec: + externalCertSecret: + - name: tenant-external-cert-secret-name + type: kubernetes.io/tls + + This field is **mutually exclusive** with :kubeconf:`spec.requestAutoCert`. + +.. kubeconf:: spec.externalClientCertSecret + + *Optional* + + The Kubernetes secret that contains the custom Certificate Authority + certificate and private key used to sign x.509 certificates used by clients + connecting to the MinIO Tenant. + + Specify an object where: + + - ``names`` specifies the name of the Kubernetes secret, and + - ``types`` specifies ``kubernetes.io/tls`` + + .. code-block:: yaml + + spec: + externalClientCertSecret: + name: tenant-external-client-cert-secret-name + type: kubernetes.io/tls -Required Fields -~~~~~~~~~~~~~~~ -Automatic TLS Certificate -~~~~~~~~~~~~~~~~~~~~~~~~~ MinIO Console Service ~~~~~~~~~~~~~~~~~~~~~ +The following fields describe the settings for deploying the MinIO Console +in the MinIO Tenant. + +.. parsed-literal:: + + spec: + :kubeconf:`~spec.console`: + :kubeconf:`~spec.console.annotations`: + :kubeconf:`~spec.console.consoleSecret`: + name: + :kubeconf:`~spec.console.env`: + :kubeconf:`~spec.console.externalCertSecret`: + name: + type: kubernetes.io/tls + :kubeconf:`~spec.console.image`: + :kubeconf:`~spec.console.imagePullPolicy`: + :kubeconf:`~spec.console.labels`: + :kubeconf:`~spec.console.nodeSelector`: + :kubeconf:`~spec.console.replicas`: + :kubeconf:`~spec.console.resources`: + :kubeconf:`~spec.console.serviceAccountName`: + + +.. kubeconf:: spec.console + + *Optional* + + The root field for describing MinIO Console-related configuration + information. + + Omit to deploy the MinIO Tenant without an attached Console service. + +.. kubeconf:: spec.console.consoleSecret + + *Required if specifying* :kubeconf:`spec.console`. + + The Kubernetes Secret object that contains all environment variables required + by the MinIO Console. Specify the name of the secret as a subfield: + + .. code-block:: yaml + + spec: + console: + consoleSecret: + name: console-secret-name + +.. kubeconf:: spec.console.annotations + + *Optional* + + One or more Kubernetes :kube-docs:`annotations ` to + associate with the MinIO Console object. + +.. kubeconf:: spec.console.env + + *Optional* + + The environment variables available for use by the MinIO Console. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-envvar + :end-before: end-kubeapi-envvar + +.. kubeconf:: spec.console.externalCertSecret + + *Optional* + + The name of the Kubernetes secret containing the custom Certificate + Authority certificate and private key to use for configuring TLS on the + Console object. Specify an object where ``names`` specifies the name + of the secret and ``types`` specifies ``kubernetes.io/tls``: + + .. code-block:: yaml + + spec: + console: + externalCertSecret: + name: console-external-secret-cert-name + type: kubernetes.io/tls + +.. kubeconf:: spec.console.image + + *Optional* + + The name of the Docker image to use for deploying the MinIO Console. + + Defaults to the latest release of MinIO Console. + +.. kubeconf:: spec.console.imagePullPolicy + + *Optional* + + The pull policy for the Docker image. Defaults to ``IfNotPresent``. + +.. kubeconf:: spec.console.labels + + *Optional* + + The Kubernetes :kube-docs:`labels + ` to apply to the + MinIO Console object. + +.. kubeconf:: spec.console.nodeSelector + + *Optional* + + The filter to apply when selecting which node or nodes on which to + deploy the MinIO Console. See the Kubernetes documentation on + :kube-docs:`Assigning Pods to Nodes + ` for more information. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-nodeselector + :end-before: end-kubeapi-nodeselector + +.. kubeconf:: spec.console.replicas + + *Optional* + + The number of MinIO Console pods to create in the cluster. + +.. kubeconf:: spec.console.resources + + *Optional* + + The :kube-docs:`resources + ` each MinIO Console + object requests. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-resources + :end-before: end-kubeapi-resources + +.. kubeconf:: spec.console.serviceAccountName + + *Optional* + + The name of the + :kube-docs:`Service Account + ` used to run all + MinIO Console pods created as part of the Tenant. + + MinIO Key Encryption Service ~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -Pod Management and Priority -~~~~~~~~~~~~~~~~~~~~~~~~~~~ - -Security Context Configuration -~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ - - - +The following fields describe the settings for deploying the MinIO +Key Encryption Service (KES) in the MinIO Tenant. +.. parsed-literal:: + + spec: + kes: + annotations: + labels: + clientCertSecret: + name: + type: kubernetes.io/tls + externalCertSecret: + name: + type: kubernetes.io/tls + image: + imagePullPolicy: + kesSecret: + nodeSelector: + replicas: + serviceAccountName: + +.. kubeconf:: spec.kes + + *Optional* + + The root field for describing MinIO Key Encryption Service-related + configuration information. + + Omit to deploy the MinIO Tenant without an attached KES service. + +.. kubeconf:: spec.kes.kesSecret + + *Required if specifying* :kubeconf:`spec.kes`. + + The Kubernetes Secret object that contains all environment variables required + by the MinIO KES. Specify the name of the secret as a subfield: + + .. code-block:: yaml + + spec: + kes: + kesSecret: + name: kes-secret-name + +.. kubeconf:: spec.kes.annotations + + *Optional* + + One or more Kubernetes :kube-docs:`annotations ` to + associate with the MinIO KES object. + +.. kubeconf:: spec.kes.env + + *Optional* + + The environment variables available for use by the MinIO KES. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-envvar + :end-before: end-kubeapi-envvar + +.. kubeconf:: spec.kes.externalCertSecret + + *Optional* + + The name of the Kubernetes secret containing the custom Certificate + Authority certificate and private key to use for configuring TLS on the + KES object. Specify an object where ``names`` specifies the name + of the secret and ``types`` specifies ``kubernetes.io/tls``: + + .. code-block:: yaml + + spec: + kes: + externalCertSecret: + name: kes-external-secret-cert-name + type: kubernetes.io/tls + +.. kubeconf:: spec.kes.image + + *Optional* + + The name of the Docker image to use for deploying MinIO KES. + + Defaults to the latest release of MinIO KES. + +.. kubeconf:: spec.kes.imagePullPolicy + + *Optional* + + The pull policy for the Docker image. Defaults to ``IfNotPresent``. + +.. kubeconf:: spec.kes.labels + + *Optional* + + The Kubernetes :kube-docs:`labels + ` to apply to the + MinIO KES object. + +.. kubeconf:: spec.kes.nodeSelector + + *Optional* + + The filter to apply when selecting which node or nodes on which to + deploy MinIO KES. See the Kubernetes documentation on + :kube-docs:`Assigning Pods to Nodes + ` for more information. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-nodeselector + :end-before: end-kubeapi-nodeselector + +.. kubeconf:: spec.kes.replicas + + *Optional* + + The number of MinIO Console pods to create in the cluster. + +.. kubeconf:: spec.kes.serviceAccountName + + *Optional* + + The name of the + :kube-docs:`Service Account + ` used to run all + MinIO KES pods created as part of the Tenant. + + +Pod Security, Scheduling, and Management +~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ + +The following fields describe the settings for Pod Security, Pod Scheduling, +and Pod Management in the MinIO Tenant. + +.. parsed-literal:: + + spec: + :kubeconf:`~spec.securityContext`: + :kubeconf:`~spec.serviceAccountName`: + :kubeconf:`~spec.podManagementPolicy`: + :kubeconf:`~spec.priorityClassName`: + +.. kubeconf:: spec.securityContext + + *Optional* + + Root field for configuring the + :kube-docs:`Security Context + ` of pods created as part of + the MinIO Tenant. + + The MinIO Operator supports the following + :kube-api:`PodSecurityContext <#podsecuritycontext-v1-core>` fields: + + - ``fsGroup`` + - ``fsGroupChangePolicy`` + - ``runAsGroup`` + - ``runAsNonRoot`` + - ``runAsUser`` + - ``seLinuxOptions`` + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-securitycontext + :end-before: end-kubeapi-securitycontext + +.. kubeconf:: spec.serviceAccountName + + *Optional* + + The name of the + :kube-docs:`Service Account + ` used to run all + MinIO server :mc:`minio` pods created as part of the Tenant. + +.. kubeconf:: spec.podManagementPolicy + + *Optional* + + The :kube-docs:`Pod Management Policy + ` used + for pods created as part of the MinIO Tenant. + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-podmanagementpolicy + :end-before: end-kubeapi-podmanagementpolicy + +.. kubeconf:: spec.priorityClassName + + *Optional* + + The Pod :kube-docs:`Priority Class + ` to apply + to pods created as part of the MinIO Tenant. + + + .. include:: /includes/common-minio-kubernetes.rst + :start-after: start-kubeapi-priorityclassname + :end-before: end-kubeapi-priorityclassname