semantic

type Action ¶

type Action int

Action is the semantic operation for one ResourceChange. The zero value is invalid.

const (
	// Create is a resource present in Desired and absent from Previous.
	Create Action = iota + 1
	// Update is a resource present in both Previous and Desired whose
	// declared content differs.
	Update
	// Delete means the resource leaves Desired release state. It does not
	// claim that Helm or Kubernetes will delete the live object.
	Delete
)

func (a Action) String() string

type ChartCRD ¶

type ChartCRD struct {
	// Source is the display path under .deployah/crds/.
	Source string
	// Index is the 0-based position among non-empty YAML documents in that
	// file.
	Index int
	// Kind is always CustomResourceDefinition.
	Kind string
	// Name is metadata.name from the source document.
	Name string
	// Lifecycle is Helm's handling of this document in this invocation.
	Lifecycle ChartCRDLifecycle
	// WillProcess is true only when Lifecycle is [ChartCRDProcess].
	// A true value contributes to [Plan.HasEffects].
	WillProcess bool
}

ChartCRD is one chart CRD document for plan presentation. It is Helm chart-CRD lifecycle, not a resource consequence.

type ChartCRDLifecycle ¶

type ChartCRDLifecycle int

ChartCRDLifecycle is Helm's install-only handling of one chart CRD document. The zero value is invalid.

const (
	// ChartCRDProcess means a fresh install will ask Helm to process the
	// chart CRD. It does not claim Kubernetes will create versus apply.
	ChartCRDProcess ChartCRDLifecycle = iota + 1
	// ChartCRDSkip means the CRD is in the chart but install-time
	// processing is disabled.
	ChartCRDSkip
	// ChartCRDUpgrade means the CRD is in the chart and Helm Upgrade will
	// not process it.
	ChartCRDUpgrade
)

func (l ChartCRDLifecycle) String() string

type DriftAction ¶

type DriftAction int

DriftAction is the observed Previous-to-Live state of one resource. The zero value is invalid. It is not a release action: there is no create, update, or delete vocabulary here.

const (
	// DriftModified means Previous and Live both exist and the declared
	// semantic surface differs.
	DriftModified DriftAction = iota + 1
	// DriftMissing means Previous exists and Live does not.
	DriftMissing
	// DriftUnexpected means a release-owned Live object has no Previous
	// logical identity.
	DriftUnexpected
)

func (a DriftAction) String() string

type DriftChange ¶

type DriftChange struct {
	Resource ResourceRef
	Action   DriftAction
	Previous *ResourceSnapshot
	Live     *ResourceSnapshot
	Fields   []FieldChange
}

DriftChange is one difference between Previous and Live. New checks and stores it. It is cluster state, separate from a release change.

Name is required, and GenerateName must be empty. Modified and Missing use the Previous declaration, including its apiVersion. Unexpected uses the Live object. An apiVersion change alone is not drift.

Previous is unset for Unexpected and is never rewritten. Live is unset for Missing. Modified Live keeps only the declared surface. Unexpected Live has server bookkeeping removed. Only Modified has Fields. New keeps them and does not recompute them.

type FieldChange ¶

type FieldChange struct {
	Path   string
	Op     FieldOp
	Before any
	After  any
}

FieldChange is one structural difference between Before and After. Path is an RFC 6901 JSON Pointer. Values are copies, not aliases into snapshots. This type is not a JSON rendering contract.

func DiffFields(before, after map[string]any) ([]FieldChange, error)

type FieldOp ¶

type FieldOp int

FieldOp classifies one structural field difference. The zero value is invalid.

const (
	// FieldAdd is a path present only in After.
	FieldAdd FieldOp = iota + 1
	// FieldRemove is a path present only in Before.
	FieldRemove
	// FieldReplace is a scalar replacement or a JSON type change.
	FieldReplace
)

func (o FieldOp) String() string

type Header ¶

type Header struct {
	Project     string
	Environment string
	Release     string
	Namespace   string
	Context     string
	// Revision is the Helm revision this plan would create. It is 1
	// for a fresh install and ReleasePrep.NextRevision for an upgrade.
	Revision     int
	FreshInstall bool
}

Header identifies the release a plan describes. Empty fields are valid; callers fill them for display.

type HelmAction ¶

type HelmAction int

HelmAction is the Helm release-intent transition a semantic plan describes. It does not control whether deployah deploy invokes Helm. The zero value is invalid.

const (
	// HelmNone means the release intent did not change. The plan must not
	// include resource changes. preDeploy and postDeploy tasks must be
	// unchanged, and WillRun must be false. HelmNone does not stop
	// `deployah deploy` from running Helm.
	HelmNone HelmAction = iota + 1
	// HelmInstall means the release is new. [Header.FreshInstall] must be
	// true.
	HelmInstall
	// HelmUpgrade means an existing release changes. The plan can have no
	// resource changes when only hooks changed, or when the manifests
	// differ only in encoding.
	HelmUpgrade
)

func (a HelmAction) String() string

type HookDefinition ¶

type HookDefinition struct {
	Resource ResourceRef
	Action   Action
	Before   *ResourceSnapshot
	After    *ResourceSnapshot
	Fields   []FieldChange
	// HookWeight is the Helm hook-weight of this document. [New] sorts
	// definitions by HookWeight then identity. It is not a JSON field.
	HookWeight int
}

