tfclient

Documentation

Index

• func ParseReattach(in string) (*plugin.ReattachConfig, error)
• type Client
  • func New(opts Option) (Client, error)
• type Option
• type RawClient
  • func NewRaw(opts Option) (*RawClient, error)
  • func (c *RawClient) AsV5Client() tfprotov5.ProviderServer
  • func (c *RawClient) AsV6Client() tfprotov6.ProviderServer
  • func (c *RawClient) Kill()

Functions

func ParseReattach

func ParseReattach(in string) (*plugin.ReattachConfig, error)

Types

type Client

type Client interface {
	// GetProviderSchema returns the complete schema for the provider.
	GetProviderSchema() (*typ.GetProviderSchemaResponse, typ.Diagnostics)

	// ValidateProviderConfig allows the provider to validate the configuration.
	// The ValidateProviderConfigResponse.PreparedConfig field is unused. The
	// final configuration is not stored in the state, and any modifications
	// that need to be made must be made during the Configure method call.
	ValidateProviderConfig(context.Context, typ.ValidateProviderConfigRequest) (*typ.ValidateProviderConfigResponse, typ.Diagnostics)

	// ValidateResourceConfig allows the provider to validate the resource
	// configuration values.
	ValidateResourceConfig(context.Context, typ.ValidateResourceConfigRequest) (*typ.ValidateResourceConfigResponse, typ.Diagnostics)

	// ValidateDataResourceConfig allows the provider to validate the data source
	// configuration values.
	ValidateDataResourceConfig(context.Context, typ.ValidateDataResourceConfigRequest) (*typ.ValidateDataResourceConfigResponse, typ.Diagnostics)

	// UpgradeResourceState is called when the state loader encounters an
	// instance state whose schema version is less than the one reported by the
	// currently-used version of the corresponding provider, and the upgraded
	// result is used for any further processing.
	UpgradeResourceState(context.Context, typ.UpgradeResourceStateRequest) (*typ.UpgradeResourceStateResponse, typ.Diagnostics)

	// ConfigureProvider configures and initialized the provider.
	ConfigureProvider(context.Context, typ.ConfigureProviderRequest) (*typ.ConfigureProviderResponse, typ.Diagnostics)

	// Stop is called when the provider should halt any in-flight actions.
	//
	// Stop should not block waiting for in-flight actions to complete. It
	// should take any action it wants and return immediately acknowledging it
	// has received the stop request. Terraform will not make any further API
	// calls to the provider after Stop is called.
	//
	// The error returned, if non-nil, is assumed to mean that signaling the
	// stop somehow failed and that the user should expect potentially waiting
	// a longer period of time.
	Stop(context.Context) error

	// ReadResource refreshes a resource and returns its current state.
	ReadResource(context.Context, typ.ReadResourceRequest) (*typ.ReadResourceResponse, typ.Diagnostics)

	// PlanResourceChange takes the current state and proposed state of a
	// resource, and returns the planned final state.
	PlanResourceChange(context.Context, typ.PlanResourceChangeRequest) (*typ.PlanResourceChangeResponse, typ.Diagnostics)

	// ApplyResourceChange takes the planned state for a resource, which may
	// yet contain unknown computed values, and applies the changes returning
	// the final state.
	ApplyResourceChange(context.Context, typ.ApplyResourceChangeRequest) (*typ.ApplyResourceChangeResponse, typ.Diagnostics)

	// ImportResourceState requests that the given resource be imported.
	ImportResourceState(context.Context, typ.ImportResourceStateRequest) (*typ.ImportResourceStateResponse, typ.Diagnostics)

	// MoveResourceState retrieves the updated value for a resource after it
	// has moved resource types.
	MoveResourceState(context.Context, typ.MoveResourceStateRequest) (*typ.MoveResourceStateResponse, typ.Diagnostics)

	// ReadDataSource returns the data source's current state.
	ReadDataSource(context.Context, typ.ReadDataSourceRequest) (*typ.ReadDataSourceResponse, typ.Diagnostics)

	// CallFunction calls a provider-contributed function.
	CallFunction(context.Context, typ.CallFunctionRequest) (*typ.CallFunctionResponse, typ.Diagnostics)

	// Close shuts down the plugin process if applicable.
	Close()
}

