clarify some comments based on PR feedback

internal/controller/authenticator/jwtcachefiller/jwtcachefiller.go

@@ -180,8 +180,14 @@ func (c *jwtCacheFillerController) Sync(ctx controllerlib.Context) error {
 		Name:     ctx.Key.Name,
 	}
 
-	// If this authenticator already exists, then only recreate it if is different from the desired
-	// authenticator. We don't want to be creating a new authenticator for every resync period.
+	// Only revalidate and update the cache if the cached authenticator is different from the desired authenticator.
+	// There is no need to repeat validations for a spec that was already successfully validated. We are making a
+	// design decision to avoid repeating the validation which dials the server, even though the server's TLS
+	// configuration could have changed, because it is also possible that the network could be flaky. We are choosing
+	// to prefer to keep the authenticator cached (available for end-user auth attempts) during times of network flakes
+	// rather than trying to show the most up-to-date status possible. These validations are for administrator
+	// convenience at the time of a configuration change, to catch typos and blatant misconfigurations, rather
+	// than to constantly monitor for external issues.
 	var jwtAuthenticatorFromCache *cachedJWTAuthenticator
 	if valueFromCache := c.cache.Get(cacheKey); valueFromCache != nil {
 		jwtAuthenticatorFromCache = c.cacheValueAsJWTAuthenticator(valueFromCache)
@@ -236,7 +242,8 @@ func (c *jwtCacheFillerController) Sync(ctx controllerlib.Context) error {
 	}
 
 	// In case we just overwrote or deleted the authenticator from the cache, clean up the old instance
-	// to avoid leaking goroutines. It's safe to call Close() on nil.
+	// to avoid leaking goroutines. It's safe to call Close() on nil. We avoid calling Close() until it is
+	// removed from the cache, because we do not want any end-user authentications to use a closed authenticator.
 	jwtAuthenticatorFromCache.Close()
 
 	err = c.updateStatus(ctx.Context, obj, conditions)

internal/controller/authenticator/jwtcachefiller/jwtcachefiller_test.go

@@ -998,7 +998,7 @@ func TestController(t *testing.T) {
 			runTestsOnResultingAuthenticator: false, // skip the tests because the authenticator left in the cache is the mock version that was added above
 		},
 		{
-			name: "Sync: JWTAuthenticator update when cached authenticator is different type: loop will complete successfully and update status conditions.",
+			name: "Sync: authenticator update when cached authenticator is the wrong data type, which should never really happen: loop will complete successfully and update status conditions.",
 			cache: func(t *testing.T, cache *authncache.Cache, wantClose bool) {
 				cache.Store(
 					authncache.Key{
@@ -1006,6 +1006,9 @@ func TestController(t *testing.T) {
 						Kind:     "JWTAuthenticator",
 						APIGroup: authenticationv1alpha1.SchemeGroupVersion.Group,
 					},
+					// Only entries of type cachedJWTAuthenticator are ever put into the cache, so this should never really happen.
+					// This test is to provide coverage on the production code which reads from the cache and casts those entries to
+					// the appropriate data type.
 					struct{ authenticator.Token }{},
 				)
 			},

internal/controller/authenticator/webhookcachefiller/webhookcachefiller.go

@@ -115,8 +115,14 @@ func (c *webhookCacheFillerController) Sync(ctx controllerlib.Context) error {
 		Name:     ctx.Key.Name,
 	}
 
-	// If this authenticator already exists, then only recreate it if is different from the desired
-	// authenticator. We don't want to be creating a new authenticator for every resync period.
+	// Only revalidate and update the cache if the cached authenticator is different from the desired authenticator.
+	// There is no need to repeat validations for a spec that was already successfully validated. We are making a
+	// design decision to avoid repeating the validation which dials the server, even though the server's TLS
+	// configuration could have changed, because it is also possible that the network could be flaky. We are choosing
+	// to prefer to keep the authenticator cached (available for end-user auth attempts) during times of network flakes
+	// rather than trying to show the most up-to-date status possible. These validations are for administrator
+	// convenience at the time of a configuration change, to catch typos and blatant misconfigurations, rather
+	// than to constantly monitor for external issues.
 	if valueFromCache := c.cache.Get(cacheKey); valueFromCache != nil {
 		webhookAuthenticatorFromCache := c.cacheValueAsWebhookAuthenticator(valueFromCache)
 		if webhookAuthenticatorFromCache != nil && reflect.DeepEqual(webhookAuthenticatorFromCache.spec, &obj.Spec) {

internal/controller/authenticator/webhookcachefiller/webhookcachefiller_test.go

@@ -471,7 +471,7 @@ func TestController(t *testing.T) {
 			wantCacheEntries: 1,
 		},
 		{
-			name: "Sync: authenticator update when cached authenticator is different type: loop will complete successfully and update status conditions.",
+			name: "Sync: authenticator update when cached authenticator is the wrong data type, which should never really happen: loop will complete successfully and update status conditions.",
 			cache: func(t *testing.T, cache *authncache.Cache) {
 				cache.Store(
 					authncache.Key{
@@ -479,6 +479,9 @@ func TestController(t *testing.T) {
 						Kind:     "WebhookAuthenticator",
 						APIGroup: authenticationv1alpha1.SchemeGroupVersion.Group,
 					},
+					// Only entries of type cachedWebhookAuthenticator are ever put into the cache, so this should never really happen.
+					// This test is to provide coverage on the production code which reads from the cache and casts those entries to
+					// the appropriate data type.
 					struct{ authenticator.Token }{},
 				)
 			},

test/integration/concierge_webhookauthenticator_status_test.go

@@ -266,12 +266,13 @@ func TestConciergeWebhookAuthenticatorCRDValidations_Parallel(t *testing.T) {
 }
 
 func allSuccessfulWebhookAuthenticatorConditions() []metav1.Condition {
-	return []metav1.Condition{{
-		Type:    "AuthenticatorValid",
-		Status:  "True",
-		Reason:  "Success",
-		Message: "authenticator initialized",
-	},
+	return []metav1.Condition{
+		{
+			Type:    "AuthenticatorValid",
+			Status:  "True",
+			Reason:  "Success",
+			Message: "authenticator initialized",
+		},
 		{
 			Type:    "EndpointURLValid",
 			Status:  "True",