https://github.com/pulumi/pulumi-component-provider-py-boilerplate
Demonstrates building a multi-lang Pulumi component provider in Python
https://github.com/pulumi/pulumi-component-provider-py-boilerplate
Last synced: about 2 months ago
JSON representation
Demonstrates building a multi-lang Pulumi component provider in Python
- Host: GitHub
- URL: https://github.com/pulumi/pulumi-component-provider-py-boilerplate
- Owner: pulumi
- License: apache-2.0
- Created: 2021-04-16T20:13:01.000Z (about 4 years ago)
- Default Branch: main
- Last Pushed: 2024-06-24T22:07:17.000Z (12 months ago)
- Last Synced: 2025-04-17T14:32:50.340Z (about 2 months ago)
- Language: Python
- Size: 224 KB
- Stars: 20
- Watchers: 22
- Forks: 11
- Open Issues: 11
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# Pulumi Component Boilerplate (Python)
This repository builds a working Pulumi component in Python. You
can use it as a boilerplate for creating your own component provider by search-replacing `xyz` with your chosen name.
### Background
This repository is part of the [guide for authoring and publishing a Pulumi Package](https://www.pulumi.com/docs/guides/pulumi-packages/how-to-author).
Learn about the concepts behind [Pulumi Packages](https://www.pulumi.com/docs/guides/pulumi-packages/#pulumi-packages) and, more specifically, [Pulumi Components](https://www.pulumi.com/docs/intro/concepts/resources/components/)
## Sample xyz Component Provider
Pulumi component providers make
[component resources](https://www.pulumi.com/docs/intro/concepts/resources/#components)
available to Pulumi code in all supported programming languages.
Specifically, `xyz` component provider defines an example `StaticPage`
component resource that provisions a public AWS S3 HTML page.
The important pieces include:
- [schema.json](schema.json) declaring the `StaticPage` interface
- [xyz_provider](provider/cmd/pulumi-resource-xyz/xyz_provider/provider.py) package
implementing `StaticPage` using typical Pulumi Python code
From here, the build generates:
- SDKs for Python, Go, .NET, and Node (under `sdk/`)
- `pulumi-resource-xyz` Pulumi plugin (under `bin/`)
Users can deploy `StaticPage` instances in their language of choice,
as seen in the [TypeScript example](examples/simple/index.ts). Only
two things are needed to run `pulumi up`:
- the code needs to reference the `xyz` SDK package
- `pulumi-resource-xyz` needs to be on `PATH` for `pulumi` to find it
## Prerequisites
- Pulumi CLI
- Python 3.6+
- Node.js
- Yarn
- Go 1.17
- Node.js (to build the Node SDK)
- .NET Code SDK (to build the .NET SDK)
## Build and Test
```bash
# Regenerate SDKs
make generate
# Build and install the provider and SDKs
make build
make install
# Test Node.js SDK
$ cd examples/simple
$ yarn install
$ yarn link @pulumi/xyz
$ pulumi stack init test
$ pulumi config set aws:region us-east-1
$ pulumi up
```
## Naming
The `xyz` plugin must be packaged as a `pulumi-resource-xyz` script or
binary (in the format `pulumi-resource-`).
While the plugin must follow this naming convention, the SDK package
naming can be custom.
## Packaging
The `xyz` plugin can be packaged as a tarball for distribution:
```bash
$ make dist
$ ls dist/
pulumi-resource-xyz-v0.0.1-darwin-amd64.tar.gz
pulumi-resource-xyz-v0.0.1-windows-amd64.tar.gz
pulumi-resource-xyz-v0.0.1-linux-amd64.tar.gz
```
Users can install the plugin with:
```bash
pulumi plugin install resource xyz 0.0.1 --file dist/pulumi-resource-xyz-v0.0.1-darwin-amd64.tar.gz
```
The tarball only includes the `xyz_provider` sources. During the
installation phase, `pulumi` will use the user's system Python command
to rebuild a virtual environment and restore dependencies (such as
Pulumi SDK).
TODO explain custom server hosting in more detail.
## Configuring CI and releases
1. Follow the instructions laid out in the [deployment templates](./deployment-templates/README-DEPLOYMENT.md).
## StaticPage Example
### Schema
The component resource's type [token](schema.json#L4)
is `xyz:index:StaticPage` in the
format of `::`. In this case, it's in the `xyz`
package and `index` module. This is the same type token passed inside
the implementation of `StaticPage` in
[staticpage.py](provider/cmd/pulumi-resource-xyz/xyz_provider/staticpage.py#L46),
and also the same token referenced in `construct` in
[provider.py](provider/cmd/pulumi-resource-xyz/xyz_provider/provider.py#L36).
This component has a required `indexContent` input property typed as
`string`, and two required output properties: `bucket` and
`websiteUrl`. Note that `bucket` is typed as the
`aws:s3/bucket:Bucket` resource from the `aws` provider (in the schema
the `/` is escaped as `%2F`).
Since this component returns a type from the `aws` provider, each SDK
must reference the associated Pulumi `aws` SDK for the language. For
the .NET, Node.js, and Python SDKs, dependencies are specified in the
[language section](schema.json#31) of the schema.
### Implementation
The key method to implement is
[construct](provider/cmd/pulumi-resource-xyz/xyz_provider/provider.py#L36)
on the `Provider` class. It receives `Inputs` representing arguments the user passed,
and returns a `ConstructResult` with the new StaticPage resource `urn` an state.
It is important that the implementation aligns the structure of inptus
and outputs with the interface declared in `schema.json`.