Documentation
¶
Overview ¶
Package source provides just-in-time (JIT) vendoring of component sources from source configuration in stack manifests.
Index ¶
- Constants
- func AutoProvisionSource(ctx context.Context, atmosConfig *schema.AtmosConfiguration, ...) (retErr error)
- func CheckDeletable(atmosConfig *schema.AtmosConfiguration, componentType string, targetDir string, ...) error
- func DetermineTargetDirectory(atmosConfig *schema.AtmosConfiguration, componentType string, component string, ...) (string, error)
- func ExtractSource(componentConfig map[string]any) (*schema.VendorComponentSource, error)
- func HasProvenance(dir string) bool
- func HasSource(componentConfig map[string]any) bool
- func Provision(ctx context.Context, params *ProvisionParams) error
- func VendorSource(ctx context.Context, atmosConfig *schema.AtmosConfiguration, ...) error
- func WriteProvenance(dir string, p *Provenance) error
- type Provenance
- type ProvisionParams
- type Target
- type VendorSourceOption
Constants ¶
const ( // DefaultVendorTimeout is the default timeout for vendor operations. DefaultVendorTimeout = 10 * time.Minute // TargetDirPermissions is the permissions for created target directories. TargetDirPermissions = 0o755 )
const DirPermissions = 0o755
DirPermissions is the default permission mode for directories.
const HookEventBeforeTerraformInit = provisioner.HookEvent("before.terraform.init")
HookEventBeforeTerraformInit is the hook event for before terraform init.
const ProvenanceFile = "source.json"
ProvenanceFile is the marker the source provisioner writes inside every shared (non-workdir) component directory it populates: <component dir>/.atmos/source.json.
`source delete` only removes directories that carry this marker (or, for workdir targets, the workdir metadata the provisioner already writes), so it can never delete a hand-written component directory that merely shares a name with a source-provisioned instance. Directories vendored by an Atmos version that predates the marker have none; re-run `source pull --force` to add it.
Variables ¶
This section is empty.
Functions ¶
func AutoProvisionSource ¶
func AutoProvisionSource( ctx context.Context, atmosConfig *schema.AtmosConfiguration, componentType string, componentConfig map[string]any, authContext *schema.AuthContext, writers provisioner.OutputWriters, ) (retErr error)
AutoProvisionSource automatically vendors component source on first use. This enables JIT (Just-in-Time) vendoring - sources are fetched automatically when running terraform/helmfile/packer commands if the target directory doesn't exist.
Parameters: - componentType: the type of component ("terraform", "helmfile", or "packer").
Behavior: - If component has no source configured: skip (not an error). - If target directory already exists: skip (use CRUD commands for updates). - If workdir is enabled: download source directly to workdir path. - If workdir is NOT enabled: download source to component path.
func CheckDeletable ¶
func CheckDeletable( atmosConfig *schema.AtmosConfiguration, componentType string, targetDir string, stackComponents map[string]any, ) error
CheckDeletable verifies that targetDir is safe for `source delete` to remove.
It refuses (ErrSourceDeleteRefused) when:
- targetDir is the local component directory of a component in stackComponents that has no `source:` (a hand-written component that merely shares a directory with the instance), or
- targetDir carries no evidence the source provisioner created it (see HasProvenance).
stackComponents is the `components.<type>` map of the stack being operated on (component instance name to its section). The check is read-only.
func DetermineTargetDirectory ¶
func DetermineTargetDirectory( atmosConfig *schema.AtmosConfiguration, componentType string, component string, componentConfig map[string]any, ) (string, error)
DetermineTargetDirectory determines where to vendor the component source. Priority: 1. Working_directory if specified in component config (metadata or settings). 2. Workdir path if provision.workdir.enabled is true: .workdir/<type>/<stack>-<component>/. 3. Default component path: <base_path>/<component>.
func ExtractSource ¶
func ExtractSource(componentConfig map[string]any) (*schema.VendorComponentSource, error)
ExtractSource extracts the source specification from component config. Supports both string form (go-getter URI) and map form (VendorComponentSource). Returns nil, nil if no source is configured (not an error).
func HasProvenance ¶
HasProvenance reports whether the source provisioner populated dir: it carries either the provenance marker or, for workdir targets, the workdir metadata the provisioner writes.
func HasSource ¶
HasSource checks if component config has a valid source defined. Returns true only if the source has a valid URI.
func Provision ¶
func Provision(ctx context.Context, params *ProvisionParams) error
Provision vendors a component source based on source configuration. It extracts the source spec from component config, resolves it, and vendors to the appropriate target directory.
func VendorSource ¶
func VendorSource( ctx context.Context, atmosConfig *schema.AtmosConfiguration, sourceSpec *schema.VendorComponentSource, targetDir string, options ...VendorSourceOption, ) error
VendorSource vendors a component source to the target directory. It uses go-getter via the existing downloader infrastructure. Downloads preserve caller cancellation and scoped source credentials.
func WriteProvenance ¶
func WriteProvenance(dir string, p *Provenance) error
WriteProvenance writes the provisioner marker into dir.
Types ¶
type Provenance ¶
type Provenance struct {
// Component is the resolved component name that names the directory.
Component string `json:"component"`
// Stack is the stack the directory was provisioned for.
Stack string `json:"stack,omitempty"`
// Source is the credential-free form of the source URI.
Source string `json:"source"`
// Version is the source version, when one was declared separately.
Version string `json:"version,omitempty"`
// ProvisionedAt is the provisioning time.
ProvisionedAt time.Time `json:"provisioned_at"`
}
Provenance records which component instance the source provisioner placed into a directory.
type ProvisionParams ¶
type ProvisionParams struct {
AtmosConfig *schema.AtmosConfiguration
ComponentType string // "terraform", "helmfile", etc.
Component string
Stack string
ComponentConfig map[string]any
AuthContext *schema.AuthContext
Force bool // Force re-vendor even if already exists.
}
ProvisionParams contains parameters for source provisioning.
type Target ¶
type Target struct {
// Dir is the absolute or base-path-relative destination directory.
Dir string
// IsWorkdir reports that Dir is an isolated per-instance workdir rather than a shared
// components/<type>/<component> directory.
IsWorkdir bool
// Component is the resolved component name (the base component, i.e. metadata.component, not
// the instance name) that names the directory outside workdir mode.
Component string
}
Target is the directory the source provisioner populates for one component instance.
It is resolved by a single function, ResolveTarget, shared by the runtime (AutoProvisionSource, used by render/deploy/plan) and by the `source pull` / `source delete` commands, so the commands always act on exactly the directory the runtime reads from.
func ResolveTarget ¶
func ResolveTarget( atmosConfig *schema.AtmosConfiguration, componentType string, fallbackComponent string, componentConfig map[string]any, ) (*Target, error)
ResolveTarget resolves where the source provisioner places a component's source.
The component name is taken from the component configuration the same way AutoProvisionSource takes it (the base component: "component", then "metadata.component", then the instance name "atmos_component"); fallbackComponent is used only when the configuration carries no name at all. Unsafe names (absolute, volume-qualified, or escaping the components directory) are rejected before any filesystem path is built. Placement honors provision.workdir.enabled and working_directory exactly as the runtime does.
type VendorSourceOption ¶ added in v1.223.0
type VendorSourceOption func(*vendorSourceOptions)
func WithBaseDir ¶ added in v1.226.0
func WithBaseDir(baseDir string) VendorSourceOption
WithBaseDir anchors a relative local-path source against baseDir instead of the process's current working directory. Callers that already resolve a working directory for the target path (e.g. the workdir step, which anchors `path` to `working_directory`) should pass the same directory here so a relative `source` resolves consistently with `path` instead of silently falling back to the process cwd.
func WithReplaceTarget ¶ added in v1.223.0
func WithReplaceTarget(replace bool) VendorSourceOption
WithReplaceTarget controls whether VendorSource may replace an existing target directory.
Source Files
Directories