Documentation
¶
Overview ¶
Package pin implements the pin mechanism: 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, 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: it is reported and never forced past — which is why nothing here ever passes client.ForceOwnership.
Index ¶
- Constants
- Variables
- func ArtifactSHA(repo *sourcev1.GitRepository) string
- func Commit(repo *sourcev1.GitRepository) string
- func Hold(repo *sourcev1.GitRepository) (manager string, held bool)
- func HoldOf(repo *sourcev1.GitRepository) (kind, manager string, held bool)
- func LedgerRef(src types.NamespacedName) wavefrontv1alpha1.ResourceRef
- func LedgerSource(ref wavefrontv1alpha1.ResourceRef) (types.NamespacedName, bool)
- func Owned(repo *sourcev1.GitRepository) bool
- func Relinquish(ctx context.Context, c client.Client, src types.NamespacedName, manager string) error
- type Owner
- type Writer
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. 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. // 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. 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.
Functions ¶
func ArtifactSHA ¶ added in v0.5.0
func ArtifactSHA(repo *sourcev1.GitRepository) string
ArtifactSHA extracts the commit of the last successful reconciliation, which is what an initial pin bootstraps from.
func Commit ¶ added in v0.5.0
func Commit(repo *sourcev1.GitRepository) string
Commit reads spec.ref.commit, "" when unpinned.
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: 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.
func HoldOf ¶ added in v0.5.0
func HoldOf(repo *sourcev1.GitRepository) (kind, manager string, held bool)
HoldOf reports how a source is held: a hand-pin outranks a suspend because it names an actor and a suspend does not. kind is one of the wavefrontv1alpha1.HoldReason* constants; manager is set only for a hand-pin.
func LedgerRef ¶ added in v0.5.0
func LedgerRef(src types.NamespacedName) wavefrontv1alpha1.ResourceRef
LedgerRef encodes a GitRepository as a release-ledger entry, in Flux's inventory ID format "<namespace>_<name>_<group>_<kind>".
func LedgerSource ¶ added in v0.5.0
func LedgerSource(ref wavefrontv1alpha1.ResourceRef) (types.NamespacedName, bool)
LedgerSource decodes a release-ledger entry written by LedgerRef. The ID is unambiguous: names, groups and kinds cannot contain "_".
func Owned ¶ added in v0.4.0
func Owned(repo *sourcev1.GitRepository) bool
Owned reports whether FieldManager owns spec.ref.commit.
func Relinquish ¶ added in v0.4.0
func Relinquish(ctx context.Context, c client.Client, src types.NamespacedName, manager string) error
Relinquish gives up manager's share of src: an apply of identity alone drops every field manager owned alone, while a value another manager co-owns survives.
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.