Documentation
¶
Overview ¶
Package terramatestackgraph owns the Terramate stack identity, tagging and ordering rules for Architecture v2 plans generated under the `terramate` target (ADR-0045 section 2 and section 5), and the machine-readable `stackkit.terramate-stack-graph/v1` artifact that the Advanced executor and Techstack consume. Generation renders one `stack.tm.hcl` per stack-bearing render instance and one project root per host; this package is the single authority both the renderer and the graph builder use, so the files and the graph cannot disagree.
Index ¶
Constants ¶
const ( // APIVersion identifies the stack graph document. APIVersion = "stackkit.terramate-stack-graph/v1" // ArtifactID is the plan-owned generation artifact that carries the graph. ArtifactID = "terramate-stack-graph" // ArtifactPath is the graph path relative to generation.outputRoot. ArtifactPath = ".stackkit/terramate-stack-graph.json" // GenerationTarget is the only target that renders the graph. GenerationTarget = "terramate" // OpenTofuRootGenerated marks a stack whose `main.tf` is a generation // artifact (the four kit cores). OpenTofuRootGenerated = "generated" // OpenTofuRootExecutor marks a stack whose `main.tf` the executor // materializes at apply time (workloads, edge and federation owners). OpenTofuRootExecutor = "executor-materialized" )
const ( // RequiredVersion is the Terramate constraint of every generated project. // The release pins Terramate 0.17.1 (scripts/release/fetch-terramate.sh). RequiredVersion = "~> 0.17" // RuntimeRoot is the executor-managed Terramate project root on each host. RuntimeRoot = ".stackkit/runtime" // ProjectRootTemplateRef identifies the per-host project root unit. ProjectRootTemplateRef = "builtin://terramate/project-root/v1" // WorkloadStackTemplateRef identifies the generic workload stack unit. WorkloadStackTemplateRef = "builtin://terramate/stack/workload/v1" // EdgeStackTemplateRef identifies the generic Cloud public edge stack unit. EdgeStackTemplateRef = "builtin://terramate/stack/edge/v1" // FederationStackTemplateRef identifies the generic federation stack unit. FederationStackTemplateRef = "builtin://terramate/stack/federation/v1" )
const ProjectRootConfig = `terramate { required_version = "` + RequiredVersion + `" config { run { env { TF_IN_AUTOMATION = "1" TF_INPUT = "0" } } } } `
ProjectRootConfig is the exact `terramate.tm.hcl` placed at RuntimeRoot on every host. The runtime tree is not a Git repository, so the project relies on explicit stack ordering, not Git change detection.
Variables ¶
This section is empty.
Functions ¶
func Marshal ¶
Marshal emits the canonical graph document: two-space indented JSON with a trailing newline.
Types ¶
type Definition ¶
type Definition struct {
ID string
Name string
Description string
Tags []string
AfterQueries []string
}
Definition is the complete Terramate identity of one stack. The renderer writes it into `stack.tm.hcl`; the graph records the same values.
func Define ¶
func Define(role Role, moduleRef, siteRef, nodeRef string) (Definition, error)
Define derives the stack identity for one module render instance on one host. The ID is stable for the same module, Site and node across plan revisions, so Terramate history and per-stack drift survive regeneration.
type Graph ¶
type Graph struct {
APIVersion string `json:"apiVersion"`
StackID string `json:"stackId"`
PlanHash string `json:"planHash"`
GenerationTarget string `json:"generationTarget"`
TerramateRequiredVersion string `json:"terramateRequiredVersion"`
Hosts []Host `json:"hosts"`
Stacks []Stack `json:"stacks"`
}
Graph is the complete Terramate stack graph of one resolved plan. Every list is sorted, so equal plans yield byte-identical documents.
type Host ¶
type Host struct {
SiteRef string `json:"siteRef"`
NodeRef string `json:"nodeRef"`
ExecutionChannelRef string `json:"executionChannelRef,omitempty"`
ProjectRoot string `json:"projectRoot"`
RootConfigArtifact string `json:"rootConfigArtifact"`
RunOrder []string `json:"runOrder"`
}
Host is one self-contained Terramate project: the executor-managed runtime tree of one node. A Techstack-dispatched change set runs per host through its execution channel, in RunOrder, after every cross-host `after` stack.
type Role ¶
type Role string
Role orders stacks inside a plan. Host and security baseline owners are not stacks; they stay native executor operations.
const ( // RoleCore is the site core of one host (Basement core, Basement core // Lite, Cloud core, Cloud standalone core). Its OpenTofu root is generated. RoleCore Role = "core" // RoleEdge is the Cloud public edge of one host. In Modern it anchors the // Cloud site, which has no Compose core. RoleEdge Role = "edge" // RoleWorkload is one selected application bundle on one host. RoleWorkload Role = "workload" // RoleFederation is one Modern federation or bridge owner on one host. RoleFederation Role = "federation" )
func RoleForTemplate ¶
RoleForTemplate returns the stack role a Terramate render-unit template produces. Unknown templates are not stacks and must fail closed.
type Stack ¶
type Stack struct {
ID string `json:"id"`
Name string `json:"name"`
Role Role `json:"role"`
ModuleRef string `json:"moduleRef"`
UnitRef string `json:"unitRef"`
InstanceRef string `json:"instanceRef"`
SiteRef string `json:"siteRef"`
NodeRef string `json:"nodeRef"`
WorkloadRef string `json:"workloadRef,omitempty"`
RuntimeRoot string `json:"runtimeRoot"`
OpenTofuRoot string `json:"openTofuRoot"`
After []string `json:"after"`
Tags []string `json:"tags"`
Artifacts StackArtifacts `json:"artifacts"`
}
Stack is one Terramate stack: one module render instance on one host.
type StackArtifacts ¶
type StackArtifacts struct {
Stack string `json:"stack"`
OpenTofu string `json:"openTofu,omitempty"`
}
StackArtifacts names the generation artifacts that belong to a stack.