Create A Pulumi Provider From OpenAPI Spec
Learn how to create a native Pulumi provider an OpenAPI 3.x spec.
This article explains how you can use pulschema to create a native Pulumi provider from an OpenAPI 3.x spec.
There are two parts to a provider: the language-specific SDK and the provider binary that handles interaction with the cloud provider REST API.
Understanding Pulumi Providers
Pulumi providers implement the ResourceProviderServer interface.
For most providers, the following methods are what you will need implement:
CheckConfigConfigureDiffCreateReadUpdateDeleteInvoke
What the provider does in each of those methods is up to the provider implementation. Of course, the goal is to implement what the doc comment for each of those functions states.
On the other end of this is the cloud provider's REST API. The provider essentially acts as an HTTP client that calls the REST API.
REST API Endpoints And Resources
Each REST API endpoint corresponds to a "resource". These are identified by Pulumi type tokens. A Pulumi type token has the format package:module:resource. You can use type tokens to identify the REST API endpoint that you need to call from the provider.
If you are wondering how type tokens are associated with all the possible endpoints for that resource, don't worry pulschema will help you with that and you'll read about it later in this post.
Pulumi Schema
It's time to introduce the Pulumi Schema.
The schema is to used to generate each of the language-specific SDK. It's this schema that can be generated using pulschema. pulschema converts an OpenAPI spec to Pulumi schema which is then used to generate the language-specific SDKs. The language-specific SDKs is what users use in their infrastructure app to create resources. The REST API interaction part is implemented by pulumi-provider-framework; a library that handles all the REST API interactions for the provider.
Artifacts Generated By pulschema
pulschema will output a schema.json file that represents the Pulumi schema interpreted from the OpenAPI doc provided to it. The other file generated by pulschema is a metadata.json. The metadata file contains mapping of resource type tokens to the CRUD endpoints for a particular resource. It can be used to determine the appropriate REST API endpoint to call based on the resource type token.
OpenAPI Conformance
Several cloud providers use code generation tools that generate invalid specs. You'll need to fix those validation errors as well as ensure that the spec is conformant as outlined in the cloud-provider-api-conformance repo.
If your OpenAPI spec is non-conformant or invalid, you may use kin-api to modify the appropriate parts of the spec using regular Go code, before it is passed to pulschema. I do NOT recommend hand-editing the OpenAPI spec since it'll be hard for you to absorb updates to the original spec from the cloud provider. If you are a member of the cloud provider, then you may want to fix the issues in the source in order to generate a conformant API spec.
How To Use pulschema
Finally, you are now ready to use pulschema. You can start with the template repo that will get you started with generating a Pulumi schema.
As mentioned earlier, the Pulumi schema is used to generate the SDKs, so the template repo can produce two binaries, a "gen" binary -- responsible for generating certain artifacts like the SDKs, and a "provider" binary -- responsible for handling the lifecycle of resources that you use in your Pulumi infrastructure app.
The Makefile in the root of the repo allows you to generate the schema, build SDKs and the provider binary. The provider binary is also called the "provider plugin". It is what gets installed when you install a language-specific SDK in your Pulumi infrastructure app. (Hint: try running pulumi plugin ls on your machine, if you have ever run a Pulumi app before, chances are you have a plugin or two still installed on your machine; they are the provider binaries.)
Useful Links
- Learn more about the anatomy of a Pulumi provider
- Explore providers already built using
pulschema - Read the official guide about publishing a provider package, which also gives you an overview of how to use GitHub or GitLab to serve the plugin binary for your provider