Documentation
¶
Index ¶
- Constants
- func IsPlanRequired(atmosConfig *schema.AtmosConfiguration, ciEnabled bool, ...) bool
- func ResolveVerifyMode(atmosConfig *schema.AtmosConfiguration, ciEnabled bool, ...) schema.PlanfileVerifyMode
- func StorageConfigured(pf *schema.PlanfilesConfig) bool
- func WritePlanfileResults(results []FileResult, planfilePath string) error
- func WritePlanfileResultsForVerification(results []FileResult, storedPlanPath, canonicalPlanPath string) error
- type FileEntry
- type FileResult
- type KeyContext
- type KeyPattern
- type Metadata
- type PlanfileInfo
- type Query
- type Store
- type StoreOptions
Constants ¶
const ( // PlanFilename is the well-known name for the plan file within a bundle. PlanFilename = "plan.tfplan" // LockFilename is the well-known name for the lock file within a bundle. LockFilename = ".terraform.lock.hcl" // StoredPlanPrefix is the prefix used for stored planfiles during plan verification. // When --verify-plan is set in CI mode, the downloaded planfile gets this prefix // so terraform can generate a fresh plan at the canonical path for comparison. StoredPlanPrefix = "stored." )
Variables ¶
This section is empty.
Functions ¶
func IsPlanRequired ¶ added in v1.222.0
func IsPlanRequired(atmosConfig *schema.AtmosConfiguration, ciEnabled bool, cliOverride schema.PlanfileVerifyMode) bool
IsPlanRequired reports whether `atmos terraform deploy` must find a stored planfile to verify against (as opposed to ResolveVerifyMode, which governs the drift comparison once a stored plan exists). Resolution:
- When verification resolves to off, nothing is downloaded or verified, so a stored plan is never required (this also short-circuits an explicit `required: true` paired with `--verify-plan=false`).
- An explicit components.terraform.planfiles.required wins.
- Unset: required tracks verify strictness — true only when verification resolves to fail (e.g. under CI with storage configured). This makes a fail-by-default deploy fail loudly on a missing plan instead of silently applying an unverified fresh plan; local deploys (no CI, no storage) resolve to off and are never required.
The cliOverride is empty when neither flag was set.
func ResolveVerifyMode ¶ added in v1.222.0
func ResolveVerifyMode(atmosConfig *schema.AtmosConfiguration, ciEnabled bool, cliOverride schema.PlanfileVerifyMode) schema.PlanfileVerifyMode
ResolveVerifyMode resolves the effective planfile drift-verification mode for `atmos terraform deploy`, applying precedence:
explicit CLI override (--verify-plan / --verify-plan=false) > config (components.terraform.planfiles.verify) > default: fail when CI is enabled and planfile storage is configured, else off.
cliOverride is empty when neither flag was set.
func StorageConfigured ¶ added in v1.222.0
func StorageConfigured(pf *schema.PlanfilesConfig) bool
StorageConfigured reports whether explicit planfile storage is configured (via a default store, a priority list, or named stores). When no planfile configuration exists, upload/download/verify are skipped.
func WritePlanfileResults ¶
func WritePlanfileResults(results []FileResult, planfilePath string) error
WritePlanfileResults writes downloaded planfile results to disk. It maps PlanFilename to planfilePath and LockFilename to the same directory. Parent directories are created as needed. Unknown filenames are skipped.
func WritePlanfileResultsForVerification ¶
func WritePlanfileResultsForVerification(results []FileResult, storedPlanPath, canonicalPlanPath string) error
WritePlanfileResultsForVerification writes downloaded planfile results for plan verification. The plan file is written to storedPlanPath (with stored prefix), while the lock file is written relative to canonicalPlanPath (the canonical location where terraform expects it). This separation allows terraform to generate a fresh plan at the canonical path for comparison.
Types ¶
type FileResult ¶
type FileResult = artifact.FileResult
Type aliases to align planfile types with artifact types.
type KeyContext ¶
type KeyContext struct {
Stack string
Component string
ComponentPath string
SHA string
BaseSHA string
Branch string
PRNumber int
RunID string
}
KeyContext contains the context for generating a planfile key.
type KeyPattern ¶
type KeyPattern struct {
Pattern string
}
KeyPattern holds the pattern configuration for generating planfile keys.
func DefaultKeyPattern ¶
func DefaultKeyPattern() KeyPattern
DefaultKeyPattern returns the default planfile key pattern.
func (KeyPattern) GenerateKey ¶
func (p KeyPattern) GenerateKey(ctx *KeyContext) (string, error)
GenerateKey generates a planfile key from the context using the pattern. Returns an error if required fields (Stack, Component, SHA) are empty when they are used in the pattern.
type Metadata ¶
type Metadata struct {
artifact.Metadata
// PlanSummary contains a human-readable summary of the plan.
PlanSummary string `json:"plan_summary,omitempty"`
// HasChanges indicates whether the plan has changes.
HasChanges bool `json:"has_changes"`
// Additions is the number of resources to add.
Additions int `json:"additions"`
// Changes is the number of resources to change.
Changes int `json:"changes"`
// Destructions is the number of resources to destroy.
Destructions int `json:"destructions"`
// TerraformVersion is the version of Terraform used.
TerraformVersion string `json:"terraform_version,omitempty"`
// TerraformTool is the Terraform tool used (e.g., "terraform", "tofu").
TerraformTool string `json:"terraform_tool,omitempty"`
}
Metadata contains metadata about a stored planfile. It embeds artifact.Metadata for common CI artifact fields and adds planfile-specific fields for Terraform plan data.
type PlanfileInfo ¶
type PlanfileInfo struct {
// Key is the storage key/path.
Key string `json:"key"`
// Size is the file size in bytes.
Size int64 `json:"size"`
// LastModified is when the file was last modified.
LastModified time.Time `json:"last_modified"`
// Metadata contains the planfile metadata if available.
Metadata *Metadata `json:"metadata,omitempty"`
}
PlanfileInfo contains basic information about a stored planfile.
type Store ¶
type Store interface {
// Name returns the store type name (e.g., "aws/s3", "azure/blob", "google/gcs", "github/artifacts", "local/dir").
Name() string
// Upload uploads a planfile to the store.
Upload(ctx context.Context, name string, files []FileEntry, metadata *Metadata) error
// Download downloads a planfile from the store.
Download(ctx context.Context, name string) ([]FileResult, *Metadata, error)
// Delete deletes a planfile from the store.
Delete(ctx context.Context, name string) error
// List lists planfiles matching the given query.
List(ctx context.Context, query Query) ([]PlanfileInfo, error)
// Exists checks if a planfile exists.
Exists(ctx context.Context, name string) (bool, error)
// GetMetadata retrieves metadata for a planfile without downloading the content.
GetMetadata(ctx context.Context, name string) (*Metadata, error)
}
Store defines the interface for planfile storage backends. Implementations include S3, Azure Blob, GCS, GitHub Artifacts, and local filesystem.
type StoreOptions ¶
type StoreOptions = artifact.StoreOptions
Type aliases to align planfile types with artifact types.
func NewAtmosConfig ¶
func NewAtmosConfig(storeType string, options map[string]any, atmosConfig *schema.AtmosConfiguration) StoreOptions
NewAtmosConfig is a helper to build StoreOptions with an AtmosConfiguration. This is used to bridge from planfile-specific config to artifact StoreOptions.
Source Files
Directories