Documentation
¶
Overview ¶
Package runner is the CI-side driver: it invokes the same terramate scripts a human runs, captures per-stack output, renders + classifies in-process, and reports progress to the control-plane server over the typed events protocol.
This file is the server client. All reporting is best-effort by design — a down or absent server degrades the build to "no live progress", never to failure — except the apply-time gate check (see gate.go), which is fail-closed. An empty server URL disables the client entirely, so local runs and the no-op `run tick` need no server.
Index ¶
- Constants
- type Client
- func (c *Client) Enabled() bool
- func (c *Client) Finalize(ctx context.Context, f events.Finalize) error
- func (c *Client) GateCheck(ctx context.Context, g events.GateCheck) (string, error)
- func (c *Client) GateRevoke(ctx context.Context, g events.GateRevoke) error
- func (c *Client) Init(ctx context.Context, in events.Init) error
- func (c *Client) LogChunk(ctx context.Context, lc events.LogChunk) error
- func (c *Client) Phase(ctx context.Context, p events.PhaseEvent) error
- func (c *Client) Update(ctx context.Context, u events.Update) error
- type LogPump
- type ScriptRunOptions
- type Terramate
- func (t *Terramate) ChangedStacks(ctx context.Context, base string) ([]string, error)
- func (t *Terramate) List(ctx context.Context) ([]string, error)
- func (t *Terramate) RunGraph(ctx context.Context) ([]events.Edge, error)
- func (t *Terramate) ScriptRun(ctx context.Context, w io.Writer, o ScriptRunOptions) error
Constants ¶
const ( EnvServer = "TFSTACKPLAN_SERVER" // control-plane base URL ("" = offline, no-op) EnvToken = "TFSTACKPLAN_TOKEN" // bearer secret for /api/* EnvExecution = "TFSTACKPLAN_EXECUTION" // execution id this run reports under EnvStack = "TFSTACKPLAN_STACK" // current stack path (fallback for `run tick --stack`) EnvEnvironment = "TFSTACKPLAN_ENVIRONMENT" // deployment environment for the execution )
Environment variables the orchestrator (`run plan`/`run apply`) sets and the per-stack `run tick` reads, so progress reporting needs no flags threaded through the terramate scripts. Empty TFSTACKPLAN_SERVER disables reporting.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Client ¶
type Client struct {
// contains filtered or unexported fields
}
Client posts execution lifecycle events to the control-plane server.
func ClientFromEnv ¶
func ClientFromEnv() *Client
ClientFromEnv builds a Client from TFSTACKPLAN_SERVER + TFSTACKPLAN_TOKEN. When the server var is empty the client is disabled (every call is a no-op).
func NewClient ¶
NewClient builds a client for the server at baseURL (empty disables it) using the given bearer secret. A short timeout keeps a slow/down server from stalling the build.
func (*Client) Enabled ¶
Enabled reports whether a server is configured. When false, every call is a no-op returning nil.
func (*Client) GateCheck ¶
GateCheck is the apply-time, fail-closed gate pre-check. Returns the leased requester SA (when the server reports one) so the caller can impersonate it. No server ⇒ ("", nil) — nothing gates. A 409, any other non-2xx, or an unreachable configured server ⇒ error (apply blocks).
func (*Client) GateRevoke ¶
GateRevoke asks the server to revoke the grants it requested (best-effort post-apply cleanup).
func (*Client) LogChunk ¶
LogChunk streams a slice of one stack's output to the server (best-effort).
type LogPump ¶
type LogPump struct {
// contains filtered or unexported fields
}
LogPump tails each stack's on-disk log file and posts newly-appended bytes to the server. It is the parallel-safe path to per-stack logs: terramate's combined `script run` stream interleaves stacks with no per-stack attribution, so by convention each stack's script writes its own file (`<root>/<stack>/<file>`, e.g. via `terraform plan ... 2>&1 | tee tfstackplan.log`) and the pump tails it. All posts are best-effort.
func NewLogPump ¶
NewLogPump builds a pump that posts via p, reading the file named `file` in each stack dir under root, tagging chunks with execID.
type ScriptRunOptions ¶
type ScriptRunOptions struct {
Script string // the terramate script name (e.g. "plan")
Changed bool // --changed: only changed stacks
Parallel int // --parallel N (0 = terramate default)
Base string // -B <ref> for change detection
}
ScriptRunOptions controls `terramate script run`.
type Terramate ¶
type Terramate struct {
Bin string // terramate binary; defaults to "terramate"
Dir string // project root (process cwd for every invocation)
}
Terramate shells out to the terramate binary. Dir is the project root: it is set as the process working directory (so asdf resolves the project's .tool-versions and terramate operates on that tree) — no --chdir is used.
func (*Terramate) ChangedStacks ¶
ChangedStacks returns the stacks changed relative to base (empty uses terramate's configured default).
Source Files