schema

package
v0.3.0 Latest Latest
Warning

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

 Go to latest Published: Oct 14, 2014 License: MPL-2.0 Imports: 9 Imported by: 0

README

Terraform Helper Lib: schema

The schema package provides a high-level interface for writing resource providers for Terraform.

If you're writing a resource provider, we recommend you use this package.

The interface exposed by this package is much friendlier than trying to write to the Terraform API directly. The core Terraform API is low-level and built for maximum flexibility and control, whereas this library is built as a framework around that to more easily write common providers.

Documentation

Overview

schema is a high-level framework for easily writing new providers for Terraform. Usage of schema is recommended over attempting to write to the low-level plugin interfaces manually.

schema breaks down provider creation into simple CRUD operations for resources. The logic of diffing, destroying before creating, updating or creating, etc. is all handled by the framework. The plugin author only needs to implement a configuration schema and the CRUD operations and everything else is meant to just work.

A good starting point is to view the Provider structure.

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

This section is empty.

Types

type ConfigureFunc 

type ConfigureFunc func(*ResourceData) (interface{}, error)

ConfigureFunc is the function used to configure a Provider.

The interface{} value returned by this function is stored and passed into the subsequent resources as the meta parameter. This return value is usually used to pass along a configured API client, a configuration structure, etc.

type CreateFunc 

type CreateFunc func(*ResourceData, interface{}) error

See Resource documentation.

type DeleteFunc 

type DeleteFunc func(*ResourceData, interface{}) error

See Resource documentation.

type Provider 

type Provider struct {
	// Schema is the schema for the configuration of this provider. If this
	// provider has no configuration, this can be omitted.
	//
	// The keys of this map are the configuration keys, and the value is
	// the schema describing the value of the configuration.
	Schema map[string]*Schema

	// ResourcesMap is the list of available resources that this provider
	// can manage, along with their Resource structure defining their
	// own schemas and CRUD operations.
	//
	// Provider automatically handles routing operations such as Apply,
	// Diff, etc. to the proper resource.
	ResourcesMap map[string]*Resource

	// ConfigureFunc is a function for configuring the provider. If the
	// provider doesn't need to be configured, this can be omitted.
	//
	// See the ConfigureFunc documentation for more information.
	ConfigureFunc ConfigureFunc
	// contains filtered or unexported fields
}

Provider represents a resource provider in Terraform, and properly implements all of the ResourceProvider API.

By defining a schema for the configuration of the provider, the map of supporting resources, and a configuration function, the schema framework takes over and handles all the provider operations for you.

After defining the provider structure, it is unlikely that you'll require any of the methods on Provider itself.

func (*Provider) Apply 

func (p *Provider) Apply(
	info *terraform.InstanceInfo,
	s *terraform.InstanceState,
	d *terraform.InstanceDiff) (*terraform.InstanceState, error)

Apply implementation of terraform.ResourceProvider interface.

func (*Provider) Configure 

func (p *Provider) Configure(c *terraform.ResourceConfig) error

Configure implementation of terraform.ResourceProvider interface.

func (*Provider) Diff 

func (p *Provider) Diff(
	info *terraform.InstanceInfo,
	s *terraform.InstanceState,
	c *terraform.ResourceConfig) (*terraform.InstanceDiff, error)

Diff implementation of terraform.ResourceProvider interface.

func (*Provider) Input added in v0.3.0 

func (p *Provider) Input(
	input terraform.UIInput,
	c *terraform.ResourceConfig) (*terraform.ResourceConfig, error)

Input implementation of terraform.ResourceProvider interface.

func (*Provider) InternalValidate 

func (p *Provider) InternalValidate() error

InternalValidate should be called to validate the structure of the provider.

This should be called in a unit test for any provider to verify before release that a provider is properly configured for use with this library.

func (*Provider) Meta 

func (p *Provider) Meta() interface{}

