@@ -621,34 +621,20 @@ treated as disabled (resources deleted), not suspended (resources scaled down).
621621
622622## Mutations Describe Intent, Not Observation
623623
624- Mutations operate on the desired object, not the server's current state. If you need to make decisions based on the
625- resource's live state in the cluster, use a data extractor to observe it and feed the result into a mutation through a
626- closure variable .
624+ Mutations operate on the desired object, not the server's current state. A mutation should be a pure function of the
625+ owner spec and other static inputs available at build time. It should never try to read the resource's live cluster
626+ state to decide what to write .
627627
628- ``` go
629- var currentReplicas int32
628+ This is not just a style preference. Within a single resource, the framework runs mutations ** before** data extraction.
629+ A data extractor registered on the same builder as a mutation will not have executed yet when that mutation runs. Any
630+ closure variable populated by the extractor will still hold its zero value.
630631
631- res , _ := deployment.NewBuilder (baseline).
632- WithDataExtractor (func (d appsv1.Deployment ) error {
633- currentReplicas = d.Status .ReadyReplicas
634- return nil
635- }).
636- WithMutation (deployment.Mutation {
637- Name : " scale-aware-annotation" ,
638- Mutate : func (m *deployment.Mutator ) error {
639- m.EditPodTemplateMetadata (func (meta *editors.ObjectMetaEditor ) error {
640- meta.EnsureAnnotation (" app.example.com/last-known-ready" ,
641- fmt.Sprintf (" %d " , currentReplicas))
642- return nil
643- })
644- return nil
645- },
646- }).
647- Build ()
648- ```
632+ Data extractors exist to pass observed state from an ** earlier** resource to a ** later** resource's guards and
633+ mutations. They are not a mechanism for feeding a resource's own live state back into its own mutations. If you find
634+ yourself wanting to do that, reconsider the design: the mutation is likely encoding observation rather than intent.
649635
650- This keeps mutations predictable: they always produce the same desired state for the same inputs , regardless of what
651- currently exists in the cluster, which aligns with Server-Side Apply's declarative model.
636+ A well-written mutation produces the same desired state for the same owner spec , regardless of what currently exists in
637+ the cluster. This aligns with Server-Side Apply's declarative model and keeps the reconciliation loop predictable .
652638
653639## Understand Participation Modes
654640
0 commit comments