Documentation
¶
Overview ¶
Package ansible implements the host-convergence lifecycle backend: declared playbooks executed inside a containerized ansible runtime (the execution image) against SSH-managed hosts. The package returns DATA — plans, recaps, aggregates; all terminal rendering belongs to cli/cmd.
Index ¶
- func CredentialsPresent(cfg *config.Config) bool
- type Aggregate
- type Backend
- func (b *Backend) Aggregate() Aggregate
- func (b *Backend) Capabilities() []runtime.Capability
- func (b *Backend) Cleanup(rctx *runtime.RuntimeContext)
- func (b *Backend) Execute(ctx context.Context, plan *runtime.LifecyclePlan, rctx *runtime.RuntimeContext) (*runtime.LifecycleResult, error)
- func (b *Backend) ImageID() string
- func (b *Backend) ImageRef() string
- func (b *Backend) Name() string
- func (b *Backend) Plan(ctx context.Context, cfg *config.Config, rctx *runtime.RuntimeContext) (*runtime.LifecyclePlan, error)
- func (b *Backend) PlayResults() []PlayResult
- func (b *Backend) Prepare(ctx context.Context, cfg *config.Config, rctx *runtime.RuntimeContext) error
- func (b *Backend) SelectPlay(p config.AnsiblePlaybook)
- func (b *Backend) SetExtraVars(vars []string)
- func (b *Backend) SetStream(f func(playID string) io.WriteCloser)
- func (b *Backend) Validate(ctx context.Context, cfg *config.Config, rctx *runtime.RuntimeContext) error
- type HostRecap
- type PlayResult
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
func CredentialsPresent ¶
CredentialsPresent reports whether the SSH key material this config needs is available in the environment — raw (<PREFIX>_SSH_KEY) or base64 (<PREFIX>_SSH_KEY_B64, the maskable single-line form, mirroring the gitops <NAME>_CA_B64 convention). The key ships as a forge-protected variable, so MR/unprotected-ref pipelines legitimately lack it — dispatch uses this for a clear "skipped" instead of a mid-run auth failure.
Types ¶
type Aggregate ¶
type Aggregate struct {
Total int // unique hosts touched across the set
Converged int // hosts with zero failed/unreachable in every play
Changed int // hosts where at least one play changed something
Unreachable int // hosts unreachable in at least one play
Failed int // hosts failed in at least one play
}
Aggregate is the converge-set rollup that feeds the ansible.* facts.
func AggregateResults ¶
func AggregateResults(plays []PlayResult) Aggregate
AggregateResults rolls per-play recaps up to unique-host totals.
type Backend ¶
type Backend struct {
// contains filtered or unexported fields
}
Backend implements runtime.LifecycleBackend for containerized ansible.
Scope defaults to the config's converge set (perform reconcile). SelectPlay narrows it to one named entry — the `ansible run <id>` path, which is also the ONLY way a converge:false runbook ever executes.
func (*Backend) Capabilities ¶
func (b *Backend) Capabilities() []runtime.Capability
func (*Backend) Cleanup ¶
func (b *Backend) Cleanup(rctx *runtime.RuntimeContext)
func (*Backend) Execute ¶
func (b *Backend) Execute(ctx context.Context, plan *runtime.LifecyclePlan, rctx *runtime.RuntimeContext) (*runtime.LifecycleResult, error)
Execute converges each play in scope, in declared order. FAIL LOUD: any failed or unreachable host fails that play's action — there is no silent partial converge.
func (*Backend) ImageRef ¶
ImageRef returns the resolved execution image reference (for trust display).
func (*Backend) Plan ¶
func (b *Backend) Plan(ctx context.Context, cfg *config.Config, rctx *runtime.RuntimeContext) (*runtime.LifecyclePlan, error)
Plan describes the plays in scope. In dry-run it runs each play with --check --diff — a real (approximate) plan against the live hosts; the terraform plan/apply idiom. In execute mode it stays off the network: the apply itself reports per-host truth, and doubling every converge with a full --check SSH pass would tax the fleet for information the recap delivers minutes later anyway.
func (*Backend) PlayResults ¶
func (b *Backend) PlayResults() []PlayResult
PlayResults returns the structured per-play outcomes after Execute (or the check results after a dry-run Plan).
func (*Backend) Prepare ¶
func (b *Backend) Prepare(ctx context.Context, cfg *config.Config, rctx *runtime.RuntimeContext) error
Prepare resolves the SSH identity: the key from <PREFIX>_SSH_KEY (decrypted via <PREFIX>_SSH_KEY_PASSPHRASE when set) is validated and held in process memory — no tmpfile; it reaches each play container over stdin. Also validates every play's groups against the inventory so an empty --limit fails here, not silently inside ansible.
func (*Backend) SelectPlay ¶
func (b *Backend) SelectPlay(p config.AnsiblePlaybook)
SelectPlay narrows execution to a single declared play (the run verb).
func (*Backend) SetExtraVars ¶
SetExtraVars supplies launch-time -e key=val pairs (the run verb).
func (*Backend) SetStream ¶
func (b *Backend) SetStream(f func(playID string) io.WriteCloser)
SetStream supplies a per-play live-output sink factory. The backend tees the play's raw subprocess output into it as it runs (pure passthrough — presentation, section markers, and destination belong to the caller) while still capturing the full text for recap parsing. Nil disables streaming.
type HostRecap ¶
type HostRecap struct {
Host string
OK int
Changed int
Unreachable int
Failed int
Skipped int
Rescued int
Ignored int
}
HostRecap is one host's line from an ansible PLAY RECAP block.
func ParseRecap ¶
ParseRecap extracts per-host counters from ansible-playbook output. Only lines after the "PLAY RECAP" marker are considered, so task output that happens to look counter-shaped can't pollute the result. An output with no recap returns nil — the caller treats that as a failed, unparseable run.
type PlayResult ¶
type PlayResult struct {
ID string // playbook id from the library
Path string // repo-relative playbook path
Check bool // true when run with --check --diff (plan mode)
ExitCode int
Hosts []HostRecap
Output string // combined stdout/stderr (human stream, recap included)
}
PlayResult is the structured outcome of executing one playbook.
func (PlayResult) FailedHosts ¶
func (p PlayResult) FailedHosts() []string
FailedHosts returns the hosts that failed or were unreachable.
Source Files