From 7cb22175993ab4df2c8beebbd84b96760d3e6ca5 Mon Sep 17 00:00:00 2001 From: Jamie Klassen Date: Wed, 5 Jul 2023 13:02:51 -0400 Subject: [PATCH 1/2] improve serviceAccountToken docs Give instructions for k8s 1.24+, and mention the in-cluster option Signed-off-by: Jamie Klassen --- docs/features/kubernetes/configuration.md | 35 +++++++++++++++++++++-- 1 file changed, 33 insertions(+), 2 deletions(-) diff --git a/docs/features/kubernetes/configuration.md b/docs/features/kubernetes/configuration.md index 9280c4f0205be..5b2d72069f8d7 100644 --- a/docs/features/kubernetes/configuration.md +++ b/docs/features/kubernetes/configuration.md @@ -110,7 +110,7 @@ cluster. Valid values are: | `google` | This will use a user's Google access token from the [Google auth provider](https://backstage.io/docs/auth/google/provider) to access the Kubernetes API on GKE clusters. | | `googleServiceAccount` | This will use the Google Cloud service account credentials to access resources in clusters | | `oidc` | This will use [Oidc Tokens](https://kubernetes.io/docs/reference/access-authn-authz/authentication/#openid-connect-tokens) to authenticate to the Kubernetes API. When this is used the `oidcTokenProvider` field should also be set. Please note the cluster must support OIDC, at the time of writing AKS clusters do not support OIDC. | -| `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set. | +| `serviceAccount` | This will use a Kubernetes [service account](https://kubernetes.io/docs/reference/access-authn-authz/service-accounts-admin/) to access the Kubernetes API. When this is used the `serviceAccountToken` field should also be set, or else Backstage should be running in-cluster. | Check the [Kubernetes Authentication][4] section for additional explanation. @@ -127,7 +127,9 @@ CPU/Memory for pods returned by the API server. Defaults to `false`. ##### `clusters.\*.serviceAccountToken` (optional) The service account token to be used when using the `serviceAccount` auth -provider. You could get the service account token with: +provider. On versions of Kubernetes [prior to +1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1), +you could get an (automatically-generated) token for a service account with: ```sh kubectl -n get secret $(kubectl -n get sa -o=json \ @@ -136,6 +138,35 @@ kubectl -n get secret $(kubectl -n get sa + namespace: + annotations: + kubernetes.io/service-account.name: +type: kubernetes.io/service-account-token +EOF +``` + +waiting for the token controller to populate a token, and retrieving it with: + +```sh +kubectl -n get secret -o go-template='{{.data.token | base64decode}}' +``` + +If a cluster has `authProvider: serviceAccount` and the `serviceAccountToken` +field is omitted, Backstage will ignore the configured URL and certificate data, +instead attempting to access the Kubernetes API via an in-cluster client as in +[this +example](https://github.com/kubernetes-client/javascript/blob/master/examples/in-cluster.js). + ##### `clusters.\*.oidcTokenProvider` (optional) This field is to be used when using the `oidc` auth provider. It will use the id tokens From 26fde684d6152f453b675de5c417a78828a9ca69 Mon Sep 17 00:00:00 2001 From: Jamie Klassen Date: Thu, 20 Jul 2023 22:17:18 -0400 Subject: [PATCH 2/2] Add caveats about production-suitability Also restructure the token instructions into a bullet list based on k8s version. Signed-off-by: Jamie Klassen --- docs/features/kubernetes/configuration.md | 75 +++++++++++++---------- 1 file changed, 42 insertions(+), 33 deletions(-) diff --git a/docs/features/kubernetes/configuration.md b/docs/features/kubernetes/configuration.md index 5b2d72069f8d7..b31c69eac1d9c 100644 --- a/docs/features/kubernetes/configuration.md +++ b/docs/features/kubernetes/configuration.md @@ -127,39 +127,48 @@ CPU/Memory for pods returned by the API server. Defaults to `false`. ##### `clusters.\*.serviceAccountToken` (optional) The service account token to be used when using the `serviceAccount` auth -provider. On versions of Kubernetes [prior to -1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1), -you could get an (automatically-generated) token for a service account with: - -```sh -kubectl -n get secret $(kubectl -n get sa -o=json \ -| jq -r '.secrets[0].name') -o=json \ -| jq -r '.data["token"]' \ -| base64 --decode -``` - -For Kubernetes 1.24+, as described in [this -guide](https://kubernetes.io/docs/concepts/configuration/secret/#service-account-token-secrets), -you can obtain a long-lived token by creating a secret: - -```sh -kubectl apply -f - < - namespace: - annotations: - kubernetes.io/service-account.name: -type: kubernetes.io/service-account-token -EOF -``` - -waiting for the token controller to populate a token, and retrieving it with: - -```sh -kubectl -n get secret -o go-template='{{.data.token | base64decode}}' -``` +provider. Note that, unless you have an effective credential rotation procedure +in place or have a single Kubernetes cluster running both Backstage and all your +services, this auth provider is probably not ideal for production. + +Assuming you have already created a service account named `SERVICE_ACCOUNT_NAME` +in namespace `NAMESPACE` and it has adequate +[permissions](#role-based-access-control), here are some sample procedures to +procure a long-lived service account token for use with this provider: + +- On versions of Kubernetes [prior to + 1.24](https://github.com/kubernetes/kubernetes/blob/master/CHANGELOG/CHANGELOG-1.24.md#no-really-you-must-read-this-before-you-upgrade-1), + you could get an (automatically-generated) token for a service account with: + + ```sh + kubectl -n get secret $(kubectl -n get sa -o=json \ + | jq -r '.secrets[0].name') -o=json \ + | jq -r '.data["token"]' \ + | base64 --decode + ``` + +- For Kubernetes 1.24+, as described in [this + guide](https://kubernetes.io/docs/concepts/configuration/secret/#service-account-token-secrets), + you can obtain a long-lived token by creating a secret: + + ```sh + kubectl apply -f - < + namespace: + annotations: + kubernetes.io/service-account.name: + type: kubernetes.io/service-account-token + EOF + ``` + + waiting for the token controller to populate a token, and retrieving it with: + + ```sh + kubectl -n get secret -o go-template='{{.data.token | base64decode}}' + ``` If a cluster has `authProvider: serviceAccount` and the `serviceAccountToken` field is omitted, Backstage will ignore the configured URL and certificate data,