# Pulumi Native Provider Boilerplate
This repository is a boilerplate showing how to create and locally test a native Pulumi provider.
## Authoring a Pulumi Native Provider
This boilerplate creates a working Pulumi-owned provider named `xyz`.
It implements a random number generator that you can [build and test out for yourself](#test-against-the-example) and then replace the Random code with code specific to your provider.
### Prerequisites
Prerequisites for this repository are already satisfied by the [Pulumi Devcontainer](https://github.com/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`](https://github.com/pulumi/pulumictl#installation)
* [Go 1.21](https://golang.org/dl/) or 1.latest
* [NodeJS](https://nodejs.org/en/) 14.x. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage NodeJS installations.
* [Yarn](https://yarnpkg.com/)
* [TypeScript](https://www.typescriptlang.org/)
* [Python](https://www.python.org/downloads/) (called as `python3`). For recent versions of MacOS, the system-installed version is fine.
* [.NET](https://dotnet.microsoft.com/download)
### Build & test the boilerplate XYZ provider
1. Create a new Github CodeSpaces environment using this repository.
1. Open a terminal in the CodeSpaces environment.
1. Run `make build install` to build and install the provider.
1. Run `make gen_examples` to generate the example programs in `examples/` off of the source `examples/yaml` example program.
1. Run `make up` to run the example program in `examples/yaml`.
1. Run `make down` to tear down the example program.
### Creating a new provider repository
Pulumi offers this repository as a [GitHub template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) for convenience. From this repository:
1. Click "Use this template".
1. Set the following options:
* Owner: pulumi
* Repository name: pulumi-xyz-native (replace "xyz" with the name of your provider)
* Description: Pulumi provider for xyz
* Repository type: Public
1. Clone the generated repository.
From the templated repository:
1. Search-replace `xyz` with the name of your desired provider.
#### Build the provider and install the plugin
```bash
$ make build install
```
This will:
1. Create the SDK codegen binary and place it in a `./bin` folder (gitignored)
2. Create the provider binary and place it in the `./bin` folder (gitignored)
3. Generate the dotnet, Go, Node, and Python SDKs and place them in the `./sdk` folder
4. Install the provider on your machine.
#### Test against the example
```bash
$ cd examples/simple
$ yarn link @pulumi/xyz
$ 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:
1. A `provider/` folder containing the building and implementation logic
1. `cmd/pulumi-resource-xyz/main.go` - holds the provider's sample implementation logic.
2. `deployment-templates` - a set of files to help you around deployment and publication
3. `sdk` - holds the generated code libraries created by `pulumi-gen-xyz/main.go`
4. `examples` a folder of Pulumi programs to try locally and/or use in CI.
5. 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](https://github.com/pulumi/pulumi-go-provider).
### 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](#test-against-the-example).
## Configuring CI and releases
1. Follow the instructions laid out in the [deployment templates](./deployment-templates/README-DEPLOYMENT.md).
## References
Other resources/examples for implementing providers:
* [Pulumi Command provider](https://github.com/pulumi/pulumi-command/blob/master/provider/pkg/provider/provider.go)
* [Pulumi Go Provider repository](https://github.com/pulumi/pulumi-go-provider)
Raw data
{
"_id": null,
"home_page": null,
"name": "pulumi-dockerbuild",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": "docker, buildkit, buildx",
"author": null,
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/16/07/3a79e201a1b187c25560b6afbd5b4a34d1e68363ec5ea4911ea62045fb79/pulumi_dockerbuild-0.0.1a2.tar.gz",
"platform": null,
"description": "# Pulumi Native Provider Boilerplate\n\nThis repository is a boilerplate showing how to create and locally test a native Pulumi provider.\n\n## Authoring a Pulumi Native Provider\n\nThis boilerplate creates a working Pulumi-owned provider named `xyz`.\nIt implements a random number generator that you can [build and test out for yourself](#test-against-the-example) and then replace the Random code with code specific to your provider.\n\n\n### Prerequisites\n\nPrerequisites for this repository are already satisfied by the [Pulumi Devcontainer](https://github.com/pulumi/devcontainer) if you are using Github Codespaces, or VSCode.\n\nIf you are not using VSCode, you will need to ensure the following tools are installed and present in your `$PATH`:\n\n* [`pulumictl`](https://github.com/pulumi/pulumictl#installation)\n* [Go 1.21](https://golang.org/dl/) or 1.latest\n* [NodeJS](https://nodejs.org/en/) 14.x. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage NodeJS installations.\n* [Yarn](https://yarnpkg.com/)\n* [TypeScript](https://www.typescriptlang.org/)\n* [Python](https://www.python.org/downloads/) (called as `python3`). For recent versions of MacOS, the system-installed version is fine.\n* [.NET](https://dotnet.microsoft.com/download)\n\n\n### Build & test the boilerplate XYZ provider\n\n1. Create a new Github CodeSpaces environment using this repository.\n1. Open a terminal in the CodeSpaces environment.\n1. Run `make build install` to build and install the provider.\n1. Run `make gen_examples` to generate the example programs in `examples/` off of the source `examples/yaml` example program.\n1. Run `make up` to run the example program in `examples/yaml`.\n1. Run `make down` to tear down the example program.\n\n### Creating a new provider repository\n\nPulumi offers this repository as a [GitHub template repository](https://docs.github.com/en/repositories/creating-and-managing-repositories/creating-a-repository-from-a-template) for convenience. From this repository:\n\n1. Click \"Use this template\".\n1. Set the following options:\n * Owner: pulumi \n * Repository name: pulumi-xyz-native (replace \"xyz\" with the name of your provider)\n * Description: Pulumi provider for xyz\n * Repository type: Public\n1. Clone the generated repository.\n\nFrom the templated repository:\n\n1. Search-replace `xyz` with the name of your desired provider.\n\n#### Build the provider and install the plugin\n\n ```bash\n $ make build install\n ```\n \nThis will:\n\n1. Create the SDK codegen binary and place it in a `./bin` folder (gitignored)\n2. Create the provider binary and place it in the `./bin` folder (gitignored)\n3. Generate the dotnet, Go, Node, and Python SDKs and place them in the `./sdk` folder\n4. Install the provider on your machine.\n\n#### Test against the example\n \n```bash\n$ cd examples/simple\n$ yarn link @pulumi/xyz\n$ yarn install\n$ pulumi stack init test\n$ pulumi up\n```\n\nNow that you have completed all of the above steps, you have a working provider that generates a random string for you.\n\n#### A brief repository overview\n\nYou now have:\n\n1. A `provider/` folder containing the building and implementation logic\n 1. `cmd/pulumi-resource-xyz/main.go` - holds the provider's sample implementation logic.\n2. `deployment-templates` - a set of files to help you around deployment and publication\n3. `sdk` - holds the generated code libraries created by `pulumi-gen-xyz/main.go`\n4. `examples` a folder of Pulumi programs to try locally and/or use in CI.\n5. A `Makefile` and this `README`.\n\n#### Additional Details\n\nThis repository depends on the pulumi-go-provider library. For more details on building providers, please check\nthe [Pulumi Go Provider docs](https://github.com/pulumi/pulumi-go-provider).\n\n### Build Examples\n\nCreate an example program using the resources defined in your provider, and place it in the `examples/` folder.\n\nYou can now repeat the steps for [build, install, and test](#test-against-the-example).\n\n## Configuring CI and releases\n\n1. Follow the instructions laid out in the [deployment templates](./deployment-templates/README-DEPLOYMENT.md).\n\n## References\n\nOther resources/examples for implementing providers:\n* [Pulumi Command provider](https://github.com/pulumi/pulumi-command/blob/master/provider/pkg/provider/provider.go)\n* [Pulumi Go Provider repository](https://github.com/pulumi/pulumi-go-provider)\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "A Pulumi provider for Docker buildx",
"version": "0.0.1a2",
"project_urls": {
"Homepage": "https://pulumi.io",
"Repository": "https://github.com/pulumi/pulumi-dockerbuild"
},
"split_keywords": [
"docker",
" buildkit",
" buildx"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "ecb837e17daf246fca0eaf61822f3a949f07abf0108a2daab2795128142697ad",
"md5": "428379178e9c50fde668934a8c379815",
"sha256": "e2db113bf179e62a0eb7b0b23831903edd0377d48b640f7a7bd37e010a31bbec"
},
"downloads": -1,
"filename": "pulumi_dockerbuild-0.0.1a2-py3-none-any.whl",
"has_sig": false,
"md5_digest": "428379178e9c50fde668934a8c379815",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 41051,
"upload_time": "2024-03-29T23:35:47",
"upload_time_iso_8601": "2024-03-29T23:35:47.627657Z",
"url": "https://files.pythonhosted.org/packages/ec/b8/37e17daf246fca0eaf61822f3a949f07abf0108a2daab2795128142697ad/pulumi_dockerbuild-0.0.1a2-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "16073a79e201a1b187c25560b6afbd5b4a34d1e68363ec5ea4911ea62045fb79",
"md5": "0a7fdb39a512606f0b09fd0723ab92ae",
"sha256": "b11b4fde16c2e971c75d8832753c2c2dd3568c739bdbac275ba20c9e8e19341c"
},
"downloads": -1,
"filename": "pulumi_dockerbuild-0.0.1a2.tar.gz",
"has_sig": false,
"md5_digest": "0a7fdb39a512606f0b09fd0723ab92ae",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 37829,
"upload_time": "2024-03-29T23:35:48",
"upload_time_iso_8601": "2024-03-29T23:35:48.713179Z",
"url": "https://files.pythonhosted.org/packages/16/07/3a79e201a1b187c25560b6afbd5b4a34d1e68363ec5ea4911ea62045fb79/pulumi_dockerbuild-0.0.1a2.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-03-29 23:35:48",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "pulumi",
"github_project": "pulumi-dockerbuild",
"github_not_found": true,
"lcname": "pulumi-dockerbuild"
}
JSON
