github.com/nevins-b/terraform@v0.3.8-0.20170215184714-bbae22007d5a/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 10 "github.com/hashicorp/terraform/config/module" 11 "github.com/hashicorp/terraform/state" 12 "github.com/hashicorp/terraform/terraform" 13 ) 14 15 // Backend is the minimal interface that must be implemented to enable Terraform. 16 type Backend interface { 17 // Ask for input and configure the backend. Similar to 18 // terraform.ResourceProvider. 19 Input(terraform.UIInput, *terraform.ResourceConfig) (*terraform.ResourceConfig, error) 20 Validate(*terraform.ResourceConfig) ([]string, []error) 21 Configure(*terraform.ResourceConfig) error 22 23 // State returns the current state for this environment. This state may 24 // not be loaded locally: the proper APIs should be called on state.State 25 // to load the state. If the state.State is a state.Locker, it's up to the 26 // caller to call Lock and Unlock as needed. 27 State() (state.State, error) 28 } 29 30 // Enhanced implements additional behavior on top of a normal backend. 31 // 32 // Enhanced backends allow customizing the behavior of Terraform operations. 33 // This allows Terraform to potentially run operations remotely, load 34 // configurations from external sources, etc. 35 type Enhanced interface { 36 Backend 37 38 // Operation performs a Terraform operation such as refresh, plan, apply. 39 // It is up to the implementation to determine what "performing" means. 40 // This DOES NOT BLOCK. The context returned as part of RunningOperation 41 // should be used to block for completion. 42 // If the state used in the operation can be locked, it is the 43 // responsibility of the Backend to lock the state for the duration of the 44 // running operation. 45 Operation(context.Context, *Operation) (*RunningOperation, error) 46 } 47 48 // Local implements additional behavior on a Backend that allows local 49 // operations in addition to remote operations. 50 // 51 // This enables more behaviors of Terraform that require more data such 52 // as `console`, `import`, `graph`. These require direct access to 53 // configurations, variables, and more. Not all backends may support this 54 // so we separate it out into its own optional interface. 55 type Local interface { 56 // Context returns a runnable terraform Context. The operation parameter 57 // doesn't need a Type set but it needs other options set such as Module. 58 Context(*Operation) (*terraform.Context, state.State, error) 59 } 60 61 // An operation represents an operation for Terraform to execute. 62 // 63 // Note that not all fields are supported by all backends and can result 64 // in an error if set. All backend implementations should show user-friendly 65 // errors explaining any incorrectly set values. For example, the local 66 // backend doesn't support a PlanId being set. 67 // 68 // The operation options are purposely designed to have maximal compatibility 69 // between Terraform and Terraform Servers (a commercial product offered by 70 // HashiCorp). Therefore, it isn't expected that other implementation support 71 // every possible option. The struct here is generalized in order to allow 72 // even partial implementations to exist in the open, without walling off 73 // remote functionality 100% behind a commercial wall. Anyone can implement 74 // against this interface and have Terraform interact with it just as it 75 // would with HashiCorp-provided Terraform Servers. 76 type Operation struct { 77 // Type is the operation to perform. 78 Type OperationType 79 80 // PlanId is an opaque value that backends can use to execute a specific 81 // plan for an apply operation. 82 // 83 // PlanOutBackend is the backend to store with the plan. This is the 84 // backend that will be used when applying the plan. 85 PlanId string 86 PlanRefresh bool // PlanRefresh will do a refresh before a plan 87 PlanOutPath string // PlanOutPath is the path to save the plan 88 PlanOutBackend *terraform.BackendState 89 90 // Module settings specify the root module to use for operations. 91 Module *module.Tree 92 93 // Plan is a plan that was passed as an argument. This is valid for 94 // plan and apply arguments but may not work for all backends. 95 Plan *terraform.Plan 96 97 // The options below are more self-explanatory and affect the runtime 98 // behavior of the operation. 99 Destroy bool 100 Targets []string 101 Variables map[string]interface{} 102 103 // Input/output/control options. 104 UIIn terraform.UIInput 105 UIOut terraform.UIOutput 106 107 // If LockState is true, the Operation must Lock any 108 // state.Lockers for its duration, and Unlock when complete. 109 LockState bool 110 } 111 112 // RunningOperation is the result of starting an operation. 113 type RunningOperation struct { 114 // Context should be used to track Done and Err for errors. 115 // 116 // For implementers of a backend, this context should not wrap the 117 // passed in context. Otherwise, canceling the parent context will 118 // immediately mark this context as "done" but those aren't the semantics 119 // we want: we want this context to be done only when the operation itself 120 // is fully done. 121 context.Context 122 123 // Err is the error of the operation. This is populated after 124 // the operation has completed. 125 Err error 126 127 // PlanEmpty is populated after a Plan operation completes without error 128 // to note whether a plan is empty or has changes. 129 PlanEmpty bool 130 131 // State is the final state after the operation completed. Persisting 132 // this state is managed by the backend. This should only be read 133 // after the operation completes to avoid read/write races. 134 State *terraform.State 135 }