resource

Documentation

Index

• Constants
• func Retry(timeout time.Duration, f RetryFunc) error
• func Test(t TestT, c TestCase)
• func UniqueId() string
• type CreateFunc
• type DestroyFunc
• type DiffFunc
• type Map
  • func (m *Map) Apply(info *terraform.InstanceInfo, s *terraform.InstanceState, ...) (*terraform.InstanceState, error)
  • func (m *Map) Diff(info *terraform.InstanceInfo, s *terraform.InstanceState, ...) (*terraform.InstanceDiff, error)
  • func (m *Map) Refresh(info *terraform.InstanceInfo, s *terraform.InstanceState, meta interface{}) (*terraform.InstanceState, error)
  • func (m *Map) Resources() []terraform.ResourceType
  • func (m *Map) Validate(t string, c *terraform.ResourceConfig) ([]string, []error)
• type RefreshFunc
• type Resource
• type RetryError
  • func (e RetryError) Error() string
• type RetryFunc
• type StateChangeConf
  • func (conf *StateChangeConf) WaitForState() (interface{}, error)
• type StateRefreshFunc
• type TestCase
• type TestCheckFunc
  • func ComposeTestCheckFunc(fs ...TestCheckFunc) TestCheckFunc
  • func TestCheckResourceAttr(name, key, value string) TestCheckFunc
  • func TestCheckResourceAttrPtr(name string, key string, value *string) TestCheckFunc
• type TestStep
• type TestT
• type UpdateFunc

Constants

const TestEnvVar = "TF_ACC"

const UniqueIdPrefix = `terraform-`

Functions

func Retry

func Retry(timeout time.Duration, f RetryFunc) error

Retry is a basic wrapper around StateChangeConf that will just retry a function until it no longer returns an error.

func Test

func Test(t TestT, c TestCase)

Test performs an acceptance test on a resource.

Tests are not run unless an environmental variable "TF_ACC" is set to some non-empty value. This is to avoid test cases surprising a user by creating real resources.

Tests will fail unless the verbose flag (`go test -v`, or explicitly the "-test.v" flag) is set. Because some acceptance tests take quite long, we require the verbose flag so users are able to see progress output.

func UniqueId

func UniqueId() string

Helper for a resource to generate a unique identifier

This uses a simple RFC 4122 v4 UUID with some basic cosmetic filters applied (base32, remove padding, downcase) to make visually distinguishing identifiers easier.

Types

type CreateFunc

type CreateFunc func(
	*terraform.InstanceState,
	*terraform.InstanceDiff,
	interface{}) (*terraform.InstanceState, error)

CreateFunc is a function that creates a resource that didn't previously exist.

type DestroyFunc

type DestroyFunc func(
	*terraform.InstanceState,
	interface{}) error

DestroyFunc is a function that destroys a resource that previously exists using the state.

type DiffFunc

type DiffFunc func(
	*terraform.InstanceState,
	*terraform.ResourceConfig,
	interface{}) (*terraform.InstanceDiff, error)

DiffFunc is a function that performs a diff of a resource.

type Map

type Map struct {
	Mapping map[string]Resource
}

Map is a map of resources that are supported, and provides helpers for more easily implementing a ResourceProvider.

func (*Map) Apply

func (m *Map) Apply(
	info *terraform.InstanceInfo,
	s *terraform.InstanceState,
	d *terraform.InstanceDiff,
	meta interface{}) (*terraform.InstanceState, error)

Apply performs a create or update depending on the diff, and calls the proper function on the matching Resource.

func (*Map) Diff

func (m *Map) Diff(
	info *terraform.InstanceInfo,
	s *terraform.InstanceState,
	c *terraform.ResourceConfig,
	meta interface{}) (*terraform.InstanceDiff, error)

Diff performs a diff on the proper resource type.

func (*Map) Refresh

func (m *Map) Refresh(
	info *terraform.InstanceInfo,
	s *terraform.InstanceState,
	meta interface{}) (*terraform.InstanceState, error)

Refresh performs a Refresh on the proper resource type.

Refresh on the Resource won't be called if the state represents a non-created resource (ID is blank).

An error is returned if the resource isn't registered.

func (*Map) Resources

func (m *Map) Resources() []terraform.ResourceType

Resources returns all the resources that are supported by this resource map and can be used to satisfy the Resources method of a ResourceProvider.

func (*Map) Validate

func (m *Map) Validate(
	t string, c *terraform.ResourceConfig) ([]string, []error)

type RefreshFunc

type RefreshFunc func(
	*terraform.InstanceState,
	interface{}) (*terraform.InstanceState, error)

RefreshFunc is a function that performs a refresh of a specific type of resource.

type Resource

type Resource struct {
	ConfigValidator *config.Validator
	Create          CreateFunc
	Destroy         DestroyFunc
	Diff            DiffFunc
	Refresh         RefreshFunc
	Update          UpdateFunc
}

type RetryError

type RetryError struct {
	Err error
}

RetryError, if returned, will quit the retry immediately with the Err.

func (RetryError) Error

func (e RetryError) Error() string

