pulumi/pulumi

Go SDK

Active contributors: Justin Van Patten, Ian Wahbe, Fraser Waters

Purpose

sdk/go/pulumi/ is the Go SDK that user Pulumi programs in Go (and provider authors writing in Go) link against. It also doubles as a cross-language type library — Go is the lingua franca of this repo, so other SDKs reference its types when modeling cross-cutting concepts.

The module path is github.com/pulumi/pulumi/sdk/v3/go/pulumi.

Directory layout

sdk/go/
├── auto/                       # Automation API
├── common/                     # Shared types: apitype, diag, env, resource, tokens, workspace, ...
├── internal/                   # Internal helpers (off-limits to user code)
├── property/                   # Cross-language property-bag types
├── pulumi/                     # The user-facing SDK proper
├── pulumi-internal/            # Internal helpers used by the SDK
├── pulumi-language-go/         # The Go language host binary
├── pulumix/                    # Generic Output[T] helpers (newer)
└── tools/                      # Generators

The sdk/ Go module imports pkg/ indirectly only via shared types in sdk/go/common/. Anything inside sdk/go/pulumi/ is meant to be safe to import from a user program.

Key abstractions

Symbol	File	Role
`Context`	`sdk/go/pulumi/context.go` (~103 KB)	Per-program context: registers resources, looks up config
`Resource` interface	`sdk/go/pulumi/resource.go` (~41 KB)	Base interface for every resource
`CustomResourceState`, `ComponentResourceState`	`sdk/go/pulumi/resource.go`	Embed these in concrete resource types
`Output[T]`, `Input[T]`	`sdk/go/pulumi/types.go`, `types_builtins.go`	Future-like values. Generated for every primitive shape (~480 KB)
`pulumix.Output[T]`	`sdk/go/pulumix/`	Generics-based Output (Go 1.18+)
`Config`	`sdk/go/pulumi/config/`	Stack config reader
`StackReference`	`sdk/go/pulumi/stack_reference.go`	Read outputs from another stack
`Run`, `RunErr`	`sdk/go/pulumi/run.go`	Top-level entry — `pulumi.Run(func(ctx) error { ... })`
`Mocks`	`sdk/go/pulumi/mocks.go`	Test harness used by user-program tests
`provider.NewProvider`	`sdk/go/pulumi/provider.go` (~30 KB), `provider_linked.go`	Server-side provider scaffolding
`policyx`	`sdk/go/pulumi/policyx/`	Policy-pack analyzer scaffolding

Output / Input

Output[T] is the central abstraction. Conceptually:

type Output[T any] interface {
    // Future-resolved value
    Apply(func(T) U) Output[U]
    // Returns the resolved T (and any pulumi.Result)
    ToOutput() Output[T]
}

In practice, the canonical SDK predates generics. The Go SDK exposes typed <T>Output and <T>Input interfaces for every primitive (StringOutput, Int64MapOutput, BoolPtrOutput, ...) generated from sdk/go/pulumi/generate/. Newer code uses sdk/go/pulumix/Output[T] which leverages generics.

Both forms compose. pulumi.All(a, b, c).ApplyT(...) joins outputs.

Resource registration

sequenceDiagram
    participant User as User code
    participant Ctx as pulumi.Context
    participant SDK as sdk/go/pulumi
    participant Mon as ResourceMonitor

    User->>Ctx: NewBucket("my-bucket", &BucketArgs{...})
    Ctx->>SDK: registerResource(...)
    SDK->>SDK: marshal inputs, resolve dependencies
    SDK->>Mon: gRPC RegisterResource
    Mon-->>SDK: outputs (with id)
    SDK-->>User: typed *Bucket with Output fields

The marshaling step in rpc.go (~35 KB) handles converting between Go reflect-driven structs and the resource-monitor's flat map[string]interface{} shape.

Provider authoring

sdk/go/pulumi/provider.go and provider_linked.go are the Go-side scaffolding for writing components — providers that are themselves Pulumi programs in Go (often called "remote components"). The provider implements proto/pulumi/provider.proto (specifically Construct and Call) and re-uses the Go SDK to register child resources.

Tests

context_test.go (~30 KB) — large coverage of registration paths.
provider_test.go (~60 KB) — provider-side scaffolding tests.
resource_test.go (~46 KB) — resource lifecycle covered with mocks.
types_builtins_test.go (~435 KB, generated) — checked-in tests for every Output type.

Build

sdk/go/Makefile orchestrates Go-specific build/lint/test. The language host has its own Makefile at sdk/go/pulumi-language-go/.

Entry points for modification

A new resource option — extend RegisterResourceOpts in resource.go, plumb into RegisterResourceRequest in proto/pulumi/resource.proto, regenerate.
A new built-in invoke — declare in pkg/resource/deploy/builtins.go, expose helper in sdk/go/pulumi/.
Generator changes — sdk/go/pulumi/generate/ produces types_builtins.go. Run go generate ./... from sdk/go/pulumi/.