diff --git a/README.md b/README.md index 4a0b457..a4a8af5 100644 --- a/README.md +++ b/README.md @@ -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/). diff --git a/sdk/nodejs/README.md b/sdk/nodejs/README.md index 4a0b457..a4a8af5 100644 --- a/sdk/nodejs/README.md +++ b/sdk/nodejs/README.md @@ -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/). diff --git a/sdk/python/README.md b/sdk/python/README.md index 4a0b457..a4a8af5 100644 --- a/sdk/python/README.md +++ b/sdk/python/README.md @@ -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/).