shim

Documentation

Overview

Package tfshim implements an abstraction layer for TF bridge backends.

Concrete backends include:

• sdk-v1 for https://github.com/hashicorp/terraform-plugin-sdk
• sdk-v2 for https://github.com/hashicorp/terraform-plugin-sdk (v2)

The tfplugin5 backend is experimental and is not as of time of this writing to build production providers by Pulumi.

Note that providers built with the Plugin Framework do not currently conform to the backend interface and are handled separately, see github.com/pulumi/pulumi-terraform-bridge/pf

This package is internal. While we avoid unnecessary breaking changes, this package may accept technically breaking changes between major version releases of the bridge.

Index

• func CloneResource(rm ResourceMap, oldKey string, newKey string) error
• type DiffAttrType
• type DiffOptions
• type IgnoreChanges
• type ImportFunc
• type InstanceDiff
• type InstanceState
• type Provider
• type Resource
• type ResourceAttrDiff
• type ResourceConfig
• type ResourceMap
• type ResourceMapWithClone
• type ResourceTimeout
• type Schema
• type SchemaDefaultFunc
• type SchemaMap
• type SchemaStateFunc
• type TimeoutKey
• type TimeoutOptions
• type ValueType
  • func (i ValueType) String() string

Functions

func CloneResource

func CloneResource(rm ResourceMap, oldKey string, newKey string) error

Types

type DiffAttrType

type DiffAttrType byte

const (
	DiffAttrUnknown DiffAttrType = iota
	DiffAttrInput
	DiffAttrOutput
)

type DiffOptions

type DiffOptions struct {
	IgnoreChanges  IgnoreChanges
	TimeoutOptions TimeoutOptions
}

type IgnoreChanges

type IgnoreChanges = func() map[string]struct{}

Supports the ignoreChanges Pulumi option.

The bridge needs to be able to suppress diffs computed by the underlying provider.

For legacy reasons, this is implemented in terms of terraform.InstanceDiff object from terraform-plugin-sdk. That is, the function needs to return a set of paths that match the keys of InstanceDiff.Attributes, something that is slightly complicated to compute correctly for nested properties and sets. Diffs that match the keys from the IgnoreChanges set exactly or by prefix (sub-diffs) are ignored.

https://www.pulumi.com/docs/concepts/options/ignorechanges/

type ImportFunc

type ImportFunc func(t, id string, meta interface{}) ([]InstanceState, error)

type InstanceDiff

type InstanceDiff interface {
	Attribute(key string) *ResourceAttrDiff
	HasNoChanges() bool
	ProposedState(res Resource, priorState InstanceState) (InstanceState, error)
	Destroy() bool
	RequiresNew() bool
}

type InstanceState

type InstanceState interface {
	Type() string

	// Return the resource identifier.
	//
	// If the ID is unknown, as would be the case when previewing a Create, return an empty
	// string (zero value).
	ID() string

	Object(sch SchemaMap) (map[string]interface{}, error)
	Meta() map[string]interface{}
}

type Provider

type Provider interface {
	Schema() SchemaMap
	ResourcesMap() ResourceMap
	DataSourcesMap() ResourceMap

	InternalValidate() error
	Validate(ctx context.Context, c ResourceConfig) ([]string, []error)
	ValidateResource(ctx context.Context, t string, c ResourceConfig) ([]string, []error)
	ValidateDataSource(ctx context.Context, t string, c ResourceConfig) ([]string, []error)

	Configure(ctx context.Context, c ResourceConfig) error

	Diff(
		ctx context.Context,
		t string,
		s InstanceState,
		c ResourceConfig,
		opts DiffOptions,
	) (InstanceDiff, error)

	Apply(ctx context.Context, t string, s InstanceState, d InstanceDiff) (InstanceState, error)

	Refresh(
		ctx context.Context, t string, s InstanceState, c ResourceConfig,
	) (InstanceState, error)

	ReadDataDiff(ctx context.Context, t string, c ResourceConfig) (InstanceDiff, error)
	ReadDataApply(ctx context.Context, t string, d InstanceDiff) (InstanceState, error)

	Meta(ctx context.Context) interface{}
	Stop(ctx context.Context) error

	InitLogging(ctx context.Context)

	// Create a Destroy diff for a resource identified by the TF token t.
	NewDestroyDiff(ctx context.Context, t string, opts TimeoutOptions) InstanceDiff

	NewResourceConfig(ctx context.Context, object map[string]interface{}) ResourceConfig

	// Checks if a value is representing a Set, and unpacks its elements on success.
	IsSet(ctx context.Context, v interface{}) ([]interface{}, bool)
}

