terraform

package
v0.3.6 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jan 6, 2015 License: MPL-2.0 Imports: 20 Imported by: 0

Documentation

Index

Constants

View Source 
const GraphRootNode = "root"

GraphRootNode is the name of the root node in the Terraform resource graph. This node is just a placemarker and has no associated functionality.

View Source 
const (
	// StateVersion is the current version for our state file
	StateVersion = 1
)

Variables

This section is empty.

Functions

func Graph 

func Graph(opts *GraphOpts) (*depgraph.Graph, error)

Graph builds a dependency graph of all the resources for infrastructure change.

This dependency graph shows the correct order that any resources need to be operated on.

The Meta field of a graph Noun can contain one of the follow types. A description is next to each type to explain what it is. 

*GraphNodeResource - A resource. See the documentation of this
  struct for more details.
*GraphNodeResourceProvider - A resource provider that needs to be
  configured at this point.

func GraphDot 

func GraphDot(g *depgraph.Graph, opts *GraphDotOpts) string

GraphDot returns the dot formatting of a visual representation of the given Terraform graph.

func ProviderSatisfies 

func ProviderSatisfies(p ResourceProvider, n string) bool

func WritePlan 

func WritePlan(d *Plan, dst io.Writer) error

WritePlan writes a plan somewhere in a binary format.

func WriteState 

func WriteState(d *State, dst io.Writer) error

WriteState writes a state somewhere in a binary format.

Types

type CallbackUIOutput added in v0.3.0 

type CallbackUIOutput struct {
	OutputFun func(string)
}

type Context 

type Context struct {
	// contains filtered or unexported fields
}

Context represents all the context that Terraform needs in order to perform operations on infrastructure. This structure is built using ContextOpts and NewContext. See the documentation for those.

Additionally, a context can be created from a Plan using Plan.Context.

func NewContext 

func NewContext(opts *ContextOpts) *Context

NewContext creates a new context.

Once a context is created, the pointer values within ContextOpts should not be mutated in any way, since the pointers are copied, not the values themselves.

func (*Context) Apply 

func (c *Context) Apply() (*State, error)

Apply applies the changes represented by this context and returns the resulting state.

In addition to returning the resulting state, this context is updated with the latest state.

func (*Context) Graph 

func (c *Context) Graph() (*depgraph.Graph, error)

Graph returns the graph for this context.

func (*Context) Input added in v0.3.0 

func (c *Context) Input(mode InputMode) error

Input asks for input to fill variables and provider configurations. This modifies the configuration in-place, so asking for Input twice may result in different UI output showing different current values.

func (*Context) Plan 

func (c *Context) Plan(opts *PlanOpts) (*Plan, error)

Plan generates an execution plan for the given context.

The execution plan encapsulates the context and can be stored in order to reinstantiate a context later for Apply.

Plan also updates the diff of this context to be the diff generated by the plan, so Apply can be called after.

func (*Context) Refresh 

func (c *Context) Refresh() (*State, error)

Refresh goes through all the resources in the state and refreshes them to their latest state. This will update the state that this context works with, along with returning it.

Even in the case an error is returned, the state will be returned and will potentially be partially updated.

func (*Context) Stop 

func (c *Context) Stop()

Stop stops the running task.

Stop will block until the task completes.

func (*Context) Validate 

func (c *Context) Validate() ([]string, []error)

Validate validates the configuration and returns any warnings or errors.

type ContextOpts 

type ContextOpts struct {
	Diff         *Diff
	Hooks        []Hook
	Module       *module.Tree
	Parallelism  int
	State        *State
	Providers    map[string]ResourceProviderFactory
	Provisioners map[string]ResourceProvisionerFactory
	Variables    map[string]string

	UIInput UIInput
}

ContextOpts are the user-creatable configuration structure to create a context with NewContext.

type Diff 

type Diff struct {
	// Modules contains all the modules that have a diff
	Modules []*ModuleDiff
}

Diff trackes the changes that are necessary to apply a configuration to an existing infrastructure.

func (*Diff) AddModule added in v0.3.0 

func (d *Diff) AddModule(path []string) *ModuleDiff

AddModule adds the module with the given path to the diff.

This should be the preferred method to add module diffs since it allows us to optimize lookups later as well as control sorting.

func (*Diff) Empty 

func (d *Diff) Empty() bool

Empty returns true if the diff has no changes.

func (*Diff) ModuleByPath added in v0.3.0 

func (d *Diff) ModuleByPath(path []string) *ModuleDiff

ModuleByPath is used to lookup the module diff for the given path. This should be the prefered lookup mechanism as it allows for future lookup optimizations.

func (*Diff) RootModule added in v0.3.0 

func (d *Diff) RootModule() *ModuleDiff

RootModule returns the ModuleState for the root module

func (*Diff) String 

func (d *Diff) String() string

type DiffAttrType 

type DiffAttrType byte

DiffAttrType is an enum type that says whether a resource attribute diff is an input attribute (comes from the configuration) or an output attribute (comes as a result of applying the configuration). An example input would be "ami" for AWS and an example output would be "private_ip". 

const (
	DiffAttrUnknown DiffAttrType = iota
	DiffAttrInput
	DiffAttrOutput
)

type DiffChangeType added in v0.3.0 

type DiffChangeType byte

DiffChangeType is an enum with the kind of changes a diff has planned. 

const (
	DiffInvalid DiffChangeType = iota
	DiffNone
	DiffCreate
	DiffUpdate
	DiffDestroy
	DiffDestroyCreate
)

type EphemeralState added in v0.3.0 

type EphemeralState struct {
	// ConnInfo is used for the providers to export information which is
	// used to connect to the resource for provisioning. For example,
	// this could contain SSH or WinRM credentials.
	ConnInfo map[string]string `json:"-"`
}

EphemeralState is used for transient state that is only kept in-memory

type GraphDotOpts added in v0.3.0 

