.. _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 `