tf5server

Documentation

Overview

Package tf5server implements a server implementation to run tfprotov5.ProviderServers as gRPC servers.

Providers will likely be calling tf5server.Serve from their main function to start the server so Terraform can connect to it.

Index

• func New(name string, serve tfprotov5.ProviderServer, opts ...ServeOpt) tfplugin5.ProviderServer
• func Serve(name string, serverFactory func() tfprotov5.ProviderServer, opts ...ServeOpt) error
• type GRPCProviderPlugin
  • func (p *GRPCProviderPlugin) Client(*plugin.MuxBroker, *rpc.Client) (interface{}, error)
  • func (p *GRPCProviderPlugin) GRPCClient(context.Context, *plugin.GRPCBroker, *grpc.ClientConn) (interface{}, error)
  • func (p *GRPCProviderPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error
  • func (p *GRPCProviderPlugin) Server(*plugin.MuxBroker) (interface{}, error)
• type ServeConfig
• type ServeOpt
  • func WithDebug(ctx context.Context, config chan *plugin.ReattachConfig, closeCh chan struct{}) ServeOpt
  • func WithGoPluginLogger(logger hclog.Logger) ServeOpt
  • func WithLogEnvVarName(name string) ServeOpt
  • func WithLoggingSink(t testing.T) ServeOpt
  • func WithManagedDebug() ServeOpt
  • func WithManagedDebugReattachConfigTimeout(timeout time.Duration) ServeOpt
  • func WithManagedDebugStopSignals(signals []os.Signal) ServeOpt
  • func WithoutLogLocation() ServeOpt
  • func WithoutLogStderrOverride() ServeOpt

Functions

func New

func New(name string, serve tfprotov5.ProviderServer, opts ...ServeOpt) tfplugin5.ProviderServer

New converts a tfprotov5.ProviderServer into a server capable of handling Terraform protocol requests and issuing responses using the gRPC types.

func Serve

func Serve(name string, serverFactory func() tfprotov5.ProviderServer, opts ...ServeOpt) error

Serve starts a tfprotov5.ProviderServer serving, ready for Terraform to connect to it. The name passed in should be the fully qualified name that users will enter in the source field of the required_providers block, like "registry.terraform.io/hashicorp/time".

Zero or more options to configure the server may also be passed. The default invocation is sufficient, but if the provider wants to run in debug mode or modify the logger that go-plugin is using, ServeOpts can be specified to support that.

Types

type GRPCProviderPlugin

type GRPCProviderPlugin struct {
	GRPCProvider func() tfprotov5.ProviderServer
	Opts         []ServeOpt
	Name         string
}

GRPCProviderPlugin is an implementation of the github.com/hashicorp/go-plugin#Plugin and github.com/hashicorp/go-plugin#GRPCPlugin interfaces, indicating how to serve tfprotov5.ProviderServers as gRPC plugins for go-plugin.

func (*GRPCProviderPlugin) Client

func (p *GRPCProviderPlugin) Client(*plugin.MuxBroker, *rpc.Client) (interface{}, error)

Client always returns an error; we're only implementing the GRPCPlugin interface, not the Plugin interface.

func (*GRPCProviderPlugin) GRPCClient

func (p *GRPCProviderPlugin) GRPCClient(context.Context, *plugin.GRPCBroker, *grpc.ClientConn) (interface{}, error)

GRPCClient always returns an error; we're only implementing the server half of the interface.

func (*GRPCProviderPlugin) GRPCServer

func (p *GRPCProviderPlugin) GRPCServer(broker *plugin.GRPCBroker, s *grpc.Server) error

GRPCServer registers the gRPC provider server with the gRPC server that go-plugin is standing up.

func (*GRPCProviderPlugin) Server

func (p *GRPCProviderPlugin) Server(*plugin.MuxBroker) (interface{}, error)

Server always returns an error; we're only implementing the GRPCPlugin interface, not the Plugin interface.

type ServeConfig

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

ServeConfig contains the configured options for how a provider should be served.

type ServeOpt

type ServeOpt interface {
	ApplyServeOpt(*ServeConfig) error
}

ServeOpt is an interface for defining options that can be passed to the Serve function. Each implementation modifies the ServeConfig being generated. A slice of ServeOpts then, cumulatively applied, render a full ServeConfig.

func WithDebug

func WithDebug(ctx context.Context, config chan *plugin.ReattachConfig, closeCh chan struct{}) ServeOpt

WithDebug returns a ServeOpt that will set the server into debug mode, using the passed options to populate the go-plugin ServeTestConfig.

This is an advanced ServeOpt that assumes the caller will fully manage the reattach configuration and server lifecycle. Refer to WithManagedDebug for a ServeOpt that handles common use cases, such as implementing provider main functions.

func WithGoPluginLogger

func WithGoPluginLogger(logger hclog.Logger) ServeOpt

WithGoPluginLogger returns a ServeOpt that will set the logger that go-plugin should use to log messages.

func WithLogEnvVarName

func WithLogEnvVarName(name string) ServeOpt

WithLogEnvVarName sets the name of the provider for the purposes of the logging environment variable that controls the provider's log level. It is the part following TF_LOG_PROVIDER_ and defaults to the name part of the provider's registry address, or disabled if it can't parse the provider's registry address. Name must only contain letters, numbers, and hyphens.

func WithLoggingSink

func WithLoggingSink(t testing.T) ServeOpt

WithLoggingSink returns a ServeOpt that will enable the logging sink, which is used in test frameworks to control where terraform-plugin-log output is written and at what levels, mimicking Terraform's logging sink behaviors.

func WithManagedDebug

func WithManagedDebug() ServeOpt

WithManagedDebug returns a ServeOpt that will start the server in debug mode, managing the reattach configuration handling and server lifecycle. Reattach configuration is output to stdout with human friendly instructions. By default, the server can be stopped with os.Interrupt (SIGINT; ctrl-c).

Refer to the optional WithManagedDebugStopSignals and WithManagedDebugReattachConfigTimeout ServeOpt for additional configuration.

The reattach configuration output of this handling is not protected by compatibility guarantees. Use the WithDebug ServeOpt for advanced use cases.

func WithManagedDebugReattachConfigTimeout

func WithManagedDebugReattachConfigTimeout(timeout time.Duration) ServeOpt

WithManagedDebugReattachConfigTimeout returns a ServeOpt that will set the timeout for a debug managed process to start and return its reattach configuration. When not configured, 2 seconds is the default.

func WithManagedDebugStopSignals

func WithManagedDebugStopSignals(signals []os.Signal) ServeOpt

WithManagedDebugStopSignals returns a ServeOpt that will set the stop signals for a debug managed process (WithManagedDebug). When not configured, os.Interrupt (SIGINT; Ctrl-c) will stop the process.

func WithoutLogLocation

func WithoutLogLocation() ServeOpt

WithoutLogLocation returns a ServeOpt that will exclude file names and line numbers from log output for the terraform-plugin-log logs generated by the SDKs and provider.

func WithoutLogStderrOverride

func WithoutLogStderrOverride() ServeOpt

WithoutLogStderrOverride returns a ServeOpt that will disable the terraform-plugin-log behavior of logging to the stderr that existed at startup, not the stderr that exists when the logging statement is called.