provider

README

pulumi-go-provider

A framework for building Go Providers for Pulumi

Note: This library is in active development, and not everthing 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 "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 p.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.

Documentation

Index

• func ConfigMissingKeys(missing map[string]string) error
• func GetSchema(ctx context.Context, name, version string, provider Provider) (schema.PackageSpec, error)
• func RunProvider(name, version string, provider Provider) error
• type CheckFailure
• type CheckRequest
• type CheckResponse
• type ConfigureRequest
• type ConstructFunc
• type ConstructRequest
• type ConstructResponse
• type Context
  • func CtxWithCancel(ctx Context) (Context, context.CancelFunc)
  • func CtxWithTimeout(ctx Context, timeout time.Duration) (Context, context.CancelFunc)
  • func CtxWithValue(ctx Context, key, value any) Context
• type CreateRequest
• type CreateResponse
• type DeleteRequest
• type DiffKind
• type DiffRequest
• type DiffResponse
• type GetSchemaRequest
• type GetSchemaResponse
• type InvokeRequest
• type InvokeResponse
• type PropertyDiff
• type Provider
  • func (d Provider) WithDefaults() Provider
• type ReadRequest
• type ReadResponse
• type RunInfo
• type UpdateRequest
• type UpdateResponse

Functions

func ConfigMissingKeys

func ConfigMissingKeys(missing map[string]string) error

Provide a structured error for missing provider keys.

func GetSchema

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

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

func RunProvider

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

Run a provider with the given name and version.

Types

type CheckFailure

type CheckFailure struct {
	Property string
	Reason   string
}

type CheckRequest

type CheckRequest struct {
	Urn  presource.URN
	Olds presource.PropertyMap
	News presource.PropertyMap
}

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, ConstructFunc) (ConstructResponse, error)
}

type ConstructResponse

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

type Context

type Context interface {
	context.Context
	// Log logs a global message, including errors and warnings.
	Log(severity diag.Severity, msg string)
	// Logf logs a global message, including errors and warnings.
	Logf(severity diag.Severity, msg string, args ...any)
	// LogStatus logs a global status message, including errors and warnings. Status messages will
	// appear in the `Info` column of the progress display, but not in the final output.
	LogStatus(severity diag.Severity, msg string)
	// LogStatusf logs a global status message, including errors and warnings. Status messages will
	// appear in the `Info` column of the progress display, but not in the final output.
	LogStatusf(severity diag.Severity, msg string, args ...any)
	RuntimeInformation() RunInfo
}

func CtxWithCancel

func CtxWithCancel(ctx Context) (Context, context.CancelFunc)

func CtxWithTimeout

func CtxWithTimeout(ctx Context, timeout time.Duration) (Context, context.CancelFunc)

func CtxWithValue

func CtxWithValue(ctx Context, key, value any) Context

Add a value to a Context. This is the moral equivalent to context.WithValue from the Go standard library.

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.
}

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 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 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, 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) error

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

	// Invokes
	Invoke func(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, CheckRequest) (CheckResponse, error)
	Diff   func(Context, DiffRequest) (DiffResponse, error)
	Create func(Context, CreateRequest) (CreateResponse, error)
	Read   func(Context, ReadRequest) (ReadResponse, error)
	Update func(Context, UpdateRequest) (UpdateResponse, error)
	Delete func(Context, DeleteRequest) error

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

func (Provider) WithDefaults

func (d Provider) WithDefaults() Provider

Provide a default value for each function.

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

You should not need to call this function manually. It will be automatically called 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.
}

type RunInfo

type RunInfo struct {
	PackageName string
	Version     string
}

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 {
	Properties presource.PropertyMap // any properties that were computed during updating.
}