package configuration import ( "context" "fmt" "os" "path/filepath" "slices" "strings" "google.golang.org/protobuf/proto" errUtils "github.com/cloudposse/atmos/errors" componentconfiguration "github.com/cloudposse/atmos/pkg/component/configuration" "github.com/cloudposse/atmos/pkg/downloader" "github.com/cloudposse/atmos/pkg/perf" adapter "github.com/cloudposse/atmos/pkg/plugin/adapter/component" pluginv1 "github.com/cloudposse/atmos/pkg/plugin/proto/atmos/plugin/v1" "github.com/cloudposse/atmos/pkg/schema" ) // Prepare reevaluates only the selected instance, after the scheduler's dependencies. func (s *Session) Prepare(ctx context.Context, info *schema.ConfigAndStacksInfo) (*schema.PreparedComponentConfiguration, error) { defer perf.Track(nil, "configurationadapter.Prepare")() if !schema.ConfigurationOwned(info.ComponentSettingsSection) { return nil, nil } if info.UseTerraformPlan || info.PlanFile != "" || info.StoredPlanFile != "" { return nil, fmt.Errorf("%w: plugin saved-plan binding is not implemented", errUtils.ErrPluginUnsupportedExtension) } selected, err := s.componentRequest(ctx, info) if err != nil { return nil, err } result, err := s.runProviderPrepare(ctx, info, selected) if err != nil { return nil, err } prepared, err := preparedConfiguration(result) if err != nil { return nil, err } if err := checkSourcesInRoot(ctx, s.root, prepared.Sources); err != nil { return nil, err } return prepared, nil } // runProviderPrepare asks the owning provider to reevaluate the selected unit with every effect // granted, after checking module ownership and engine selection. Only an explicit --command // flag may switch the engine discovered from the global configuration. The dependencies the // scheduler ordered are rechecked first, so no provider effect runs when they changed. func (s *Session) runProviderPrepare(ctx context.Context, info *schema.ConfigAndStacksInfo, selected *selectedComponent) (*pluginv1.PrepareComponentResponse, error) { if err := checkSourceOverride(info, selected.instance); err != nil { return nil, err } if engine := expectedEngine(info, selected.instance); engine != selected.instance.Engine && info.ComponentCommand == "" { return nil, engineMismatch(info, selected.instance.Engine, engine) } if err := s.checkPreparationDependencies(ctx, selected.instance, selected.request.Invocation.Environment, info.SubCommand); err != nil { return nil, err } selected.request.Effects = &pluginv1.ComponentEffects{Commands: true, Network: true, Secrets: true, Writes: true, StateReads: true} result, err := selected.provider.Prepare(ctx, selected.request) if err != nil { return nil, err } if result.Engine != expectedEngine(info, selected.instance) { return nil, errUtils.ErrPluginProtocol } if result.State != nil { s.prepared.Store(addressKey(selected.instance.Address), proto.Clone(result.State)) } return result, nil } // checkSourceOverride rejects a stack that points the component at another module. The module // belongs to the unit's own `terraform { source }`; every other `source` attribute (version, ttl, // included paths) is ordinary configuration and merges normally. func checkSourceOverride(info *schema.ConfigAndStacksInfo, instance *pluginv1.DiscoveredComponent) error { discovered, err := adapter.DecodeObject(instance.Configuration) if err != nil { return err } want, got := sourceURI(discovered["source"]), sourceURI(info.ComponentSection["source"]) if want == "" || got == "" || want == got { return nil } // Either URI can carry credentials, so the error shows only their redacted forms. return errUtils.Build(fmt.Errorf("%w: the Terraform module of component %q in stack %q is owned by its unit, so `source.uri: %s` cannot replace `%s`", errUtils.ErrConfigurationOverrideUnsupported, info.ComponentFromArg, info.Stack, downloader.RedactSource(got), downloader.RedactSource(want))). WithContext("component", info.ComponentFromArg). WithContext("stack", info.Stack). WithHint("Change `terraform { source = ... }` in the unit's `terragrunt.hcl`, or define a regular component with its own `source`"). Err() } // sourceURI returns the module location of a component `source`, written as a string or as a map with `uri`. func sourceURI(source any) string { switch value := source.(type) { case string: return value case map[string]any: uri, _ := value["uri"].(string) return uri } return "" } // engineMismatch explains a command that selects a different engine than the one the component was // discovered with. Stack configuration may pick another version or path of the same engine, but // not switch between Terraform and OpenTofu, because the unit's lock file and state belong to one. func engineMismatch(info *schema.ConfigAndStacksInfo, discovered, selected string) error { return errUtils.Build(fmt.Errorf("%w: command %q selects the %s engine, but component %q was discovered for %s", errUtils.ErrConfigurationOverrideUnsupported, info.Command, selected, info.ComponentFromArg, discovered)). WithContext("component", info.ComponentFromArg). WithContext("stack", info.Stack). WithContext("command", info.Command). WithHint("Set `command` to another " + discovered + " executable, or change `components.terraform.command` in `atmos.yaml` to switch every unit to " + selected). Err() } // expectedEngine is the engine of the command this invocation runs. Discovery records the engine of // the globally configured command, but --command may explicitly select another one, // and the provider prepares for the binary it is given. Any other engine is a protocol violation. func expectedEngine(info *schema.ConfigAndStacksInfo, instance *pluginv1.DiscoveredComponent) string { if info.Command == "" { return instance.Engine } // Match execution's executable-name detection (pkg/component/terraform/detection.go). if strings.Contains(strings.ToLower(filepath.Base(info.Command)), "tofu") { return "opentofu" } return "terraform" } // selectedComponent bundles the request, owning provider, and discovered instance for one component. type selectedComponent struct { request *pluginv1.ComponentRequest provider Provider instance *pluginv1.DiscoveredComponent } // componentRequest shares coordinates and invocation environment, but grants no effects. func (s *Session) componentRequest(ctx context.Context, info *schema.ConfigAndStacksInfo) (*selectedComponent, error) { if err := s.ensure(ctx); err != nil { return nil, err } // A unit that failed discovery reports its own diagnostic, not a generic lookup failure. if err := s.failureFor(info.Stack, info.ComponentFromArg); err != nil { return nil, err } instance, err := s.instanceFor(info) if err != nil { return nil, err } if instance == nil { return nil, errUtils.Build(errUtils.ErrPluginInvalidConfig). WithExplanation("The component is not provided by any enabled configuration provider."). WithContext("component", info.ComponentFromArg). WithContext("stack", info.Stack). WithHint("Run `atmos list instances` to see the discovered and imported components"). Err() } registry, err := s.providers(ctx) if err != nil { return nil, err } provider, ok := registry[instance.Provider] if !ok { return nil, errUtils.ErrPluginUnsupportedExtension } env := preparationEnvironment(info) env["ATMOS_TERRAFORM_BINARY"] = info.Command env["TF_WORKSPACE"] = info.TerraformWorkspace request := &pluginv1.ComponentRequest{ Provider: instance.Provider, Address: instance.Address, Source: instance.Source, RootDirectory: s.root, Configuration: instance.Configuration, ProviderConfiguration: s.providerSettings(instance.Provider), Invocation: &pluginv1.Invocation{Environment: env}, Operation: &pluginv1.ComponentOperation{Command: info.SubCommand, Mode: "native", TerraformArguments: slices.Clone(info.AdditionalArgsAndFlags)}, } return &selectedComponent{request: request, provider: provider, instance: instance}, nil } // instanceFor finds the unit behind a component. A discovered unit is addressed by its derived // stack; an imported unit lives in whichever stack imported it, so it is found by its source file // and addressed as the stack and component the user selected. When a discovered unit and an // imported unit claim the same stack and component, neither is chosen: the conflict is reported. func (s *Session) instanceFor(info *schema.ConfigAndStacksInfo) (*pluginv1.DiscoveredComponent, error) { configuration, _ := info.ComponentSettingsSection["configuration"].(map[string]any) source, _ := configuration["source"].(string) s.importMu.lock() imported := s.imported[source] s.importMu.unlock() if discovered := s.instances[[3]string{info.Stack, "terraform", info.ComponentFromArg}]; discovered != nil { if imported != nil && imported.Source != discovered.Source { return nil, componentconfiguration.ImportConflict(info.ComponentFromArg, discovered.Source, imported.Source, "stack "+info.Stack+": one discovered, one imported") } return discovered, nil } if imported == nil { return nil, nil } instance := proto.Clone(imported).(*pluginv1.DiscoveredComponent) instance.Address = &pluginv1.ComponentAddress{Stack: info.Stack, Component: info.ComponentFromArg, ComponentType: terraformType} return instance, nil } // Reevaluate the inventory without preparation effects before any dependency // outputs are read. Identity and component environment overrides must not change // the units that the scheduler ordered using the original discovery result. func (s *Session) checkPreparationDependencies(ctx context.Context, instance *pluginv1.DiscoveredComponent, env map[string]string, command string) error { baseline := s.preparationBaseline(instance) if baseline == nil { return errUtils.ErrPluginInvalidConfig } request := proto.Clone(baseline.request).(*pluginv1.DiscoverComponentsRequest) request.Invocation = &pluginv1.Invocation{Environment: env} request.Operation = &pluginv1.ComponentOperation{Command: command, Mode: "native"} response, err := s.registry[instance.Provider].Discover(ctx, request) if err != nil { return err } current := make(map[[3]string]*pluginv1.DiscoveredComponent) if err := addDiscovered(make(map[string]map[string]any), current, response); err != nil { return err } selected := current[addressKey(baseline.self.Address)] if !sameDependencyUnit(baseline.self, selected) || !sameDependencies(baseline.self.Dependencies, selected.Dependencies) { return fmt.Errorf("%w: preparation changed discovered dependency paths", errUtils.ErrPluginInvalidConfig) } for _, dependency := range selected.Dependencies { key := addressKey(dependency.Target) before, after := baseline.units[key], current[key] // A target outside the evaluated scope, such as a dependency beyond a single imported // unit's root, is absent from both inventories. The unchanged edge is already compared above. if before == nil && after == nil { continue } if !sameDependencyUnit(before, after) { return fmt.Errorf("%w: preparation changed discovered dependency paths", errUtils.ErrPluginInvalidConfig) } } return s.checkDependencyStates(ctx, baseline, selected.Dependencies, env, command) } // preparationEvidence is the discovery request that found a unit, every unit that request found, // and the unit as that request reported it, all under the provider's own addresses. type preparationEvidence struct { request *pluginv1.DiscoverComponentsRequest units map[[3]string]*pluginv1.DiscoveredComponent self *pluginv1.DiscoveredComponent // importStack is the stack that imported the unit; it is empty for a discovered unit. importStack string } // preparationBaseline finds the evidence for a discovered unit in its provider's discovery // request, and for an imported unit in the import that resolved it. An imported unit is // addressed by the importing stack, so its provider address comes from the cached import. func (s *Session) preparationBaseline(instance *pluginv1.DiscoveredComponent) *preparationEvidence { if discovered := s.instances[addressKey(instance.Address)]; discovered != nil && discovered.Source == instance.Source { for _, request := range s.requests { if request.Provider == instance.Provider { return &preparationEvidence{request: request, units: s.instances, self: discovered} } } return nil } return s.importBaseline(instance) } // importBaseline finds the cached import that resolved an imported unit. func (s *Session) importBaseline(instance *pluginv1.DiscoveredComponent) *preparationEvidence { s.importMu.lock() defer s.importMu.unlock() reported := s.imported[instance.Source] if reported == nil { return nil } for key, units := range s.importResults { if !slices.Contains(units, reported) { continue } template := s.importTemplate(instance.Provider) if template == nil { return nil } request := proto.Clone(template).(*pluginv1.DiscoverComponentsRequest) request.IncludePaths, request.ExcludePaths, request.Imports = nil, nil, []string{key} byAddress := make(map[[3]string]*pluginv1.DiscoveredComponent, len(units)) for _, unit := range units { byAddress[addressKey(unit.Address)] = unit } return &preparationEvidence{request: request, units: byAddress, self: reported, importStack: instance.Address.Stack} } return nil } // importTemplate returns the import request template of a provider, under any configured alias. func (s *Session) importTemplate(provider string) *pluginv1.DiscoverComponentsRequest { for _, template := range s.importProviders { if template.Provider == provider { return template } } return nil } // checkDependencyStates keeps output reads on the dependency's own state. The // provider evaluates a dependency's remote_state under the dependent's // environment, so an identity or component override can select different state. // The reference is the identity the dependency was prepared with in this // invocation, or else its identity under the discovery environment. func (s *Session) checkDependencyStates(ctx context.Context, baseline *preparationEvidence, dependencies []*pluginv1.ComponentDependency, env map[string]string, command string) error { discovery := baseline.request for _, dependency := range dependencies { if dependency.Kind != pluginv1.ComponentDependency_OUTPUT { continue } key := addressKey(dependency.Target) target := baseline.units[key] if target == nil { // The provider did not evaluate the target, so it has no state evidence to compare. continue } current, err := s.dependencyState(ctx, discovery, target, env, command) if err != nil { return err } expected, err := s.referenceState(ctx, discovery, target, preparedKey(baseline, key), command) if err != nil { return err } if !proto.Equal(expected, current) { return fmt.Errorf("%w: dependency %s/%s state differs under the dependent's environment", errUtils.ErrPluginInvalidConfig, key[0], key[2]) } } return nil } // preparedKey is the address under which a dependency's prepared state is stored: the address // the dependency was selected with. An imported unit's dependencies are its siblings in the // importing stack, so they take that stack rather than the provider's own. func preparedKey(baseline *preparationEvidence, key [3]string) [3]string { if baseline.importStack != "" { key[0] = baseline.importStack } return key } func (s *Session) referenceState(ctx context.Context, discovery *pluginv1.DiscoverComponentsRequest, target *pluginv1.DiscoveredComponent, key [3]string, command string) (*pluginv1.ComponentStateIdentity, error) { if prepared, ok := s.prepared.Load(key); ok { return prepared.(*pluginv1.ComponentStateIdentity), nil } return s.dependencyState(ctx, discovery, target, discovery.GetInvocation().GetEnvironment(), command) } func (s *Session) dependencyState(ctx context.Context, discovery *pluginv1.DiscoverComponentsRequest, target *pluginv1.DiscoveredComponent, env map[string]string, command string) (*pluginv1.ComponentStateIdentity, error) { result, err := s.registry[target.Provider].ResolveState(ctx, &pluginv1.ComponentRequest{ Provider: target.Provider, Address: target.Address, Source: target.Source, RootDirectory: s.root, Configuration: target.Configuration, ProviderConfiguration: discovery.ProviderConfiguration, Invocation: &pluginv1.Invocation{Environment: env}, Operation: &pluginv1.ComponentOperation{Command: command, Mode: "native"}, }) if err != nil { return nil, err } if result == nil || result.State == nil { return nil, errUtils.ErrPluginProtocol } return result.State, nil } func sameDependencyUnit(before, after *pluginv1.DiscoveredComponent) bool { return before != nil && after != nil && before.Source == after.Source && before.Provider == after.Provider && before.Engine == after.Engine } func sameDependencies(before, after []*pluginv1.ComponentDependency) bool { type edge struct { target [3]string kind pluginv1.ComponentDependency_Kind } counts := make(map[edge]int) for _, dependency := range before { counts[edge{addressKey(dependency.Target), dependency.Kind}]++ } for _, dependency := range after { counts[edge{addressKey(dependency.Target), dependency.Kind}]-- } for _, count := range counts { if count != 0 { return false } } return true } func preparedConfiguration(result *pluginv1.PrepareComponentResponse) (*schema.PreparedComponentConfiguration, error) { inputs, sensitiveKeys, err := adapter.DecodeObjectWithSensitiveKeys(result.Inputs) if err != nil { return nil, err } backend, err := adapter.DecodeObject(result.State.Backend) if err != nil { return nil, err } if result.State.BackendType == "local" { resolveLocalBackend(backend, result.State.WorkingDirectory) } prepared := &schema.PreparedComponentConfiguration{Engine: result.Engine, Source: result.ModuleSource, Inputs: inputs, SensitiveInputKeys: sensitiveKeys, BackendType: result.State.BackendType, Backend: backend, Workspace: result.State.Workspace, BackendGenerated: result.BackendGenerated} execution, err := preparedExecution(result.Execution) if err != nil { return nil, err } prepared.Execution = execution for _, file := range result.Files { prepared.Files = append(prepared.Files, schema.ComponentConfigurationFile{Path: file.Path, Content: file.Content, IfExists: file.IfExists, Sensitive: file.Sensitive, Mode: file.Mode, UnitFileCopy: file.UnitFileCopy}) } for _, source := range result.Sources { prepared.Sources = append(prepared.Sources, schema.ComponentConfigurationSource{Path: source.Path, Directory: source.Kind == pluginv1.ComponentSource_DIRECTORY}) } return prepared, nil } func resolveLocalBackend(backend map[string]any, root string) { for key, fallback := range map[string]string{"path": "terraform.tfstate", "workspace_dir": "terraform.tfstate.d"} { path, _ := backend[key].(string) if path == "" { path = fallback } if !filepath.IsAbs(path) { path = filepath.Join(root, path) } backend[key] = path } } // The sanitized base is authoritative, including an explicitly empty slice. // Never reintroduce ambient credentials removed by the selected identity. func preparationEnvironment(info *schema.ConfigAndStacksInfo) map[string]string { base := info.SanitizedEnv if base == nil { base = os.Environ() } env := make(map[string]string) for _, entries := range [][]string{base, info.ComponentEnvList} { for _, entry := range entries { key, value, ok := strings.Cut(entry, "=") if ok { env[key] = value } } } return env } func (s *Session) providerSettings(name string) *pluginv1.ComponentValue { var settings *pluginv1.ComponentValue for _, request := range s.importProviders { if request.Provider == name { settings = request.ProviderConfiguration } } return settings }