HookDefinition is a rendered Helm hook document difference for a preDeploy or postDeploy task. It compares Previous and Desired hook declarations. It is not a live Kubernetes apply or prune.

type Input ¶

type Input struct {
	Header     Header
	HelmAction HelmAction
	Changes    []ResourceChange
	Tasks      []TaskPlan
	Drift      []DriftChange
	ChartCRDs  []ChartCRD
}

Input is the caller data for New. TaskPlan.WillRun on Tasks is ignored.

type Plan ¶

type Plan struct {
	Header     Header
	HelmAction HelmAction
	Changes    []ResourceChange
	Drift      []DriftChange
	Tasks      []TaskPlan
	ChartCRDs  []ChartCRD
	Summary    Summary
}

Plan is one run's Helm release intent, its Previous-to-Desired resource changes, and its Previous-to-Live drift. Build it with New. Snapshots still contain secrets, and this type is not the plan JSON document.

func New(in Input) (Plan, error)

func (p Plan) HasDrift() bool

func (p Plan) HasEffects() bool

func (p Plan) IsNoOp() bool

type ResourceChange ¶

type ResourceChange struct {
	Resource ResourceRef
	Action   Action
	// Before is the Previous declaration. It is unset for [Create].
	Before *ResourceSnapshot
	// After is the Desired declaration. It is unset for [Delete].
	After *ResourceSnapshot
	// Fields are the semantic differences the caller computed. [New]
	// keeps them; it does not recompute them from the snapshots.
	Fields []FieldChange
	// HelmOrder is where this change sits in Helm's deploy or upgrade
	// order. A lower number comes first. Create and Update follow
	// Helm's install kind order, and equal kinds keep manifest order.
	// Deletes come after those, in Previous release order. The planner
	// sets it. [New] sorts by HelmOrder, then by the resource
	// reference. It is not written to JSON. It does not say how Helm
	// writes or deletes.
	HelmOrder int
}

ResourceChange is one declarative difference between Previous and Desired for a resource in the Helm release Header names.

type ResourceRef ¶

type ResourceRef struct {
	APIVersion   string
	Kind         string
	Namespace    string
	Name         string
	GenerateName string
}

ResourceRef names one resource in a change. APIVersion comes from the object this change uses. Core resources use "v1". Namespace is the effective namespace used to pair Previous and Desired. It is not always the namespace written in the snapshot. GenerateName is set only when Name is empty.

Sorting and task links compare every field, including APIVersion and GenerateName. That comparison is not logical identity. Logical identity ignores APIVersion and does not use GenerateName.

func (r ResourceRef) String() string

type ResourceSnapshot ¶

type ResourceSnapshot struct {
	Object map[string]any
}

ResourceSnapshot is one Kubernetes object, with secret values still present. Object is a plain map, not a typed client object. It is not the JSON document the plan view writes.

type Summary ¶

type Summary struct {
	Create int
	Update int
	Delete int
}

Summary counts ResourceChange values by action. New always sets it from Summarize; callers cannot supply an independent summary.

func Summarize(changes []ResourceChange) Summary

func (s Summary) Total() int

type TaskAction ¶

type TaskAction int

TaskAction is the definition-level action for a TaskPlan. The zero value is invalid. It is independent of TaskPlan.WillRun.

const (
	// TaskUnchanged means the task still exists and its definition did
	// not change.
	TaskUnchanged TaskAction = iota + 1
	// TaskCreate means the task is new in the desired spec.
	TaskCreate
	// TaskUpdate means the task still exists and at least one rendered
	// definition or referenced resource changed.
	TaskUpdate
	// TaskDelete means the task was removed. WillRun is always false.
	TaskDelete
)

func (a TaskAction) String() string

type TaskPhase ¶

type TaskPhase int

TaskPhase is when a TaskPlan belongs in a deploy. The zero value is invalid.

const (
	// TaskPreDeploy is a preDeploy hook task.
	TaskPreDeploy TaskPhase = iota + 1
	// TaskPostDeploy is a postDeploy hook task.
	TaskPostDeploy
	// TaskSchedule is a scheduled task whose backing objects are normal
	// Helm Manifest resources.
	TaskSchedule
)

func (p TaskPhase) String() string

type TaskPlan ¶

type TaskPlan struct {
	Name   string
	Phase  TaskPhase
	Action TaskAction
	// WillRun reports whether this task's hook takes part in the Helm
	// transition. [New] sets it and ignores a caller value. Schedule
	// and delete tasks do not run. Other preDeploy and postDeploy
	// tasks run for [HelmInstall] and [HelmUpgrade], and do not run
	// for [HelmNone]. It does not predict whether a later
	// `deployah deploy` skips the hook.
	WillRun     bool
	Definitions []HookDefinition
	Resources   []ResourceRef
	// HookWeight is the resolved Helm hook-weight used to sort preDeploy
	// and postDeploy tasks. It is not a JSON field.
	HookWeight int
}

TaskPlan is one Deployah task in a Plan.

A preDeploy or postDeploy task carries HookDefinition diffs. A schedule task points at ResourceChange entries in Plan.Changes.

A manual task that exists only in the current spec is left out. If the task is manual now, but was preDeploy, postDeploy, or schedule in the previous release, the plan shows that old hook or schedule as removed.

Moving between schedule and preDeploy or postDeploy is a TaskUpdate of the phase the task has now. The old CronJob stays in Plan.Changes. Old hook documents are not listed as deletes.