Meta returns the metadata associated with this provider that was returned by the Configure call. It will be nil until Configure is called.

func (*Provider) Refresh 

func (p *Provider) Refresh(
	info *terraform.InstanceInfo,
	s *terraform.InstanceState) (*terraform.InstanceState, error)

Refresh implementation of terraform.ResourceProvider interface.

func (*Provider) Resources 

func (p *Provider) Resources() []terraform.ResourceType

Resources implementation of terraform.ResourceProvider interface.

func (*Provider) SetMeta 

func (p *Provider) SetMeta(v interface{})

SetMeta can be used to forcefully set the Meta object of the provider. Note that if Configure is called the return value will override anything set here.

func (*Provider) Validate 

func (p *Provider) Validate(c *terraform.ResourceConfig) ([]string, []error)

Validate implementation of terraform.ResourceProvider interface.

func (*Provider) ValidateResource 

func (p *Provider) ValidateResource(
	t string, c *terraform.ResourceConfig) ([]string, []error)

ValidateResource implementation of terraform.ResourceProvider interface.

type ReadFunc 

type ReadFunc func(*ResourceData, interface{}) error

See Resource documentation.

type Resource 

type Resource struct {
	// Schema is the schema for the configuration of this resource.
	//
	// The keys of this map are the configuration keys, and the values
	// describe the schema of the configuration value.
	//
	// The schema is used to represent both configurable data as well
	// as data that might be computed in the process of creating this
	// resource.
	Schema map[string]*Schema

	// The functions below are the CRUD operations for this resource.
	//
	// The only optional operation is Update. If Update is not implemented,
	// then updates will not be supported for this resource.
	//
	// The ResourceData parameter in the functions below are used to
	// query configuration and changes for the resource as well as to set
	// the ID, computed data, etc.
	//
	// The interface{} parameter is the result of the ConfigureFunc in
	// the provider for this resource. If the provider does not define
	// a ConfigureFunc, this will be nil. This parameter should be used
	// to store API clients, configuration structures, etc.
	//
	// If any errors occur during each of the operation, an error should be
	// returned. If a resource was partially updated, be careful to enable
	// partial state mode for ResourceData and use it accordingly.
	Create CreateFunc
	Read   ReadFunc
	Update UpdateFunc
	Delete DeleteFunc
}

Resource represents a thing in Terraform that has a set of configurable attributes and a lifecycle (create, read, update, delete).

The Resource schema is an abstraction that allows provider writers to worry only about CRUD operations while off-loading validation, diff generation, etc. to this higher level library.

func (*Resource) Apply 

func (r *Resource) Apply(
	s *terraform.InstanceState,
	d *terraform.InstanceDiff,
	meta interface{}) (*terraform.InstanceState, error)

Apply creates, updates, and/or deletes a resource.

func (*Resource) Diff 

func (r *Resource) Diff(
	s *terraform.InstanceState,
	c *terraform.ResourceConfig) (*terraform.InstanceDiff, error)

Diff returns a diff of this resource and is API compatible with the ResourceProvider interface.

func (*Resource) InternalValidate 

func (r *Resource) InternalValidate() error

InternalValidate should be called to validate the structure of the resource.

This should be called in a unit test for any resource to verify before release that a resource is properly configured for use with this library.

Provider.InternalValidate() will automatically call this for all of the resources it manages, so you don't need to call this manually if it is part of a Provider.

func (*Resource) Refresh 

func (r *Resource) Refresh(
	s *terraform.InstanceState,
	meta interface{}) (*terraform.InstanceState, error)

Refresh refreshes the state of the resource.

func (*Resource) Validate 

func (r *Resource) Validate(c *terraform.ResourceConfig) ([]string, []error)

Validate validates the resource configuration against the schema.

type ResourceData 

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

ResourceData is used to query and set the attributes of a resource.

ResourceData is the primary argument received for CRUD operations on a resource as well as configuration of a provider. It is a powerful structure that can be used to not only query data, but check for changes, define partial state updates, etc.

