Skip to content

Latest commit

 

History

History
110 lines (76 loc) · 4.83 KB

contributing-guide.md

File metadata and controls

110 lines (76 loc) · 4.83 KB
Raw

Working with The Provider

Background

Learn about the concepts behind Pulumi Packages.

Follow this link to see an architecture diagram for Pulumi.

A Pulumi Resource Provider:

  • is a gRPC server which allows for the Pulumi engine to create resources in a specific cloud
  • holds the lifecycle logic for these cloud resources
  • holds a pulumi JSON schema that describes the provider
  • provides language-specific SDKs so resources can be created in whichever language you prefer

When we speak of a "native" provider, we mean that all implementation is native to Pulumi.

Prerequisites

Ensure the following tools are installed and present in your $PATH:

Repository

Build the provider and install the plugin

$ 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

$ cd examples/simple
$ yarn link @pulumi/esxi-native
$ yarn install
$ pulumi stack init test
$ pulumi up

A brief repository overview

You now have:

  1. A provider/ folder containing the building and implementation logic
    1. cmd/
      1. pulumi-gen-esxi-native/ - generates language SDKs from the schema
      2. pulumi-resource-esxi-native/ - holds the package schema, injects the package version, and starts the gRPC server
    2. pkg
      1. provider - holds the gRPC methods (and for now, the sample implementation logic) required by the Pulumi engine
      2. version - semver package to be consumed by build processes
  2. sdk - holds the generated code libraries created by pulumi-gen-esxi-native/main.go
  3. examples a folder of Pulumi programs to try locally and/or use in CI.
  4. A Makefile and this README.

Writing the schema

The JSON schema file is used by pulumi-gen-esxi-native to create language-specific SDKs. It is, therefore, a central requirement for any resource provider. Provider schemas can be handwritten, or alternatively machine-generated by combining API specification with pulumi-specific logic.

This repository provides the esxi-native schema to get you started. Refer to the package schema documentation for additional details when writing the schema.

Implementing the gRPC methods

Once you have a schema that describes all the resources and metadata for your provider, you will need to implement the desired gRPC methods. You will find a mostly blank implementation of these in pkg/provider/provider.go. Note that these methods do not link 1:1 to the Pulumi CLI commands.

Basic Functionality

The struct and creation of the provider are implemented already, the main functionalities are provided in the following methods:

  1. Check - validates resource Inputs
  2. Diff - calculates the differences between the actual and the desired state of a resource
  3. Create - creates a new instance of a resource from an Input
  4. Update - updates a resource in-place (i.e. without deleting/recreating)
  5. Read - reads current inputs and state for a resource
  6. Delete - deletes a resource and its corresponding state

Resource lifecycle methods are documented here.

The following methods are necessary for every provider and are already implemented:

  1. GetPluginInfo - returns generic information about this plugin, like its version
  2. GetSchema - returns the Pulumi schema to the provider

Build Examples

Create an example program using the resources defined in the provider, and place it in the examples/ folder.

You can now repeat the steps for build, install, and test.

Documentation

Please follow this guide to add documentation to the provider.