chore: clarify pull secret in-place update behavior and add CP watches

Clarify spec.pullSecret API godoc, add CP pull-secret watches
to HCCO resources and globalps controllers, extract testable
predicates with unit tests, and overhaul global-pull-secret docs.

Author: enxebre

AGENTS.md

@@ -151,6 +151,11 @@ See [docs/content/reference/versioning-support.md](docs/content/reference/versio
 
 See [docs/content/how-to/upgrades.md](docs/content/how-to/upgrades.md) for Control Plane and Data Plane upgrades
 
+### Pull secret cycling
+
+When changing how workers and the guest cluster authenticate to registries, treat **HostedCluster** `spec.pullSecret`, **management-cluster** Secret data, **HCCO** reconciliation into the data plane, and optional **Global Pull Secret** (`kube-system/additional-pull-secret`) as one system. Changing only the Secret bytes in place does not change `spec.pullSecret` and therefore does not drive a **NodePool** rollout, but controllers can still propagate credentials into the control plane namespace, guest `openshift-config`, `kube-system/original-pull-secret`, and (where the Global Pull Secret DaemonSet is scheduled) kubelet configuration.
+
+See [docs/content/how-to/common/global-pull-secret.md](docs/content/how-to/common/global-pull-secret.md) for behavior, platform and NodePool eligibility (AWS/Azure Replace vs InPlace and other platforms), merge semantics, and operational guidance.
 
 ## Dependencies and Modules
 

api/hypershift/v1beta1/hostedcluster_types.go

@@ -674,10 +674,13 @@ type HostedClusterSpec struct {
 	// pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
 	// If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
 	// TODO(alberto): Signal this in a condition.
-	// This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-	// and it will be injected into the container runtime of all NodePools.
-	// Changing this value will trigger a rollout for all existing NodePools in the cluster.
-	// Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+	// This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+	// Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+	// Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+	// In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+	// will still propagate the updated credentials down to the guest cluster and kubelet config.
+	// See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+	// for details.
 	// +required
 	// +rollout
 	// TODO(alberto): have our own local reference type to include our opinions and avoid transparent changes.

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/AAA_ungated.yaml

@@ -5690,10 +5690,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/AutoNodeKarpenter.yaml

@@ -5809,10 +5809,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/ClusterUpdateAcceptRisks.yaml

@@ -5673,10 +5673,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/ClusterVersionOperatorConfiguration.yaml

@@ -5693,10 +5693,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/ExternalOIDC.yaml

@@ -6006,10 +6006,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/ExternalOIDCWithUIDAndExtraClaimMappings.yaml

@@ -6146,10 +6146,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/ExternalOIDCWithUpstreamParity.yaml

@@ -6127,10 +6127,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""

api/hypershift/v1beta1/zz_generated.featuregated-crd-manifests/hostedclusters.hypershift.openshift.io/GCPPlatform.yaml

@@ -6119,10 +6119,13 @@ spec:
                 description: |-
                   pullSecret is a local reference to a Secret that must have a ".dockerconfigjson" key whose content must be a valid Openshift pull secret JSON.
                   If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.
-                  This pull secret will be part of every payload generated by the controllers for any NodePool of the HostedCluster
-                  and it will be injected into the container runtime of all NodePools.
-                  Changing this value will trigger a rollout for all existing NodePools in the cluster.
-                  Changing the content of the secret inplace will not trigger a rollout and might result in unpredictable behaviour.
+                  This pull secret is included in NodePool ignition/bootstrap payloads and applied to the container runtime when nodes provision.
+                  Changing this value will trigger a rollout for all existing NodePools in the cluster (for both replace and inplace upgrade types).
+                  Updating the referenced Secret's data in place (without changing this reference) does not trigger that rollout.
+                  In AWS and Azure NodePools using the Replace upgrade strategy, the Secret's data in place changes
+                  will still propagate the updated credentials down to the guest cluster and kubelet config.
+                  See https://github.com/openshift/hypershift/blob/3e0e06f78460ac1100dd8432dd7eee4e980a87d0/docs/content/how-to/common/global-pull-secret.md
+                  for details.
                 properties:
                   name:
                     default: ""