The most relevant methods to take a look at are Get, Set, and Partial.

func (*ResourceData) ConnInfo 

func (d *ResourceData) ConnInfo() map[string]string

ConnInfo returns the connection info for this resource.

func (*ResourceData) Get 

func (d *ResourceData) Get(key string) interface{}

Get returns the data for the given key, or nil if the key doesn't exist in the schema.

If the key does exist in the schema but doesn't exist in the configuration, then the default value for that type will be returned. For strings, this is "", for numbers it is 0, etc.

If you want to test if something is set at all in the configuration, use GetOk.

func (*ResourceData) GetChange 

func (d *ResourceData) GetChange(key string) (interface{}, interface{})

GetChange returns the old and new value for a given key.

HasChange should be used to check if a change exists. It is possible that both the old and new value are the same if the old value was not set and the new value is. This is common, for example, for boolean fields which have a zero value of false.

func (*ResourceData) GetOk 

func (d *ResourceData) GetOk(key string) (interface{}, bool)

GetOk returns the data for the given key and whether or not the key existed or not in the configuration. The second boolean result will also be false if a key is given that isn't in the schema at all.

The first result will not necessarilly be nil if the value doesn't exist. The second result should be checked to determine this information.

func (*ResourceData) HasChange 

func (d *ResourceData) HasChange(key string) bool

HasChange returns whether or not the given key has been changed.

func (*ResourceData) Id 

func (d *ResourceData) Id() string

Id returns the ID of the resource.

func (*ResourceData) Partial 

func (d *ResourceData) Partial(on bool)

Partial turns partial state mode on/off.

When partial state mode is enabled, then only key prefixes specified by SetPartial will be in the final state. This allows providers to return partial states for partially applied resources (when errors occur).

func (*ResourceData) Set 

func (d *ResourceData) Set(key string, value interface{}) error

Set sets the value for the given key.

If the key is invalid or the value is not a correct type, an error will be returned.

func (*ResourceData) SetConnInfo 

func (d *ResourceData) SetConnInfo(v map[string]string)

SetConnInfo sets the connection info for a resource.

func (*ResourceData) SetId 

func (d *ResourceData) SetId(v string)

SetId sets the ID of the resource. If the value is blank, then the resource is destroyed.

func (*ResourceData) SetPartial 

func (d *ResourceData) SetPartial(k string)

SetPartial adds the key prefix to the final state output while in partial state mode.

If partial state mode is disabled, then this has no effect. Additionally, whenever partial state mode is toggled, the partial data is cleared.

func (*ResourceData) State 

func (d *ResourceData) State() *terraform.InstanceState

State returns the new InstanceState after the diff and any Set calls.

type Schema 

