This repository is a boilerplate showing how to create and locally test a native Pulumi provider.
This boilerplate creates a working Pulumi-owned provider named synadia-cloud
.
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 for this repository are already satisfied by the Pulumi Devcontainer if you are using Github Codespaces, or VSCode.
If you are not using VSCode, 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
- Create a new Github CodeSpaces environment using this repository.
- Open a terminal in the CodeSpaces environment.
- Run
make build install
to build and install the provider. - Run
make gen_examples
to generate the example programs inexamples/
off of the sourceexamples/yaml
example program. - Run
make up
to run the example program inexamples/yaml
. - Run
make down
to tear down the example program.
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-synadia-cloud-native (replace "synadia-cloud" with the name of your provider)
- Description: Pulumi provider for synadia-cloud
- 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 REPOSITORY=github.com/pulumi/pulumi-foo ORG=myorg
This will do the following:
- rename folders in
provider/cmd
topulumi-resource-{NAME}
- replace dependencies in
provider/go.mod
to reflect your repository name - find and replace all instances of the boilerplate
synadia-cloud
with theNAME
of your provider. - find and replace all instances of the boilerplate
rebelopsio
with theORG
of your provider. - replace all instances of the
github.com/rebelopsio/pulumi-synadia-cloud
repository with theREPOSITORY
location
- rename folders in
$ 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.
$ cd examples/simple
$ yarn link @pulumi/synadia-cloud
$ 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.
You now have:
- A
provider/
folder containing the building and implementation logiccmd/pulumi-resource-synadia-cloud/main.go
- holds the provider's sample implementation logic.
deployment-templates
- a set of files to help you around deployment and publicationsdk
- holds the generated code libraries created bypulumi-gen-synadia-cloud/main.go
examples
a folder of Pulumi programs to try locally and/or use in CI.- A
Makefile
and thisREADME
.
This repository depends on the pulumi-go-provider library. For more details on building providers, please check the Pulumi Go Provider docs.
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.
- Follow the instructions laid out in the deployment templates.
Other resources/examples for implementing providers: