OCPBUGS-112723: Document that disabling Image Registry deletes companion SA tokens

modules/service-account-auto-secret-removed.adoc

@@ -1,6 +1,7 @@
 // Module included in the following assemblies:
 //
 // * authentication/using-service-accounts-in-applications.adoc
+// * authentication/understanding-and-creating-service-accounts.adoc
 // * pods/nodes-pods-secrets.adoc
 
 :_mod-docs-content-type: CONCEPT
@@ -14,11 +15,24 @@
 ====
 Prior to {product-title} 4.16, a long-lived service account API token secret was also generated for each service account that was created. Starting with {product-title} 4.16, this service account API token secret is no longer created.
 
-After upgrading to {product-version}, any existing long-lived service account API token secrets are not deleted and will continue to function. For information about detecting long-lived API tokens that are in use in your cluster or deleting them if they are not needed, see "Long-lived service account API tokens in {product-title} (Red Hat Knowledgebase)".
+After upgrading to {product-version}, any existing long-lived service account API token secrets that are not part of the managed image pull secret pair are not deleted by the upgrade and continue to function. For information about detecting long-lived API tokens that are in use in your cluster or deleting them if they are not needed, see "Long-lived service account API tokens in {product-title} (Red Hat Knowledgebase)".
+
+This upgrade behavior does not apply to companion `kubernetes.io/service-account-token` secrets that are linked to auto-generated image pull secrets. Those companion tokens can be deleted when you disable the integrated {product-registry}.
 ====
 
 This image pull secret is necessary to integrate the {product-registry} into the cluster's user authentication and authorization system.
 
 However, if you do not enable the `ImageRegistry` capability or if you disable the integrated {product-registry} in the Cluster Image Registry Operator's configuration, an image pull secret is not generated for each service account.
 
 When the integrated {product-registry} is disabled on a cluster that previously had it enabled, the previously generated image pull secrets are deleted automatically.
+
+[IMPORTANT]
+====
+The managed image pull secret of type `kubernetes.io/dockercfg` is paired with a companion secret of type `kubernetes.io/service-account-token`. That companion secret is a valid API authentication token. When you disable the integrated {product-registry}, the cluster can delete both the image pull secret and the companion token.
+
+Do not use auto-generated dockercfg companion tokens as long-lived credentials for applications, such as GitOps tools. Use bound service account tokens instead. See xref:../authentication/bound-service-account-tokens.adoc#bound-sa-tokens-about_bound-service-account-tokens[Using bound service account tokens].
+
+The `kubernetes.io/legacy-token-last-used` annotation does not prevent this cleanup.
+
+Cleanup can skip some secrets, for example when a secret was created recently, the dockercfg and token pair is incomplete, or a pod still references the pull secret. As a result, disabling the registry can delete these secrets on one cluster and leave them on another cluster that uses the same procedure.
+====