provider

README

pulumi-go-provider

A framework for building Providers for Pulumi in Go.

Library documentation can be found at

Note: This library is in active development, and not everything is hooked up. You should expect breaking changes as we fine tune the exposed APIs. We definitely appreciate community feedback, but you should probably wait to port any existing providers over.

The highest level of pulumi-go-provider is infer, which derives as much possible from your Go code. The "Hello, Pulumi" example below uses infer. For detailed instructions on building providers with infer, click here.

The "Hello, Pulumi" Provider

Here we provide the code to create an entire native provider consumable from any of the Pulumi languages (TypeScript, Python, Go, C#, Java and Pulumi YAML).

func main() {
	p.RunProvider("greetings", "0.1.0",
		// We tell the provider what resources it needs to support.
		// In this case, a single custom resource.
		infer.Provider(infer.Options{
			Resources: []infer.InferredResource{
				infer.Resource[HelloWorld, HelloWorldArgs, HelloWorldState](),
			},
		}))
}

// Each resource has a controlling struct.
type HelloWorld struct{}

// Each resource has in input struct, defining what arguments it accepts.
type HelloWorldArgs struct {
	// Fields projected into Pulumi must be public and hava a `pulumi:"..."` tag.
	// The pulumi tag doesn't need to match the field name, but its generally a
	// good idea.
	Name string `pulumi:"name"`
	// Fields marked `optional` are optional, so they should have a pointer
	// ahead of their type.
	Loud *bool `pulumi:"loud,optional"`
}

// Each resource has a state, describing the fields that exist on the created resource.
type HelloWorldState struct {
	// It is generally a good idea to embed args in outputs, but it isn't strictly necessary.
	HelloWorldArgs
	// Here we define a required output called message.
	Message string `pulumi:"message"`
}

// All resources must implement Create at a minumum.
func (HelloWorld) Create(
	ctx context.Context, name string, input HelloWorldArgs, preview bool,
) (string, HelloWorldState, error) {
	state := HelloWorldState{HelloWorldArgs: input}
	if preview {
		return name, state, nil
	}
	state.Message = fmt.Sprintf("Hello, %s", input.Name)
	if input.Loud != nil && *input.Loud {
		state.Message = strings.ToUpper(state.Message)
	}
	return name, state, nil
}

The framework is doing a lot of work for us here. Since we didn't implement Diff it is assumed to be structural. The diff will require a replace if any field changes, since we didn't implement Update. Check will confirm that our inputs can be serialized into HelloWorldArgs and Read will do the same. Delete is a no-op.

Library structure

The library is designed to allow as many use cases as possible while still keeping simple things simple. The library comes in 4 parts:

1. A base abstraction for a Pulumi Provider and the facilities to drive it. This is the Provider interface and the RunProvider function respectively. The rest of the library is written against the Provider interface.
2. Middleware layers built on top of the Provider interface. Middleware layers handle things like token dispatch, schema generation, cancel propagation, ect.
3. A testing framework found in the integration folder. This allows unit and integration tests against Providers.
4. A top layer called infer, which generates full providers from Go types and methods. infer is the expected entry-point into the library. It is the fastest way to get started with a provider in go.[^1]

[^1]: The "Hello, Pulumi" example shows the infer layer.

Generating SDKs and schema

Using Pulumi YAML, you can use the provider as-is. In order to use the provider in other languages, you need to generate at least one SDK. pulumi package gen-sdk ./bin/your-provider will do this, by default for all supported languages. See pulumi package gen-sdk --help for more options.

It's not necessary to export the Pulumi schema to use the provider. If you would like to do so, e.g., for debugging purposes, you can use pulumi package get-schema ./bin/your-provider.

Documentation

Overview

Package provider works as a shared high-level interface for rpc.ResourceProviderServer.

It is the lowest level that the rest of this repo should target, and servers as an interoperability layer between middle-wares.

Index

• func ConfigMissingKeys(missing map[string]string) error
• func GetSchema(ctx context.Context, name, version string, provider Provider) (schema.PackageSpec, error)
• func InternalErrorf(msg string, a ...any) error
• func RawServer(name, version string, provider Provider) func(*pprovider.HostClient) (rpc.ResourceProviderServer, error)
• func RunProvider(name, version string, provider Provider) error
• type CallRequest
• type CallResponse
• type CheckFailure
• type CheckRequest
• type CheckResponse
• type ConfigureRequest
• type ConstructFunc
• type ConstructRequest
• type ConstructResponse
• type CreateRequest
• type CreateResponse
• type DeleteRequest
• type DiffKind
• type DiffRequest
• type DiffResponse
• type GetSchemaRequest
• type GetSchemaResponse
• type InitializationFailed
• type InvokeRequest
• type InvokeResponse
• type Logger
  • func GetLogger(ctx context.Context) Logger
  • func (l Logger) Debug(msg string)
  • func (l Logger) DebugStatus(msg string)
  • func (l Logger) DebugStatusf(msg string, a ...any)
  • func (l Logger) Debugf(msg string, a ...any)
  • func (l Logger) Error(msg string)
  • func (l Logger) ErrorStatus(msg string)
  • func (l Logger) ErrorStatusf(msg string, a ...any)
  • func (l Logger) Errorf(msg string, a ...any)
  • func (l Logger) Info(msg string)
  • func (l Logger) InfoStatus(msg string)
  • func (l Logger) InfoStatusf(msg string, a ...any)
  • func (l Logger) Infof(msg string, a ...any)
  • func (l Logger) Warning(msg string)
  • func (l Logger) WarningStatus(msg string)
  • func (l Logger) WarningStatusf(msg string, a ...any)
  • func (l Logger) Warningf(msg string, a ...any)
• type PropertyDiff
• type Provider
  • func (d Provider) WithDefaults() Provider
• type ReadRequest
• type ReadResponse
• type RunInfo
  • func GetRunInfo(ctx context.Context) RunInfo
• type UpdateRequest
• type UpdateResponse

Functions

func ConfigMissingKeys

func ConfigMissingKeys(missing map[string]string) error

ConfigMissingKeys creates a structured error for missing provider keys.

func GetSchema

func GetSchema(ctx context.Context, name, version string, provider Provider) (schema.PackageSpec, error)

GetSchema retrieves the schema from the provider by invoking GetSchema on the provider.

This is a helper method to retrieve the schema from a provider without running the provider in a separate process. It should not be necessary for most providers.

To retrieve the schema from a provider binary, use

pulumi package get-schema ./pulumi-resource-MYPROVIDER

func InternalErrorf

func InternalErrorf(msg string, a ...any) error

InternalErrorf indicates that the provider encountered an internal error.

This will tell the user that the provider had a bug, and the bug should be reported to the provider author.

This is different then internal.Error, which indicates that pulumi-go-provider has a bug.

func RawServer

func RawServer(
	name, version string,
	provider Provider,
) func(*pprovider.HostClient) (rpc.ResourceProviderServer, error)

RawServer converts the Provider into a factory for gRPC servers.

If you are trying to set up a standard main function, see RunProvider.

func RunProvider

func RunProvider(name, version string, provider Provider) error

RunProvider runs a provider with the given name and version.

Types

type CallRequest

type CallRequest struct {
	Tok     tokens.ModuleMember
	Args    presource.PropertyMap
	Context *pulumi.Context
}

CallRequest represents a requested resource method invocation.

It corresponds to rpc.CallRequest on the wire.

type CallResponse

type CallResponse struct {
	// The returned values, if the call was successful.
	Return presource.PropertyMap
	// The failures if any arguments didn't pass verification.
	Failures []CheckFailure
}

CallResponse represents a completed resource method invocation.

It corresponds to rpc.CallResponse on the wire.

type CheckFailure

type CheckFailure struct {
	Property string
	Reason   string
}

type CheckRequest

type CheckRequest struct {
	Urn        presource.URN
	Olds       presource.PropertyMap
	News       presource.PropertyMap
	RandomSeed []byte
}

type CheckResponse

type CheckResponse struct {
	Inputs   presource.PropertyMap
	Failures []CheckFailure
}

type ConfigureRequest

type ConfigureRequest struct {
	Variables map[string]string
	Args      presource.PropertyMap
}

type ConstructFunc

type ConstructFunc = func(
	*pulumi.Context, comProvider.ConstructInputs, pulumi.ResourceOption,
) (pulumi.ComponentResource, error)

type ConstructRequest

type ConstructRequest struct {
	URN       presource.URN
	Preview   bool
	Construct func(context.Context, ConstructFunc) (ConstructResponse, error)
}

type ConstructResponse

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

type CreateRequest

type CreateRequest struct {
	Urn        presource.URN         // the Pulumi URN for this resource.
	Properties presource.PropertyMap // the provider inputs to set during creation.
	Timeout    float64               // the create request timeout represented in seconds.
	Preview    bool                  // true if this is a preview and the provider should not actually create the resource.
}

type CreateResponse

type CreateResponse struct {
	ID         string                // the ID of the created resource.
	Properties presource.PropertyMap // any properties that were computed during creation.

	// non-nil to indicate that the create failed and left the resource in a partial
	// state.
	//
	// If PartialState is non-nil, then an error will be returned, annotated with
	// [pulumirpc.ErrorResourceInitFailed].
	PartialState *InitializationFailed
}

type DeleteRequest

type DeleteRequest struct {
	ID         string                // the ID of the resource to delete.
	Urn        presource.URN         // the Pulumi URN for this resource.
	Properties presource.PropertyMap // the current properties on the resource.
	Timeout    float64               // the delete request timeout represented in seconds.
}

type DiffKind

type DiffKind string

const (
	Add           DiffKind = "add"            // this property was added
	AddReplace    DiffKind = "add&replace"    // this property was added, and this change requires a replace
	Delete        DiffKind = "delete"         // this property was removed
	DeleteReplace DiffKind = "delete&replace" // this property was removed, and this change requires a replace
	Update        DiffKind = "update"         // this property's value was changed
	UpdateReplace DiffKind = "update&replace" // this property's value was changed, and this change requires a replace
	Stable        DiffKind = "stable"         // this property's value will not change
)

type DiffRequest

type DiffRequest struct {
	ID            string
	Urn           presource.URN
	Olds          presource.PropertyMap
	News          presource.PropertyMap
	IgnoreChanges []presource.PropertyKey
}

type DiffResponse

type DiffResponse struct {
	DeleteBeforeReplace bool // if true, this resource must be deleted before replacing it.
	HasChanges          bool // if true, this diff represents an actual difference and thus requires an update.
	// detailedDiff is an optional field that contains map from each changed property to the type of the change.
	//
	// The keys of this map are property paths. These paths are essentially Javascript property access expressions
	// in which all elements are literals, and obey the following EBNF-ish grammar:
	//
	//   propertyName := [a-zA-Z_$] { [a-zA-Z0-9_$] }
	//   quotedPropertyName := '"' ( '\' '"' | [^"] ) { ( '\' '"' | [^"] ) } '"'
	//   arrayIndex := { [0-9] }
	//
	//   propertyIndex := '[' ( quotedPropertyName | arrayIndex ) ']'
	//   rootProperty := ( propertyName | propertyIndex )
	//   propertyAccessor := ( ( '.' propertyName ) |  propertyIndex )
	//   path := rootProperty { propertyAccessor }
	//
	// Examples of valid keys:
	// - root
	// - root.nested
	// - root["nested"]
	// - root.double.nest
	// - root["double"].nest
	// - root["double"]["nest"]
	// - root.array[0]
	// - root.array[100]
	// - root.array[0].nested
	// - root.array[0][1].nested
	// - root.nested.array[0].double[1]
	// - root["key with \"escaped\" quotes"]
	// - root["key with a ."]
	// - ["root key with \"escaped\" quotes"].nested
	// - ["root key with a ."][100]
	DetailedDiff map[string]PropertyDiff
}

type GetSchemaRequest

type GetSchemaRequest struct {
	Version int
}

type GetSchemaResponse

type GetSchemaResponse struct {
	Schema string
}

type InitializationFailed

type InitializationFailed struct {
	// Reasons why the resource did not fully initialize.
	Reasons []string
}

InitializationFailed indicates that a resource exists but failed to initialize, and is thus in a partial state.

type InvokeRequest

type InvokeRequest struct {
	Token tokens.Type           // the function token to invoke.
	Args  presource.PropertyMap // the arguments for the function invocation.
}

type InvokeResponse

type InvokeResponse struct {
	Return   presource.PropertyMap // the returned values, if invoke was successful.
	Failures []CheckFailure        // the failures if any arguments didn't pass verification.
}

type Logger

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

Logger provides methods for user visible logging.

Log info will be associated with the URN passed if any.

func GetLogger

func GetLogger(ctx context.Context) Logger

func (Logger) Debug

func (l Logger) Debug(msg string)

Debug logs a debug message visible to the user.

func (Logger) DebugStatus

func (l Logger) DebugStatus(msg string)

DebugStatus logs a debug message visible to the user.

The message will only be displayed while it is the latest message.

func (Logger) DebugStatusf

func (l Logger) DebugStatusf(msg string, a ...any)

DebugStatusf logs a debug message visible to the user, formatting it with fmt.Sprintf.

The message will only be displayed while it is the latest message.

func (Logger) Debugf

func (l Logger) Debugf(msg string, a ...any)

Debugf logs a debug message visible to the user, formatting it with fmt.Sprintf.

func (Logger) Error

func (l Logger) Error(msg string)

func (Logger) ErrorStatus

func (l Logger) ErrorStatus(msg string)

func (Logger) ErrorStatusf

func (l Logger) ErrorStatusf(msg string, a ...any)

func (Logger) Errorf

func (l Logger) Errorf(msg string, a ...any)

func (Logger) Info

func (l Logger) Info(msg string)

func (Logger) InfoStatus

func (l Logger) InfoStatus(msg string)

func (Logger) InfoStatusf

func (l Logger) InfoStatusf(msg string, a ...any)

func (Logger) Infof

func (l Logger) Infof(msg string, a ...any)

func (Logger) Warning

func (l Logger) Warning(msg string)

func (Logger) WarningStatus

func (l Logger) WarningStatus(msg string)

func (Logger) WarningStatusf

func (l Logger) WarningStatusf(msg string, a ...any)

func (Logger) Warningf

func (l Logger) Warningf(msg string, a ...any)

type PropertyDiff

type PropertyDiff struct {
	Kind      DiffKind // The kind of diff asdsociated with this property.
	InputDiff bool     // The difference is between old and new inputs, not old and new state.
}

type Provider

type Provider struct {

	// GetSchema fetches the schema for this resource provider.
	GetSchema func(context.Context, GetSchemaRequest) (GetSchemaResponse, error)
	// Cancel signals the provider to gracefully shut down and abort any ongoing resource operations.
	// Operations aborted in this way will return an error (e.g., `Update` and `Create` will either return a
	// creation error or an initialization error). Since Cancel is advisory and non-blocking, it is up
	// to the host to decide how long to wait after Cancel is called before (e.g.)
	// hard-closing any gRPC connection.
	Cancel func(context.Context) error

	// Provider Config
	CheckConfig func(context.Context, CheckRequest) (CheckResponse, error)
	DiffConfig  func(context.Context, DiffRequest) (DiffResponse, error)
	// NOTE: We opt into all options.
	Configure func(context.Context, ConfigureRequest) error

	// Invokes
	Invoke func(context.Context, InvokeRequest) (InvokeResponse, error)

	// Check validates that the given property bag is valid for a resource of the given type and returns the inputs
	// that should be passed to successive calls to Diff, Create, or Update for this resource. As a rule, the provider
	// inputs returned by a call to Check should preserve the original representation of the properties as present in
	// the program inputs. Though this rule is not required for correctness, violations thereof can negatively impact
	// the end-user experience, as the provider inputs are using for detecting and rendering diffs.
	Check  func(context.Context, CheckRequest) (CheckResponse, error)
	Diff   func(context.Context, DiffRequest) (DiffResponse, error)
	Create func(context.Context, CreateRequest) (CreateResponse, error)
	Read   func(context.Context, ReadRequest) (ReadResponse, error)
	Update func(context.Context, UpdateRequest) (UpdateResponse, error)
	Delete func(context.Context, DeleteRequest) error

	// Call allows methods to be attached to resources.
	//
	// Right now, Call is restricted to methods on component resources.[^1][^2]
	//
	// [^1]: On the provider resource: https://github.com/pulumi/pulumi/issues/17025
	// [^2]: On custom resources: https://github.com/pulumi/pulumi/issues/16257
	Call func(context.Context, CallRequest) (CallResponse, error)

	// Components Resources
	Construct func(context.Context, ConstructRequest) (ConstructResponse, error)
}

func (Provider) WithDefaults

func (d Provider) WithDefaults() Provider

WithDefaults returns a provider with sensible defaults. It does not mutate its receiver.

Most default values return a NotYetImplemented error, which the engine knows to ignore. Other defaults are no-op functions.

You should not need to call this function manually. It will be automatically invoked before a provider is run.

type ReadRequest

type ReadRequest struct {
	ID         string                // the ID of the resource to read.
	Urn        presource.URN         // the Pulumi URN for this resource.
	Properties presource.PropertyMap // the current state (sufficiently complete to identify the resource).
	Inputs     presource.PropertyMap // the current inputs, if any (only populated during refresh).
}

type ReadResponse

type ReadResponse struct {
	ID         string                // the ID of the resource read back (or empty if missing).
	Properties presource.PropertyMap // the state of the resource read from the live environment.
	Inputs     presource.PropertyMap // the inputs for this resource that would be returned from Check.

	// non-nil to indicate that the read failed and left the resource in a partial
	// state.
	//
	// If PartialState is non-nil, then an error will be returned, annotated with
	// [pulumirpc.ErrorResourceInitFailed].
	PartialState *InitializationFailed
}

type RunInfo

type RunInfo struct {
	PackageName string
	Version     string
}

func GetRunInfo

func GetRunInfo(ctx context.Context) RunInfo

type UpdateRequest

type UpdateRequest struct {
	ID            string                  // the ID of the resource to update.
	Urn           presource.URN           // the Pulumi URN for this resource.
	Olds          presource.PropertyMap   // the old values of provider inputs for the resource to update.
	News          presource.PropertyMap   // the new values of provider inputs for the resource to update.
	Timeout       float64                 // the update request timeout represented in seconds.
	IgnoreChanges []presource.PropertyKey // a set of property paths that should be treated as unchanged.
	Preview       bool                    // true if the provider should not actually create the resource.
}

type UpdateResponse

type UpdateResponse struct {
	// any properties that were computed during updating.
	Properties presource.PropertyMap
	// non-nil to indicate that the update failed and left the resource in a partial
	// state.
	//
	// If PartialState is non-nil, then an error will be returned, annotated with
	// [pulumirpc.ErrorResourceInitFailed].
	PartialState *InitializationFailed
}