tfsdk

package
v0.9.0 Latest Latest
Warning

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

 Go to latest Published: Jun 15, 2022 License: MPL-2.0 Imports: 11 Imported by: 193

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	// ErrPathInsideAtomicAttribute is used with AttributeAtPath is called
	// on a path that doesn't have a schema associated with it, because
	// it's an element, attribute, or block of a complex type, not a nested
	// attribute.
	ErrPathInsideAtomicAttribute = errors.New("path leads to element, attribute, or block of a schema.Attribute that has no schema associated with it")

	// ErrPathIsBlock is used with AttributeAtPath is called on a path is a
	// block, not an attribute. Use blockAtPath on the path instead.
	ErrPathIsBlock = errors.New("path leads to block, not an attribute")
)

Functions

func ConvertValue added in v0.4.0 

func ConvertValue(ctx context.Context, val attr.Value, typ attr.Type) (attr.Value, diag.Diagnostics)

ConvertValue creates a new attr.Value of the attr.Type `typ`, using the data in `val`, which can be of any attr.Type so long as its TerraformType method returns a tftypes.Type that `typ`'s ValueFromTerraform method can accept.

func ResourceImportStatePassthroughID added in v0.4.0 

func ResourceImportStatePassthroughID(ctx context.Context, path *tftypes.AttributePath, req ImportResourceStateRequest, resp *ImportResourceStateResponse)

ResourceImportStatePassthroughID is a helper function to set the import identifier to a given state attribute path. The attribute must accept a string value.

func ValueAs added in v0.3.0 

func ValueAs(ctx context.Context, val attr.Value, target interface{}) diag.Diagnostics

ValueAs takes the attr.Value `val` and populates the Go value `target` with its content.

This is achieved using reflection rules provided by the internal/reflect package.

func ValueFrom added in v0.9.0 

func ValueFrom(ctx context.Context, val interface{}, targetType attr.Type, target interface{}) diag.Diagnostics

ValueFrom takes the Go value `val` and populates `target` with an attr.Value, based on the type definition provided in `targetType`.

This is achieved using reflection rules provided by the internal/reflect package.

Types

type Attribute added in v0.3.0 

type Attribute struct {
	// Type indicates what kind of attribute this is. You'll most likely
	// want to use one of the types in the types package.
	//
	// If Type is set, Attributes cannot be.
	Type attr.Type

	// Attributes can have their own, nested attributes. This nested map of
	// attributes behaves exactly like the map of attributes on the Schema
	// type.
	//
	// If Attributes is set, Type cannot be.
	Attributes NestedAttributes

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this attribute is,
	// what it's for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this attribute is, what it's for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// Required indicates whether the practitioner must enter a value for
	// this attribute or not. Required and Optional cannot both be true,
	// and Required and Computed cannot both be true.
	Required bool

	// Optional indicates whether the practitioner can choose not to enter
	// a value for this attribute or not. Optional and Required cannot both
	// be true.
	//
	// When defining an attribute that has Optional set to true,
	// and uses PlanModifiers to set a "default value" when none is provided,
	// Computed must also be set to true. This is necessary because default
	// values are, in effect, set by the provider (i.e. computed).
	Optional bool

	// Computed indicates whether the provider may return its own value for
	// this Attribute or not. Required and Computed cannot both be true. If
	// Required and Optional are both false, Computed must be true, and the
	// attribute will be considered "read only" for the practitioner, with
	// only the provider able to set its value.
	//
	// When defining an Optional Attribute that has a "default value"
	// plan modifier, Computed must also be set to true. Otherwise,
	// Terraform will return an error like:
	//
	//      planned value ... for a non-computed attribute
	//
	Computed bool

	// Sensitive indicates whether the value of this attribute should be
	// considered sensitive data. Setting it to true will obscure the value
	// in CLI output. Sensitive does not impact how values are stored, and
	// practitioners are encouraged to store their state as if the entire
	// file is sensitive.
	Sensitive bool

	// DeprecationMessage defines a message to display to practitioners
	// using this attribute, warning them that it is deprecated and
	// instructing them on what upgrade steps to take.
	DeprecationMessage string

	// Validators defines validation functionality for the attribute.
	Validators []AttributeValidator

	// PlanModifiers defines a sequence of modifiers for this attribute at
	// plan time. Attribute-level plan modifications occur before any
	// resource-level plan modifications.
	//
	// Any errors will prevent further execution of this sequence
	// of modifiers and modifiers associated with any nested Attribute, but
	// will not prevent execution of PlanModifiers on any other Attribute or
	// Block in the Schema.
	//
	// Plan modification only applies to resources, not data sources or
	// providers. Setting PlanModifiers on a data source or provider attribute
	// will have no effect.
	//
	// When providing PlanModifiers, it's necessary to set Computed to true.
	PlanModifiers AttributePlanModifiers
}

Attribute defines the constraints and behaviors of a single value field in a schema. Attributes are the fields that show up in Terraform state files and can be used in configuration files.

func (Attribute) ApplyTerraform5AttributePathStep added in v0.3.0 

func (a Attribute) ApplyTerraform5AttributePathStep(step tftypes.AttributePathStep) (interface{}, error)

ApplyTerraform5AttributePathStep transparently calls ApplyTerraform5AttributePathStep on a.Type or a.Attributes, whichever is non-nil. It allows Attributes to be walked using tftypes.Walk and tftypes.Transform.

func (Attribute) Equal added in v0.3.0 

func (a Attribute) Equal(o Attribute) bool

Equal returns true if `a` and `o` should be considered Equal.

type AttributePlanModifier added in v0.3.0 

type AttributePlanModifier interface {
	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this modifier is,
	// what it's for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description(context.Context) string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this modifier is, what it's for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription(context.Context) string

	// Modify is called when the provider has an opportunity to modify
	// the plan: once during the plan phase when Terraform is determining
	// the diff that should be shown to the user for approval, and once
	// during the apply phase with any unknown values from configuration
	// filled in with their final values.
	//
	// The Modify function has access to the config, state, and plan for
	// both the attribute in question and the entire resource, but it can
	// only modify the value of the one attribute.
	//
	// Any returned errors will stop further execution of plan modifications
	// for this Attribute and any nested Attribute. Other Attribute at the same
	// or higher levels of the Schema will still execute any plan modifications
	// to ensure all warnings and errors across all root Attribute are
	// captured.
	//
	// Please see the documentation for ResourceWithModifyPlan#ModifyPlan
	// for further details.
	Modify(context.Context, ModifyAttributePlanRequest, *ModifyAttributePlanResponse)
}

AttributePlanModifier represents a modifier for an attribute at plan time. An AttributePlanModifier can only modify the planned value for the attribute on which it is defined. For plan-time modifications that modify the values of several attributes at once, please instead use the ResourceWithModifyPlan interface by defining a ModifyPlan function on the resource.

func RequiresReplace added in v0.3.0 

func RequiresReplace() AttributePlanModifier

RequiresReplace returns an AttributePlanModifier specifying the attribute as requiring replacement. This behaviour is identical to the ForceNew behaviour in terraform-plugin-sdk and will result in the resource being destroyed and recreated when the following conditions are met:

