Pulumi Native Provider Boilerplate

This repository is a boilerplate showing how to create and locally test a native Pulumi provider (with examples of both CustomResource and ComponentResource resource types).

Authoring a Pulumi Native Provider

This boilerplate creates a working Pulumi-owned provider named provider-boilerplate. It implements a random number generator that you can build and test out for yourself and then replace the Random code with code specific to your provider.

Prerequisites

You will need to ensure the following tools are installed and present in your $PATH:

pulumictl
Go 1.21 or 1.latest
NodeJS 14.x. We recommend using nvm to manage NodeJS installations.
Yarn
TypeScript
Python (called as python3). For recent versions of MacOS, the system-installed version is fine.
.NET

Build & test the boilerplate provider

Run make build install to build and install the provider.
Run make gen_examples to generate the example programs in examples/ off of the source examples/yaml example program.
Run make up to run the example program in examples/yaml.
Run make down to tear down the example program.

Creating a new provider repository

Pulumi offers this repository as a GitHub template repository for convenience. From this repository:

Click "Use this template".
Set the following options:
- Owner: pulumi
- Repository name: pulumi-provider-boilerplate (replace "provider-boilerplate" with the name of your provider)
- Description: Pulumi provider for xyz
- Repository type: Public
Clone the generated repository.

From the templated repository:

Run the following command to update files to use the name of your provider (third-party: use your GitHub organization/username):
```
make prepare NAME=foo ORG=myorg REPOSITORY=github.com/myorg/pulumi-foo
```
This will do the following:
- rename folders in provider/cmd to pulumi-resource-{NAME}
- replace dependencies in provider/go.mod to reflect your repository name
- find and replace all instances of provider-boilerplate with the NAME of your provider.
- find and replace all instances of the boilerplate abc with the ORG of your provider.
- replace all instances of the github.com/pulumi/pulumi-provider-boilerplate repository with the REPOSITORY location

Build the provider and install the plugin

$ make build install

This will:

Create the SDK codegen binary and place it in a ./bin folder (gitignored)
Create the provider binary and place it in the ./bin folder (gitignored)
Generate the dotnet, Go, Node, and Python SDKs and place them in the ./sdk folder
Install the provider on your machine.

Test against the example

$ cd examples/simple
$ yarn link @pulumi/provider-boilerplate
$ yarn install
$ pulumi stack init test
$ pulumi up

Now that you have completed all of the above steps, you have a working provider that generates a random string for you.

A brief repository overview

You now have:

A provider/ folder containing the building and implementation logic.
1. cmd/pulumi-resource-provider-boilerplate/main.go - holds the provider's sample implementation logic.
Makefile - targets to help with building and publishing the provider. Run make ci-mgmt to regenerate CI workflows.
sdk - holds the generated code libraries created by pulumi gen-sdk.
examples a folder of Pulumi programs to try locally and/or use in CI.
A Makefile and this README.

Additional Details

This repository depends on the pulumi-go-provider library. For more details on building providers, please check the Pulumi Go Provider docs.

Build Examples

Create an example program using the resources defined in your provider, and place it in the examples/ folder.

You can now repeat the steps for build, install, and test.

Configuring CI and releases

Follow the instructions laid out in the deployment templates.

References

Other resources/examples for implementing providers:

Release files for pulumi-provider-boilerplate 0.0.36a1756384715

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for pulumi-provider-boilerplate 0.0.36a1756384715
File	Size	Uploaded
pulumi_provider_boilerplate-0.0.36a1756384715.tar.gz	11.1 kB	Aug 28, 2025	Details

Built distribution (wheel)

Table of built distributions (wheels) for pulumi-provider-boilerplate 0.0.36a1756384715
File	Interpreter	ABI	Platform	Reset
pulumi_provider_boilerplate-0.0.36a1756384715-py3-none-any.whl 14.0 kB Aug 28, 2025	Python 3	none	any	Details

Total release size: 25.1 kB

Release files / pulumi_provider_boilerplate-0.0.36a1756384715.tar.gz

Download URL	pulumi_provider_boilerplate-0.0.36a1756384715.tar.gz
Size	11.1 kB
Tags	Source
SHA-256 checksum How to use checksums	`010db3e1c3ccecbe0b5ef8d105c81d9fd0da8a271b784f6cce4e53ca375b1808`
BLAKE2b-256 checksum How to use checksums	`ecb76b8e8d92498282e285e51cbe1e6d0682983615a6363e72c6af585e73cfdc`
Upload date	Aug 28, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.11.8`

Release files / pulumi_provider_boilerplate-0.0.36a1756384715-py3-none-any.whl

Download URL	pulumi_provider_boilerplate-0.0.36a1756384715-py3-none-any.whl
Size	14.0 kB
Tags	Python 3
SHA-256 checksum How to use checksums	`5dd4f11dc289d1e5a228053a89cca20db9357931a3a8d96db3f11409bbcf0e33`
BLAKE2b-256 checksum How to use checksums	`2c6bd764c96c4370e588ebe0852200f7f303791e7f568beac8eaf50b064c8e3f`
Upload date	Aug 28, 2025
Uploaded using Trusted Publishing? What is trusted publishing?	No
Uploaded via	`twine/5.0.0 CPython/3.11.8`