type GraphDotOpts struct {
	// ModuleDepth is the depth of modules to expand. Zero is no expansion,
	// one expands the first set of modules, etc. If this is set to -1, then
	// all modules are expanded.
	ModuleDepth int
	// contains filtered or unexported fields
}

GraphDotOpts are options for turning a graph into dot format.

type GraphMeta added in v0.3.0 

type GraphMeta struct {
	// ModulePath is the path of the module that this graph represents.
	ModulePath []string
}

GraphMeta is the metadata attached to the graph itself.

type GraphNodeModule added in v0.3.0 

type GraphNodeModule struct {
	Config *config.Module
	Path   []string
	Graph  *depgraph.Graph
	State  *ModuleState
	Flags  ResourceFlag
}

GraphNodeModule is a node type in the graph that represents a module that will be created/managed.

type GraphNodeResource 

type GraphNodeResource struct {
	Index                int
	Config               *config.Resource
	Resource             *Resource
	ResourceProviderNode string

	// All the fields below are related to expansion. These are set by
	// the graph but aren't useful individually.
	ExpandMode ResourceExpandMode
	Diff       *ModuleDiff
	State      *ModuleState
}

GraphNodeResource is a node type in the graph that represents a resource that will be created or managed. Unlike the GraphNodeResourceMeta node, this represents a _single_, _resource_ to be managed, not a set of resources or a component of a resource.

func (*GraphNodeResource) Expand added in v0.3.0 

func (n *GraphNodeResource) Expand() (*depgraph.Graph, error)

Expand will expand this node into a subgraph if Expand is set.

type GraphNodeResourceProvider 

type GraphNodeResourceProvider struct {
	ID       string
	Provider *graphSharedProvider
}

GraphNodeResourceProvider is a node type in the graph that represents the configuration for a resource provider.

type GraphOpts 

type GraphOpts struct {

	// Module is the relative root of a module tree for this graph. This
	// is the only required item. This should always be the absolute root
	// of the tree. ModulePath below should be used to constrain the depth.
	//
	// ModulePath specifies the place in the tree where Module exists.
	// This is used for State lookups.
	Module     *module.Tree
	ModulePath []string

	// Diff of changes that will be applied to the given state. This will
	// associate a ResourceDiff with applicable resources. Additionally,
	// new resource nodes representing resource destruction may be inserted
	// into the graph.
	Diff *Diff

	// State, if present, will make the ResourceState available on each
	// resource node. Additionally, any orphans will be added automatically
	// to the graph.
	//
	// Note: the state will be modified so it is initialized with basic
	// empty states for all modules/resources in this graph. If you call prune
	// later, these will be removed, but the graph adds important metadata.
	State *State

	// Providers is a mapping of prefixes to a resource provider. If given,
	// resource providers will be found, initialized, and associated to the
	// resources in the graph.
	//
	// This will also potentially insert new nodes into the graph for
	// the configuration of resource providers.
	Providers map[string]ResourceProviderFactory

	// Provisioners is a mapping of names to a resource provisioner.
	// These must be provided to support resource provisioners.
	Provisioners map[string]ResourceProvisionerFactory
	// contains filtered or unexported fields
}

GraphOpts are options used to create the resource graph that Terraform walks to make changes to infrastructure.

Depending on what options are set, the resulting graph will come in varying degrees of completeness.

type Hook 

type Hook interface {
	// PreApply and PostApply are called before and after a single
	// resource is applied. The error argument in PostApply is the
	// error, if any, that was returned from the provider Apply call itself.
	PreApply(*InstanceInfo, *InstanceState, *InstanceDiff) (HookAction, error)
	PostApply(*InstanceInfo, *InstanceState, error) (HookAction, error)

	// PreDiff and PostDiff are called before and after a single resource
	// resource is diffed.
	PreDiff(*InstanceInfo, *InstanceState) (HookAction, error)
	PostDiff(*InstanceInfo, *InstanceDiff) (HookAction, error)

	// Provisioning hooks
	//
	// All should be self-explanatory. ProvisionOutput is called with
	// output sent back by the provisioners. This will be called multiple
	// times as output comes in, but each call should represent a line of
	// output. The ProvisionOutput method cannot control whether the
	// hook continues running.
	PreProvisionResource(*InstanceInfo, *InstanceState) (HookAction, error)
	PostProvisionResource(*InstanceInfo, *InstanceState) (HookAction, error)
	PreProvision(*InstanceInfo, string) (HookAction, error)
	PostProvision(*InstanceInfo, string) (HookAction, error)
	ProvisionOutput(*InstanceInfo, string, string)

	// PreRefresh and PostRefresh are called before and after a single
	// resource state is refreshed, respectively.
	PreRefresh(*InstanceInfo, *InstanceState) (HookAction, error)
	PostRefresh(*InstanceInfo, *InstanceState) (HookAction, error)
}

Hook is the interface that must be implemented to hook into various parts of Terraform, allowing you to inspect or change behavior at runtime.

There are MANY hook points into Terraform. If you only want to implement some hook points, but not all (which is the likely case), then embed the NilHook into your struct, which implements all of the interface but does nothing. Then, override only the functions you want to implement.

type HookAction 

type HookAction byte

HookAction is an enum of actions that can be taken as a result of a hook callback. This allows you to modify the behavior of Terraform at runtime. 

const (
	// HookActionContinue continues with processing as usual.
	HookActionContinue HookAction = iota

	// HookActionHalt halts immediately: no more hooks are processed
	// and the action that Terraform was about to take is cancelled.
	HookActionHalt
)

type InputMode added in v0.3.0 

type InputMode byte

InputMode defines what sort of input will be asked for when Input is called on Context. 

const (
	// InputModeVar asks for variables
	InputModeVar InputMode = 1 << iota

	// InputModeProvider asks for provider variables
	InputModeProvider

	// InputModeStd is the standard operating mode and asks for both variables
	// and providers.
	InputModeStd = InputModeVar | InputModeProvider
)

type InputOpts added in v0.3.0 