1. The resource's state is not null; a null state indicates that we're creating a resource, and we never need to destroy and recreate a resource when we're creating it.

2. The resource's plan is not null; a null plan indicates that we're deleting a resource, and we never need to destroy and recreate a resource when we're deleting it.

3. The attribute's config is not null or the attribute is not computed; a computed attribute with a null config almost always means that the provider is changing the value, and practitioners are usually unpleasantly surprised when a resource is destroyed and recreated when their configuration hasn't changed. This has the unfortunate side effect that removing a computed field from the config will not trigger a destroy and recreate cycle, even when that is warranted. To get around this, provider developer can implement their own AttributePlanModifier that handles that behavior in the way that most makes sense for their use case.

4. The attribute's value in the plan does not match the attribute's value in the state.

func RequiresReplaceIf added in v0.3.0 

func RequiresReplaceIf(f RequiresReplaceIfFunc, description, markdownDescription string) AttributePlanModifier

RequiresReplaceIf returns an AttributePlanModifier that mimics RequiresReplace, but only when the passed function `f` returns true. The resource will be destroyed and recreated if `f` returns true and the following conditions are met:

1. The resource's state is not null; a null state indicates that we're creating a resource, and we never need to destroy and recreate a resource when we're creating it.

2. The resource's plan is not null; a null plan indicates that we're deleting a resource, and we never need to destroy and recreate a resource when we're deleting it.

3. The attribute's config is not null or the attribute is not computed; a computed attribute with a null config almost always means that the provider is changing the value, and practitioners are usually unpleasantly surprised when a resource is destroyed and recreated when their configuration hasn't changed. This has the unfortunate side effect that removing a computed field from the config will not trigger a destroy and recreate cycle, even when that is warranted. To get around this, provider developer can implement their own AttributePlanModifier that handles that behavior in the way that most makes sense for their use case.

4. The attribute's value in the plan does not match the attribute's value in the state.

If `f` does not return true, RequiresReplaceIf will *not* override prior AttributePlanModifiers' determination of whether the resource needs to be recreated or not. This allows for multiple RequiresReplaceIf (or other modifiers that sometimes set RequiresReplace) to be used on a single attribute without the last one in the list always determining the outcome.

func UseStateForUnknown added in v0.5.0 

func UseStateForUnknown() AttributePlanModifier

UseStateForUnknown returns a UseStateForUnknownModifier.

type AttributePlanModifiers added in v0.3.0 

type AttributePlanModifiers []AttributePlanModifier

AttributePlanModifiers represents a sequence of AttributePlanModifiers, in order.

type AttributeValidator added in v0.3.0 

type AttributeValidator interface {
	// Description describes the validation in plain text formatting.
	//
	// This information may be automatically added to schema plain text
	// descriptions by external tooling.
	Description(context.Context) string

	// MarkdownDescription describes the validation in Markdown formatting.
	//
	// This information may be automatically added to schema Markdown
	// descriptions by external tooling.
	MarkdownDescription(context.Context) string

	// Validate performs the validation.
	Validate(context.Context, ValidateAttributeRequest, *ValidateAttributeResponse)
}

AttributeValidator describes reusable Attribute validation functionality.

type Block added in v0.5.0 

type Block struct {
	// Attributes are value fields inside the block. This map of attributes
	// behaves exactly like the map of attributes on the Schema type.
	Attributes map[string]Attribute

	// Blocks can have their own nested blocks. This nested map of blocks
	// behaves exactly like the map of blocks on the Schema type.
	Blocks map[string]Block

	// DeprecationMessage defines a message to display to practitioners
	// using this block, warning them that it is deprecated and
	// instructing them on what upgrade steps to take.
	DeprecationMessage string

	// Description is used in various tooling, like the language server, to
	// give practitioners more information about what this attribute is,
	// what it's for, and how it should be used. It should be written as
	// plain text, with no special formatting.
	Description string

	// MarkdownDescription is used in various tooling, like the
	// documentation generator, to give practitioners more information
	// about what this attribute is, what it's for, and how it should be
	// used. It should be formatted using Markdown.
	MarkdownDescription string

	// MaxItems is the maximum number of blocks that can be present in a
	// practitioner configuration.
	MaxItems int64

	// MinItems is the minimum number of blocks that must be present in a
	// practitioner configuration. Setting to 1 or above effectively marks
	// this configuration as required.
	MinItems int64

	// NestingMode indicates the block kind. This field must be set or a
	// runtime error will be raised by the framework when fetching the schema.
	NestingMode BlockNestingMode

	// PlanModifiers defines a sequence of modifiers for this block at
	// plan time. Block-level plan modifications occur before any
	// resource-level plan modifications.
	//
	// Any errors will prevent further execution of this sequence
	// of modifiers and modifiers associated with any nested Attribute or
	// Block, but will not prevent execution of PlanModifiers on any
	// other Attribute or Block in the Schema.
	//
	// Plan modification only applies to resources, not data sources or
	// providers. Setting PlanModifiers on a data source or provider attribute
	// will have no effect.
	PlanModifiers AttributePlanModifiers

	// Validators defines validation functionality for the block.
	Validators []AttributeValidator
}

Block defines the constraints and behaviors of a single structural field in a schema.

The NestingMode field must be set or a runtime error will be raised by the framework when fetching the schema.

func (Block) ApplyTerraform5AttributePathStep added in v0.5.0 

func (b Block) ApplyTerraform5AttributePathStep(step tftypes.AttributePathStep) (interface{}, error)

ApplyTerraform5AttributePathStep allows Blocks to be walked using tftypes.Walk and tftypes.Transform.

func (Block) Equal added in v0.5.0 

func (b Block) Equal(o Block) bool

Equal returns true if `b` and `o` should be considered Equal.

type BlockNestingMode added in v0.5.0 

type BlockNestingMode uint8

BlockNestingMode is an enum type of the ways attributes and blocks can be nested in a block. They can be a list or a set.

While the protocol and theoretically Terraform itself support map, single, and group nesting modes, this framework intentionally only supports list and set blocks as those other modes were not typically implemented or tested since the older Terraform Plugin SDK did not support them. 

const (
	// BlockNestingModeUnknown is an invalid nesting mode, used to catch when a
	// nesting mode is expected and not set.
	BlockNestingModeUnknown BlockNestingMode = 0

	// BlockNestingModeList is for attributes that represent a list of objects,
	// with multiple instances of those attributes nested inside a list
	// under another attribute.
	BlockNestingModeList BlockNestingMode = 1

	// BlockNestingModeSet is for attributes that represent a set of objects,
	// with multiple, unique instances of those attributes nested inside a
	// set under another attribute.
	BlockNestingModeSet BlockNestingMode = 2
)

type Config 

type Config struct {
	Raw    tftypes.Value
	Schema Schema
}

Config represents a Terraform config.

func (Config) Get 

func (c Config) Get(ctx context.Context, target interface{}) diag.Diagnostics

Get populates the struct passed as `target` with the entire config.