Client represents the set of methods required for a complete resource provider plugin.

func New

func New(opts Option) (Client, error)

New creates a normalized client. It spins up an un-configured provider server, whose lifecycle is managed by the client, so make sure to call the "Kill" method on exit.

type Option

type Option struct {
	// One of the following must be set, but not both.
	//
	// Cmd is the unstarted subprocess for starting the plugin. If this is
	// set, then the Client starts the plugin process on its own and connects
	// to it.
	//
	// Reattach is configuration for reattaching to an existing plugin process
	// that is already running. This isn't common.
	Cmd      *exec.Cmd
	Reattach *plugin.ReattachConfig

	// SecureConfig is configuration for verifying the integrity of the
	// executable. It can not be used with Reattach.
	SecureConfig *plugin.SecureConfig

	// TLSConfig is used to enable TLS on the RPC client.
	TLSConfig *tls.Config

	// The minimum and maximum port to use for communicating with
	// the subprocess. If not set, this defaults to 10,000 and 25,000
	// respectively.
	MinPort, MaxPort uint

	// StartTimeout is the timeout to wait for the plugin to say it
	// has started successfully.
	StartTimeout time.Duration

	// If non-nil, then the stderr of the client will be written to here
	// (as well as the log). This is the original os.Stderr of the subprocess.
	// This isn't the output of synced stderr.
	Stderr io.Writer

	// SyncStdout, SyncStderr can be set to override the
	// respective os.Std* values in the plugin. Care should be taken to
	// avoid races here. If these are nil, then this will be set to
	// ioutil.Discard.
	SyncStdout io.Writer
	SyncStderr io.Writer

	// Logger is the logger that the client will used. If none is provided,
	// it will default to hclog's default logger.
	Logger hclog.Logger

	// AutoMTLS has the client and server automatically negotiate mTLS for
	// transport authentication. This ensures that only the original client will
	// be allowed to connect to the server, and all other connections will be
	// rejected. The client will also refuse to connect to any server that isn't
	// the original instance started by the client.
	//
	// In this mode of operation, the client generates a one-time use tls
	// certificate, sends the public x.509 certificate to the new server, and
	// the server generates a one-time use tls certificate, and sends the public
	// x.509 certificate back to the client. These are used to authenticate all
	// rpc connections between the client and server.
	//
	// Setting AutoMTLS to true implies that the server must support the
	// protocol, and correctly negotiate the tls certificates, or a connection
	// failure will result.
	//
	// The client should not set TLSConfig, nor should the server set a
	// TLSProvider, because AutoMTLS implies that a new certificate and tls
	// configuration will be generated at startup.
	//
	// You cannot Reattach to a server with this option enabled.
	AutoMTLS bool

	// GRPCDialOptions allows plugin users to pass custom grpc.DialOption
	// to create gRPC connections. This only affects plugins using the gRPC
	// protocol.
	GRPCDialOptions []grpc.DialOption

	// ProviderSchema allows users to provide a pre-fetched provider schema, which saves
	// a GetProviderSchema call during the client initialization.
	// Tis is only used for performance sensitive scenario where multiple clients are created,
	// but target to the same provider.
	ProviderSchema *typ.GetProviderSchemaResponse
}

type RawClient

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

func NewRaw

func NewRaw(opts Option) (*RawClient, error)

NewRaw creates a raw client. It spins up an un-configured provider server, whose lifecycle is managed by the client, so make sure to call the "Kill" method on exit.

func (*RawClient) AsV5Client

func (c *RawClient) AsV5Client() tfprotov5.ProviderServer

AsV5Client returns the v5 client if the linked provider is running in protocol v5, otherwise return nil

func (*RawClient) AsV6Client

func (c *RawClient) AsV6Client() tfprotov6.ProviderServer

AsV6Client returns the v6 client if the linked provider is running in protocol v6, otherwise return nil

func (*RawClient) Kill

func (c *RawClient) Kill()

Kill ends the executing subprocess (if it is running) and perform any cleanup tasks necessary such as capturing any remaining logs and so on.

This method blocks until the process successfully exits.

This method can safely be called multiple times.