type InputOpts struct {
	// Id is a unique ID for the question being asked that might be
	// used for logging or to look up a prior answered question.
	Id string

	// Query is a human-friendly question for inputting this value.
	Query string

	// Description is a description about what this option is. Be wary
	// that this will probably be in a terminal so split lines as you see
	// necessary.
	Description string

	// Default will be the value returned if no data is entered.
	Default string
}

InputOpts are options for asking for input.

type InstanceDiff added in v0.3.0 

type InstanceDiff struct {
	Attributes     map[string]*ResourceAttrDiff
	Destroy        bool
	DestroyTainted bool
}

InstanceDiff is the diff of a resource from some state to another.

func (*InstanceDiff) ChangeType added in v0.3.0 

func (d *InstanceDiff) ChangeType() DiffChangeType

ChangeType returns the DiffChangeType represented by the diff for this single instance.

func (*InstanceDiff) Empty added in v0.3.0 

func (d *InstanceDiff) Empty() bool

Empty returns true if this diff encapsulates no changes.

func (*InstanceDiff) RequiresNew added in v0.3.0 

func (d *InstanceDiff) RequiresNew() bool

RequiresNew returns true if the diff requires the creation of a new resource (implying the destruction of the old).

func (*InstanceDiff) Same added in v0.3.0 

func (d *InstanceDiff) Same(d2 *InstanceDiff) bool

Same checks whether or not two InstanceDiff's are the "same". When we say "same", it is not necessarily exactly equal. Instead, it is just checking that the same attributes are changing, a destroy isn't suddenly happening, etc.

type InstanceInfo added in v0.3.0 

type InstanceInfo struct {
	// Id is a unique name to represent this instance. This is not related
	// to InstanceState.ID in any way.
	Id string

	// ModulePath is the complete path of the module containing this
	// instance.
	ModulePath []string

	// Type is the resource type of this instance
	Type string
}

InstanceInfo is used to hold information about the instance and/or resource being modified.

func (*InstanceInfo) HumanId added in v0.3.0 

func (i *InstanceInfo) HumanId() string

HumanId is a unique Id that is human-friendly and useful for UI elements.

type InstanceState added in v0.3.0 

type InstanceState struct {
	// A unique ID for this resource. This is opaque to Terraform
	// and is only meant as a lookup mechanism for the providers.
	ID string `json:"id"`

	// Attributes are basic information about the resource. Any keys here
	// are accessible in variable format within Terraform configurations:
	// ${resourcetype.name.attribute}.
	Attributes map[string]string `json:"attributes,omitempty"`

	// Ephemeral is used to store any state associated with this instance
	// that is necessary for the Terraform run to complete, but is not
	// persisted to a state file.
	Ephemeral EphemeralState `json:"-"`
}

InstanceState is used to track the unique state information belonging to a given instance.

func (*InstanceState) GoString added in v0.3.0 

func (i *InstanceState) GoString() string

func (*InstanceState) MergeDiff added in v0.3.0 

func (s *InstanceState) MergeDiff(d *InstanceDiff) *InstanceState

MergeDiff takes a ResourceDiff and merges the attributes into this resource state in order to generate a new state. This new state can be used to provide updated attribute lookups for variable interpolation.

If the diff attribute requires computing the value, and hence won't be available until apply, the value is replaced with the computeID.

func (*InstanceState) String added in v0.3.0 

func (i *InstanceState) String() string

type MockHook 

type MockHook struct {
	PreApplyCalled bool
	PreApplyInfo   *InstanceInfo
	PreApplyDiff   *InstanceDiff
	PreApplyState  *InstanceState
	PreApplyReturn HookAction
	PreApplyError  error

	PostApplyCalled      bool
	PostApplyInfo        *InstanceInfo
	PostApplyState       *InstanceState
	PostApplyError       error
	PostApplyReturn      HookAction
	PostApplyReturnError error

	PreDiffCalled bool
	PreDiffInfo   *InstanceInfo
	PreDiffState  *InstanceState
	PreDiffReturn HookAction
	PreDiffError  error

	PostDiffCalled bool
	PostDiffInfo   *InstanceInfo
	PostDiffDiff   *InstanceDiff
	PostDiffReturn HookAction
	PostDiffError  error

	PreProvisionResourceCalled bool
	PreProvisionResourceInfo   *InstanceInfo
	PreProvisionInstanceState  *InstanceState
	PreProvisionResourceReturn HookAction
	PreProvisionResourceError  error

	PostProvisionResourceCalled bool
	PostProvisionResourceInfo   *InstanceInfo
	PostProvisionInstanceState  *InstanceState
	PostProvisionResourceReturn HookAction
	PostProvisionResourceError  error

	PreProvisionCalled        bool
	PreProvisionInfo          *InstanceInfo
	PreProvisionProvisionerId string
	PreProvisionReturn        HookAction
	PreProvisionError         error

	PostProvisionCalled        bool
	PostProvisionInfo          *InstanceInfo
	PostProvisionProvisionerId string
	PostProvisionReturn        HookAction
	PostProvisionError         error

	ProvisionOutputCalled        bool
	ProvisionOutputInfo          *InstanceInfo
	ProvisionOutputProvisionerId string
	ProvisionOutputMessage       string

	PostRefreshCalled bool
	PostRefreshInfo   *InstanceInfo
	PostRefreshState  *InstanceState
	PostRefreshReturn HookAction
	PostRefreshError  error

	PreRefreshCalled bool
	PreRefreshInfo   *InstanceInfo
	PreRefreshState  *InstanceState
	PreRefreshReturn HookAction
	PreRefreshError  error
}

MockHook is an implementation of Hook that can be used for tests. It records all of its function calls.

func (*MockHook) PostApply 

func (h *MockHook) PostApply(n *InstanceInfo, s *InstanceState, e error) (HookAction, error)

func (*MockHook) PostDiff 

func (h *MockHook) PostDiff(n *InstanceInfo, d *InstanceDiff) (HookAction, error)

func (*MockHook) PostProvision 