func (Config) GetAttribute 

func (c Config) GetAttribute(ctx context.Context, path *tftypes.AttributePath, target interface{}) diag.Diagnostics

GetAttribute retrieves the attribute found at `path` and populates the `target` with the value.

type ConfigureProviderRequest 

type ConfigureProviderRequest struct {
	// TerraformVersion is the version of Terraform executing the request.
	// This is supplied for logging, analytics, and User-Agent purposes
	// only. Providers should not try to gate provider behavior on
	// Terraform versions.
	TerraformVersion string

	// Config is the configuration the user supplied for the provider. This
	// information should usually be persisted to the underlying type
	// that's implementing the Provider interface, for use in later
	// resource CRUD operations.
	Config Config
}

ConfigureProviderRequest represents a request containing the values the user specified for the provider configuration block, along with other runtime information from Terraform or the Plugin SDK. An instance of this request struct is supplied as an argument to the provider's Configure function.

type ConfigureProviderResponse 

type ConfigureProviderResponse struct {
	// Diagnostics report errors or warnings related to configuring the
	// provider. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

ConfigureProviderResponse represents a response to a ConfigureProviderRequest. An instance of this response struct is supplied as an argument to the provider's Configure function, in which the provider should set values on the ConfigureProviderResponse as appropriate.

type CreateResourceRequest 

type CreateResourceRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config Config

	// Plan is the planned state for the resource.
	Plan Plan

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta Config
}

CreateResourceRequest represents a request for the provider to create a resource. An instance of this request struct is supplied as an argument to the resource's Create function.

type CreateResourceResponse 

