From d8d5a8ee9730f245909c5a439f51e056da148750 Mon Sep 17 00:00:00 2001 From: Andrea Hoffer Date: Mon, 16 Mar 2020 14:36:17 -0400 Subject: [PATCH] OSDOCS-876: Adding docs for bound service account tokens --- _topic_map.yml | 2 + .../bound-service-account-tokens.adoc | 15 ++++ modules/bound-sa-tokens-about.adoc | 13 ++++ modules/bound-sa-tokens-configuring.adoc | 78 +++++++++++++++++++ 4 files changed, 108 insertions(+) create mode 100644 authentication/bound-service-account-tokens.adoc create mode 100644 modules/bound-sa-tokens-about.adoc create mode 100644 modules/bound-sa-tokens-configuring.adoc diff --git a/_topic_map.yml b/_topic_map.yml index ee9308683a41..47dd1e526ad4 100644 --- a/_topic_map.yml +++ b/_topic_map.yml @@ -349,6 +349,8 @@ Topics: File: using-service-accounts-as-oauth-client - Name: Scoping tokens File: tokens-scoping +- Name: Using bound service account tokens + File: bound-service-account-tokens - Name: Managing Security Context Constraints File: managing-security-context-constraints Distros: openshift-enterprise,openshift-webscale,openshift-origin diff --git a/authentication/bound-service-account-tokens.adoc b/authentication/bound-service-account-tokens.adoc new file mode 100644 index 000000000000..0fe74af21608 --- /dev/null +++ b/authentication/bound-service-account-tokens.adoc @@ -0,0 +1,15 @@ +[id="bound-service-account-tokens"] += Using bound service account tokens +include::modules/common-attributes.adoc[] +:context: bound-service-account-tokens +toc::[] + +You can use bound service account tokens, which improves the ability to integrate with cloud provider identity access management (IAM) services, such as AWS IAM. + +// About bound service account tokens +include::modules/bound-sa-tokens-about.adoc[leveloffset=+1] + +// Configuring bound service account tokens using volume projection +include::modules/bound-sa-tokens-configuring.adoc[leveloffset=+1] + +// TODO: Verify distros: openshift-enterprise,openshift-webscale,openshift-origin,openshift-dedicated diff --git a/modules/bound-sa-tokens-about.adoc b/modules/bound-sa-tokens-about.adoc new file mode 100644 index 000000000000..9c4dcc3a0daf --- /dev/null +++ b/modules/bound-sa-tokens-about.adoc @@ -0,0 +1,13 @@ +// Module included in the following assemblies: +// +// * authentication/bound-service-account-tokens.adoc + +[id="bound-sa-tokens-about_{context}"] += About bound service account tokens + +You can use bound service account tokens to limit the scope of permissions for a given service account token. These tokens are audience and time-bound. This facilitates the authentication of a service account to an IAM role and the generation of temporary credentials mounted to a Pod. You can request bound service account tokens by using volume projection and the TokenRequest API. + +[IMPORTANT] +==== +Because the cluster installation process does not use them, bound service account tokens are configured post-installation. +==== diff --git a/modules/bound-sa-tokens-configuring.adoc b/modules/bound-sa-tokens-configuring.adoc new file mode 100644 index 000000000000..1fcdb630bc36 --- /dev/null +++ b/modules/bound-sa-tokens-configuring.adoc @@ -0,0 +1,78 @@ +// Module included in the following assemblies: +// +// * authentication/bound-service-account-tokens.adoc + +[id="bound-sa-tokens-configuring_{context}"] += Configuring bound service account tokens using volume projection + +You can configure Pods to request bound service account tokens by using volume projection. + +.Prerequisites + +* You have access to the cluster as a user with the `cluster-admin` role. +* You have created a service account. This procedure assumes that the service account is named `build-robot`. + +.Procedure + +. Optionally, set the service account issuer. ++ +This step is typically not required if the bound tokens are used only within the cluster. + +.. Edit the `cluster` authentication object: ++ +---- +$ oc edit authentications cluster +---- + +.. Set the `spec.serviceAccountIssuer` field to the desired service account issuer value: ++ +[source,yaml] +---- +spec: + serviceAccountIssuer: https://test.default.svc <1> +---- +<1> This value should be a URL from which the recipient of a bound token can source the public keys necessary to verify the signature of the token. The default is [x-]`https://kubernetes.default.svc`. + +. Configure a Pod to use a bound service account token by using volume projection. + +.. Create a file called `pod-projected-svc-token.yaml` with the following contents: ++ +[source,yaml] +---- +apiVersion: v1 +kind: Pod +metadata: + name: nginx +spec: + containers: + - image: nginx + name: nginx + volumeMounts: + - mountPath: /var/run/secrets/tokens + name: vault-token + serviceAccountName: build-robot <1> + volumes: + - name: vault-token + projected: + sources: + - serviceAccountToken: + path: vault-token <2> + expirationSeconds: 7200 <3> + audience: vault <4> +---- +<1> A reference to an existing service account. +<2> The path relative to the mount point of the file to project the token into. +<3> Optionally set the expiration of the service account token, in seconds. The default is 3600 seconds (1 hour) and must be at least 600 seconds (10 minutes). The kubelet will start trying to rotate the token if the token is older than 80 percent of its time to live or if the token is older than 24 hours. +<4> Optionally set the intended audience of the token. The recipient of a token should verify that the recipient identity matches the the audience claim of the token, and should otherwise reject the token. The audience defaults to the identifier of the API server. + +.. Create the Pod: ++ +---- +$ oc create -f pod-projected-svc-token.yaml +---- ++ +The kubelet requests and stores the token on behalf of the Pod, makes the token available to the Pod at a configurable file path, and refreshes the token as it approaches expiration. + +. The application that uses the bound token must handle reloading the token when it rotates. ++ +The kubelet rotates the token if it is older than 80 percent of its time to live, or if the token is older than 24 hours.