func (h *MockHook) PostProvision(n *InstanceInfo, provId string) (HookAction, error)

func (*MockHook) PostProvisionResource 

func (h *MockHook) PostProvisionResource(n *InstanceInfo, s *InstanceState) (HookAction, error)

func (*MockHook) PostRefresh 

func (h *MockHook) PostRefresh(n *InstanceInfo, s *InstanceState) (HookAction, error)

func (*MockHook) PreApply 

func (h *MockHook) PreApply(n *InstanceInfo, s *InstanceState, d *InstanceDiff) (HookAction, error)

func (*MockHook) PreDiff 

func (h *MockHook) PreDiff(n *InstanceInfo, s *InstanceState) (HookAction, error)

func (*MockHook) PreProvision 

func (h *MockHook) PreProvision(n *InstanceInfo, provId string) (HookAction, error)

func (*MockHook) PreProvisionResource 

func (h *MockHook) PreProvisionResource(n *InstanceInfo, s *InstanceState) (HookAction, error)

func (*MockHook) PreRefresh 

func (h *MockHook) PreRefresh(n *InstanceInfo, s *InstanceState) (HookAction, error)

func (*MockHook) ProvisionOutput added in v0.3.0 

func (h *MockHook) ProvisionOutput(
	n *InstanceInfo,
	provId string,
	msg string)

type MockResourceProvider 

type MockResourceProvider struct {
	sync.Mutex

	// Anything you want, in case you need to store extra data with the mock.
	Meta interface{}

	InputCalled                  bool
	InputInput                   UIInput
	InputConfig                  *ResourceConfig
	InputReturnConfig            *ResourceConfig
	InputReturnError             error
	InputFn                      func(UIInput, *ResourceConfig) (*ResourceConfig, error)
	ApplyCalled                  bool
	ApplyInfo                    *InstanceInfo
	ApplyState                   *InstanceState
	ApplyDiff                    *InstanceDiff
	ApplyFn                      func(*InstanceInfo, *InstanceState, *InstanceDiff) (*InstanceState, error)
	ApplyReturn                  *InstanceState
	ApplyReturnError             error
	ConfigureCalled              bool
	ConfigureConfig              *ResourceConfig
	ConfigureFn                  func(*ResourceConfig) error
	ConfigureReturnError         error
	DiffCalled                   bool
	DiffInfo                     *InstanceInfo
	DiffState                    *InstanceState
	DiffDesired                  *ResourceConfig
	DiffFn                       func(*InstanceInfo, *InstanceState, *ResourceConfig) (*InstanceDiff, error)
	DiffReturn                   *InstanceDiff
	DiffReturnError              error
	RefreshCalled                bool
	RefreshInfo                  *InstanceInfo
	RefreshState                 *InstanceState
	RefreshFn                    func(*InstanceInfo, *InstanceState) (*InstanceState, error)
	RefreshReturn                *InstanceState
	RefreshReturnError           error
	ResourcesCalled              bool
	ResourcesReturn              []ResourceType
	ValidateCalled               bool
	ValidateConfig               *ResourceConfig
	ValidateFn                   func(*ResourceConfig) ([]string, []error)
	ValidateReturnWarns          []string
	ValidateReturnErrors         []error
	ValidateResourceFn           func(string, *ResourceConfig) ([]string, []error)
	ValidateResourceCalled       bool
	ValidateResourceType         string
	ValidateResourceConfig       *ResourceConfig
	ValidateResourceReturnWarns  []string
	ValidateResourceReturnErrors []error
}

MockResourceProvider implements ResourceProvider but mocks out all the calls for testing purposes.

func (*MockResourceProvider) Apply 

func (p *MockResourceProvider) Apply(
	info *InstanceInfo,
	state *InstanceState,
	diff *InstanceDiff) (*InstanceState, error)

func (*MockResourceProvider) Configure 

func (p *MockResourceProvider) Configure(c *ResourceConfig) error

func (*MockResourceProvider) Diff 

func (p *MockResourceProvider) Diff(
	info *InstanceInfo,
	state *InstanceState,
	desired *ResourceConfig) (*InstanceDiff, error)

func (*MockResourceProvider) Input added in v0.3.0 

func (p *MockResourceProvider) Input(
	input UIInput, c *ResourceConfig) (*ResourceConfig, error)

func (*MockResourceProvider) Refresh 

func (p *MockResourceProvider) Refresh(
	info *InstanceInfo,
	s *InstanceState) (*InstanceState, error)

func (*MockResourceProvider) Resources 

func (p *MockResourceProvider) Resources() []ResourceType

func (*MockResourceProvider) Validate 

func (p *MockResourceProvider) Validate(c *ResourceConfig) ([]string, []error)

func (*MockResourceProvider) ValidateResource 

func (p *MockResourceProvider) ValidateResource(t string, c *ResourceConfig) ([]string, []error)

type MockResourceProvisioner 

type MockResourceProvisioner struct {
	// Anything you want, in case you need to store extra data with the mock.
	Meta interface{}

	ApplyCalled      bool
	ApplyOutput      UIOutput
	ApplyState       *InstanceState
	ApplyConfig      *ResourceConfig
	ApplyFn          func(*InstanceState, *ResourceConfig) error
	ApplyReturnError error

	ValidateCalled       bool
	ValidateConfig       *ResourceConfig
	ValidateFn           func(c *ResourceConfig) ([]string, []error)
	ValidateReturnWarns  []string
	ValidateReturnErrors []error
}

MockResourceProvisioner implements ResourceProvisioner but mocks out all the calls for testing purposes.

func (*MockResourceProvisioner) Apply 

func (p *MockResourceProvisioner) Apply(
	output UIOutput,
	state *InstanceState,
	c *ResourceConfig) error

func (*MockResourceProvisioner) Validate 

func (p *MockResourceProvisioner) Validate(c *ResourceConfig) ([]string, []error)

type MockUIInput added in v0.3.0 