type CreateResourceResponse struct {
	// State is the state of the resource following the Create operation.
	// This field is pre-populated from CreateResourceRequest.Plan and
	// should be set during the resource's Create operation.
	State State

	// Diagnostics report errors or warnings related to creating the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

CreateResourceResponse represents a response to a CreateResourceRequest. An instance of this response struct is supplied as an argument to the resource's Create function, in which the provider should set values on the CreateResourceResponse as appropriate.

type DataSource 

type DataSource interface {
	// Read is called when the provider must read data source values in
	// order to update state. Config values should be read from the
	// ReadDataSourceRequest and new state values set on the
	// ReadDataSourceResponse.
	Read(context.Context, ReadDataSourceRequest, *ReadDataSourceResponse)
}

DataSource represents a data source instance. This is the core interface that all data sources must implement.

type DataSourceConfigValidator added in v0.3.0 

type DataSourceConfigValidator interface {
	// Description describes the validation in plain text formatting.
	//
	// This information may be automatically added to data source plain text
	// descriptions by external tooling.
	Description(context.Context) string

	// MarkdownDescription describes the validation in Markdown formatting.
	//
	// This information may be automatically added to data source Markdown
	// descriptions by external tooling.
	MarkdownDescription(context.Context) string

	// Validate performs the validation.
	Validate(context.Context, ValidateDataSourceConfigRequest, *ValidateDataSourceConfigResponse)
}

DataSourceConfigValidator describes reusable data source configuration validation functionality.

type DataSourceType 

type DataSourceType interface {
	// GetSchema returns the schema for this data source.
	GetSchema(context.Context) (Schema, diag.Diagnostics)

	// NewDataSource instantiates a new DataSource of this DataSourceType.
	NewDataSource(context.Context, Provider) (DataSource, diag.Diagnostics)
}

A DataSourceType is a type of data source. For each type of data source this provider supports, it should define a type implementing DataSourceType and return an instance of it in the map returned by Provider.GetDataSources.

type DataSourceWithConfigValidators added in v0.3.0 

type DataSourceWithConfigValidators interface {
	DataSource

	// ConfigValidators returns a list of DataSourceConfigValidators. Each DataSourceConfigValidator's Validate method will be called when validating the data source.
	ConfigValidators(context.Context) []DataSourceConfigValidator
}

DataSourceWithConfigValidators is an interface type that extends DataSource to include declarative validations.

Declaring validation using this methodology simplifies implmentation of reusable functionality. These also include descriptions, which can be used for automating documentation.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type DataSourceWithValidateConfig added in v0.3.0 

type DataSourceWithValidateConfig interface {
	DataSource

	// ValidateConfig performs the validation.
	ValidateConfig(context.Context, ValidateDataSourceConfigRequest, *ValidateDataSourceConfigResponse)
}

DataSourceWithValidateConfig is an interface type that extends DataSource to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single data source. Any documentation of this functionality must be manually added into schema descriptions.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type DeleteResourceRequest 

type DeleteResourceRequest struct {
	// State is the current state of the resource prior to the Delete
	// operation.
	State State

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta Config
}

DeleteResourceRequest represents a request for the provider to delete a resource. An instance of this request struct is supplied as an argument to the resource's Delete function.

type DeleteResourceResponse 

type DeleteResourceResponse struct {
	// State is the state of the resource following the Delete operation.
	// This field is pre-populated from UpdateResourceRequest.Plan and
	// should be set during the resource's Update operation.
	State State

	// Diagnostics report errors or warnings related to deleting the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

DeleteResourceResponse represents a response to a DeleteResourceRequest. An instance of this response struct is supplied as an argument to the resource's Delete function, in which the provider should set values on the DeleteResourceResponse as appropriate.

type ImportResourceStateRequest added in v0.4.0 

type ImportResourceStateRequest struct {
	// ID represents the import identifier supplied by the practitioner when
	// calling the import command. In many cases, this may align with the
	// unique identifier for the resource, which can optionally be stored
	// as an Attribute. However, this identifier can also be treated as
	// its own type of value and parsed during import. This value
	// is not stored in the state unless the provider explicitly stores it.
	ID string
}

ImportResourceStateRequest represents a request for the provider to import a resource. An instance of this request struct is supplied as an argument to the Resource's ImportState method.

type ImportResourceStateResponse added in v0.4.0 

type ImportResourceStateResponse struct {
	// Diagnostics report errors or warnings related to importing the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics

	// State is the state of the resource following the import operation.
	// It must contain enough information so Terraform can successfully
	// refresh the resource, e.g. call the Resource Read method.
	State State
}

ImportResourceStateResponse represents a response to a ImportResourceStateRequest. An instance of this response struct is supplied as an argument to the Resource's ImportState method, in which the provider should set values on the ImportResourceStateResponse as appropriate.

type ModifyAttributePlanRequest added in v0.3.0 

type ModifyAttributePlanRequest struct {
	// AttributePath is the path of the attribute.
	AttributePath *tftypes.AttributePath

	// Config is the configuration the user supplied for the resource.
	Config Config

	// State is the current state of the resource.
	State State

	// Plan is the planned new state for the resource.
	Plan Plan

	// AttributeConfig is the configuration the user supplied for the attribute.
	AttributeConfig attr.Value

	// AttributeState is the current state of the attribute.
	AttributeState attr.Value

	// AttributePlan is the planned new state for the attribute.
	AttributePlan attr.Value

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta Config
}

ModifyAttributePlanRequest represents a request for the provider to modify an attribute value, or mark it as requiring replacement, at plan time. An instance of this request struct is supplied as an argument to the Modify function of an attribute's plan modifier(s).

type ModifyAttributePlanResponse added in v0.3.0 

type ModifyAttributePlanResponse struct {
	// AttributePlan is the planned new state for the attribute.
	AttributePlan attr.Value

	// RequiresReplace indicates whether a change in the attribute
	// requires replacement of the whole resource.
	RequiresReplace bool

	// Diagnostics report errors or warnings related to determining the
	// planned state of the requested resource. Returning an empty slice
	// indicates a successful validation with no warnings or errors
	// generated.
	Diagnostics diag.Diagnostics
}

ModifyAttributePlanResponse represents a response to a ModifyAttributePlanRequest. An instance of this response struct is supplied as an argument to the Modify function of an attribute's plan modifier(s).

type ModifyResourcePlanRequest added in v0.3.0 

type ModifyResourcePlanRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config Config

	// State is the current state of the resource.
	State State

	// Plan is the planned new state for the resource.
	Plan Plan

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta Config
}

ModifyResourcePlanRequest represents a request for the provider to modify the planned new state that Terraform has generated for the resource.

type ModifyResourcePlanResponse added in v0.3.0 

type ModifyResourcePlanResponse struct {
	// Plan is the planned new state for the resource.
	Plan Plan

	// RequiresReplace is a list of tftypes.AttributePaths that require the
	// resource to be replaced. They should point to the specific field
	// that changed that requires the resource to be destroyed and
	// recreated.
	RequiresReplace []*tftypes.AttributePath

	// Diagnostics report errors or warnings related to determining the
	// planned state of the requested resource. Returning an empty slice
	// indicates a successful plan modification with no warnings or errors
	// generated.
	Diagnostics diag.Diagnostics
}

ModifyResourcePlanResponse represents a response to a ModifyResourcePlanRequest. An instance of this response struct is supplied as an argument to the resource's ModifyPlan function, in which the provider should modify the Plan and populate the RequiresReplace field as appropriate.

type NestedAttributes added in v0.3.0 

type NestedAttributes interface {
	tftypes.AttributePathStepper
	AttributeType() attr.Type
	GetNestingMode() NestingMode
	GetAttributes() map[string]Attribute
	Equal(NestedAttributes) bool
	// contains filtered or unexported methods
}

NestedAttributes surfaces a group of attributes to nest beneath another attribute, and how that nesting should behave. Nesting can have the following modes:

* SingleNestedAttributes are nested attributes that represent a struct or object; there should only be one instance of them nested beneath that specific attribute.

* ListNestedAttributes are nested attributes that represent a list of structs or objects; there can be multiple instances of them beneath that specific attribute.

* SetNestedAttributes are nested attributes that represent a set of structs or objects; there can be multiple instances of them beneath that specific attribute. Unlike ListNestedAttributes, these nested attributes must have unique values.

* MapNestedAttributes are nested attributes that represent a string-indexed map of structs or objects; there can be multiple instances of them beneath that specific attribute. Unlike ListNestedAttributes, these nested attributes must be associated with a unique key. Unlike SetNestedAttributes, the key must be explicitly set by the user.

func ListNestedAttributes added in v0.3.0 

func ListNestedAttributes(attributes map[string]Attribute) NestedAttributes

ListNestedAttributes nests `attributes` under another attribute, allowing multiple instances of that group of attributes to appear in the configuration.

func MapNestedAttributes added in v0.3.0 

func MapNestedAttributes(attributes map[string]Attribute) NestedAttributes

MapNestedAttributes nests `attributes` under another attribute, allowing multiple instances of that group of attributes to appear in the configuration. Each group will need to be associated with a unique string by the user.

func SetNestedAttributes added in v0.3.0 

func SetNestedAttributes(attributes map[string]Attribute) NestedAttributes

SetNestedAttributes nests `attributes` under another attribute, allowing multiple instances of that group of attributes to appear in the configuration, while requiring each group of values be unique.

func SingleNestedAttributes added in v0.3.0 

func SingleNestedAttributes(attributes map[string]Attribute) NestedAttributes

SingleNestedAttributes nests `attributes` under another attribute, only allowing one instance of that group of attributes to appear in the configuration.

type NestingMode added in v0.3.0 

type NestingMode uint8

NestingMode is an enum type of the ways nested attributes can be nested in an attribute. They can be a list, a set, a map (with string keys), or they can be nested directly, like an object. 

const (
	// NestingModeUnknown is an invalid nesting mode, used to catch when a
	// nesting mode is expected and not set.
	NestingModeUnknown NestingMode = 0

	// NestingModeSingle is for attributes that represent a struct or
	// object, a single instance of those attributes directly nested under
	// another attribute.
	NestingModeSingle NestingMode = 1

	// NestingModeList is for attributes that represent a list of objects,
	// with multiple instances of those attributes nested inside a list
	// under another attribute.
	NestingModeList NestingMode = 2

	// NestingModeSet is for attributes that represent a set of objects,
	// with multiple, unique instances of those attributes nested inside a
	// set under another attribute.
	NestingModeSet NestingMode = 3

	// NestingModeMap is for attributes that represent a map of objects,
	// with multiple instances of those attributes, each associated with a
	// unique string key, nested inside a map under another attribute.
	NestingModeMap NestingMode = 4
)

type Plan 

type Plan struct {
	Raw    tftypes.Value
	Schema Schema
}

Plan represents a Terraform plan.

func (Plan) Get 

func (p Plan) Get(ctx context.Context, target interface{}) diag.Diagnostics

Get populates the struct passed as `target` with the entire plan.

func (Plan) GetAttribute 

func (p Plan) GetAttribute(ctx context.Context, path *tftypes.AttributePath, target interface{}) diag.Diagnostics

GetAttribute retrieves the attribute found at `path` and populates the `target` with the value.

func (*Plan) Set 

func (p *Plan) Set(ctx context.Context, val interface{}) diag.Diagnostics

Set populates the entire plan using the supplied Go value. The value `val` should be a struct whose values have one of the attr.Value types. Each field must be tagged with the corresponding schema field.

func (*Plan) SetAttribute 

func (p *Plan) SetAttribute(ctx context.Context, path *tftypes.AttributePath, val interface{}) diag.Diagnostics

SetAttribute sets the attribute at `path` using the supplied Go value.

The attribute path and value must be valid with the current schema. If the attribute path already has a value, it will be overwritten. If the attribute path does not have a value, it will be added, including any parent attribute paths as necessary.

Lists can only have the next element added according to the current length.

type Provider 

type Provider interface {
	// GetSchema returns the schema for this provider's configuration. If
	// this provider has no configuration, return an empty schema.Schema.
	GetSchema(context.Context) (Schema, diag.Diagnostics)

	// Configure is called at the beginning of the provider lifecycle, when
	// Terraform sends to the provider the values the user specified in the
	// provider configuration block. These are supplied in the
	// ConfigureProviderRequest argument.
	// Values from provider configuration are often used to initialise an
	// API client, which should be stored on the struct implementing the
	// Provider interface.
	Configure(context.Context, ConfigureProviderRequest, *ConfigureProviderResponse)

	// GetResources returns a mapping of resource names to type
	// implementations.
	//
	// Conventionally, resource names should each include a prefix of the
	// provider name and an underscore. For example, a provider named
	// "examplecloud" with resources "thing" and "widget" should use
	// "examplecloud_thing" and "examplecloud_widget" as resource names.
	GetResources(context.Context) (map[string]ResourceType, diag.Diagnostics)

	// GetDataSources returns a mapping of data source name to types
	// implementations.
	//
	// Conventionally, data source names should each include a prefix of the
	// provider name and an underscore. For example, a provider named
	// "examplecloud" with data sources "thing" and "widget" should use
	// "examplecloud_thing" and "examplecloud_widget" as data source names.
	GetDataSources(context.Context) (map[string]DataSourceType, diag.Diagnostics)
}

Provider is the core interface that all Terraform providers must implement.

type ProviderConfigValidator added in v0.3.0 

type ProviderConfigValidator interface {
	// Description describes the validation in plain text formatting.
	//
	// This information may be automatically added to provider plain text
	// descriptions by external tooling.
	Description(context.Context) string

	// MarkdownDescription describes the validation in Markdown formatting.
	//
	// This information may be automatically added to provider Markdown
	// descriptions by external tooling.
	MarkdownDescription(context.Context) string

	// Validate performs the validation.
	Validate(context.Context, ValidateProviderConfigRequest, *ValidateProviderConfigResponse)
}

ProviderConfigValidator describes reusable Provider configuration validation functionality.

type ProviderWithConfigValidators added in v0.3.0 

type ProviderWithConfigValidators interface {
	Provider

	// ConfigValidators returns a list of functions which will all be performed during validation.
	ConfigValidators(context.Context) []ProviderConfigValidator
}

ProviderWithConfigValidators is an interface type that extends Provider to include declarative validations.

Declaring validation using this methodology simplifies implementation of reusable functionality. These also include descriptions, which can be used for automating documentation.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type ProviderWithProviderMeta 

type ProviderWithProviderMeta interface {
	Provider
	// GetMetaSchema returns the provider meta schema.
	GetMetaSchema(context.Context) (Schema, diag.Diagnostics)
}

ProviderWithProviderMeta is a provider with a provider meta schema. This functionality is currently experimental and subject to change or break without warning; it should only be used by providers that are collaborating on its use with the Terraform team.

type ProviderWithValidateConfig added in v0.3.0 

type ProviderWithValidateConfig interface {
	Provider

	// ValidateConfig performs the validation.
	ValidateConfig(context.Context, ValidateProviderConfigRequest, *ValidateProviderConfigResponse)
}

ProviderWithValidateConfig is an interface type that extends Provider to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single provider. Any documentation of this functionality must be manually added into schema descriptions.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type ReadDataSourceRequest 

type ReadDataSourceRequest struct {
	// Config is the configuration the user supplied for the data source.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config Config

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta Config
}

ReadDataSourceRequest represents a request for the provider to read a data source, i.e., update values in state according to the real state of the data source. An instance of this request struct is supplied as an argument to the data source's Read function.

type ReadDataSourceResponse 

type ReadDataSourceResponse struct {
	// State is the state of the data source following the Read operation.
	// This field should be set during the resource's Read operation.
	State State

	// Diagnostics report errors or warnings related to reading the data
	// source. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

ReadDataSourceResponse represents a response to a ReadDataSourceRequest. An instance of this response struct is supplied as an argument to the data source's Read function, in which the provider should set values on the ReadDataSourceResponse as appropriate.

type ReadResourceRequest 

type ReadResourceRequest struct {
	// State is the current state of the resource prior to the Read
	// operation.
	State State

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta Config
}

ReadResourceRequest represents a request for the provider to read a resource, i.e., update values in state according to the real state of the resource. An instance of this request struct is supplied as an argument to the resource's Read function.

type ReadResourceResponse 

type ReadResourceResponse struct {
	// State is the state of the resource following the Read operation.
	// This field is pre-populated from ReadResourceRequest.State and
	// should be set during the resource's Read operation.
	State State

	// Diagnostics report errors or warnings related to reading the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

ReadResourceResponse represents a response to a ReadResourceRequest. An instance of this response struct is supplied as an argument to the resource's Read function, in which the provider should set values on the ReadResourceResponse as appropriate.

type RequiresReplaceIfFunc added in v0.3.0 

type RequiresReplaceIfFunc func(ctx context.Context, state, config attr.Value, path *tftypes.AttributePath) (bool, diag.Diagnostics)

RequiresReplaceIfFunc is a conditional function used in the RequiresReplaceIf plan modifier to determine whether the attribute requires replacement.

type RequiresReplaceIfModifier added in v0.3.0 

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

RequiresReplaceIfModifier is an AttributePlanModifier that sets RequiresReplace on the attribute if the conditional function returns true.

func (RequiresReplaceIfModifier) Description added in v0.3.0 

func (r RequiresReplaceIfModifier) Description(ctx context.Context) string

Description returns a human-readable description of the plan modifier.

func (RequiresReplaceIfModifier) MarkdownDescription added in v0.3.0 

func (r RequiresReplaceIfModifier) MarkdownDescription(ctx context.Context) string

MarkdownDescription returns a markdown description of the plan modifier.

func (RequiresReplaceIfModifier) Modify added in v0.3.0 

func (r RequiresReplaceIfModifier) Modify(ctx context.Context, req ModifyAttributePlanRequest, resp *ModifyAttributePlanResponse)

Modify fills the AttributePlanModifier interface. It sets RequiresReplace on the response to true if the following criteria are met:

1. `f` returns true. If `f` returns false, the response will not be modified at all.

2. The resource's state is not null; a null state indicates that we're creating a resource, and we never need to destroy and recreate a resource when we're creating it.

3. The resource's plan is not null; a null plan indicates that we're deleting a resource, and we never need to destroy and recreate a resource when we're deleting it.

4. The attribute's config is not null or the attribute is not computed; a computed attribute with a null config almost always means that the provider is changing the value, and practitioners are usually unpleasantly surprised when a resource is destroyed and recreated when their configuration hasn't changed. This has the unfortunate side effect that removing a computed field from the config will not trigger a destroy and recreate cycle, even when that is warranted. To get around this, provider developer can implement their own AttributePlanModifier that handles that behavior in the way that most makes sense for their use case.

5. The attribute's value in the plan does not match the attribute's value in the state.

type RequiresReplaceModifier added in v0.3.0 

type RequiresReplaceModifier struct{}

RequiresReplaceModifier is an AttributePlanModifier that sets RequiresReplace on the attribute.

func (RequiresReplaceModifier) Description added in v0.3.0 

func (r RequiresReplaceModifier) Description(ctx context.Context) string

Description returns a human-readable description of the plan modifier.

func (RequiresReplaceModifier) MarkdownDescription added in v0.3.0 

func (r RequiresReplaceModifier) MarkdownDescription(ctx context.Context) string

MarkdownDescription returns a markdown description of the plan modifier.

func (RequiresReplaceModifier) Modify added in v0.3.0 

func (r RequiresReplaceModifier) Modify(ctx context.Context, req ModifyAttributePlanRequest, resp *ModifyAttributePlanResponse)

Modify fills the AttributePlanModifier interface. It sets RequiresReplace on the response to true if the following criteria are met:

1. The resource's state is not null; a null state indicates that we're creating a resource, and we never need to destroy and recreate a resource when we're creating it.

2. The resource's plan is not null; a null plan indicates that we're deleting a resource, and we never need to destroy and recreate a resource when we're deleting it.

3. The attribute's config is not null or the attribute is not computed; a computed attribute with a null config almost always means that the provider is changing the value, and practitioners are usually unpleasantly surprised when a resource is destroyed and recreated when their configuration hasn't changed. This has the unfortunate side effect that removing a computed field from the config will not trigger a destroy and recreate cycle, even when that is warranted. To get around this, provider developer can implement their own AttributePlanModifier that handles that behavior in the way that most makes sense for their use case.

4. The attribute's value in the plan does not match the attribute's value in the state.

type Resource 

type Resource interface {
	// Create is called when the provider must create a new resource. Config
	// and planned state values should be read from the
	// CreateResourceRequest and new state values set on the
	// CreateResourceResponse.
	Create(context.Context, CreateResourceRequest, *CreateResourceResponse)

	// Read is called when the provider must read resource values in order
	// to update state. Planned state values should be read from the
	// ReadResourceRequest and new state values set on the
	// ReadResourceResponse.
	Read(context.Context, ReadResourceRequest, *ReadResourceResponse)

	// Update is called to update the state of the resource. Config, planned
	// state, and prior state values should be read from the
	// UpdateResourceRequest and new state values set on the
	// UpdateResourceResponse.
	Update(context.Context, UpdateResourceRequest, *UpdateResourceResponse)

	// Delete is called when the provider must delete the resource. Config
	// values may be read from the DeleteResourceRequest.
	//
	// If execution completes without error, the framework will automatically
	// call DeleteResourceResponse.State.RemoveResource(), so it can be omitted
	// from provider logic.
	Delete(context.Context, DeleteResourceRequest, *DeleteResourceResponse)
}

Resource represents a resource instance. This is the core interface that all resources must implement.

It is also conventional for resources to implement the ResourceWithImportState interface, which enables practitioners to import existing infrastructure into Terraform.

type ResourceConfigValidator added in v0.3.0 

type ResourceConfigValidator interface {
	// Description describes the validation in plain text formatting.
	//
	// This information may be automatically added to resource plain text
	// descriptions by external tooling.
	Description(context.Context) string

	// MarkdownDescription describes the validation in Markdown formatting.
	//
	// This information may be automatically added to resource Markdown
	// descriptions by external tooling.
	MarkdownDescription(context.Context) string

	// Validate performs the validation.
	Validate(context.Context, ValidateResourceConfigRequest, *ValidateResourceConfigResponse)
}

ResourceConfigValidator describes reusable Resource configuration validation functionality.

type ResourceStateUpgrader added in v0.7.0 

type ResourceStateUpgrader struct {
	// Schema information for the prior state version. While not required,
	// setting this will populate the UpgradeResourceStateRequest type State
	// field similar to other Resource data types. This allows for easier data
	// handling such as calling Get() or GetAttribute().
	//
	// If not set, prior state data is available in the
	// UpgradeResourceStateRequest type RawState field.
	PriorSchema *Schema

	// Provider defined logic for upgrading a resource state from the prior
	// state version to the current schema version.
	//
	// The context.Context parameter contains framework-defined loggers and
	// supports request cancellation.
	//
	// The UpgradeResourceStateRequest parameter contains the prior state data.
	// If PriorSchema was set, the State field will be available. Otherwise,
	// the RawState must be used.
	//
	// The UpgradeResourceStateResponse parameter should contain the upgraded
	// state data and can be used to signal any logic warnings or errors.
	StateUpgrader func(context.Context, UpgradeResourceStateRequest, *UpgradeResourceStateResponse)
}

Implementation handler for a UpgradeResourceState operation.

This is used to encapsulate all upgrade logic from a prior state to the current schema version when a Resource implements the ResourceWithUpgradeState interface.

type ResourceType 

type ResourceType interface {
	// GetSchema returns the schema for this resource.
	GetSchema(context.Context) (Schema, diag.Diagnostics)

	// NewResource instantiates a new Resource of this ResourceType.
	NewResource(context.Context, Provider) (Resource, diag.Diagnostics)
}

A ResourceType is a type of resource. For each type of resource this provider supports, it should define a type implementing ResourceType and return an instance of it in the map returned by Provider.GetResources.

type ResourceWithConfigValidators added in v0.3.0 

type ResourceWithConfigValidators interface {
	Resource

	// ConfigValidators returns a list of functions which will all be performed during validation.
	ConfigValidators(context.Context) []ResourceConfigValidator
}

ResourceWithConfigValidators is an interface type that extends Resource to include declarative validations.

Declaring validation using this methodology simplifies implmentation of reusable functionality. These also include descriptions, which can be used for automating documentation.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type ResourceWithImportState added in v0.7.0 

type ResourceWithImportState interface {
	// ImportState is called when the provider must import the state of a
	// resource instance. This method must return enough state so the Read
	// method can properly refresh the full resource.
	//
	// If setting an attribute with the import identifier, it is recommended
	// to use the ResourceImportStatePassthroughID() call in this method.
	ImportState(context.Context, ImportResourceStateRequest, *ImportResourceStateResponse)
}

Optional interface on top of Resource that enables provider control over the ImportResourceState RPC. This RPC is called by Terraform when the `terraform import` command is executed. Afterwards, the ReadResource RPC is executed to allow providers to fully populate the resource state.

type ResourceWithModifyPlan added in v0.3.0 

type ResourceWithModifyPlan interface {
	Resource

	// ModifyPlan is called when the provider has an opportunity to modify
	// the plan: once during the plan phase when Terraform is determining
	// the diff that should be shown to the user for approval, and once
	// during the apply phase with any unknown values from configuration
	// filled in with their final values.
	//
	// The planned new state is represented by
	// ModifyResourcePlanResponse.Plan. It must meet the following
	// constraints:
	// 1. Any non-Computed attribute set in config must preserve the exact
	// config value or return the corresponding attribute value from the
	// prior state (ModifyResourcePlanRequest.State).
	// 2. Any attribute with a known value must not have its value changed
	// in subsequent calls to ModifyPlan or Create/Read/Update.
	// 3. Any attribute with an unknown value may either remain unknown
	// or take on any value of the expected type.
	//
	// Any errors will prevent further resource-level plan modifications.
	ModifyPlan(context.Context, ModifyResourcePlanRequest, *ModifyResourcePlanResponse)
}

ResourceWithModifyPlan represents a resource instance with a ModifyPlan function.

type ResourceWithUpgradeState added in v0.7.0 

type ResourceWithUpgradeState interface {
	// A mapping of prior state version to current schema version state upgrade
	// implementations. Only the specified state upgrader for the prior state
	// version is called, rather than each version in between, so it must
	// encapsulate all logic to convert the prior state to the current schema
	// version.
	//
	// Version keys begin at 0, which is the default schema version when
	// undefined. The framework will return an error diagnostic should the
	// requested state version not be implemented.
	UpgradeState(context.Context) map[int64]ResourceStateUpgrader
}

Optional interface on top of Resource that enables provider control over the UpgradeResourceState RPC. This RPC is automatically called by Terraform when the current Schema type Version field is greater than the stored state. Terraform does not store previous Schema information, so any breaking changes to state data types must be handled by providers.

Terraform CLI can execute the UpgradeResourceState RPC even when the prior state version matches the current schema version. The framework will automatically intercept this request and attempt to respond with the existing state. In this situation the framework will not execute any provider defined logic, so declaring it for this version is extraneous.

type ResourceWithValidateConfig added in v0.3.0 

type ResourceWithValidateConfig interface {
	Resource

	// ValidateConfig performs the validation.
	ValidateConfig(context.Context, ValidateResourceConfigRequest, *ValidateResourceConfigResponse)
}

ResourceWithValidateConfig is an interface type that extends Resource to include imperative validation.

Declaring validation using this methodology simplifies one-off functionality that typically applies to a single resource. Any documentation of this functionality must be manually added into schema descriptions.

Validation will include ConfigValidators and ValidateConfig, if both are implemented, in addition to any Attribute or Type validation.

type Schema added in v0.3.0 

type Schema struct {
	// Attributes are value fields inside the resource, provider, or data
	// source that the schema is defining. The map key should be the name
	// of the attribute, and the body defines how it behaves. Names must
	// only contain lowercase letters, numbers, and underscores. Names must
	// not collide with any Blocks names.
	//
	// In practitioner configurations, an equals sign (=) is required to set
	// the value. See also:
	//   https://www.terraform.io/docs/language/syntax/configuration.html
	//
	// Attributes are strongly preferred over Blocks.
	Attributes map[string]Attribute

	// Blocks are structural fields inside the resource, provider, or data
	// source that the schema is defining. The map key should be the name
	// of the block, and the body defines how it behaves. Names must
	// only contain lowercase letters, numbers, and underscores. Names must
	// not collide with any Attributes names.
	//
	// Blocks are by definition, structural, meaning they are implicitly
	// required in values.
	//
	// In practitioner configurations, an equals sign (=) cannot be used to
	// set the value. Blocks are instead repeated as necessary, or require
	// the use of dynamic block expressions. See also:
	//   https://www.terraform.io/docs/language/syntax/configuration.html
	//   https://www.terraform.io/docs/language/expressions/dynamic-blocks.html
	//
	// Attributes are preferred over Blocks. Blocks should typically be used
	// for configuration compatibility with previously existing schemas from
	// an older Terraform Plugin SDK. Efforts should be made to convert from
	// Blocks to Attributes as a breaking change for practitioners.
	Blocks map[string]Block

	// Version indicates the current version of the schema. Schemas are
	// versioned to help with automatic upgrade process. This is not
	// typically required unless there is a change in the schema, such as
	// changing an attribute type, that needs manual upgrade handling.
	// Versions should only be incremented by one each release.
	Version int64

	DeprecationMessage  string
	Description         string
	MarkdownDescription string
}

Schema is used to define the shape of practitioner-provider information, like resources, data sources, and providers. Think of it as a type definition, but for Terraform.

func (Schema) ApplyTerraform5AttributePathStep added in v0.3.0 

func (s Schema) ApplyTerraform5AttributePathStep(step tftypes.AttributePathStep) (interface{}, error)

ApplyTerraform5AttributePathStep applies the given AttributePathStep to the schema.

func (Schema) AttributeAtPath added in v0.3.0 

func (s Schema) AttributeAtPath(path *tftypes.AttributePath) (Attribute, error)

AttributeAtPath returns the Attribute at the passed path. If the path points to an element or attribute of a complex type, rather than to an Attribute, it will return an ErrPathInsideAtomicAttribute error.

func (Schema) AttributeType added in v0.3.0 

func (s Schema) AttributeType() attr.Type

AttributeType returns a types.ObjectType composed from the schema types.

func (Schema) AttributeTypeAtPath added in v0.3.0 

func (s Schema) AttributeTypeAtPath(path *tftypes.AttributePath) (attr.Type, error)

AttributeTypeAtPath returns the attr.Type of the attribute at the given path.

func (Schema) TerraformType added in v0.3.0 

func (s Schema) TerraformType(ctx context.Context) tftypes.Type

TerraformType returns a tftypes.Type that can represent the schema.

type State 

type State struct {
	Raw    tftypes.Value
	Schema Schema
}

State represents a Terraform state.

func (State) Get 

func (s State) Get(ctx context.Context, target interface{}) diag.Diagnostics

Get populates the struct passed as `target` with the entire state.

func (State) GetAttribute 

func (s State) GetAttribute(ctx context.Context, path *tftypes.AttributePath, target interface{}) diag.Diagnostics

GetAttribute retrieves the attribute found at `path` and populates the `target` with the value.

func (*State) RemoveResource 

func (s *State) RemoveResource(ctx context.Context)

RemoveResource removes the entire resource from state.

If a Resource type Delete method is completed without error, this is automatically called on the DeleteResourceResponse.State.

func (*State) Set 

func (s *State) Set(ctx context.Context, val interface{}) diag.Diagnostics

Set populates the entire state using the supplied Go value. The value `val` should be a struct whose values have one of the attr.Value types. Each field must be tagged with the corresponding schema field.

func (*State) SetAttribute 

func (s *State) SetAttribute(ctx context.Context, path *tftypes.AttributePath, val interface{}) diag.Diagnostics

SetAttribute sets the attribute at `path` using the supplied Go value.

The attribute path and value must be valid with the current schema. If the attribute path already has a value, it will be overwritten. If the attribute path does not have a value, it will be added, including any parent attribute paths as necessary.

Lists can only have the next element added according to the current length.

type UpdateResourceRequest 

type UpdateResourceRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config Config

	// Plan is the planned state for the resource.
	Plan Plan

	// State is the current state of the resource prior to the Update
	// operation.
	State State

	// ProviderMeta is metadata from the provider_meta block of the module.
	ProviderMeta Config
}

UpdateResourceRequest represents a request for the provider to update a resource. An instance of this request struct is supplied as an argument to the resource's Update function.

type UpdateResourceResponse 

type UpdateResourceResponse struct {
	// State is the state of the resource following the Update operation.
	// This field is pre-populated from UpdateResourceRequest.Plan and
	// should be set during the resource's Update operation.
	State State

	// Diagnostics report errors or warnings related to updating the
	// resource. An empty slice indicates a successful operation with no
	// warnings or errors generated.
	Diagnostics diag.Diagnostics
}

UpdateResourceResponse represents a response to an UpdateResourceRequest. An instance of this response struct is supplied as an argument to the resource's Update function, in which the provider should set values on the UpdateResourceResponse as appropriate.

type UpgradeResourceStateRequest added in v0.7.0 

type UpgradeResourceStateRequest struct {
	// Previous state of the resource in JSON (Terraform CLI 0.12 and later)
	// or flatmap format, depending on which version of Terraform CLI last
	// wrote the resource state. This data is always available, regardless
	// whether the wrapping ResourceStateUpgrader type PriorSchema field was
	// present.
	//
	// This is advanced functionality for providers wanting to skip the full
	// redeclaration of older schemas and instead use lower level handlers to
	// transform data. A typical implementation for working with this data will
	// call the Unmarshal() method.
	//
	// TODO: Create framework defined type that is not protocol specific.
	// Reference: https://github.com/hashicorp/terraform-plugin-framework/issues/340
	RawState *tfprotov6.RawState

	// Previous state of the resource if the wrapping ResourceStateUpgrader
	// type PriorSchema field was present. When available, this allows for
	// easier data handling such as calling Get() or GetAttribute().
	State *State
}

Request information for the provider logic to update a resource state from a prior state version to the current schema version. An instance of this is supplied as a parameter to the StateUpgrader function defined in a ResourceStateUpgrader, which ultimately comes from a Resource's UpgradeState method.

type UpgradeResourceStateResponse added in v0.7.0 

type UpgradeResourceStateResponse struct {
	// Diagnostics report errors or warnings related to upgrading the resource
	// state. An empty slice indicates a successful operation with no warnings
	// or errors generated.
	Diagnostics diag.Diagnostics

	// Upgraded state of the resource, which should match the current schema
	// version. If set, this will override State.
	//
	// This field is intended only for advanced provider functionality, such as
	// skipping the full redeclaration of older schemas or using lower level
	// handlers to transform data. Call tfprotov6.NewDynamicValue() to set this
	// value.
	//
	// All data must be populated to prevent data loss during the upgrade
	// operation. No prior state data is copied automatically.
	//
	// TODO: Remove in preference of requiring State, rather than using either
	// a new framework defined type or keeping this protocol specific type.
	// Reference: https://github.com/hashicorp/terraform-plugin-framework/issues/340
	DynamicValue *tfprotov6.DynamicValue

	// Upgraded state of the resource, which should match the current schema
	// version. If DynamicValue is set, it will override this value.
	//
	// This field allows for easier data handling such as calling Set() or
	// SetAttribute(). It is generally recommended over working with the lower
	// level types and functionality required for DynamicValue.
	//
	// All data must be populated to prevent data loss during the upgrade
	// operation. No prior state data is copied automatically.
	State State
}

Response information for the provider logic to update a resource state from a prior state version to the current schema version. An instance of this is supplied as a parameter to the StateUpgrader function defined in a ResourceStateUpgrader, which ultimately came from a Resource's UpgradeState method.

type UseStateForUnknownModifier added in v0.5.0 

type UseStateForUnknownModifier struct{}

UseStateForUnknownModifier is an AttributePlanModifier that copies the prior state value for an attribute into that attribute's plan, if that state is non-null.

Computed attributes without the UseStateForUnknown attribute plan modifier will have their value set to Unknown in the plan, so their value always will be displayed as "(known after apply)" in the CLI plan output. If this plan modifier is used, the prior state value will be displayed in the plan instead unless a prior plan modifier adjusts the value.

func (UseStateForUnknownModifier) Description added in v0.5.0 

func (r UseStateForUnknownModifier) Description(ctx context.Context) string

Description returns a human-readable description of the plan modifier.

func (UseStateForUnknownModifier) MarkdownDescription added in v0.5.0 

func (r UseStateForUnknownModifier) MarkdownDescription(ctx context.Context) string

MarkdownDescription returns a markdown description of the plan modifier.

func (UseStateForUnknownModifier) Modify added in v0.5.0 

func (r UseStateForUnknownModifier) Modify(ctx context.Context, req ModifyAttributePlanRequest, resp *ModifyAttributePlanResponse)

Modify copies the attribute's prior state to the attribute plan if the prior state value is not null.

type ValidateAttributeRequest added in v0.3.0 

type ValidateAttributeRequest struct {
	// AttributePath contains the path of the attribute.
	AttributePath *tftypes.AttributePath

	// AttributeConfig contains the value of the attribute in the configuration.
	AttributeConfig attr.Value

	// Config contains the entire configuration of the data source, provider, or resource.
	Config Config
}

ValidateAttributeRequest repesents a request for

type ValidateAttributeResponse added in v0.3.0 

type ValidateAttributeResponse struct {
	// Diagnostics report errors or warnings related to validating the data
	// source configuration. An empty slice indicates success, with no warnings
	// or errors generated.
	Diagnostics diag.Diagnostics
}

ValidateAttributeResponse represents a response to a ValidateAttributeRequest. An instance of this response struct is automatically passed through to each AttributeValidator.

type ValidateDataSourceConfigRequest added in v0.3.0 

type ValidateDataSourceConfigRequest struct {
	// Config is the configuration the user supplied for the data source.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config Config
}

ValidateDataSourceConfigRequest represents a request to validate the configuration of a data source. An instance of this request struct is supplied as an argument to the DataSource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateDataSourceConfigResponse added in v0.3.0 

type ValidateDataSourceConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the data
	// source configuration. An empty slice indicates success, with no warnings
	// or errors generated.
	Diagnostics diag.Diagnostics
}

ValidateDataSourceConfigResponse represents a response to a ValidateDataSourceConfigRequest. An instance of this response struct is supplied as an argument to the DataSource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateProviderConfigRequest added in v0.3.0 

type ValidateProviderConfigRequest struct {
	// Config is the configuration the user supplied for the provider.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config Config
}

ValidateProviderConfigRequest represents a request to validate the configuration of a provider. An instance of this request struct is supplied as an argument to the Provider ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateProviderConfigResponse added in v0.3.0 

type ValidateProviderConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the provider
	// configuration. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

ValidateProviderConfigResponse represents a response to a ValidateProviderConfigRequest. An instance of this response struct is supplied as an argument to the Provider ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateResourceConfigRequest added in v0.3.0 

type ValidateResourceConfigRequest struct {
	// Config is the configuration the user supplied for the resource.
	//
	// This configuration may contain unknown values if a user uses
	// interpolation or other functionality that would prevent Terraform
	// from knowing the value at request time.
	Config Config
}

ValidateResourceConfigRequest represents a request to validate the configuration of a resource. An instance of this request struct is supplied as an argument to the Resource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

type ValidateResourceConfigResponse added in v0.3.0 

type ValidateResourceConfigResponse struct {
	// Diagnostics report errors or warnings related to validating the resource
	// configuration. An empty slice indicates success, with no warnings or
	// errors generated.
	Diagnostics diag.Diagnostics
}

ValidateResourceConfigResponse represents a response to a ValidateResourceConfigRequest. An instance of this response struct is supplied as an argument to the Resource ValidateConfig receiver method or automatically passed through to each ConfigValidator.

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.