type Resource

type Resource interface {
	Schema() SchemaMap
	SchemaVersion() int
	Importer() ImportFunc
	DeprecationMessage() string
	Timeouts() *ResourceTimeout

	InstanceState(id string, object, meta map[string]interface{}) (InstanceState, error)
	DecodeTimeouts(config ResourceConfig) (*ResourceTimeout, error)
}

type ResourceAttrDiff

type ResourceAttrDiff struct {
	Old         string
	New         string
	NewComputed bool
	NewRemoved  bool
	NewExtra    interface{}
	RequiresNew bool
	Sensitive   bool
	Type        DiffAttrType
}

type ResourceConfig

type ResourceConfig interface {
	IsSet(k string) bool
}

type ResourceMap

type ResourceMap interface {
	Len() int
	Get(key string) Resource
	GetOk(key string) (Resource, bool)
	Range(each func(key string, value Resource) bool)

	Set(key string, value Resource)
}

type ResourceMapWithClone

type ResourceMapWithClone interface {
	ResourceMap
	Clone(oldKey, newKey string) error
}

type ResourceTimeout

type ResourceTimeout struct {
	Create, Read, Update, Delete, Default *time.Duration
}

type Schema

type Schema interface {
	Type() ValueType
	Optional() bool
	Required() bool
	Default() interface{}
	DefaultFunc() SchemaDefaultFunc
	DefaultValue() (interface{}, error)
	Description() string
	Computed() bool
	ForceNew() bool
	StateFunc() SchemaStateFunc

	// s.Elem() may return a nil, a Schema value, or a Resource value.
	//
	// The design of Elem() follows Terraform Plugin SDK directly. Case analysis:
	//
	// Case 1: s represents a compound type (s.Type() is one of TypeList, TypeSet or TypeMap), and s.Elem()
	// represents the element of this type as a Schema value. That is, if s ~ List[String] then s.Elem() ~ String.
	//
	// Case 2: s represents a single-nested Terraform block. Logically this is like s having an anonymous object
	// type such as s ~ {"x": Int, "y": String}. In this case s.Type() == TypeMap and s.Elem() is a Resource value.
	// This value is not a real Resource and only implements the Schema field to enable inspecting s.Elem().Schema()
	// to find out the names ("x", "y") and types (Int, String) of the block properties.
	//
	// Case 3: s represents a list or set-nested Terraform block. That is, s ~ List[{"x": Int, "y": String}]. In
	// this case s.Type() is one of TypeList, TypeSet, and s.Elem() is a Resource that encodes the object type
	// similarly to Case 2.
	//
	// Case 4: s.Elem() is nil and s.Type() is a scalar type (none of TypeList, TypeSet, TypeMap).
	//
	// Case 5: s.Elem() is nil but s.Type() is one of TypeList, TypeSet, TypeMap. The element type is unknown.
	//
	// This encoding cannot support map-nested blocks or object types as it would introduce confusion with Case 2,
	// because Map[String, {"x": Int}] and {"x": Int} both have s.Type() = TypeMap and s.Elem() being a Resource.
	// Following the Terraform design, only set and list-nested blocks are supported.
	//
	// See also: https://github.com/hashicorp/terraform-plugin-sdk/blob/main/helper/schema/schema.go#L231
	Elem() interface{}

	MaxItems() int
	MinItems() int
	ConflictsWith() []string
	ExactlyOneOf() []string
	Deprecated() string
	Removed() string
	Sensitive() bool

	SetElement(config interface{}) (interface{}, error)
	SetHash(v interface{}) int
}

type SchemaDefaultFunc

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

type SchemaMap

type SchemaMap interface {
	Len() int
	Get(key string) Schema
	GetOk(key string) (Schema, bool)
	Range(each func(key string, value Schema) bool)

	Set(key string, value Schema)
	Delete(key string)

	Validate() error
}

type SchemaStateFunc

type SchemaStateFunc func(interface{}) string

type TimeoutKey

type TimeoutKey string

const (
	TimeoutCreate  TimeoutKey = "create"
	TimeoutRead    TimeoutKey = "read"
	TimeoutUpdate  TimeoutKey = "update"
	TimeoutDelete  TimeoutKey = "delete"
	TimeoutDefault TimeoutKey = "default"
)

type TimeoutOptions

type TimeoutOptions struct {
	ResourceTimeout  *ResourceTimeout // optional
	TimeoutOverrides map[TimeoutKey]time.Duration
}

type ValueType

type ValueType int

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

func (ValueType) String

func (i ValueType) String() string