type Schema struct {
	// Type is the type of the value and must be one of the ValueType values.
	//
	// This type not only determines what type is expected/valid in configuring
	// this value, but also what type is returned when ResourceData.Get is
	// called. The types returned by Get are:
	//
	//   TypeBool - bool
	//   TypeInt - int
	//   TypeString - string
	//   TypeList - []interface{}
	//   TypeMap - map[string]interface{}
	//   TypeSet - *schema.Set
	//
	Type ValueType

	// If one of these is set, then this item can come from the configuration.
	// Both cannot be set. If Optional is set, the value is optional. If
	// Required is set, the value is required.
	//
	// One of these must be set if the value is not computed. That is:
	// value either comes from the config, is computed, or is both.
	Optional bool
	Required bool

	// If this is non-nil, then this will be a default value that is used
	// when this item is not set in the configuration/state.
	//
	// DefaultFunc can be specified if you want a dynamic default value.
	// Only one of Default or DefaultFunc can be set.
	//
	// If Required is true above, then Default cannot be set. DefaultFunc
	// can be set with Required. If the DefaultFunc returns nil, then there
	// will no default and the user will be asked to fill it in.
	//
	// If either of these is set, then the user won't be asked for input
	// for this key if the default is not nil.
	Default     interface{}
	DefaultFunc SchemaDefaultFunc

	// Description is used as the description for docs or asking for user
	// input. It should be relatively short (a few sentences max) and should
	// be formatted to fit a CLI.
	Description string

	// InputDefault is the default value to use for when inputs are requested.
	// This differs from Default in that if Default is set, no input is
	// asked for. If Input is asked, this will be the default value offered.
	InputDefault string

	// The fields below relate to diffs.
	//
	// If Computed is true, then the result of this value is computed
	// (unless specified by config) on creation.
	//
	// If ForceNew is true, then a change in this resource necessitates
	// the creation of a new resource.
	//
	// StateFunc is a function called to change the value of this before
	// storing it in the state (and likewise before comparing for diffs).
	// The use for this is for example with large strings, you may want
	// to simply store the hash of it.
	Computed  bool
	ForceNew  bool
	StateFunc SchemaStateFunc

	// The following fields are only set for a TypeList or TypeSet Type.
	//
	// Elem must be either a *Schema or a *Resource only if the Type is
	// TypeList, and represents what the element type is. If it is *Schema,
	// the element type is just a simple value. If it is *Resource, the
	// element type is a complex structure, potentially with its own lifecycle.
	Elem interface{}

	// The follow fields are only valid for a TypeSet type.
	//
	// Set defines a function to determine the unique ID of an item so that
	// a proper set can be built.
	Set SchemaSetFunc

	// ComputedWhen is a set of queries on the configuration. Whenever any
	// of these things is changed, it will require a recompute (this requires
	// that Computed is set to true).
	//
	// NOTE: This currently does not work.
	ComputedWhen []string
}

Schema is used to describe the structure of a value.

Read the documentation of the struct elements for important details.

func (*Schema) GoString 

func (s *Schema) GoString() string

type SchemaDefaultFunc added in v0.3.0 

type SchemaDefaultFunc func() (interface{}, error)

SchemaDefaultFunc is a function called to return a default value for a field.

type SchemaSetFunc 

type SchemaSetFunc func(interface{}) int

SchemaSetFunc is a function that must return a unique ID for the given element. This unique ID is used to store the element in a hash.

type SchemaStateFunc 

type SchemaStateFunc func(interface{}) string

SchemaStateFunc is a function used to convert some type to a string to be stored in the state.

type Set 

type Set struct {
	F SchemaSetFunc
	// contains filtered or unexported fields
}

Set is a set data structure that is returned for elements of type TypeSet.

func (*Set) Add 

func (s *Set) Add(item interface{})

Add adds an item to the set if it isn't already in the set.

func (*Set) Contains 

func (s *Set) Contains(item interface{}) bool

Contains checks if the set has the given item.

func (*Set) Difference 

func (s *Set) Difference(other *Set) *Set

Differences performs a set difference of the two sets, returning a new third set that has only the elements unique to this set.

func (*Set) Intersection 

func (s *Set) Intersection(other *Set) *Set

Intersection performs the set intersection of the two sets and returns a new third set.

func (*Set) Len 

func (s *Set) Len() int

Len returns the amount of items in the set.

func (*Set) List 

func (s *Set) List() []interface{}

List returns the elements of this set in slice format.

The order of the returned elements is deterministic. Given the same set, the order of this will always be the same.

func (*Set) Union 

func (s *Set) Union(other *Set) *Set

Union performs the set union of the two sets and returns a new third set.

type UpdateFunc 

type UpdateFunc func(*ResourceData, interface{}) error

See Resource documentation.

type ValueType 

type ValueType int

ValueType is an enum of the type that can be represented by a schema. 

const (
	TypeInvalid ValueType = iota
	TypeBool
	TypeInt
	TypeString
	TypeList
	TypeMap
	TypeSet
)

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.