BZ-2070577: Adding a step to wait for the API server pods to restart

Author: bergerhoffer

modules/bound-sa-tokens-configuring.adoc

@@ -23,15 +23,7 @@ This step is typically not required if the bound tokens are used only within the
 ====
 If you update the `serviceAccountIssuer` field and there are bound tokens already in use, all bound tokens with the previous issuer value will be invalidated. Unless the holder of a bound token has explicit support for a change in issuer, the holder will not request a new bound token until pods have been restarted.
 
-If necessary, you can use the following command to manually restart all pods in the cluster. Be aware that running this command causes a service interruption, because it deletes every running pod in every namespace. These pods will automatically restart after they are deleted.
-
-[source,terminal]
-----
-$ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \
-      do oc delete pods --all -n $I; \
-      sleep 1; \
-      done
-----
+If necessary, you can manually restart all pods in the cluster so that the holder will request a new bound token. Before doing this, wait for a new revision of the Kubernetes API server pods to roll out with your service account issuer changes.
 ====
 
 .. Edit the `cluster` `Authentication` object:
@@ -50,6 +42,46 @@ spec:
 ----
 <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`.
 
+.. Save the file to apply the changes.
+
+.. Optional: Manually restart all pods in the cluster so that the holder will request a new bound token.
+
+... Wait for a new revision of the Kubernetes API server pods to roll out. It can take several minutes for all nodes to update to the new revision. Run the following command:
++
+[source,terminal]
+----
+$ oc get kubeapiserver -o=jsonpath='{range .items[0].status.conditions[?(@.type=="NodeInstallerProgressing")]}{.reason}{"\n"}{.message}{"\n"}'
+----
++
+Review the `NodeInstallerProgressing` status condition for the Kubernetes API server to verify that all nodes are at the latest revision. The output shows `AllNodesAtLatestRevision` upon successful update:
++
+[source,terminal]
+----
+AllNodesAtLatestRevision
+3 nodes are at revision 12 <1>
+----
+<1> In this example, the latest revision number is `12`.
++
+If the output shows a message similar to one of the following messages, the update is still in progress. Wait a few minutes and try again.
+
+** `3 nodes are at revision 11; 0 nodes have achieved new revision 12`
+** `2 nodes are at revision 11; 1 nodes are at revision 12`
+
+... Manually restart all pods in the cluster:
++
+[WARNING]
+====
+Be aware that running this command causes a service interruption, because it deletes every running pod in every namespace. These pods will automatically restart after they are deleted.
+====
++
+[source,terminal]
+----
+$ for I in $(oc get ns -o jsonpath='{range .items[*]} {.metadata.name}{"\n"} {end}'); \
+      do oc delete pods --all -n $I; \
+      sleep 1; \
+      done
+----
+
 . 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: