NO-JIRA: docs: clarify pull secret in-place update behavior and add CP watches

Clarify HostedCluster.spec.pullSecret API docs to describe the actual
in-place update propagation behavior: changing the Secret data without
changing the reference does not trigger a NodePool rollout, but on
AWS/Azure Replace NodePools the updated credentials still propagate
to the guest cluster and kubelet config via the Global Pull Secret
DaemonSet path.

Add CP pull-secret watches to both the resources and globalps HCCO
controllers so in-place Secret updates propagate promptly:
- resources controller: reconciles openshift-config/pull-secret
- globalps controller: reconciles kube-system/original-pull-secret
  and the DaemonSet mount path

Update global-pull-secret.md to document platform and NodePool
eligibility, the positive-selection scheduling model, and the baseline
sync behavior when no additional-pull-secret exists.

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>

Author: enxebre

AGENTS.md

@@ -147,6 +147,12 @@ See [docs/content/reference/goals-and-design-invariants.md](docs/content/referen
 
 See [docs/content/reference/versioning-support.md](docs/content/reference/versioning-support.md) for release cycle, version skew policies, and support matrices for the HyperShift Operator, CPO, and other components.
 
+### 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
 
 This is a Go 1.25+ project using:

api/hypershift/v1beta1/hostedcluster_types.go

@@ -674,14 +674,17 @@ 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.
-	PullSecret corev1.LocalObjectReference `json:"pullSecret"`
+	PullSecret corev1.LocalObjectReference `json:"pullSecret,omitzero"`
 
 	// sshKey is a local reference to a Secret that must have a "id_rsa.pub" key whose content must be the public part of 1..N SSH keys.
 	// If the reference is set but none of the above requirements are met, the HostedCluster will enter a degraded state.

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: ""