iac

Documentation

Overview

Package iac turns multi-document YAML resource files into a plan of changes against a control plane and applies it through the ordinary REST API, so per-resource authorization applies to every item.

Index

• Constants
• Variables
• func Build(docs []*Document, opts Options) ([]*Resource, []Issue)
• func IsDenied(err error) bool
• func IsNotFound(err error) bool
• func IsUnavailable(err error) bool
• func ParseDocuments(sources []Source) ([]*Document, []Issue)
• func SchemaJSON() ([]byte, error)
• type Action
• type ApplyResult
  • func Apply(ctx context.Context, d Doer, res []*Resource, opts Options, ...) (ApplyResult, error)
  • func (r ApplyResult) OK() bool
• type Change
  • func (c Change) Key() string
• type Document
  • func FilterProject(docs []*Document, project string) []*Document
• type Doer
• type ExportFile
• type ExportOptions
• type ExportResult
  • func Export(ctx context.Context, d Doer, opts ExportOptions) (ExportResult, error)
  • func (r ExportResult) Join() string
• type FieldChange
• type Issue
  • func (i Issue) String() string
• type ItemResult
• type Kind
• type Options
• type Plan
  • func PlanFor(st *State, res []*Resource, opts Options) Plan
  • func (p Plan) Pending() bool
• type Resource
  • func (r *Resource) Key() string
• type Source
• type State
  • func Load(ctx context.Context, d Doer, res []*Resource, opts Options) (*State, error)
  • func (st *State) ManagedApps() []string
• type StatusError
  • func (e *StatusError) Error() string
• type Summary

Constants

const (
	StatusApplied = "applied"
	StatusFailed  = "failed"
	StatusDenied  = "denied"
	StatusSkipped = "skipped"
	StatusNoop    = "noop"
)

Item outcomes.

const (
	OpAdd    = "add"
	OpChange = "change"
	OpRemove = "remove"
	OpKeep   = "keep"
)

Field operations shown in a plan.

const (
	LabelManagedBy = "managed-by"
)

Labels with a meaning of their own.

const SchemaVersion = 1

SchemaVersion is the only resource document version this package accepts.

Variables

var ErrPlanChanged = errors.New("the plan changed since it was reviewed; plan again")

ErrPlanChanged means live state moved between the plan a user reviewed and the apply that followed.

var Kinds = []Kind{KindProject, KindEnvironment, KindTag, KindDatabase, KindApp, KindDomain, KindLoadBalancer, KindPipeline, KindAlertRule}

Kinds lists every kind in the order changes are applied.

Functions

func Build

func Build(docs []*Document, opts Options) ([]*Resource, []Issue)

Build validates every document (schema first, then semantics) and turns them into canonical resources. It returns no resources when any issue exists, so nothing is planned from a partly valid input.

func IsDenied

func IsDenied(err error) bool

IsDenied reports whether err is an authorization failure.

func IsNotFound

func IsNotFound(err error) bool

IsNotFound reports whether err is a 404.

func IsUnavailable

func IsUnavailable(err error) bool

IsUnavailable reports whether err says the feature is not configured.

func ParseDocuments

func ParseDocuments(sources []Source) ([]*Document, []Issue)

ParseDocuments splits sources into documents and decodes each envelope. It reports YAML syntax errors and missing kind or name, nothing deeper; Validate does the schema and semantic checks.

func SchemaJSON

func SchemaJSON() ([]byte, error)

SchemaJSON returns the published JSON Schema: the resource envelope schema with the app.yaml schema definitions merged in unchanged, except that an env value may also be a { secretRef } object.

Types

type Action

type Action string

Action is what a plan item does.

const (
	ActionCreate Action = "create"
	ActionUpdate Action = "update"
	ActionDelete Action = "delete"
	ActionNoop   Action = "noop"
	ActionError  Action = "error"
)

Plan actions.

type ApplyResult

type ApplyResult struct {
	Plan    Plan         `json:"plan"`
	Results []ItemResult `json:"results"`
	Applied int          `json:"applied"`
	Failed  int          `json:"failed"`
	Skipped int          `json:"skipped"`
}

ApplyResult is the outcome of an apply.

func Apply

func Apply(ctx context.Context, d Doer, res []*Resource, opts Options, expectedHash string) (ApplyResult, error)

Apply plans and executes resources through doer. Validation and reading happen before any write; a plan holding an error item applies nothing unless ContinueOnError is set. Items run in dependency order and each goes through the ordinary endpoint, so a denied write is reported on its own item and the rest proceed only when ContinueOnError is set.

func (ApplyResult) OK

func (r ApplyResult) OK() bool

OK reports whether every item that had to change did.

type Change

type Change struct {
	Kind     Kind          `json:"kind"`
	Name     string        `json:"name"`
	Scope    string        `json:"scope,omitempty"`
	Action   Action        `json:"action"`
	Fields   []FieldChange `json:"fields,omitempty"`
	Kept     []FieldChange `json:"kept,omitempty"`
	Warnings []string      `json:"warnings,omitempty"`
	Reason   string        `json:"reason,omitempty"`
	Denied   bool          `json:"denied,omitempty"`
	File     string        `json:"file,omitempty"`
	Line     int           `json:"line,omitempty"`
}

Change is one line of a plan.

func (Change) Key

func (c Change) Key() string

Key is the change's stable identity.

type Document

type Document struct {
	File     string
	Line     int
	Kind     Kind
	Name     string
	Labels   map[string]string
	Root     *yaml.Node
	SpecNode *yaml.Node
}