type MockUIInput struct {
	InputCalled       bool
	InputOpts         *InputOpts
	InputReturnMap    map[string]string
	InputReturnString string
	InputReturnError  error
	InputFn           func(*InputOpts) (string, error)
}

MockUIInput is an implementation of UIInput that can be used for tests.

func (*MockUIInput) Input added in v0.3.0 

func (i *MockUIInput) Input(opts *InputOpts) (string, error)

type MockUIOutput added in v0.3.0 

type MockUIOutput struct {
	OutputCalled  bool
	OutputMessage string
	OutputFn      func(string)
}

MockUIOutput is an implementation of UIOutput that can be used for tests.

func (*MockUIOutput) Output added in v0.3.0 

func (o *MockUIOutput) Output(v string)

type ModuleDiff added in v0.3.0 

type ModuleDiff struct {
	Path      []string
	Resources map[string]*InstanceDiff
	Destroy   bool // Set only by the destroy plan
}

ModuleDiff tracks the differences between resources to apply within a single module.

func (*ModuleDiff) ChangeType added in v0.3.0 

func (d *ModuleDiff) ChangeType() DiffChangeType

ChangeType returns the type of changes that the diff for this module includes.

At a module level, this will only be DiffNone, DiffUpdate, DiffDestroy, or DiffCreate. If an instance within the module has a DiffDestroyCreate then this will register as a DiffCreate for a module.

func (*ModuleDiff) Empty added in v0.3.0 

func (d *ModuleDiff) Empty() bool

Empty returns true if the diff has no changes within this module.

func (*ModuleDiff) Instances added in v0.3.0 

func (d *ModuleDiff) Instances(id string) []*InstanceDiff

Instances returns the instance diffs for the id given. This can return multiple instance diffs if there are counts within the resource.

func (*ModuleDiff) IsRoot added in v0.3.0 

func (d *ModuleDiff) IsRoot() bool

IsRoot says whether or not this module diff is for the root module.

func (*ModuleDiff) String added in v0.3.0 

func (d *ModuleDiff) String() string

String outputs the diff in a long but command-line friendly output format that users can read to quickly inspect a diff.

type ModuleState added in v0.3.0 

type ModuleState struct {
	// Path is the import path from the root module. Modules imports are
	// always disjoint, so the path represents amodule tree
	Path []string `json:"path"`

	// Outputs declared by the module and maintained for each module
	// even though only the root module technically needs to be kept.
	// This allows operators to inspect values at the boundaries.
	Outputs map[string]string `json:"outputs"`

	// Resources is a mapping of the logically named resource to
	// the state of the resource. Each resource may actually have
	// N instances underneath, although a user only needs to think
	// about the 1:1 case.
	Resources map[string]*ResourceState `json:"resources"`

	// Dependencies are a list of things that this module relies on
	// existing to remain intact. For example: an module may depend
	// on a VPC ID given by an aws_vpc resource.
	//
	// Terraform uses this information to build valid destruction
	// orders and to warn the user if they're destroying a module that
	// another resource depends on.
	//
	// Things can be put into this list that may not be managed by
	// Terraform. If Terraform doesn't find a matching ID in the
	// overall state, then it assumes it isn't managed and doesn't
	// worry about it.
	Dependencies []string `json:"depends_on,omitempty"`
}

ModuleState is used to track all the state relevant to a single module. Previous to Terraform 0.3, all state belonged to the "root" module.

func (*ModuleState) GoString added in v0.3.0 

func (m *ModuleState) GoString() string

func (*ModuleState) IsRoot added in v0.3.0 

func (m *ModuleState) IsRoot() bool

IsRoot says whether or not this module diff is for the root module.

func (*ModuleState) Orphans added in v0.3.0 

func (m *ModuleState) Orphans(c *config.Config) []string

Orphans returns a list of keys of resources that are in the State but aren't present in the configuration itself. Hence, these keys represent the state of resources that are orphans.

func (*ModuleState) String added in v0.3.0 

func (m *ModuleState) String() string

func (*ModuleState) View added in v0.3.0 

func (m *ModuleState) View(id string) *ModuleState

View returns a view with the given resource prefix.

type NilHook 

type NilHook struct{}

NilHook is a Hook implementation that does nothing. It exists only to simplify implementing hooks. You can embed this into your Hook implementation and only implement the functions you are interested in.

func (*NilHook) PostApply 

func (*NilHook) PostApply(*InstanceInfo, *InstanceState, error) (HookAction, error)

func (*NilHook) PostDiff 

func (*NilHook) PostDiff(*InstanceInfo, *InstanceDiff) (HookAction, error)

func (*NilHook) PostProvision 

func (*NilHook) PostProvision(*InstanceInfo, string) (HookAction, error)

func (*NilHook) PostProvisionResource 

func (*NilHook) PostProvisionResource(*InstanceInfo, *InstanceState) (HookAction, error)

func (*NilHook) PostRefresh 

func (*NilHook) PostRefresh(*InstanceInfo, *InstanceState) (HookAction, error)

func (*NilHook) PreApply 

func (*NilHook) PreApply(*InstanceInfo, *InstanceState, *InstanceDiff) (HookAction, error)

func (*NilHook) PreDiff 

func (*NilHook) PreDiff(*InstanceInfo, *InstanceState) (HookAction, error)

func (*NilHook) PreProvision 

func (*NilHook) PreProvision(*InstanceInfo, string) (HookAction, error)

func (*NilHook) PreProvisionResource 

func (*NilHook) PreProvisionResource(*InstanceInfo, *InstanceState) (HookAction, error)

func (*NilHook) PreRefresh 

func (*NilHook) PreRefresh(*InstanceInfo, *InstanceState) (HookAction, error)

func (*NilHook) ProvisionOutput added in v0.3.0 

func (*NilHook) ProvisionOutput(
	*InstanceInfo, string, string)

type Plan 

type Plan struct {
	Diff   *Diff
	Module *module.Tree
	State  *State
	Vars   map[string]string
	// contains filtered or unexported fields
}

Plan represents a single Terraform execution plan, which contains all the information necessary to make an infrastructure change.

