github.com/muratcelep/terraform@v1.1.0-beta2-not-internal-4/not-internal/backend/backend.go (about) 1 // Package backend provides interfaces that the CLI uses to interact with 2 // Terraform. A backend provides the abstraction that allows the same CLI 3 // to simultaneously support both local and remote operations for seamlessly 4 // using Terraform in a team environment. 5 package backend 6 7 import ( 8 "context" 9 "errors" 10 "io/ioutil" 11 "log" 12 "os" 13 14 "github.com/muratcelep/terraform/not-internal/addrs" 15 "github.com/muratcelep/terraform/not-internal/command/clistate" 16 "github.com/muratcelep/terraform/not-internal/command/views" 17 "github.com/muratcelep/terraform/not-internal/configs" 18 "github.com/muratcelep/terraform/not-internal/configs/configload" 19 "github.com/muratcelep/terraform/not-internal/configs/configschema" 20 "github.com/muratcelep/terraform/not-internal/depsfile" 21 "github.com/muratcelep/terraform/not-internal/plans" 22 "github.com/muratcelep/terraform/not-internal/plans/planfile" 23 "github.com/muratcelep/terraform/not-internal/states" 24 "github.com/muratcelep/terraform/not-internal/states/statemgr" 25 "github.com/muratcelep/terraform/not-internal/terraform" 26 "github.com/muratcelep/terraform/not-internal/tfdiags" 27 "github.com/mitchellh/go-homedir" 28 "github.com/zclconf/go-cty/cty" 29 ) 30 31 // DefaultStateName is the name of the default, initial state that every 32 // backend must have. This state cannot be deleted. 33 const DefaultStateName = "default" 34 35 var ( 36 // ErrDefaultWorkspaceNotSupported is returned when an operation does not 37 // support using the default workspace, but requires a named workspace to 38 // be selected. 39 ErrDefaultWorkspaceNotSupported = errors.New("default workspace not supported\n" + 40 "You can create a new workspace with the \"workspace new\" command.") 41 42 // ErrWorkspacesNotSupported is an error returned when a caller attempts 43 // to perform an operation on a workspace other than "default" for a 44 // backend that doesn't support multiple workspaces. 45 // 46 // The caller can detect this to do special fallback behavior or produce 47 // a specific, helpful error message. 48 ErrWorkspacesNotSupported = errors.New("workspaces not supported") 49 ) 50 51 // InitFn is used to initialize a new backend. 52 type InitFn func() Backend 53 54 // Backend is the minimal interface that must be implemented to enable Terraform. 55 type Backend interface { 56 // ConfigSchema returns a description of the expected configuration 57 // structure for the receiving backend. 58 // 59 // This method does not have any side-effects for the backend and can 60 // be safely used before configuring. 61 ConfigSchema() *configschema.Block 62 63 // PrepareConfig checks the validity of the values in the given 64 // configuration, and inserts any missing defaults, assuming that its 65 // structure has already been validated per the schema returned by 66 // ConfigSchema. 67 // 68 // This method does not have any side-effects for the backend and can 69 // be safely used before configuring. It also does not consult any 70 // external data such as environment variables, disk files, etc. Validation 71 // that requires such external data should be deferred until the 72 // Configure call. 73 // 74 // If error diagnostics are returned then the configuration is not valid 75 // and must not subsequently be passed to the Configure method. 76 // 77 // This method may return configuration-contextual diagnostics such 78 // as tfdiags.AttributeValue, and so the caller should provide the 79 // necessary context via the diags.InConfigBody method before returning 80 // diagnostics to the user. 81 PrepareConfig(cty.Value) (cty.Value, tfdiags.Diagnostics) 82 83 // Configure uses the provided configuration to set configuration fields 84 // within the backend. 85 // 86 // The given configuration is assumed to have already been validated 87 // against the schema returned by ConfigSchema and passed validation 88 // via PrepareConfig. 89 // 90 // This method may be called only once per backend instance, and must be 91 // called before all other methods except where otherwise stated. 92 // 93 // If error diagnostics are returned, the not-internal state of the instance 94 // is undefined and no other methods may be called. 95 Configure(cty.Value) tfdiags.Diagnostics 96 97 // StateMgr returns the state manager for the given workspace name. 98 // 99 // If the returned state manager also implements statemgr.Locker then 100 // it's the caller's responsibility to call Lock and Unlock as appropriate. 101 // 102 // If the named workspace doesn't exist, or if it has no state, it will 103 // be created either immediately on this call or the first time 104 // PersistState is called, depending on the state manager implementation. 105 StateMgr(workspace string) (statemgr.Full, error) 106 107 // DeleteWorkspace removes the workspace with the given name if it exists. 108 // 109 // DeleteWorkspace cannot prevent deleting a state that is in use. It is 110 // the responsibility of the caller to hold a Lock for the state manager 111 // belonging to this workspace before calling this method. 112 DeleteWorkspace(name string) error 113 114 // States returns a list of the names of all of the workspaces that exist 115 // in this backend. 116 Workspaces() ([]string, error) 117 } 118 119 // Enhanced implements additional behavior on top of a normal backend. 120 // 121 // Enhanced backends allow customizing the behavior of Terraform operations. 122 // This allows Terraform to potentially run operations remotely, load 123 // configurations from external sources, etc. 124 type Enhanced interface { 125 Backend 126 127 // Operation performs a Terraform operation such as refresh, plan, apply. 128 // It is up to the implementation to determine what "performing" means. 129 // This DOES NOT BLOCK. The context returned as part of RunningOperation 130 // should be used to block for completion. 131 // If the state used in the operation can be locked, it is the 132 // responsibility of the Backend to lock the state for the duration of the 133 // running operation. 134 Operation(context.Context, *Operation) (*RunningOperation, error) 135 } 136 137 // Local implements additional behavior on a Backend that allows local 138 // operations in addition to remote operations. 139 // 140 // This enables more behaviors of Terraform that require more data such 141 // as `console`, `import`, `graph`. These require direct access to 142 // configurations, variables, and more. Not all backends may support this 143 // so we separate it out into its own optional interface. 144 type Local interface { 145 // LocalRun uses information in the Operation to prepare a set of objects 146 // needed to start running that operation. 147 // 148 // The operation doesn't need a Type set, but it needs various other 149 // options set. This is a rather odd API that tries to treat all 150 // operations as the same when they really aren't; see the local and remote 151 // backend's implementations of this to understand what this actually 152 // does, because this operation has no well-defined contract aside from 153 // "whatever it already does". 154 LocalRun(*Operation) (*LocalRun, statemgr.Full, tfdiags.Diagnostics) 155 } 156 157 // LocalRun represents the assortment of objects that we can collect or 158 // calculate from an Operation object, which we can then use for local 159 // operations. 160 // 161 // The operation methods on terraform.Context (Plan, Apply, Import, etc) each 162 // generate new artifacts which supersede parts of the LocalRun object that 163 // started the operation, so callers should be careful to use those subsequent 164 // artifacts instead of the fields of LocalRun where appropriate. The LocalRun 165 // data intentionally doesn't update as a result of calling methods on Context, 166 // in order to make data flow explicit. 167 // 168 // This type is a weird architectural wart resulting from the overly-general 169 // way our backend API models operations, whereby we behave as if all 170 // Terraform operations have the same inputs and outputs even though they 171 // are actually all rather different. The exact meaning of the fields in 172 // this type therefore vary depending on which OperationType was passed to 173 // Local.Context in order to create an object of this type. 174 type LocalRun struct { 175 // Core is an already-initialized Terraform Core context, ready to be 176 // used to run operations such as Plan and Apply. 177 Core *terraform.Context 178 179 // Config is the configuration we're working with, which typically comes 180 // from either config files directly on local disk (when we're creating 181 // a plan, or similar) or from a snapshot embedded in a plan file 182 // (when we're applying a saved plan). 183 Config *configs.Config 184 185 // InputState is the state that should be used for whatever is the first 186 // method call to a context created with CoreOpts. When creating a plan 187 // this will be the previous run state, but when applying a saved plan 188 // this will be the prior state recorded in that plan. 189 InputState *states.State 190 191 // PlanOpts are options to pass to a Plan or Plan-like operation. 192 // 193 // This is nil when we're applying a saved plan, because the plan itself 194 // contains enough information about its options to apply it. 195 PlanOpts *terraform.PlanOpts 196 197 // Plan is a plan loaded from a saved plan file, if our operation is to 198 // apply that saved plan. 199 // 200 // This is nil when we're not applying a saved plan. 201 Plan *plans.Plan 202 } 203 204 // An operation represents an operation for Terraform to execute. 205 // 206 // Note that not all fields are supported by all backends and can result 207 // in an error if set. All backend implementations should show user-friendly 208 // errors explaining any incorrectly set values. For example, the local 209 // backend doesn't support a PlanId being set. 210 // 211 // The operation options are purposely designed to have maximal compatibility 212 // between Terraform and Terraform Servers (a commercial product offered by 213 // HashiCorp). Therefore, it isn't expected that other implementation support 214 // every possible option. The struct here is generalized in order to allow 215 // even partial implementations to exist in the open, without walling off 216 // remote functionality 100% behind a commercial wall. Anyone can implement 217 // against this interface and have Terraform interact with it just as it 218 // would with HashiCorp-provided Terraform Servers. 219 type Operation struct { 220 // Type is the operation to perform. 221 Type OperationType 222 223 // PlanId is an opaque value that backends can use to execute a specific 224 // plan for an apply operation. 225 // 226 // PlanOutBackend is the backend to store with the plan. This is the 227 // backend that will be used when applying the plan. 228 PlanId string 229 PlanRefresh bool // PlanRefresh will do a refresh before a plan 230 PlanOutPath string // PlanOutPath is the path to save the plan 231 PlanOutBackend *plans.Backend 232 233 // ConfigDir is the path to the directory containing the configuration's 234 // root module. 235 ConfigDir string 236 237 // ConfigLoader is a configuration loader that can be used to load 238 // configuration from ConfigDir. 239 ConfigLoader *configload.Loader 240 241 // DependencyLocks represents the locked dependencies associated with 242 // the configuration directory given in ConfigDir. 243 // 244 // Note that if field PlanFile is set then the plan file should contain 245 // its own dependency locks. The backend is responsible for correctly 246 // selecting between these two sets of locks depending on whether it 247 // will be using ConfigDir or PlanFile to get the configuration for 248 // this operation. 249 DependencyLocks *depsfile.Locks 250 251 // Hooks can be used to perform actions triggered by various events during 252 // the operation's lifecycle. 253 Hooks []terraform.Hook 254 255 // Plan is a plan that was passed as an argument. This is valid for 256 // plan and apply arguments but may not work for all backends. 257 PlanFile *planfile.Reader 258 259 // The options below are more self-explanatory and affect the runtime 260 // behavior of the operation. 261 PlanMode plans.Mode 262 AutoApprove bool 263 Targets []addrs.Targetable 264 ForceReplace []addrs.AbsResourceInstance 265 Variables map[string]UnparsedVariableValue 266 267 // Some operations use root module variables only opportunistically or 268 // don't need them at all. If this flag is set, the backend must treat 269 // all variables as optional and provide an unknown value for any required 270 // variables that aren't set in order to allow partial evaluation against 271 // the resulting incomplete context. 272 // 273 // This flag is honored only if PlanFile isn't set. If PlanFile is set then 274 // the variables set in the plan are used instead, and they must be valid. 275 AllowUnsetVariables bool 276 277 // View implements the logic for all UI interactions. 278 View views.Operation 279 280 // Input/output/control options. 281 UIIn terraform.UIInput 282 UIOut terraform.UIOutput 283 284 // StateLocker is used to lock the state while providing UI feedback to the 285 // user. This will be replaced by the Backend to update the context. 286 // 287 // If state locking is not necessary, this should be set to a no-op 288 // implementation of clistate.Locker. 289 StateLocker clistate.Locker 290 291 // Workspace is the name of the workspace that this operation should run 292 // in, which controls which named state is used. 293 Workspace string 294 } 295 296 // HasConfig returns true if and only if the operation has a ConfigDir value 297 // that refers to a directory containing at least one Terraform configuration 298 // file. 299 func (o *Operation) HasConfig() bool { 300 return o.ConfigLoader.IsConfigDir(o.ConfigDir) 301 } 302 303 // Config loads the configuration that the operation applies to, using the 304 // ConfigDir and ConfigLoader fields within the receiving operation. 305 func (o *Operation) Config() (*configs.Config, tfdiags.Diagnostics) { 306 var diags tfdiags.Diagnostics 307 config, hclDiags := o.ConfigLoader.LoadConfig(o.ConfigDir) 308 diags = diags.Append(hclDiags) 309 return config, diags 310 } 311 312 // ReportResult is a helper for the common chore of setting the status of 313 // a running operation and showing any diagnostics produced during that 314 // operation. 315 // 316 // If the given diagnostics contains errors then the operation's result 317 // will be set to backend.OperationFailure. It will be set to 318 // backend.OperationSuccess otherwise. It will then use o.View.Diagnostics 319 // to show the given diagnostics before returning. 320 // 321 // Callers should feel free to do each of these operations separately in 322 // more complex cases where e.g. diagnostics are interleaved with other 323 // output, but terminating immediately after reporting error diagnostics is 324 // common and can be expressed concisely via this method. 325 func (o *Operation) ReportResult(op *RunningOperation, diags tfdiags.Diagnostics) { 326 if diags.HasErrors() { 327 op.Result = OperationFailure 328 } else { 329 op.Result = OperationSuccess 330 } 331 if o.View != nil { 332 o.View.Diagnostics(diags) 333 } else { 334 // Shouldn't generally happen, but if it does then we'll at least 335 // make some noise in the logs to help us spot it. 336 if len(diags) != 0 { 337 log.Printf( 338 "[ERROR] Backend needs to report diagnostics but View is not set:\n%s", 339 diags.ErrWithWarnings(), 340 ) 341 } 342 } 343 } 344 345 // RunningOperation is the result of starting an operation. 346 type RunningOperation struct { 347 // For implementers of a backend, this context should not wrap the 348 // passed in context. Otherwise, cancelling the parent context will 349 // immediately mark this context as "done" but those aren't the semantics 350 // we want: we want this context to be done only when the operation itself 351 // is fully done. 352 context.Context 353 354 // Stop requests the operation to complete early, by calling Stop on all 355 // the plugins. If the process needs to terminate immediately, call Cancel. 356 Stop context.CancelFunc 357 358 // Cancel is the context.CancelFunc associated with the embedded context, 359 // and can be called to terminate the operation early. 360 // Once Cancel is called, the operation should return as soon as possible 361 // to avoid running operations during process exit. 362 Cancel context.CancelFunc 363 364 // Result is the exit status of the operation, populated only after the 365 // operation has completed. 366 Result OperationResult 367 368 // PlanEmpty is populated after a Plan operation completes without error 369 // to note whether a plan is empty or has changes. 370 PlanEmpty bool 371 372 // State is the final state after the operation completed. Persisting 373 // this state is managed by the backend. This should only be read 374 // after the operation completes to avoid read/write races. 375 State *states.State 376 } 377 378 // OperationResult describes the result status of an operation. 379 type OperationResult int 380 381 const ( 382 // OperationSuccess indicates that the operation completed as expected. 383 OperationSuccess OperationResult = 0 384 385 // OperationFailure indicates that the operation encountered some sort 386 // of error, and thus may have been only partially performed or not 387 // performed at all. 388 OperationFailure OperationResult = 1 389 ) 390 391 func (r OperationResult) ExitStatus() int { 392 return int(r) 393 } 394 395 // If the argument is a path, Read loads it and returns the contents, 396 // otherwise the argument is assumed to be the desired contents and is simply 397 // returned. 398 func ReadPathOrContents(poc string) (string, error) { 399 if len(poc) == 0 { 400 return poc, nil 401 } 402 403 path := poc 404 if path[0] == '~' { 405 var err error 406 path, err = homedir.Expand(path) 407 if err != nil { 408 return path, err 409 } 410 } 411 412 if _, err := os.Stat(path); err == nil { 413 contents, err := ioutil.ReadFile(path) 414 if err != nil { 415 return string(contents), err 416 } 417 return string(contents), nil 418 } 419 420 return poc, nil 421 }