Documentation
¶
Overview ¶
Package pin implements the pin mechanism (DESIGN §3.5): advancing a GitRepository's spec.ref.commit to an admitted SHA under the controller's own field manager, and detecting hand-pins made by anyone else.
The mechanism rests entirely on server-side apply co-ownership. The catalog renders the tracking ref (spec.ref.name) and omits spec.ref.commit (§3.5.1), so the controller can own the commit field alone without ever contending with kustomize-controller. A commit owned by a third field manager is a human override (§3.5.3): it is reported and never forced past — which is why nothing here ever passes client.ForceOwnership.
Index ¶
Constants ¶
const ( // FieldManager is the field manager under which the controller owns // spec.ref.commit and its provenance annotations. FieldManager = "wavefront-controller" // ManagedLabel is the participation label (DESIGN §8.2). The controller // only ever reads it: labels are the catalog's to write. ManagedLabel = "wavefront.as-code.io/managed" // AnnotAdmittedAt records when the pin was advanced, in RFC3339 UTC. AnnotAdmittedAt = "wavefront.as-code.io/admitted-at" // AnnotPreviousPin records the outgoing pin, enabling rollback (§3.7). // It is set to the empty string on an initial pin so that the applied // field set stays stable across advances. AnnotPreviousPin = "wavefront.as-code.io/previous-pin" // AnnotObservedRef records the tracking ref the admitted SHA came from. AnnotObservedRef = "wavefront.as-code.io/observed-ref" // WfctlFieldManager is the SSA field manager wfctl uses for hand-pins, so // the controller reports them as external holds (DESIGN §3.5.3). WfctlFieldManager = "wfctl" // AnnotDisplacedPin records, on a wfctl hand-pin, the spec.ref.commit value // the hand-pin displaced, so `wfctl release` can restore provenance. AnnotDisplacedPin = "wavefront.as-code.io/displaced-pin" )
Variables ¶
var ErrHeld = errors.New("spec.ref.commit is held by another field manager")
ErrHeld is returned when the SSA patch conflicts with a foreign field manager — i.e. a human hand-pin. Never force past it (DESIGN §3.5.3).
Functions ¶
func Hold ¶
func Hold(repo *sourcev1.GitRepository) (manager string, held bool)
Hold inspects managedFields and reports a foreign owner of spec.ref.commit.
Ownership by anyone other than FieldManager means the pin was set by hand (DESIGN §3.5.3): the node is held, and the controller must report it rather than advance it. The first foreign owner encountered wins; entries for subresources (status) cannot own spec and are skipped.
Types ¶
type Owner ¶
type Owner struct {
Manager string `json:"manager"`
Operation metav1.ManagedFieldsOperationType `json:"operation"` // Apply | Update
}
Owner is one managedFields entry that owns spec.ref.commit.
func Owners ¶
func Owners(repo *sourcev1.GitRepository) []Owner
Owners lists every managedFields entry owning spec.ref.commit, in managedFields order, skipping subresource entries and unparseable FieldsV1 (same rules as Hold). Includes the controller's own entry.
type Writer ¶
Writer advances pins via server-side apply.
func (*Writer) Advance ¶
func (w *Writer) Advance(ctx context.Context, repo types.NamespacedName, prev, sha, observedRef string, at time.Time) error
Advance pins repo to sha with provenance annotations, via SSA under FieldManager WITHOUT ForceOwnership. A 409 conflict is normalised to ErrHeld. prev is the outgoing pin ("" for an initial pin); observedRef the tracking ref.
The applied object is deliberately minimal — identity, the three provenance annotations, and spec.ref.commit — so the controller's field set never grows to cover anything the catalog owns.
Source Files