diff --git a/source/developers/security-token-service.rst b/source/developers/security-token-service.rst index 815907dc..17c53d15 100644 --- a/source/developers/security-token-service.rst +++ b/source/developers/security-token-service.rst @@ -14,6 +14,9 @@ The MinIO Security Token Service (STS) APIs allow applications to generate tempo The STS API is *required* for MinIO deployments configured to use external identity managers, as the API allows conversion of the external IDP credentials into AWS Signature v4-compatible credentials. +STS API Endpoints +----------------- + MinIO supports the following STS API endpoints: .. list-table:: @@ -35,6 +38,7 @@ MinIO supports the following STS API endpoints: * - :ref:`AssumeRoleWithCustomToken ` - MinIO Identity Plugin - Generates a token for use with an external identity provider and the :ref:`MinIO Identity Plugin `. + .. toctree:: :titlesonly: diff --git a/source/developers/sts-for-operator.rst b/source/developers/sts-for-operator.rst new file mode 100644 index 00000000..a39ec114 --- /dev/null +++ b/source/developers/sts-for-operator.rst @@ -0,0 +1,187 @@ +.. _minio-sts-operator: + +=============================================== +Security Token Service (STS) for MinIO Operator +=============================================== + +.. default-domain:: minio + +.. contents:: Table of Contents + :local: + :depth: 2 + +Overview +-------- + +.. versionadded:: Operator v5.0.0 + + The MinIO Operator supports a set of API calls that allows an application to obtain STS credentials for a MinIO Tenant. + +Benefits of STS for MinIO Operator include: + +- :ref:`STS credentials ` allow an application to access objects on a MinIO Tenant without the need to create credentials for the application on the tenant. + +- Allows applications to access objects in MinIO tenants using a Kubernetes-native authentication mechanism. + + Service Accounts or Service Account Tokens are a core concept of :kube-docs:`Role-Based Access Control (RBAC) ` :kube-docs:`authentication ` in Kubernetes. + +- Implementing STS for MinIO Operator allows you to utilize infrastructure as code principles and configuration by using the tenant custom resource definition (CRD) and a MinIO PolicyBinding CRD. + +.. important:: + + MinIO Operator launches with STS *disabled* by default. + To use STS with the Operator, you must first explicitly enable it. + + The procedure on this page includes instructions to enable the STS API in the MinIO Operator. + +How STS Authorization Works in Kubernetes +----------------------------------------- + +An application can use an ``AssumeRoleWithWebIdentity`` call including a :kube-docs:`Kubernetes Service Account's ` :abbr:`JWT (JSON Web Token)` to send a request for temporary credentials to the MinIO Operator. +When linked to a pod, such as through a deployment's ``.spec.spec.serviceAccountName`` field, Kubernetes mounts a :abbr:`JWT (JSON Web Token)` for the service account from a well-known location, such as ``/var/run/secrets/kubernetes.io/serviceaccount/token``. +The Pod can access those service accounts from that location. + +The Operator checks the validity of the request, retrieves policies for the application, obtains credentials from the tenant, and then passes the credentials back the application. +The application uses the issued credentials to work with the object storage on the tenant. + +.. image:: /images/k8s/sts-diagram.png + :width: 600px + :alt: A diagram showing STS token process flow on a Kubernetes MinIO deployment between the requesting application, MinIO Operator, Kubernetes API, PolicyBinding custom resource definition, and the MinIO tenant. + :align: center + +The complete process includes the following steps: + +1. An application sends an ``AssumeRoleWithWebidentity`` :ref:`API request ` to the MinIO Operator containing the tenant namespace and a service account to use. +2. The MinIO Operator uses the Kubernetes API to check that the JSON Web Token (JWT) associated with the :ref:`service account ` in the application's request is valid. +3. The Kubernetes API returns the results of its validity check. +4. The MinIO Operator checks for :ref:`Policy Bindings ` that matches the application. +5. The PolicyBinding CRD returns the policy or policies that match the request, if any. +6. The MinIO Operator sends the combined policy information for the application to the MinIO Tenant. +7. The tenant creates temporary credentials matching the policy or policies for the request and returns those to the MinIO Operator. +8. The MinIO Operator forwards the temporary credentials back to the application. +9. The application uses the credentials to send the object storage calls to the MinIO tenant. + +Requirements +------------ + +STS for the MinIO Operator requires the following: + +- MinIO Operator v5.0.0 or later. +- The deployment **must** have :ref:`TLS configured `. +- :envvar:`OPERATOR_STS_ENABLED` environment variable set to ``on``. + +Procedure +--------- + +1. Enable STS functionality for the deployment + + .. code-block:: shell + :class: copyable + + kubectl -n minio-operator set env deployment/minio-operator OPERATOR_STS_ENABLED=on + + - Replace ``minio-operator`` with the namespace for your deployment. + - Replace ``deployment/minio-operator`` with the value for your deployment's MinIO Operator. + + You can find the deployment value by running ``kubectl get deployments -n ``, where you replace ```` with the namespace for the MinIO Operator. + Your MinIO Operator namespace is typically ``minio-operator``, though this value can change during install. + +2. Ensure an appropriate :ref:`policy ` or policies exist on the MinIO Tenant for the application to use for the application + + The next step uses a YAML document to map one or more existing tenant policies to a service account through a custom resource called a ``PolicyBinding``. + +3. Create YAML resources for the Service Account and Policy Binding: + + - Create the :ref:`Service Account ` in the MinIO Tenant for the application to use. + + For more on service accounts in Kubernetes, see the :kube-docs:`Kubernetes documentation `. + - Create a :ref:`Policy Binding ` in the target tenant's namespace that links the application to one or more of the MinIO Tenant's policies. + +4. Apply the YAML file to create the resources on the deployment + + .. code-block:: shell + :class: copyable + + kubectl apply -k path/to/yaml/file.yaml + +5. Use an SDK that supports the ``AssumeRoleWithWebIdentity`` like behavior to send a call from your application to the deployment + + The STS API expects a JWT for the service account to exist in the Kubernetes environment. + When linked to a pod, such as through a deployment's ``.spec.spec.serviceAccountName`` field, Kubernetes mounts a :abbr:`JWT (JSON Web Token)` for the service account from a well-known location, such as ``/var/run/secrets/kubernetes.io/serviceaccount/token``. + + Alternatively, you can define the token path as an environment variable: + + .. code-block:: shell + :class: copyable + + AWS_WEB_IDENTITY_TOKEN_FILE=/var/run/secrets/kubernetes.io/serviceaccount/token + + The following MinIO SDKs support ``AssumeRoleRoleWithWebIdentity``: + + - :ref:`Golang ` + - :ref:`Java ` + - :ref:`JavaScript ` + - :ref:`.NET ` + - :ref:`Python ` + + For examples of using the SDKs to assume a role, see :minio-git:`GitHub `. + +Example Resources +----------------- + +.. _minio-operator-sts-service-account: + +Service Account +~~~~~~~~~~~~~~~ + +A Service Account is a :kube-docs:`Kubernetes resource type ` that allows an external application to interact with the Kubernetes deployment. +When linked to a pod, such as through a deployment's ``.spec.spec.serviceAccountName`` field, Kubernetes mounts a :abbr:`JWT (JSON Web Token)` for the service account from a well-known location, such as ``/var/run/secrets/kubernetes.io/serviceaccount/token``. + +The following yaml creates a service account called ``stsclient-sa`` for the ``sts-client`` namespace. + +.. code-block:: yaml + :class: copyable + + apiVersion: v1 + kind: ServiceAccount + metadata: + namespace: sts-client # The namespace to add the service account to. Usually a tenant, but can be any namespace in the deployment. + name: stsclient-sa # The name to use for the service account. + +.. _minio-operator-sts-policy-binding: + +Policy Binding +~~~~~~~~~~~~~~ + +A ``PolicyBinding`` is a MinIO-specific custom resource type for Kubernetes that links an ``application`` to a set of policies. + +Create Policy Bindings in the namespace of the tenant they are for. + +For the purposes of the MinIO Operator, an application is any requesting resource that identifies with a specific service account and tenant namespace. +The ``PolicyBinding`` resource links the application to one or more policies for the tenant on that namespace. + +The below yaml creates a ``PolicyBinding`` that links an application using the service account ``stsclient-sa`` that exists in the namespace ``sts-client`` to the policy ``test-bucket-rw`` in the target tenant located in the namespace ``minio-tenant-1``. +The policies granted in the yaml definition **must** already exist on the MinIO Tenant. + +.. code-block:: yaml + :class: copyable + + apiVersion: sts.min.io/v1alpha1 + kind: PolicyBinding + metadata: + name: binding-1 + namespace: minio-tenant-1 # The namespace of the tenant this binding is for + spec: + application: + namespace: sts-client # The namespace that contains the service account for the application + serviceaccount: stsclient-sa # The service account to use for the application + policies: + - test-bucket-rw # A policy that already exists in the tenant + # - test-bucket-policy-2 # Add as many policies as needed + +Reference +--------- + +- :minio-git:`STS Examples by SDK ` +- :kube-docs:`Kubernetes documentation on Service Accounts ` +- :minio-git:`MinIO STS API ` \ No newline at end of file diff --git a/source/images/k8s/sts-diagram.png b/source/images/k8s/sts-diagram.png new file mode 100644 index 00000000..801ae959 Binary files /dev/null and b/source/images/k8s/sts-diagram.png differ diff --git a/source/index.rst b/source/index.rst index a85dd4c9..28051d07 100644 --- a/source/index.rst +++ b/source/index.rst @@ -164,7 +164,7 @@ Any file uploaded to ``play`` should be considered public and non-protected. /administration/batch-framework /administration/concepts -.. cond:: not linux +.. cond:: not (linux or k8s) .. toctree:: :titlesonly: @@ -198,6 +198,12 @@ Any file uploaded to ``play`` should be considered public and non-protected. :titlesonly: :hidden: + Software Development Kits (SDK) + /developers/sts-for-operator + Object Lambda + MinIO Client + MinIO Admin Client + Integrations /reference/kubectl-minio-plugin .. toctree:: diff --git a/source/url-excludes.yaml b/source/url-excludes.yaml index 4f82c1c9..70aea572 100644 --- a/source/url-excludes.yaml +++ b/source/url-excludes.yaml @@ -98,7 +98,17 @@ excludes: - 'reference/minio-server*' - 'reference/minio-mc*' - 'reference/deprecated/*' -- 'developers/*' +- 'reference/deprecated/*' +- 'developers/dotnet/*' +- 'developers/go/*' +- 'developers/haskell/*' +- 'developers/java/*' +- 'developers/javascript/*' +- 'developers/python/*' +- 'developers/security-token-service/*' +- 'developers/minio-drivers.rst' +- 'developers/security-token-service.rst' +- 'developers/transforms-with-object-lambda.rst' - 'integrations/*' --- tag: openshift