feat(applier): hold the applier, resuming a suspended Kustomization for each apply

.coverage-baseline

@@ -1 +1 @@
-80.0
+80.2

.docs-lint-scope

@@ -25,11 +25,12 @@
 README.md
 docs/architecture.md
 docs/configuration.md
-docs/flux.md
-docs/argocd.md
+docs/bi-directional-flux.md
+docs/bi-directional-argocd.md
 docs/spec/attribution.md
 docs/components.md
 docs/quickstart.md
 docs/demo/commit-window.md
 docs/facts/kubernetes-watch-options.md
 docs/spec/watch-event-ordering-and-attribution-grace.md
+docs/bi-directional.md

README.md

@@ -57,9 +57,11 @@ several source clusters, repositories, branches, and folders.
 
 ## Principles
 
-- **Creates Git commits.** The only output is Git commits that reflect the state of your cluster.
+- **Creates Git commits.** The output is Git commits that reflect the state of your cluster.
   Deploying is Flux's and Argo CD's job: run one alongside to bring changes from Git back into the
-  cluster. See [bi-directional usage](docs/bi-directional.md).
+  cluster. Only a folder that both GitOps Reverser writes and Flux or Argo CD applies needs more: an
+  apply trigger, so GitOps Reverser decides when it is applied. See
+  [bi-directional usage](docs/bi-directional.md).
 - **API-first, not API-only.** Most changes are assumed to arrive through the API, so that is what
   publishing is tuned for. Your changes end up in your remote Git repo within seconds. Other
   authors can push to the same branch, and that is handled without conflicts. If an API edit and a