Document is one parsed YAML document with its envelope decoded.

func FilterProject

func FilterProject(docs []*Document, project string) []*Document

FilterProject keeps the documents that belong to one project: the project itself, its environments, apps and databases, the domains, load balancers, pipelines and alert rules of those apps, and the tags those apps use.

type Doer

type Doer interface {
	Do(ctx context.Context, method, path string, body, out any) error
}

Doer performs one JSON request against the control plane REST API. The CLI implements it over HTTP with the caller's token; the server implements it in process with the caller's own credentials, so per resource authorization applies to every call either way.

type ExportFile

type ExportFile struct {
	Name    string `json:"name"`
	Kind    Kind   `json:"kind"`
	Content string `json:"content"`
}

ExportFile is one exported document.

type ExportOptions

type ExportOptions struct {
	Project string
	App     string
	// IncludeEnvValues writes literal env values; when false every value
	// becomes a ${{ env.NAME }} placeholder.
	IncludeEnvValues bool
}

ExportOptions select what to export.

type ExportResult

type ExportResult struct {
	Files    []ExportFile `json:"files"`
	Warnings []string     `json:"warnings,omitempty"`
}

ExportResult is the exported documents in stable order plus warnings for live settings the documents cannot express.

func Export

func Export(ctx context.Context, d Doer, opts ExportOptions) (ExportResult, error)

Export reads live state and renders it as documents. Output is stable: no timestamps or generated ids, sorted keys and a fixed document order.

func (ExportResult) Join

func (r ExportResult) Join() string

Join concatenates exported files into one multi-document stream.

type FieldChange

type FieldChange struct {
	Path string `json:"path"`
	Op   string `json:"op"`
	Old  string `json:"old,omitempty"`
	New  string `json:"new,omitempty"`
}

FieldChange is one leaf difference. Values under env are never shown.

type Issue

type Issue struct {
	File    string `json:"file,omitempty"`
	Path    string `json:"path,omitempty"`
	Line    int    `json:"line"`
	Message string `json:"message"`
}

Issue is one validation problem, located by file, line and dotted path.

func (Issue) String

func (i Issue) String() string

type ItemResult

type ItemResult struct {
	Change
	Status string `json:"status"`
	Error  string `json:"error,omitempty"`
}

ItemResult is one plan item's outcome.

type Kind

type Kind string

Kind names a resource document type.

const (
	KindProject      Kind = "Project"
	KindEnvironment  Kind = "Environment"
	KindTag          Kind = "Tag"
	KindDatabase     Kind = "Database"
	KindApp          Kind = "App"
	KindDomain       Kind = "Domain"
	KindLoadBalancer Kind = "LoadBalancer"
	KindPipeline     Kind = "Pipeline"
	KindAlertRule    Kind = "AlertRule"
)

Resource kinds, in dependency order.

type Options

type Options struct {
	// Vars resolve ${{ env.NAME }} placeholders.
	Vars map[string]string
	// Source names this apply source; apps it creates carry a managed-by
	// tag and only those are ever pruned.
	Source string
	// Secrets maps "NAME" or "app/NAME" to a value to store at apply time.
	// Values never appear in a plan, result or export.
	Secrets map[string]string
	// Project limits prune to managed apps of this project, matching the
	// project filter applied to the files.
	Project string
	// Prune deletes managed resources absent from the files.
	Prune bool
	// NoDeploy skips the restart that applies an env change to a running app.
	NoDeploy bool
	// ContinueOnError keeps applying after an item fails.
	ContinueOnError bool
}

Options carry apply-time inputs that never live in a resource file.

type Plan

type Plan struct {
	Source  string   `json:"source,omitempty"`
	Prune   bool     `json:"prune,omitempty"`
	Changes []Change `json:"changes"`
	Summary Summary  `json:"summary"`
	Hash    string   `json:"hash"`
}

Plan is the ordered set of changes needed to reach the desired state.

func PlanFor

func PlanFor(st *State, res []*Resource, opts Options) Plan

PlanFor computes the plan for resources against live state.

func (Plan) Pending

func (p Plan) Pending() bool

Pending reports whether applying would change anything.

type Resource

type Resource struct {
	Kind   Kind
	Name   string
	Scope  string
	Doc    *Document
	Fields map[string]any
	// SecretRefs are app env names backed by the secrets store.
	SecretRefs []string
	Warnings   []string
}

Resource is one desired object in canonical form, ready to compare with live state.

func (*Resource) Key

func (r *Resource) Key() string

Key is the stable identity used in plans: kind plus scope plus name.

type Source

type Source struct {
	Name string
	Data []byte
}

Source is one input file, or stdin, before parsing.

type State

type State struct {
	// contains filtered or unexported fields
}

State is the live control plane data a plan needs, read through the API with the caller's own permissions. A read the caller may not perform is recorded in denied instead of failing the whole plan.

func Load

func Load(ctx context.Context, d Doer, res []*Resource, opts Options) (*State, error)

Load reads the live state the resources and prune scope need.

func (*State) ManagedApps

func (st *State) ManagedApps() []string

ManagedApps lists the apps carrying this source's managed-by tag.

type StatusError

type StatusError struct {
	Status  int
	Message string
}

StatusError is a non-2xx API answer.

func (*StatusError) Error

func (e *StatusError) Error() string

type Summary

type Summary struct {
	Create int `json:"create"`
	Update int `json:"update"`
	Delete int `json:"delete"`
	Noop   int `json:"noop"`
	Error  int `json:"error"`
}

Summary counts a plan's items by action.