tfprovider

Documentation

Overview

Package tfprovider is a client library for the Terraform provider plugin API, allowing Go programs to call into Terraform provider plugins without using code from Terraform itself.

This package currently implements clients for protocol versions 5 and 6. In particular, that means it isn't compatible with provider plugins that are only compatible with Terraform v0.11 and earlier.

Index

• type Config
• type DataResourceType
• type DataResourceTypeSchema
• type Diagnostic
• type DiagnosticSeverity
• type Diagnostics
• type ManagedResourceReadRequest
• type ManagedResourceReadResponse
• type ManagedResourceType
• type ManagedResourceTypeSchema
• type Provider
  • func Start(ctx context.Context, exe string, args ...string) (Provider, error)
• type Schema

Types

type Config

type Config = common.Config

Config represents a provider configuration that has already been prepared using Provider.PrepareConfig, ready to be passed to Configure.

type DataResourceType

type DataResourceType = common.DataResourceType

type DataResourceTypeSchema

type DataResourceTypeSchema = common.Schema

type Diagnostic

type Diagnostic = common.Diagnostic

type DiagnosticSeverity

type DiagnosticSeverity = common.DiagnosticSeverity

const (
	Error   DiagnosticSeverity = common.Error
	Warning DiagnosticSeverity = common.Warning
)

type Diagnostics

type Diagnostics = common.Diagnostics

type ManagedResourceReadRequest

type ManagedResourceReadRequest = common.ManagedResourceReadRequest

type ManagedResourceReadResponse

type ManagedResourceReadResponse = common.ManagedResourceReadResponse

type ManagedResourceType

type ManagedResourceType = common.ManagedResourceType

type ManagedResourceTypeSchema

type ManagedResourceTypeSchema = common.Schema

type Provider

type Provider interface {
	// Schema retrieves the full schema for the provider.
	Schema(ctx context.Context) (*Schema, Diagnostics)

	// PrepareConfig validates and normalizes an object representing a provider
	// configuration, returning either the normalized object or error
	// diagnostics describing any problems with it.
	PrepareConfig(ctx context.Context, config cty.Value) (Config, Diagnostics)

	// Configure configures the provider using the given configuration.
	//
	// Each provider instance can be configured only once. If this method
	// is called more than once, subsequent calls will return errors.
	//
	// Unless Configure returns error diagnostics, after it returns the caller
	// may use other methods which are documented as requiring configuration
	// first.
	//
	// The given Config must have been prepared using PrepareConfig.
	Configure(ctx context.Context, config Config) Diagnostics

	// ValidateManagedResourceConfig runs the provider's validation logic
	// for a particular managed resource type.
	ValidateManagedResourceConfig(ctx context.Context, typeName string, config cty.Value) Diagnostics

	// ValidateDataResourceConfig runs the provider's validation logic
	// for a particular managed resource type.
	ValidateDataResourceConfig(ctx context.Context, typeName string, config cty.Value) Diagnostics

	// ManagedResourceType returns an object representing the managed resource
	// type with the given name, or nil if the provider has no such managed
	// resource type.
	//
	// The provider must be configured using [Configure] before calling this
	// method. An unconfigured provider always returns nil.
	ManagedResourceType(name string) ManagedResourceType

	// Close kills the child process for this provider plugin, rendering the
	// reciever unusable. Any further calls on the object after Close returns
	// cause undefined behavior.
	//
	// Calling Close also invalidates any associated objects such as
	// resource type objects.
	Close() error

	// Sealed is a do-nothing method that exists only to represent that this
	// interface may not be implemented by any type outside of this module,
	// to allow the interface to expand in future to support new provider
	// plugin protocol features.
	Sealed() common.Sealed
}

Provider represents a running provider plugin.

func Start

func Start(ctx context.Context, exe string, args ...string) (Provider, error)

Start executes the given command line as a Terraform provider plugin and returns an object representing it.

The provider is initially unconfigured, meaning that it can only be used for object validation tasks. It must be configured (that is, it must be provided with a valid configuration object) before it can take any non-validation actions.

Terraform providers run as child processes, so if this function returns successfully there will be a new child process beneath the calling process waiting to recieve provider commands. Be sure to call Close on the returned object when you no longer need the provider, so that the child process can be killed.

Terraform provider executables conventionally have names starting with "terraform-provider-", because that is the prefix Terraform itself looks for in order to discover them automatically.

type Schema

type Schema = common.Schema