type RetryFunc

type RetryFunc func() error

RetryFunc is the function retried until it succeeds.

type StateChangeConf

type StateChangeConf struct {
	Delay          time.Duration    // Wait this time before starting checks
	Pending        []string         // States that are "allowed" and will continue trying
	Refresh        StateRefreshFunc // Refreshes the current state
	Target         string           // Target state
	Timeout        time.Duration    // The amount of time to wait before timeout
	MinTimeout     time.Duration    // Smallest time to wait before refreshes
	NotFoundChecks int              // Number of times to allow not found
}

StateChangeConf is the configuration struct used for `WaitForState`.

func (*StateChangeConf) WaitForState

func (conf *StateChangeConf) WaitForState() (interface{}, error)

WaitForState watches an object and waits for it to achieve the state specified in the configuration using the specified Refresh() func, waiting the number of seconds specified in the timeout configuration.

If the Refresh function returns a error, exit immediately with that error.

If the Refresh function returns a state other than the Target state or one listed in Pending, return immediately with an error.

If the Timeout is exceeded before reaching the Target state, return an error.

Otherwise, result the result of the first call to the Refresh function to reach the target state.

type StateRefreshFunc

type StateRefreshFunc func() (result interface{}, state string, err error)

StateRefreshFunc is a function type used for StateChangeConf that is responsible for refreshing the item being watched for a state change.

It returns three results. `result` is any object that will be returned as the final object after waiting for state change. This allows you to return the final updated object, for example an EC2 instance after refreshing it.

`state` is the latest state of that object. And `err` is any error that may have happened while refreshing the state.

type TestCase

type TestCase struct {
	// PreCheck, if non-nil, will be called before any test steps are
	// executed. It will only be executed in the case that the steps
	// would run, so it can be used for some validation before running
	// acceptance tests, such as verifying that keys are setup.
	PreCheck func()

	// Providers is the ResourceProvider that will be under test.
	//
	// Alternately, ProviderFactories can be specified for the providers
	// that are valid. This takes priority over Providers.
	//
	// The end effect of each is the same: specifying the providers that
	// are used within the tests.
	Providers         map[string]terraform.ResourceProvider
	ProviderFactories map[string]terraform.ResourceProviderFactory

	// CheckDestroy is called after the resource is finally destroyed
	// to allow the tester to test that the resource is truly gone.
	CheckDestroy TestCheckFunc

	// Steps are the apply sequences done within the context of the
	// same state. Each step can have its own check to verify correctness.
	Steps []TestStep
}

TestCase is a single acceptance test case used to test the apply/destroy lifecycle of a resource in a specific configuration.

When the destroy plan is executed, the config from the last TestStep is used to plan it.

type TestCheckFunc

type TestCheckFunc func(*terraform.State) error

TestCheckFunc is the callback type used with acceptance tests to check the state of a resource. The state passed in is the latest state known, or in the case of being after a destroy, it is the last known state when it was created.

func ComposeTestCheckFunc

func ComposeTestCheckFunc(fs ...TestCheckFunc) TestCheckFunc

ComposeTestCheckFunc lets you compose multiple TestCheckFuncs into a single TestCheckFunc.

As a user testing their provider, this lets you decompose your checks into smaller pieces more easily.

func TestCheckResourceAttr

func TestCheckResourceAttr(name, key, value string) TestCheckFunc

func TestCheckResourceAttrPtr

func TestCheckResourceAttrPtr(name string, key string, value *string) TestCheckFunc

TestCheckResourceAttrPtr is like TestCheckResourceAttr except the value is a pointer so that it can be updated while the test is running. It will only be dereferenced at the point this step is run.

type TestStep

type TestStep struct {
	// Config a string of the configuration to give to Terraform.
	Config string

	// Check is called after the Config is applied. Use this step to
	// make your own API calls to check the status of things, and to
	// inspect the format of the ResourceState itself.
	//
	// If an error is returned, the test will fail. In this case, a
	// destroy plan will still be attempted.
	//
	// If this is nil, no check is done on this step.
	Check TestCheckFunc

	// Destroy will create a destroy plan if set to true.
	Destroy bool

	// TransientResource indicates that resources created as part
	// of this test step are temporary and might be recreated anew
	// with every planning step. This should only be set for
	// pseudo-resources, like the null resource or templates.
	TransientResource bool
}

TestStep is a single apply sequence of a test, done within the context of a state.

Multiple TestSteps can be sequenced in a Test to allow testing potentially complex update logic. In general, simply create/destroy tests will only need one step.

type TestT

type TestT interface {
	Error(args ...interface{})
	Fatal(args ...interface{})
	Skip(args ...interface{})
}

TestT is the interface used to handle the test lifecycle of a test.

Users should just use a *testing.T object, which implements this.

type UpdateFunc

type UpdateFunc func(
	*terraform.InstanceState,
	*terraform.InstanceDiff,
	interface{}) (*terraform.InstanceState, error)

UpdateFunc is a function that is called to update a resource that previously existed. The difference between this and CreateFunc is that the diff is guaranteed to only contain attributes that don't require a new resource.