sam_oneal/pulumi-docker-build
1
0
Fork 0
Code Actions Packages Releases Wiki Activity

Initial provider implementation (#18)

Browse Source 
This brings over the initial buildx prototype from pulumi/pulumi-docker
and fixes various build and release issues.
This commit is contained in:
Bryce Lampe
2024-04-25 11:03:59 -07:00
committed by GitHub
parent 2545dd3089
commit 26c144c916
398 changed files with 65361 additions and 1702 deletions
Download Patch File Download Diff File Expand all files Collapse all files

117
README.md
View File

@@ -1,106 +1,23 @@
# Pulumi Native Provider Boilerplate
[![Slack](http://www.pulumi.com/images/docs/badges/slack.svg)](https://slack.pulumi.com)
[![NPM version](https://badge.fury.io/js/%40pulumi%2fdocker-build.svg)](https://www.npmjs.com/package/@pulumi/docker-build)
[![Python version](https://badge.fury.io/py/pulumi-docker-build.svg)](https://pypi.org/project/pulumi-docker-build)
[![NuGet version](https://badge.fury.io/nu/pulumi.dockerbuild.svg)](https://badge.fury.io/nu/pulumi.dockerbuild)
[![PkgGoDev](https://pkg.go.dev/badge/github.com/pulumi/pulumi-docker-build/sdk/go)](https://pkg.go.dev/github.com/pulumi/pulumi-docker-build/sdk/go)
[![License](https://img.shields.io/npm/l/%40pulumi%2Fpulumi.svg)](https://github.com/pulumi/pulumi-docker-build/blob/main/LICENSE)
This repository is a boilerplate showing how to create and locally test a native Pulumi provider.
# Docker-Build Resource Provider
## Authoring a Pulumi Native Provider
A [Pulumi](http://pulumi.com) provider for building modern Docker images with [buildx](https://docs.docker.com/build/architecture/) and [BuildKit](https://docs.docker.com/build/buildkit/).
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.
Not to be confused with the earlier
[Docker](http://github.com/pulumi/pulumi-docker) provider, which is still
appropriate for managing resources unrelated to building images.
| Provider | Use cases |
| ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `@pulumi/docker-build` | Anything related to building images with `docker build`. |
| `@pulumi/docker` | Everything else -- including running containers and creating networks. |
### Prerequisites
## Reference
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)
For more information, including examples and migration guidance, please see the Docker-Build provider's detailed [API documentation](https://www.pulumi.com/registry/packages/docker-build/).