terraform

Documentation

Index

• Variables
• func BuildPluginsConfig() (string, error)
• func RestoreSources(dst string) error
• func ServePlugin(name string)
• type AWSCredentials
  • func (a *AWSCredentials) ToEnvironment() map[string]string
  • func (a *AWSCredentials) Validate() error
• type Credentials
  • func (c *Credentials) ToEnvironment() (map[string]string, error)
• type ExecutionStatus
• type Executor
  • func NewExecutor(executionPath string) (*Executor, error)
  • func (ex *Executor) AddCredentials(credentials *Credentials) error
  • func (ex *Executor) AddEnvironmentVariables(envVars map[string]string)
  • func (ex *Executor) AddFile(name string, content []byte) error
  • func (ex *Executor) AddVariables(content []byte) error
  • func (ex *Executor) Cleanup()
  • func (ex *Executor) Execute(args ...string) (int, chan struct{}, error)
  • func (ex *Executor) Output(id int) (io.ReadCloser, error)
  • func (ex *Executor) State() *terraform.State
  • func (ex *Executor) Status(id int) (ExecutionStatus, error)
  • func (ex *Executor) WorkingDirectory() string
  • func (ex *Executor) Zip(w io.Writer, withTopFolder bool) error

Variables

var ErrBinaryNotFound = errors.New(
	"TerraForm not in executable's folder, cwd nor PATH",
)

ErrBinaryNotFound denotes the fact that the TerraForm binary could not be found on disk.

Functions

func BuildPluginsConfig

func BuildPluginsConfig() (string, error)

BuildPluginsConfig creates a configuration that can be used by TerraForm to make available any provider/provisioners that are vendored in the present binary.

func RestoreSources

func RestoreSources(dst string) error

RestoreSources locates the TerraForm sources for Tectonic and copy them to the given directory.

It recursively searches the directory trees upward, for all the defined sources' files and directories, from to the installer's executable first and then from cwd if it didn't already find them.

func ServePlugin

func ServePlugin(name string)

ServePlugin serves every vendored TerraForm providers/provisioners. This function never returns and should be the final function called in the main function of the plugin. Additionally, there should be no stdout/stderr outputs, which may interfere with the handshake and further communications.

Types

type AWSCredentials

type AWSCredentials struct {
	AWSAccessKeyID     string `json:"AWSAccessKeyID"`
	AWSSecretAccessKey string `json:"AWSSecretAccessKey"`
	AWSSessionToken    string `json:"AWSSessionToken"`
	AWSRegion          string `json:"AWSRegion"`
}

AWSCredentials represents the credentials required by TerraForm's AWS provider.

func (*AWSCredentials) ToEnvironment

func (a *AWSCredentials) ToEnvironment() map[string]string

ToEnvironment returns the environment variables that are expected by TerraForm's provider.

func (*AWSCredentials) Validate

func (a *AWSCredentials) Validate() error

Validate verifies that the given credentials are valid.

type Credentials

type Credentials struct {
	*AWSCredentials `json:",inline"`
}

Credentials holds all the information that are necessary to make TerraForm authenticate against various providers.

func (*Credentials) ToEnvironment

func (c *Credentials) ToEnvironment() (map[string]string, error)

ToEnvironment returns the environment variables that are expected by TerraForm's provider.

type ExecutionStatus

type ExecutionStatus string

ExecutionStatus describes whether an execution succeeded, failed or is still in progress.

const (
	// ExecutionStatusUnknown indicates that the status of execution is unknown.
	ExecutionStatusUnknown ExecutionStatus = "Unknown"
	// ExecutionStatusRunning indicates that the the execution is still in
	// process.
	ExecutionStatusRunning ExecutionStatus = "Running"
	// ExecutionStatusSuccess indicates that the execution succeeded.
	ExecutionStatusSuccess ExecutionStatus = "Success"
	// ExecutionStatusFailure indicates that the execution failed.
	ExecutionStatusFailure ExecutionStatus = "Failure"
)

type Executor

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

Executor enables calling TerraForm from Go, across platforms, with any additional providers/provisioners that the currently executing binary exposes.

The TerraForm binary is expected to be in the executing binary's folder, in the current working directory or in the PATH. Each Executor runs in a temporary folder, so each Executor should only be used for one TF project.

TODO: Ideally, we would use TerraForm as a Go library, so we can monitor a hook and report the current state in real-time when Apply/Refresh/Destroy are used. While technically possible today, because TerraForm currently hides the providers/provisioners list construction in their main package, it would require to reproduce a bunch of their logic, which is out of the scope of the first-version of the Executor. With a bit of efforts, we could actually even stop requiring having a TerraForm binary altogether, by linking the builtin providers/provisioners to this particular binary and re-implemeting the routing here. Alternatively, we could contribute upstream to add a 'debug' flag that would enable a hook that would expose the live state to a file (or else).

func NewExecutor

func NewExecutor(executionPath string) (*Executor, error)

NewExecutor initializes a new Executor.

func (*Executor) AddCredentials

func (ex *Executor) AddCredentials(credentials *Credentials) error

AddCredentials is a convenience function that converts the given Credentials into environment variables and add them to the Executor.

If the credentials parameter is nil, nothing is done. An error is returned if the credentials are invalid.

func (*Executor) AddEnvironmentVariables

func (ex *Executor) AddEnvironmentVariables(envVars map[string]string)

AddEnvironmentVariables adds extra environment variables that will be set during the execution. Existing variables are replaced. This function is not thread-safe.

func (*Executor) AddFile

func (ex *Executor) AddFile(name string, content []byte) error

AddFile is a convenience function that writes a single file in the Executor's working directory using the given content. It may replace an existing file.

func (*Executor) AddVariables

func (ex *Executor) AddVariables(content []byte) error

AddVariables writes the `terraform.tfvars` file in the Executor's working directory using the given content. It may replace an existing file.

func (*Executor) Cleanup

func (ex *Executor) Cleanup()

Cleanup removes resources that were allocated by the Executor.

func (*Executor) Execute

func (ex *Executor) Execute(args ...string) (int, chan struct{}, error)

Execute runs the given command and arguments against TerraForm, and returns an identifier that can be used to read the output of the process as it is executed and after.

Execute is non-blocking, and takes a lock in the execution path. Locking is handled by TerraForm itself.

An error is returned if the TerraForm binary could not be found, or if the TerraForm call itself failed, in which case, details can be found in the output.

func (*Executor) Output

func (ex *Executor) Output(id int) (io.ReadCloser, error)

Output returns a ReadCloser on the output file of an execution, or an error if no output for that execution identifier can be found.

func (*Executor) State

func (ex *Executor) State() *terraform.State

State returns the current TerraForm State.

The returned value can be nil if there is currently no state held.

func (*Executor) Status

func (ex *Executor) Status(id int) (ExecutionStatus, error)

Status returns the status of a given execution process.

An error can be returned if the running processes could not be listed, or if the process failed, in which case the exit message is returned in an error of type ExecutionError.

Note that if the identifier is invalid, the current implementation will return ExecutionStatusSuccess rather than ExecutionStatusUnknown.

func (*Executor) WorkingDirectory

func (ex *Executor) WorkingDirectory() string

WorkingDirectory returns the directory in which TerraForm runs, which can be useful for inspection or to retrieve any generated files.

func (*Executor) Zip

func (ex *Executor) Zip(w io.Writer, withTopFolder bool) error

Zip streams the working directory as a ZIP file to the given io.writer.