|
1 | | -# Pulumi Native Provider Template |
| 1 | +# Pulumi Native Provider for Scaleway Instances (Preview) |
2 | 2 |
|
3 | | -This repository is a boilerplate showing how to create a native Pulumi provider using the [Pulumi Provider Framework](https://github.com/cloudy-sky-software/pulumi-provider-framework). |
| 3 | +[Scaleway Instances](https://www.scaleway.com/en/virtual-instances/). Build, deploy and scale applications on Europe's most complete cloud ecosystem. |
4 | 4 |
|
5 | | -### Background |
| 5 | +> This provider was generated using [`pulschema`](https://github.com/cloudy-sky-software/pulschema) and [`pulumi-provider-framework`](https://github.com/cloudy-sky-software/pulumi-provider-framework). |
6 | 6 |
|
7 | | -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). |
| 7 | +## Package SDKs |
8 | 8 |
|
9 | | -Learn about the concepts behind [Pulumi Packages](https://www.pulumi.com/docs/guides/pulumi-packages/#pulumi-packages). |
| 9 | +- Node.js: https://www.npmjs.com/package/@cloudyskysoftware/pulumi-scaleway-instances |
| 10 | +- Python: https://pypi.org/project/pulumi_scaleway_instances/ |
| 11 | +- .NET: https://www.nuget.org/packages/Pulumi.ScalewayInstances |
| 12 | +- Go: `import github.com/cloudy-sky-software/pulumi-scaleway-instances/sdk/go/sclwyinst` |
10 | 13 |
|
11 | | -Follow this link to see [an architecture diagram for Pulumi](https://www.pulumi.com/docs/intro/concepts/how-pulumi-works/#how-pulumi-works). |
| 14 | +## Using The Provider |
12 | 15 |
|
13 | | -A Pulumi Resource Provider: |
| 16 | +You'll need an API key. Follow Scaleway's [docs](https://developers.scaleway.com/en/quickstart/#authentication) to create one or head straight to the [credential section](https://console.scaleway.com/project/credentials) in their web console. |
| 17 | +Then set the API key as a secret with `pulumi config set --secret scaleway-instances:apiKey`. |
14 | 18 |
|
15 | | -- is a gRPC server which allows for the Pulumi engine to create resources in a specific cloud |
16 | | -- holds the lifecycle logic for these cloud resources |
17 | | -- holds a pulumi JSON schema that describes the provider |
18 | | -- provides language-specific SDKs so resources can be created in whichever language you prefer |
| 19 | +## Releasing A New Version |
19 | 20 |
|
20 | | -When we speak of a "native" provider, we mean that all implementation is native to Pulumi, as opposed |
21 | | -to [Terraform based providers](https://github.com/pulumi/pulumi-tf-provider-boilerplate). |
| 21 | +:info: Switch to the `main` branch first and get the latest `git pull origin main && git fetch`. Check what the last release tag was. |
22 | 22 |
|
23 | | -## Authoring a Pulumi Native Provider |
| 23 | +1. Regular releases should just increment the patch version unless a minor or a major (breaking changes) version bump is warranted. |
| 24 | +1. Update the `CHANGELOG.md` with notes about what will be included in this release. |
| 25 | +1. Commit the changelog with `git commit -am "vX.Y.Z"` or something similar and push `git push origin main`. |
| 26 | +1. Tag the commit with the release version by running |
24 | 27 |
|
25 | | -The following instructions assume that the provider is written for the Pulumi organisation. |
26 | | -In the future, we will add instruction for providers published and maintained by the Pulumi community, referred to as "third-party" providers. |
| 28 | + ```bash |
| 29 | + git tag vX.Y.Z |
| 30 | + git tag sdk/vX.Y.Z |
| 31 | + ``` |
27 | 32 |
|
28 | | -This boilerplate creates a working Pulumi-owned provider named `scaleway-instances`. |
29 | | -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. |
| 33 | +1. Push the tags. |
30 | 34 |
|
31 | | -### Prerequisites |
32 | | - |
33 | | -Ensure the following tools are installed and present in your `$PATH`: |
34 | | - |
35 | | -- [`pulumictl`](https://github.com/pulumi/pulumictl#installation) |
36 | | -- [Go 1.17](https://golang.org/dl/) or 1.latest |
37 | | -- [NodeJS](https://nodejs.org/en/) 14.x. We recommend using [nvm](https://github.com/nvm-sh/nvm) to manage NodeJS installations. |
38 | | -- [Yarn](https://yarnpkg.com/) |
39 | | -- [TypeScript](https://www.typescriptlang.org/) |
40 | | -- [Python](https://www.python.org/downloads/) (called as `python3`). For recent versions of MacOS, the system-installed version is fine. |
41 | | -- [.NET](https://dotnet.microsoft.com/download) |
42 | | - |
43 | | -### Creating and Initializing the Repository |
44 | | - |
45 | | -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: |
46 | | - |
47 | | -1. Click "Use this template". |
48 | | -1. Set the following options: |
49 | | - - Owner: pulumi |
50 | | - - Repository name: pulumi-scaleway-instances-native (replace "scaleway-instances" with the name of your provider) |
51 | | - - Description: Pulumi provider for scaleway-instances |
52 | | - - Repository type: Public |
53 | | -1. Clone the generated repository. |
54 | | - |
55 | | -From the templated repository: |
56 | | - |
57 | | -1. Search-replace `scaleway-instances` with the name of your desired provider. |
58 | | - |
59 | | -#### Build the provider and install the plugin |
60 | | - |
61 | | -```bash |
62 | | -$ make build install |
63 | | -``` |
64 | | - |
65 | | -This will: |
66 | | - |
67 | | -1. Create the SDK codegen binary and place it in a `./bin` folder (gitignored) |
68 | | -2. Create the provider binary and place it in the `./bin` folder (gitignored) |
69 | | -3. Generate the dotnet, Go, Node, and Python SDKs and place them in the `./sdk` folder |
70 | | -4. Install the provider on your machine. |
71 | | - |
72 | | -#### Test against the example |
73 | | - |
74 | | -```bash |
75 | | -$ cd examples/simple |
76 | | -$ yarn link @pulumi/scaleway-instances |
77 | | -$ yarn install |
78 | | -$ pulumi stack init test |
79 | | -$ pulumi up |
80 | | -``` |
81 | | - |
82 | | -Now that you have completed all of the above steps, you have a working provider that generates a random string for you. |
83 | | - |
84 | | -#### A brief repository overview |
85 | | - |
86 | | -You now have: |
87 | | - |
88 | | -1. A `provider/` folder containing the building and implementation logic |
89 | | - 1. `cmd/` |
90 | | - 1. `pulumi-gen-scaleway-instances/` - generates language SDKs from the schema |
91 | | - 2. `pulumi-resource-scaleway-instances/` - holds the package schema, injects the package version, and starts the gRPC server |
92 | | - 2. `pkg` |
93 | | - 1. `provider` - holds the gRPC methods (and for now, the sample implementation logic) required by the Pulumi engine |
94 | | - 2. `version` - semver package to be consumed by build processes |
95 | | -2. `deployment-templates` - a set of files to help you around deployment and publication |
96 | | -3. `sdk` - holds the generated code libraries created by `pulumi-gen-scaleway-instances/main.go` |
97 | | -4. `examples` a folder of Pulumi programs to try locally and/or use in CI. |
98 | | -5. A `Makefile` and this `README`. |
99 | | - |
100 | | -### Writing the schema |
101 | | - |
102 | | -The [JSON schema file](https://www.pulumi.com/docs/guides/pulumi-packages/schema) is used by `pulumi-gen-scaleway-instances` to create language-specific SDKs. |
103 | | -It is, therefore, a central requirement for any resource provider. |
104 | | -Provider schemas can be handwritten, or alternatively machine-generated by combining API specification with pulumi-specific logic. |
105 | | - |
106 | | -When writing the schema by hand, it is helpful to associate the JSON schema in your IDE for completion or Intellisense features to work: |
107 | | - |
108 | | -- Visual Studio Code: the easiest option is to [map the schema file](https://code.visualstudio.com/Docs/languages/json#_mapping-in-the-user-settings) |
109 | | - in your User Settings which enables it for all your provider projects: |
110 | | - ```json |
111 | | - "json.schemas": [ |
112 | | - { |
113 | | - "fileMatch": [ |
114 | | - "/provider/cmd/pulumi-*/schema.json" |
115 | | - ], |
116 | | - "url": "https://raw.githubusercontent.com/pulumi/pulumi/master/pkg/codegen/schema/pulumi.json" |
117 | | - } |
118 | | - ] |
119 | | - ``` |
120 | | - |
121 | | -This repository provides the [scaleway-instances example schema](./provider/cmd/pulumi-resource-scaleway-instances/schema.json) to get you started. |
122 | | -[The AWS Native Provider schema](https://github.com/pulumi/pulumi-aws-native/blob/master/provider/cmd/pulumi-resource-aws-native/schema.json) provides a much larger example. |
123 | | -Refer to the [package schema documentation](https://www.pulumi.com/docs/guides/pulumi-packages/schema/#pulumi-package-schema) for additional details when writing the schema. |
124 | | - |
125 | | -### Implementing the gRPC methods |
126 | | - |
127 | | -Once you have a schema that describes all the resources and metadata for your provider, you will need to implement the desired gRPC methods. |
128 | | -You will find a mostly blank implementation of these in `pkg/provider/provider.go`. |
129 | | -Note that these methods do not link 1:1 to the Pulumi CLI commands. |
130 | | - |
131 | | -#### Basic Functionality |
132 | | - |
133 | | -The struct and creation of the provider are implemented already: |
134 | | - |
135 | | -```go |
136 | | -// provider/pkg/provider.go |
137 | | -type scaleway-instancesProvider struct { |
138 | | - host *provider.HostClient |
139 | | - name string |
140 | | - version string |
141 | | - schema []byte |
142 | | -} |
143 | | - |
144 | | -func makeProvider(host *provider.HostClient, name, version string, pulumiSchema []byte) (pulumirpc.ResourceProviderServer, error) { |
145 | | - // Return the new provider |
146 | | - return &scaleway-instancesProvider{ |
147 | | - host: host, |
148 | | - name: name, |
149 | | - version: version, |
150 | | - schema: pulumiSchema, |
151 | | - }, nil |
152 | | -} |
153 | | -``` |
154 | | - |
155 | | -You need to provide the following methods: |
156 | | - |
157 | | -1. Check - validates resource Inputs |
158 | | -2. Diff - calculates the differences between the actual and the desired state of a resource |
159 | | -3. Create - creates a new instance of a resource from an Input |
160 | | -4. Update - updates a resource in-place (i.e. without deleting/recreating) |
161 | | -5. Read - reads current inputs and state for a resource |
162 | | -6. Delete - deletes a resource and its corresponding state |
163 | | - |
164 | | -[Resource lifecycle methods are documented here](https://pulumi-developer-docs.readthedocs.io/en/stable/providers/implementers-guide.html#custom-resource-lifecycle). |
165 | | - |
166 | | -The following methods are necessary for every provider and are already implemented: |
167 | | - |
168 | | -1. GetPluginInfo - returns generic information about this plugin, like its version |
169 | | -2. GetSchema - returns the Pulumi schema to the provider |
170 | | - |
171 | | -#### Additional Methods |
172 | | - |
173 | | -The [resource provider service](https://github.com/pulumi/pulumi/blob/master/sdk/proto/provider.proto) includes a few more gRPC methods that you may need to implement and can read more about. |
174 | | - |
175 | | -### Build Examples |
176 | | - |
177 | | -Create an example program using the resources defined in your provider, and place it in the `examples/` folder. |
178 | | - |
179 | | -You can now repeat the steps for [build, install, and test](#test-against-the-example). |
180 | | - |
181 | | -## Documentation |
182 | | - |
183 | | -Please [follow this guide to add documentation to your provider](https://www.pulumi.com/docs/guides/pulumi-packages/how-to-author/#write-documentation). |
184 | | - |
185 | | -## Configuring CI and releases |
186 | | - |
187 | | -1. Follow the instructions laid out in the [deployment templates](./deployment-templates/README-DEPLOYMENT.md). |
188 | | - |
189 | | -## References |
190 | | - |
191 | | -Other resources for learning about the Pulumi resource model: |
192 | | - |
193 | | -- [Pulumi Kubernetes provider](https://github.com/pulumi/pulumi-kubernetes/blob/master/provider/pkg/provider/provider.go) |
194 | | -- [Pulumi Terraform Remote State provider](https://github.com/pulumi/pulumi-terraform/blob/master/provider/cmd/pulumi-resource-terraform/provider.go) |
195 | | -- [Dynamic Providers](https://www.pulumi.com/docs/intro/concepts/programming-model/#dynamicproviders) |
| 35 | + ```bash |
| 36 | + git push --tags |
| 37 | + ``` |
0 commit comments