Documentation
¶
Overview ¶
Package argocd implements the engine adapter contract for Argo CD, including current-revision readiness without observedGeneration.
Index ¶
- Constants
- Variables
- func Application(t Target, p *plan.Document, r *plan.Release, valuesJSON []byte) (*unstructured.Unstructured, error)
- func Rebuild(t Target, runtimeUID string, apps []unstructured.Unstructured, also ...string) (*plan.Document, []*plan.Content, error)
- func SpecDigest(app *unstructured.Unstructured) string
- type Adapter
- func (a *Adapter) Adopt(ctx context.Context, fromUID, toUID, name, uid string) error
- func (a *Adapter) Capabilities(ctx context.Context) error
- func (a *Adapter) Ensure(ctx context.Context, p *plan.Document, r *plan.Release, valuesJSON []byte) (*Ensured, error)
- func (a *Adapter) Foreign(ctx context.Context, runtimeUID string) (map[string][]string, error)
- func (a *Adapter) Inventory(ctx context.Context, runtimeUID string) ([]InventoryItem, error)
- func (a *Adapter) Observe(ctx context.Context, p *plan.Document, r *plan.Release, valuesJSON []byte, ...) (Observation, error)
- func (a *Adapter) Orphan(ctx context.Context, runtimeUID string) ([]string, error)
- func (a *Adapter) RebuildLive(ctx context.Context, runtimeUID string, also ...string) (*plan.Document, []*plan.Content, error)
- func (a *Adapter) Refresh(ctx context.Context, r *plan.Release) error
- func (a *Adapter) Remove(ctx context.Context, runtimeUID, name, uid, rollout string) error
- func (a *Adapter) Retired(ctx context.Context, name, uid string) (Observation, error)
- func (a *Adapter) Suspend(ctx context.Context, runtimeUID string, suspended bool) ([]string, error)
- func (a *Adapter) Verify(ctx context.Context, p *plan.Document, r *plan.Release, valuesJSON []byte) error
- type Ensured
- type InventoryItem
- type Observation
- type State
- type Target
Constants ¶
const ( ReasonEngineMissing = "EngineMissing" ReasonProjectMissing = "ProjectMissing" ReasonForeignObject = "ForeignObject" ReasonApplicationGone = "ApplicationMissing" )
Condition reasons the adapter reports.
const ( // ReasonSpecNotWritten: the Application carries another plan. ReasonSpecNotWritten = "SpecNotWritten" // ReasonSpecDrifted: the Application carries this plan but its spec or // the operator's metadata was changed by someone else. ReasonSpecDrifted = "SpecDrifted" // ReasonSyncNotStarted: a Verify step's sync has not started since the // step began, and none is pending. ReasonSyncNotStarted = "SyncNotStarted" // ReasonPriorSyncFailed: the Application carries this plan, but its last // sync of the chart digest failed before the step began, did not provably // apply another source, and no sync is pending. Automated sync never // retries a failed sync of the same revision and source, and a failed hook // leaves the resources Synced, so the step must start one. ReasonPriorSyncFailed = "PriorSyncFailed" // ReasonRetired: the Application a Remove step deletes is gone. ReasonRetired = "Retired" // ReasonReconcileStale: the Application is synced and healthy, but no // sync of the chart's revision succeeded since the step began and, for a // step that does not sync, Argo CD last compared it before then, so the // evidence predates the step. ReasonReconcileStale = "ReconcileStale" )
Observation reasons the rollout controller acts on.
const FieldManager = "aicr-operator"
FieldManager owns the fields the operator applies.
const InClusterServer = "https://kubernetes.default.svc"
InClusterServer is the destination for every Application.
const MaxMessageLen = 240
MaxMessageLen is the most runes of an Argo CD error that an Observation carries.
const OrphanFieldManager = "aicr-operator-orphan"
OrphanFieldManager records orphaned-from when a runtime is deleted with deletionPolicy Orphan.
const PolicyVersion = "argocd.v2"
PolicyVersion names the engine policy this adapter sets on every Application. It is part of plan identity: changing any policy field below requires a new version, so plans and live objects stay comparable. A plan renders under the policy it records, so Applications an earlier operator wrote still match their plan.
const ReasonApplicationEdited = "ApplicationEdited"
ReasonApplicationEdited marks an owned Application whose spec no longer matches what the operator writes, so the plan it came from cannot be rebuilt from it.
const ReasonOrphanAnnotationRefused = "OrphanAnnotationRefused"
ReasonOrphanAnnotationRefused marks an Orphan error that names the Applications the API server refused to annotate, after the rest were.
const RefreshAnnotation = "argocd.argoproj.io/refresh"
RefreshAnnotation asks Argo CD to reconcile an Application now.
const RemovalFieldManager = "aicr-operator-removal"
RemovalFieldManager marks an Application for removal; it is separate from FieldManager so that the partial apply leaves the operator's spec owned.
const ResourcesFinalizer = "resources-finalizer.argocd.argoproj.io"
ResourcesFinalizer makes Argo CD delete an Application's resources, in foreground order, before the Application itself.
const SuspensionFieldManager = "aicr-operator-suspension"
SuspensionFieldManager turns automated sync off and on for spec.suspendEngine. It is the operator's own manager: the next Ensure after a resume takes the field back without reporting an override.
Variables ¶
var AppProjectGVK = schema.GroupVersionKind{Group: "argoproj.io", Version: "v1alpha1", Kind: "AppProject"}
AppProjectGVK is the Argo CD AppProject kind.
var ApplicationGVK = schema.GroupVersionKind{Group: "argoproj.io", Version: "v1alpha1", Kind: "Application"}
ApplicationGVK is the Argo CD Application kind, read and written as unstructured objects so the operator does not depend on Argo CD's module.
Functions ¶
func Application ¶
func Application(t Target, p *plan.Document, r *plan.Release, valuesJSON []byte) (*unstructured.Unstructured, error)
Application renders the desired Application for one plan release, with the plan graph in its annotations so a plan can be rebuilt from it. valuesJSON is the release's canonical values document. It has no resources finalizer: deleting it never deletes the stack.
func Rebuild ¶
func Rebuild(t Target, runtimeUID string, apps []unstructured.Unstructured, also ...string) (*plan.Document, []*plan.Content, error)
Rebuild reconstructs the plan a runtime's Applications were written from: the release graph from the operator's annotations, namespace, chart and values from each spec. It returns the plan, provenance Rebuilt and without a recipe, with its values contents. Automated-sync suspension is runtime state and is ignored. An Application of another runtime, one missing an annotation, or one whose spec differs from what the operator writes for the rebuilt release is reported by name; the rebuilt digest equals the original only when every object was written by the same plan.
Applications of the runtimes named in also are accepted too: an adoption interrupted mid-way leaves some objects with the adopting runtime and the rest with the earlier one, and the plan spans both.
func SpecDigest ¶
func SpecDigest(app *unstructured.Unstructured) string
SpecDigest fingerprints what an Application deploys: its source or sources, Helm values included, and its destination. It leaves out the sync policy, which a suspension toggles, and everything Argo CD writes. It is empty for an object without any of them.
Types ¶
type Adapter ¶
type Adapter struct {
Writer client.Client
Reader client.Reader
Mapper meta.RESTMapper
Target Target
}
Adapter implements the engine contract for Argo CD. Writes go through Writer with server-side apply; every read that decides a write or readiness goes through Reader, which must be uncached.
func (*Adapter) Adopt ¶
Adopt moves one Application from runtime fromUID to toUID: it rewrites the runtime-uid annotation and removes orphaned-from, the Adopt step's only mutation. The patch is preconditioned on the object's UID and current owner, so a recreated or already moved object is never rewritten by mistake; an object already owned by toUID is done.
func (*Adapter) Capabilities ¶
Capabilities reports whether Argo CD can take the operator's writes: the Application CRD is served and the project exists. Only a kind that is not served or a project that is not found carries a reason; any other failure to read them is transient and carries none.
func (*Adapter) Ensure ¶
func (a *Adapter) Ensure(ctx context.Context, p *plan.Document, r *plan.Release, valuesJSON []byte) (*Ensured, error)
Ensure creates or updates the Application for one release: exactly one object, applied with force after an uncached read confirms it is the operator's. An object without this runtime's ownership is foreign and never written.
func (*Adapter) Foreign ¶
Foreign lists, by runtime UID, the runtime's labeled Applications that another runtime UID owns: objects orphaned by deletion or left when a finalizer was removed by hand. A label without the annotation owns nothing and is not listed.
func (*Adapter) Inventory ¶
Inventory lists the runtime's Applications through the uncached reader, sorted by release ID. Objects with the label but another runtime's UID are not the runtime's and are left out.
func (*Adapter) Observe ¶
func (a *Adapter) Observe(ctx context.Context, p *plan.Document, r *plan.Release, valuesJSON []byte, since time.Time, verify bool) (Observation, error)
Observe applies current-revision readiness: an Application is Ready only when it is the operator's object for this plan, Argo CD compared and synced exactly the current spec at the chart digest, it is Healthy, no error condition is present, and that evidence is from after since (the step start). Missing or stale evidence is never Ready.
With verify, for a Verify step, only a sync operation started since the step began counts: a fresh reconcile without a sync never re-ran the gate.
func (*Adapter) Orphan ¶
Orphan annotates every Application of a deleted runtime with operator.aicr.run/orphaned-from and returns the names it annotated. The objects keep their spec, so Argo CD keeps reconciling them, and their annotations remain the record a later runtime adopts from. The annotation is a record only: an Application the API server refuses it for good, such as by an admission policy, is skipped, and the error, of reason ReasonOrphanAnnotationRefused, names it once the rest are annotated.
func (*Adapter) RebuildLive ¶
func (a *Adapter) RebuildLive(ctx context.Context, runtimeUID string, also ...string) (*plan.Document, []*plan.Content, error)
RebuildLive rebuilds the plan from the runtime's live Applications, read through the uncached reader.
func (*Adapter) Refresh ¶
Refresh asks Argo CD to compare a release's Application now rather than at its periodic reconcile, for a step that observes an Application it did not write.
func (*Adapter) Remove ¶
Remove deletes the Application of an approved Remove step. It first marks the object with the rollout and the resources finalizer, so Argo CD deletes the release's resources in foreground order, then deletes it. Only the object with the UID recorded in the step is ever touched; a gone object is already retired.
func (*Adapter) Retired ¶
Retired observes a Remove step: the release is retired once the Application with the recorded UID is gone.
func (*Adapter) Suspend ¶
Suspend turns automated sync off, or back on, for every Application of the runtime, and returns the names it changed. It writes only syncPolicy.automated.enabled and never deletes. While suspended, Argo CD neither syncs nor heals, and the operator starts no step and repairs no drift; the next Ensure after a resume states enabled: true again. One refused write does not stop the rest: the error names every Application left unchanged.
func (*Adapter) Verify ¶
func (a *Adapter) Verify(ctx context.Context, p *plan.Document, r *plan.Release, valuesJSON []byte) error
Verify starts a sync of a release's Application so that Argo CD runs its hooks, a readiness gate, again for the parent's current revision, or retries a failed sync of the current revision that did not provably apply another source, which automated sync never retries. The Application is written with the sync operation in one apply, and only when no operation is pending or running; the caller observes and calls again until a sync has started since its step began.
type Ensured ¶
type Ensured struct {
// Application is the object as written.
Application *unstructured.Unstructured
// Overridden names other field managers that owned fields the operator
// sets; their values were forced back to the plan's.
Overridden []string
}
Ensured is what Ensure wrote and whom it overrode.
type InventoryItem ¶
type InventoryItem struct {
ReleaseID string `json:"releaseID"`
Name string `json:"name"`
UID string `json:"uid"`
PlanDigest string `json:"planDigest"`
Revision string `json:"revision"`
SpecDigest string `json:"specDigest,omitempty"`
}
InventoryItem is one owned Application as the rollout sees it. SpecDigest is omitted when empty, so an inventory recorded without it digests as it did.
type Observation ¶
type Observation struct {
State State
Reason string
SpecDigest string
// Message is a bounded, single-line excerpt of the error Argo CD
// reported with Reason, when it reported one.
Message string
}
Observation is a release's state with the evidence that decided it. SpecDigest is the observed object's; at Ready, it is the spec the operator wrote.
func (Observation) Text ¶
func (o Observation) Text() string
Text is the Reason, followed by the Message when there is one.