func ReadPlan 

func ReadPlan(src io.Reader) (*Plan, error)

ReadPlan reads a plan structure out of a reader in the format that was written by WritePlan.

func (*Plan) Context 

func (p *Plan) Context(opts *ContextOpts) *Context

Context returns a Context with the data encapsulated in this plan.

The following fields in opts are overridden by the plan: Config, Diff, State, Variables.

func (*Plan) String 

func (p *Plan) String() string

type PlanOpts 

type PlanOpts struct {
	// If set to true, then the generated plan will destroy all resources
	// that are created. Otherwise, it will move towards the desired state
	// specified in the configuration.
	Destroy bool
}

PlanOpts are the options used to generate an execution plan for Terraform.

type PrefixUIInput added in v0.3.0 

type PrefixUIInput struct {
	IdPrefix    string
	QueryPrefix string
	UIInput     UIInput
}

PrefixUIInput is an implementation of UIInput that prefixes the ID with a string, allowing queries to be namespaced.

func (*PrefixUIInput) Input added in v0.3.0 

func (i *PrefixUIInput) Input(opts *InputOpts) (string, error)

type ProvisionerUIOutput added in v0.3.0 

type ProvisionerUIOutput struct {
	Info  *InstanceInfo
	Type  string
	Hooks []Hook
}

ProvisionerUIOutput is an implementation of UIOutput that calls a hook for the output so that the hooks can handle it.

func (*ProvisionerUIOutput) Output added in v0.3.0 

func (o *ProvisionerUIOutput) Output(msg string)

type RemoteState added in v0.3.5 

type RemoteState struct {
	// Type controls the client we use for the remote state
	Type string `json:"type"`

	// Config is used to store arbitrary configuration that
	// is type specific
	Config map[string]string `json:"config"`
}

RemoteState is used to track the information about a remote state store that we push/pull state to.

func (*RemoteState) Empty added in v0.3.5 

func (r *RemoteState) Empty() bool

func (*RemoteState) Equals added in v0.3.5 

func (r *RemoteState) Equals(other *RemoteState) bool

type Resource 

type Resource struct {
	Id           string
	Info         *InstanceInfo
	Config       *ResourceConfig
	Dependencies []string
	Diff         *InstanceDiff
	Provider     ResourceProvider
	State        *InstanceState
	Provisioners []*ResourceProvisionerConfig
	CountIndex   int
	Flags        ResourceFlag
	TaintedIndex int
}

Resource encapsulates a resource, its configuration, its provider, its current state, and potentially a desired diff from the state it wants to reach.

type ResourceAttrDiff 

type ResourceAttrDiff struct {
	Old         string      // Old Value
	New         string      // New Value
	NewComputed bool        // True if new value is computed (unknown currently)
	NewRemoved  bool        // True if this attribute is being removed
	NewExtra    interface{} // Extra information for the provider
	RequiresNew bool        // True if change requires new resource
	Type        DiffAttrType
}

ResourceAttrDiff is the diff of a single attribute of a resource.

func (*ResourceAttrDiff) GoString 

func (d *ResourceAttrDiff) GoString() string

type ResourceConfig 

type ResourceConfig struct {
	ComputedKeys []string
	Raw          map[string]interface{}
	Config       map[string]interface{}
	// contains filtered or unexported fields
}

ResourceConfig holds the configuration given for a resource. This is done instead of a raw `map[string]interface{}` type so that rich methods can be added to it to make dealing with it easier.

func NewResourceConfig 

func NewResourceConfig(c *config.RawConfig) *ResourceConfig

NewResourceConfig creates a new ResourceConfig from a config.RawConfig.

func (*ResourceConfig) CheckSet 

func (c *ResourceConfig) CheckSet(keys []string) []error

CheckSet checks that the given list of configuration keys is properly set. If not, errors are returned for each unset key.

This is useful to be called in the Validate method of a ResourceProvider.

func (*ResourceConfig) Get 

func (c *ResourceConfig) Get(k string) (interface{}, bool)

Get looks up a configuration value by key and returns the value.

The second return value is true if the get was successful. Get will not succeed if the value is being computed.

func (*ResourceConfig) IsComputed added in v0.3.0 

func (c *ResourceConfig) IsComputed(k string) bool

IsComputed returns whether the given key is computed or not.

func (*ResourceConfig) IsSet 

func (c *ResourceConfig) IsSet(k string) bool

IsSet checks if the key in the configuration is set. A key is set if it has a value or the value is being computed (is unknown currently).

This function should be used rather than checking the keys of the raw configuration itself, since a key may be omitted from the raw configuration if it is being computed.

type ResourceDependency 

type ResourceDependency struct {
	// ID of the resource that we depend on. This ID should map
	// directly to another ResourceState's ID.
	ID string
}

ResourceDependency maps a resource to another resource that it depends on to remain intact and uncorrupted.

type ResourceExpandMode added in v0.3.0 

type ResourceExpandMode byte

ResourceExpandMode specifies the expand behavior of the GraphNodeResource node. 

const (
	ResourceExpandNone ResourceExpandMode = iota
	ResourceExpandApply
	ResourceExpandDestroy
)

type ResourceFlag added in v0.3.0 

type ResourceFlag byte

ResourceKind specifies what kind of instance we're working with, whether its a primary instance, a tainted instance, or an orphan. 

const (
	FlagPrimary ResourceFlag = 1 << iota
	FlagTainted
	FlagOrphan
	FlagHasTainted
	FlagReplacePrimary
	FlagDeposed
)

type ResourceProvider 

type ResourceProvider interface {
	// Input is called to ask the provider to ask the user for input
	// for completing the configuration if necesarry.
	//
	// This may or may not be called, so resource provider writers shouldn't
	// rely on this being available to set some default values for validate
	// later. Example of a situation where this wouldn't be called is if
	// the user is not using a TTY.
	Input(UIInput, *ResourceConfig) (*ResourceConfig, error)

	// Validate is called once at the beginning with the raw configuration
	// (no interpolation done) and can return a list of warnings and/or
	// errors.
	//
	// This is called once with the provider configuration only. It may not
	// be called at all if no provider configuration is given.
	//
	// This should not assume that any values of the configurations are valid.
	// The primary use case of this call is to check that required keys are
	// set.
	Validate(*ResourceConfig) ([]string, []error)

	// ValidateResource is called once at the beginning with the raw
	// configuration (no interpolation done) and can return a list of warnings
	// and/or errors.
	//
	// This is called once per resource.
	//
	// This should not assume any of the values in the resource configuration
	// are valid since it is possible they have to be interpolated still.
	// The primary use case of this call is to check that the required keys
	// are set and that the general structure is correct.
	ValidateResource(string, *ResourceConfig) ([]string, []error)

	// Configure configures the provider itself with the configuration
	// given. This is useful for setting things like access keys.
	//
	// This won't be called at all if no provider configuration is given.
	//
	// Configure returns an error if it occurred.
	Configure(*ResourceConfig) error

	// Resources returns all the available resource types that this provider
	// knows how to manage.
	Resources() []ResourceType

	// Apply applies a diff to a specific resource and returns the new
	// resource state along with an error.
	//
	// If the resource state given has an empty ID, then a new resource
	// is expected to be created.
	Apply(
		*InstanceInfo,
		*InstanceState,
		*InstanceDiff) (*InstanceState, error)

	// Diff diffs a resource versus a desired state and returns
	// a diff.
	Diff(
		*InstanceInfo,
		*InstanceState,
		*ResourceConfig) (*InstanceDiff, error)

	// Refresh refreshes a resource and updates all of its attributes
	// with the latest information.
	Refresh(*InstanceInfo, *InstanceState) (*InstanceState, error)
}

ResourceProvider is an interface that must be implemented by any resource provider: the thing that creates and manages the resources in a Terraform configuration.

type ResourceProviderFactory 

type ResourceProviderFactory func() (ResourceProvider, error)

ResourceProviderFactory is a function type that creates a new instance of a resource provider.

func ResourceProviderFactoryFixed 

func ResourceProviderFactoryFixed(p ResourceProvider) ResourceProviderFactory

ResourceProviderFactoryFixed is a helper that creates a ResourceProviderFactory that just returns some fixed provider.

type ResourceProvisioner 

type ResourceProvisioner interface {
	// Validate is called once at the beginning with the raw
	// configuration (no interpolation done) and can return a list of warnings
	// and/or errors.
	//
	// This is called once per resource.
	//
	// This should not assume any of the values in the resource configuration
	// are valid since it is possible they have to be interpolated still.
	// The primary use case of this call is to check that the required keys
	// are set and that the general structure is correct.
	Validate(*ResourceConfig) ([]string, []error)

	// Apply runs the provisioner on a specific resource and returns the new
	// resource state along with an error. Instead of a diff, the ResourceConfig
	// is provided since provisioners only run after a resource has been
	// newly created.
	Apply(UIOutput, *InstanceState, *ResourceConfig) error
}

ResourceProvisioner is an interface that must be implemented by any resource provisioner: the thing that initializes resources in a Terraform configuration.

type ResourceProvisionerConfig 

type ResourceProvisionerConfig struct {
	Type        string
	Provisioner ResourceProvisioner
	Config      *ResourceConfig
	RawConfig   *config.RawConfig
	ConnInfo    *config.RawConfig
}

ResourceProvisionerConfig is used to pair a provisioner with its provided configuration. This allows us to use singleton instances of each ResourceProvisioner and to keep the relevant configuration instead of instantiating a new Provisioner for each resource.

type ResourceProvisionerFactory 

type ResourceProvisionerFactory func() (ResourceProvisioner, error)

ResourceProvisionerFactory is a function type that creates a new instance of a resource provisioner.

type ResourceState 

type ResourceState struct {
	// This is filled in and managed by Terraform, and is the resource
	// type itself such as "mycloud_instance". If a resource provider sets
	// this value, it won't be persisted.
	Type string `json:"type"`

	// Dependencies are a list of things that this resource relies on
	// existing to remain intact. For example: an AWS instance might
	// depend on a subnet (which itself might depend on a VPC, and so
	// on).
	//
	// Terraform uses this information to build valid destruction
	// orders and to warn the user if they're destroying a resource that
	// another resource depends on.
	//
	// Things can be put into this list that may not be managed by
	// Terraform. If Terraform doesn't find a matching ID in the
	// overall state, then it assumes it isn't managed and doesn't
	// worry about it.
	Dependencies []string `json:"depends_on,omitempty"`

	// Primary is the current active instance for this resource.
	// It can be replaced but only after a successful creation.
	// This is the instances on which providers will act.
	Primary *InstanceState `json:"primary"`

	// Tainted is used to track any underlying instances that
	// have been created but are in a bad or unknown state and
	// need to be cleaned up subsequently.  In the
	// standard case, there is only at most a single instance.
	// However, in pathological cases, it is possible for the number
	// of instances to accumulate.
	Tainted []*InstanceState `json:"tainted,omitempty"`
}

ResourceState holds the state of a resource that is used so that a provider can find and manage an existing resource as well as for storing attributes that are used to populate variables of child resources.

Attributes has attributes about the created resource that are queryable in interpolation: "${type.id.attr}"

Extra is just extra data that a provider can return that we store for later, but is not exposed in any way to the user.

func (*ResourceState) GoString added in v0.2.0 

func (s *ResourceState) GoString() string

func (*ResourceState) String added in v0.3.0 

func (s *ResourceState) String() string

type ResourceStateV1 added in v0.3.0 

type ResourceStateV1 struct {
	// This is filled in and managed by Terraform, and is the resource
	// type itself such as "mycloud_instance". If a resource provider sets
	// this value, it won't be persisted.
	Type string

	// A unique ID for this resource. This is opaque to Terraform
	// and is only meant as a lookup mechanism for the providers.
	ID string

	// Attributes are basic information about the resource. Any keys here
	// are accessible in variable format within Terraform configurations:
	// ${resourcetype.name.attribute}.
	Attributes map[string]string

	// ConnInfo is used for the providers to export information which is
	// used to connect to the resource for provisioning. For example,
	// this could contain SSH or WinRM credentials.
	ConnInfo map[string]string

	// Extra information that the provider can store about a resource.
	// This data is opaque, never shown to the user, and is sent back to
	// the provider as-is for whatever purpose appropriate.
	Extra map[string]interface{}

	// Dependencies are a list of things that this resource relies on
	// existing to remain intact. For example: an AWS instance might
	// depend on a subnet (which itself might depend on a VPC, and so
	// on).
	//
	// Terraform uses this information to build valid destruction
	// orders and to warn the user if they're destroying a resource that
	// another resource depends on.
	//
	// Things can be put into this list that may not be managed by
	// Terraform. If Terraform doesn't find a matching ID in the
	// overall state, then it assumes it isn't managed and doesn't
	// worry about it.
	Dependencies []ResourceDependency
}

/ ResourceState holds the state of a resource that is used so that a provider can find and manage an existing resource as well as for storing attributes that are uesd to populate variables of child resources.

Attributes has attributes about the created resource that are queryable in interpolation: "${type.id.attr}"

Extra is just extra data that a provider can return that we store for later, but is not exposed in any way to the user.

func (*ResourceStateV1) GoString added in v0.3.0 

func (s *ResourceStateV1) GoString() string

func (*ResourceStateV1) MergeDiff added in v0.3.0 

func (s *ResourceStateV1) MergeDiff(d *InstanceDiff) *ResourceStateV1

MergeDiff takes a ResourceDiff and merges the attributes into this resource state in order to generate a new state. This new state can be used to provide updated attribute lookups for variable interpolation.

If the diff attribute requires computing the value, and hence won't be available until apply, the value is replaced with the computeID.

type ResourceType 

type ResourceType struct {
	Name string
}

ResourceType is a type of resource that a resource provider can manage.

type Semaphore added in v0.3.1 

type Semaphore chan struct{}

Semaphore is a wrapper around a channel to provide utility methods to clarify that we are treating the channel as a semaphore

func NewSemaphore added in v0.3.1 

func NewSemaphore(n int) Semaphore

NewSemaphore creates a semaphore that allows up to a given limit of simultaneous acquisitions

func (Semaphore) Acquire added in v0.3.1 

func (s Semaphore) Acquire()

Acquire is used to acquire an available slot. Blocks until available.

func (Semaphore) Release added in v0.3.1 

func (s Semaphore) Release()

Release is used to return a slot. Acquire must be called as a pre-condition.

func (Semaphore) TryAcquire added in v0.3.1 

func (s Semaphore) TryAcquire() bool

TryAcquire is used to do a non-blocking acquire. Returns a bool indicating success

type State 

type State struct {
	// Version is the protocol version. Currently only "1".
	Version int `json:"version"`

	// Serial is incremented on any operation that modifies
	// the State file. It is used to detect potentially conflicting
	// updates.
	Serial int64 `json:"serial"`

	// Remote is used to track the metadata required to
	// pull and push state files from a remote storage endpoint.
	Remote *RemoteState `json:"remote,omitempty"`

	// Modules contains all the modules in a breadth-first order
	Modules []*ModuleState `json:"modules"`
}

State keeps track of a snapshot state-of-the-world that Terraform can use to keep track of what real world resources it is actually managing. This is the latest format as of Terraform 0.3

func NewState added in v0.3.5 

func NewState() *State

NewState is used to initialize a blank state

func ReadState 

func ReadState(src io.Reader) (*State, error)

ReadState reads a state structure out of a reader in the format that was written by WriteState.

func (*State) AddModule added in v0.3.0 

func (s *State) AddModule(path []string) *ModuleState

AddModule adds the module with the given path to the state.

This should be the preferred method to add module states since it allows us to optimize lookups later as well as control sorting.

func (*State) Children added in v0.3.0 

func (s *State) Children(path []string) []*ModuleState

Children returns the ModuleStates that are direct children of the given path. If the path is "root", for example, then children returned might be "root.child", but not "root.child.grandchild".

func (*State) GoString added in v0.3.0 

func (s *State) GoString() string

func (*State) ModuleByPath added in v0.3.0 

func (s *State) ModuleByPath(path []string) *ModuleState

ModuleByPath is used to lookup the module state for the given path. This should be the prefered lookup mechanism as it allows for future lookup optimizations.

func (*State) RootModule added in v0.3.0 

func (s *State) RootModule() *ModuleState

RootModule returns the ModuleState for the root module

func (*State) String 

func (s *State) String() string

type StateV1 added in v0.3.0 

type StateV1 struct {
	Outputs   map[string]string
	Resources map[string]*ResourceStateV1
	Tainted   map[string]struct{}
	// contains filtered or unexported fields
}

StateV1 is used to represent the state of Terraform files before 0.3. It is automatically upgraded to a modern State representation on start.

func ReadStateV1 added in v0.3.0 

func ReadStateV1(src io.Reader) (*StateV1, error)

ReadStateV1 reads a state structure out of a reader in the format that was written by WriteState.

func (*StateV1) Orphans added in v0.3.0 

func (s *StateV1) Orphans(c *config.Config) []string

Orphans returns a list of keys of resources that are in the State but aren't present in the configuration itself. Hence, these keys represent the state of resources that are orphans.

func (*StateV1) String added in v0.3.0 

func (s *StateV1) String() string

type UIInput added in v0.3.0 

type UIInput interface {
	Input(*InputOpts) (string, error)
}

UIInput is the interface that must be implemented to ask for input from this user. This should forward the request to wherever the user inputs things to ask for values.

type UIOutput added in v0.3.0 

type UIOutput interface {
	Output(string)
}

UIOutput is the interface that must be implemented to output data to the end user.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.