From 7cb22175993ab4df2c8beebbd84b96760d3e6ca5 Mon Sep 17 00:00:00 2001
From: Jamie Klassen <jklassen@vmware.com>
Date: Wed, 5 Jul 2023 13:02:51 -0400
Subject: [PATCH] improve serviceAccountToken docs

Give instructions for k8s 1.24+, and mention the in-cluster option

Signed-off-by: Jamie Klassen <jklassen@vmware.com>
---
 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 9280c4f020..5b2d72069f 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 <NAMESPACE> get secret $(kubectl -n <NAMESPACE> get sa <SERVICE_ACCOUNT_NAME> -o=json \
@@ -136,6 +138,35 @@ kubectl -n <NAMESPACE> get secret $(kubectl -n <NAMESPACE> get sa <SERVICE_ACCOU
 | 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 - <<EOF
+apiVersion: v1
+kind: Secret
+metadata:
+  name: <SECRET_NAME>
+  namespace: <NAMESPACE>
+  annotations:
+    kubernetes.io/service-account.name: <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 <NAMESPACE> get secret <SECRET_NAME> -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