@@ -158,14 +160,15 @@ made after the changes or before them. It runs on top of the quickstart above.
 ## Try it with your existing repo
 
 Start with a [scratch branch](docs/configuration.md#seeing-what-a-target-will-do-before-it-does-it)
-containing your existing manifests, with no reconciler deploying that branch. Select a small resource
+containing your existing manifests, with nothing deploying that branch. Select a small resource
 scope and one destination folder. Inspect the initial commits before making a live edit, then check
 which source files changed.
 
-The operator pushes directly to the configured branch. If you later write to a branch that Flux or
-Argo CD deploys, read the [bidirectional guide](docs/bi-directional.md) first. Live edits can be
-reverted by the reconciler, and [replaying captured state](docs/api-first-publication.md) can overwrite
-concurrent Git edits to the same object. Decide per folder which side is authoritative.
+The operator pushes directly to the configured branch. Flux or Argo CD deploying other folders is
+unaffected. If one of them deploys the folder you write, read the
+[bi-directional guide](docs/bi-directional.md) first. Without an apply trigger, live edits can be
+reverted by Flux or Argo CD, and [replaying captured state](docs/api-first-publication.md) can
+overwrite concurrent Git edits to the same object. Decide per folder which side is authoritative.
 
 ## Before you adopt it
 

api/v1alpha3/applytrigger_types.go

@@ -0,0 +1,211 @@
+// SPDX-License-Identifier: Apache-2.0
+
+package v1alpha3
+
+import (
+	"time"
+
+	meta "github.com/fluxcd/pkg/apis/meta"
+	metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
+	"k8s.io/apimachinery/pkg/runtime"
+	"k8s.io/apimachinery/pkg/types"
+)
+
+// What every apply trigger kind shares: the reference a GitTarget names one by, why an apply is
+// asked for, and the operation a trigger's status records. The kinds themselves are in
+// fluxtrigger_types.go and argocdtrigger_types.go. docs/definitions.md fixes the words: the
+// APPLIER is the Flux Kustomization or Argo CD Application, and the TRIGGER is this operator's
+// resource that holds it.
+
+// The apply trigger kinds GitTarget.spec.applyTriggerRef can name.
+const (
+	// ApplyTriggerKindFlux is a FluxTrigger, which holds a Flux Kustomization.
+	ApplyTriggerKindFlux = "FluxTrigger"
+	// ApplyTriggerKindArgoCD is an ArgoCDTrigger, which holds an Argo CD Application.
+	ApplyTriggerKindArgoCD = "ArgoCDTrigger"
+)
+
+// The kinds of applier a trigger holds.
+const (
+	// ApplierKindKustomization is a Flux Kustomization (FluxTrigger.spec.kustomizationRef).
+	ApplierKindKustomization = "Kustomization"
+	// ApplierKindApplication is an Argo CD Application (ArgoCDTrigger.spec.applicationRef).
+	ApplierKindApplication = "Application"
+)
+
+// Why a kind and a name, and no namespace: the kind keeps each trigger its own schema, the way
+// Flux's sourceRef names a kind, and the namespace is the GitTarget's own because the trigger's
+// ClusterProvider admits the namespace it is in (spec.accessFrom). A GitTarget that could name a
+// trigger elsewhere would drive an applier that its own namespace was never admitted to.
+
+// ApplyTriggerReference names an apply trigger in the GitTarget's own namespace.
+type ApplyTriggerReference struct {
+	// Kind is the trigger's kind: FluxTrigger or ArgoCDTrigger.
+	// +required
+	// +kubebuilder:validation:Enum=FluxTrigger;ArgoCDTrigger
+	Kind string `json:"kind"`
+
+	// Name is the trigger's name.
+	// +required
+	// +kubebuilder:validation:MinLength=1
+	Name string `json:"name"`
+}
+
+// ApplyReason is why GitOps Reverser asked an applier to apply.
+// +kubebuilder:validation:Enum=ForeignCommit;Refusal;Repair;CatchUp
+type ApplyReason string
+
+const (
+	// ApplyReasonForeignCommit is a commit GitOps Reverser did not push.
+	ApplyReasonForeignCommit ApplyReason = "ForeignCommit"
+	// ApplyReasonRefusal is a refused edit on a target with spec.onRefusal: Reapply.
+	ApplyReasonRefusal ApplyReason = "Refusal"
+	// ApplyReasonRepair puts back an API edit that an earlier apply reverted on the cluster after
+	// the edit was made. Git kept the edit; the cluster runs the older value until the repair.
+	ApplyReasonRepair ApplyReason = "Repair"
+	// ApplyReasonCatchUp keeps the applier current with GitOps Reverser's own pushes.
+	ApplyReasonCatchUp ApplyReason = "CatchUp"
+)
+
+// ApplyOperationPhase is where an apply operation stands.
+// +kubebuilder:validation:Enum=Requested;Running;Settling;Unresolved;Succeeded;Failed
+type ApplyOperationPhase string
+
+const (
+	// ApplyOperationRequested is an operation GitOps Reverser has asked the applier for.
+	ApplyOperationRequested ApplyOperationPhase = "Requested"
+	// ApplyOperationRunning is an operation the applier is seen working on.
+	ApplyOperationRunning ApplyOperationPhase = "Running"
+	// ApplyOperationSettling is a Flux operation that has applied, and whose Kustomization is not
+	// yet seen suspended again.
+	ApplyOperationSettling ApplyOperationPhase = "Settling"
+	// ApplyOperationUnresolved is an operation that has not completed in the time it was given. It
+	// is still followed, and no timer ends it.
+	ApplyOperationUnresolved ApplyOperationPhase = "Unresolved"
+	// ApplyOperationSucceeded is an operation that completed and applied.
+	ApplyOperationSucceeded ApplyOperationPhase = "Succeeded"
+	// ApplyOperationFailed is an operation that completed without applying the commit. It may have
+	// applied part of it.
+	ApplyOperationFailed ApplyOperationPhase = "Failed"
+)
+
+// Completed reports whether the phase ends its operation.
+func (p ApplyOperationPhase) Completed() bool {
+	return p == ApplyOperationSucceeded || p == ApplyOperationFailed
+}
+
+// ApplyOperation is an apply GitOps Reverser started on the trigger's applier: the one in flight,
+// or the last one, once it completed. The branch worker writes it on every transition.
+type ApplyOperation struct {
+	// Phase is where the operation stands. Requested, Running, Settling and Unresolved are in
+	// flight: while one is, an edit to an object the applier applies can still be reverted by it,
+	// and the applier is asked nothing else. Succeeded and Failed have completed.
+	// +required
+	Phase ApplyOperationPhase `json:"phase"`
+
+	// Reason is why the apply was asked for. With several GitTargets on the trigger, it is the
+	// strongest of their reasons.
+	// +optional
+	Reason ApplyReason `json:"reason,omitempty"`
+
+	// Commit is the commit the applier was asked to apply. Empty when the remote did not carry the
+	// branch.
+	// +optional
+	Commit string `json:"commit,omitempty"`
+
+	// Token identifies the request in the applier's own status: the reconcile.fluxcd.io/requestedAt
+	// value on a Flux object, or the "gitops-reverser request" entry in an Argo CD operation's info.
+	// +optional
+	Token string `json:"token,omitempty"`
+
+	// SuspendToken is the reconcile.fluxcd.io/requestedAt value the suspend after the apply carried.
+	// Once the Kustomization reports it handled, nothing started before the suspend is still
+	// running. Flux only.
+	// +optional
+	SuspendToken string `json:"suspendToken,omitempty"`
+
+	// AppliedRevision is the revision the applier reports it applied once the operation completed.
+	// It can differ from commit when the branch moved between the check and the apply.
+	// +optional
+	AppliedRevision string `json:"appliedRevision,omitempty"`
+
+	// RequestedAt is when the applier was asked.
+	// +required
+	RequestedAt metav1.Time `json:"requestedAt"`
+
+	// FinishedAt is when the operation was seen to complete.
+	// +optional
+	FinishedAt *metav1.Time `json:"finishedAt,omitempty"`
+
+	// Message says why a Failed operation failed, or why an Unresolved one is overdue.
+	// +optional
+	Message string `json:"message,omitempty"`
+}
+
+// DefaultApplierQuietPeriod is FluxTrigger.spec.quietPeriod when it is omitted.
+const DefaultApplierQuietPeriod = 30 * time.Second
+
+// ApplyTrigger is what every trigger kind answers, so the controllers, the branch workers and the
+// dispatcher handle a FluxTrigger and an ArgoCDTrigger alike.
+// +kubebuilder:object:generate=false
+type ApplyTrigger interface {
+	metav1.Object
+	runtime.Object
+
+	// TriggerKind is the trigger's kind (ApplyTriggerKind*).
+	TriggerKind() string
+	// ClusterProvider is the name of the ClusterProvider whose cluster holds the applier.
+	ClusterProvider() string
+	// ApplierKind is the kind of applier the trigger holds (ApplierKind*).
+	ApplierKind() string
+	// Applier is the object the trigger holds, its namespace defaulted to the trigger's own.
+	Applier() types.NamespacedName
+	// EffectiveQuietPeriod is how long the branch must be quiet before a CatchUp.
+	EffectiveQuietPeriod() time.Duration
+	// SourceBinding is the repository and branch the applier applies, as the trigger last read
+	// them, and false when it has not read them.
+	SourceBinding() (repositoryURL, branch string, known bool)
+	// SharedSource is the source object the applier reads, which other appliers may read too, and
+	// false when the applier has none it shares this way or the trigger has not read it. Appliers
+	// sharing one have one operation at a time.
+	SharedSource() (source types.NamespacedName, known bool)
+	// Prefetches reports whether a push may be fetched into the shared source ahead of the apply:
+	// every other reader of it is held, so a new artifact applies nothing on its own.
+	Prefetches() bool
+	// Operation is status.operation, and SetOperation replaces it and status.repairPending.
+	Operation() *ApplyOperation
+	RepairPending() bool
+	SetOperation(operation *ApplyOperation, repairPending bool)
+	// StatusConditions returns the condition set, and SetObservedGeneration stamps the generation.
+	StatusConditions() *[]metav1.Condition
+	SetObservedGeneration(generation int64)
+}
+
+// NewApplyTrigger returns an empty trigger of kind, or nil for a kind this release does not know.
+func NewApplyTrigger(kind string) ApplyTrigger {
+	switch kind {
+	case ApplyTriggerKindFlux:
+		return &FluxTrigger{}
+	case ApplyTriggerKindArgoCD:
+		return &ArgoCDTrigger{}
+	default:
+		return nil
+	}
+}
+
+// defaultedNamespace is namespace, or fallback when it is empty.
+func defaultedNamespace(namespace, fallback string) string {
+	if namespace == "" {
+		return fallback
+	}
+	return namespace
+}
+
+// clusterProviderName is ref's name, or DefaultClusterProviderName when ref names none, the way
+// GitTarget.SourceCluster resolves an omitted clusterProviderRef.
+func clusterProviderName(ref *meta.LocalObjectReference) string {
+	if ref == nil || ref.Name == "" {
+		return DefaultClusterProviderName
+	}
+	return ref.Name
+}