terramatestackgraph

package
v0.46.6 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Sep 25, 2026 License: Apache-2.0 Imports: 10 Imported by: 0

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

View Source
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"
)
View Source
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"
)
View Source
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

func Marshal(graph Graph) ([]byte, error)

Marshal emits the canonical graph document: two-space indented JSON with a trailing newline.

func Render

func Render(canonicalPlan []byte) ([]byte, error)

Render builds and marshals the graph of a canonical ResolvedPlan.

func RunOrder

func RunOrder(graph Graph) ([]string, error)

RunOrder returns every stack ID of the graph in the global run order: the same topological order and tie-breaking that derive each host's RunOrder, so cross-host `after` edges (federation after every core and edge) hold.

func StackID

func StackID(moduleRef, siteRef, nodeRef string) string

StackID is `stackkit-` plus the first 20 hex characters of sha256("stackkit.terramate-stack/v1\n<moduleRef>\n<siteRef>\n<nodeRef>").

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.

func Build

func Build(canonicalPlan []byte) (Graph, error)

Build derives the stack graph from a canonical ResolvedPlan generated under the `terramate` target. It reads only plan facts; it never inspects rendered bytes, so the executor can recompute and compare it.

func Parse

func Parse(raw []byte) (Graph, error)

Parse strictly decodes a graph document and proves it is canonical, closed and internally consistent: unknown fields, unsorted lists, identities or orderings that differ from the rules, dangling references and cycles are rejected.

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

func RoleForTemplate(templateRef string) (Role, bool)

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.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL