Skip to content

Latest commit

 

History

History
158 lines (98 loc) · 10.1 KB

README.md

File metadata and controls

158 lines (98 loc) · 10.1 KB
Raw

Registry

Pulumi Registry is the global index of everything you can do with Pulumi.

Authoring a Pulumi Package

We’re always eager to expand that index with new Pulumi Packages. Whether you want to author a new native provider, bridge a provider from the Terraform ecosystem, or create a cloud component with best practices and sensible defaults built in, we’d like to work with you to list it on Pulumi Registry. To get started, use our guide on authoring a Pulumi Package of your own.

Publishing a Community Package on the Registry

Community Steps

To publish a community-maintained package on the Pulumi Registry as a community member:

  1. Ensure your provider repo has the following files:
    • docs/_index.md, which should contain a summary of the provider's purpose (required) along with a code sample (preferred). This file will render as the index page for your provider (example).
    • docs/installation-configuration.md, which should contain links to SDK packages in each language along with instructions for configuring the provider (e.g., required credentials and/or environment variables). This file will render as the Installation & Configuration page for your provider (example).
  2. Create a release of your provider in GitHub.
  3. Add your package to the community packages list via pull request to this repository.

For assistance, please reach out on the Pulumi community slack or get in touch with us via this contact form.

Pulumi Steps

Once the community member has submitted the PR to add the provider to the registry, a Pulumi staff member should perform the following steps:

  1. Review the PR. Ensure that the PR has been rebased if necessary before merging. If ok, merge.

  2. Once the PR is merged, a scheduled task will pick up the changes and create a PR to add the package metadata to the registry. A correct metadata PR (example) will include the following files, at a minimum:

    • data/registry/${PROVIDER}.yaml which includes structured metadata about the provider. This file is always included with every PR that gets generated for a new release.
    • themes/default/content/registry/packages/${PROVIDER}/installation-configuration.md, as described above. This file must be included in the first release, but will only be included in subsequent PRs if the content has changed.
    • themes/default/content/registry/packages/exoscale/_index.md, as described above. This file must be included in the first release, but will only be included in subsequent PRs if the content has changed.

    Optionally, the PR may include additional content files like How-To Guides if they are present in the upstream repo.

  3. Merge the PR if it looks ok.

  4. In pulumi/docs, a scheduled task runs hourly and will pick up any changes in this repo, generate files from the provider schema and data/registry/${PROVIDER}.yaml, and publish to pulumi.com.

This scheduled task currently lacks adequate monitoring, and should be watched to ensure that it runs correctly to completion. (If it fails, it will block all updates to pulumi.com, including marketing and manually maintained docs pages.)

About this repository

This repository is a Hugo module that doubles as a development server to make it easier to work on the pages that make up Pulumi Registry. It contains most of the Hugo content and layouts files comprising what you see at https://pulumi.com/registry -- but not everything. A few things you won't find in this repository include:

  • JavaScript, CSS, and web component - We build the JavaScript and CSS bundles that power the Pulumi Registry here, under the themes/default/theme directory. If you are making styling changes along-side content changes, use make serve-all to enable hot reloading of both the pages and CSS/JS assets.

  • Layouts and content for pulumi.com marketing pages, CLI docs, the blog, etc., all of which are managed in the pulumi/pulumi-hugo repository.

You can, however, develop locally with this repository using content from these other Hugo-module repositories, either by loading their content remotely or pointing your Hugo development server to local clones of them. More on this below.

Using this repository

Prerequisites

We build the Pulumi website statically with Hugo, manage our Node.js dependencies with Yarn, and write most of our documentation in Markdown. Below is a list of the tools you'll need to run the website locally:

Installing dependencies

The prerequisites listed above need to be installed on your machine in order to serve the site.

  1. Run make ensure to check for the appropriate tools and versions, and install any dependencies. The script will let you know if you're missing anything important.

    make ensure

  2. Once that succeeds, run make build_assets to build the assets the site depends on. This needs to be done before the first time you serve this repo so the assets exist on your local machine.

    make build-assets

Running Hugo locally

Once you've run the above successfully, you're ready to run the development server:

make serve

When you do this, Hugo will load the latest versions of:

  • The pulumi/pulumi-hugo module, which contains our marketing pages, some docs content, the blog, and our CSS and JavaScript bundles (web components, styles, etc.).

... and then start a development server at http://localhost:1313. Any changes you make to the content, layouts, or other Hugo component folders should be reloaded automatically.

Developing alongside another Hugo module

If you want to develop another module alongside this one -- e.g., add a new web component to use in the Registry, or to make changes to Registry-specific CSS -- you can point your development server to a local clone of pulumi/pulumi-hugo. To do that, first clone the repository, then add a replace line to the go.mod file at the root of this repository to override the existing reference to pulumi/pulumi-hugo temporarily. For instance:

module github.com/pulumi/pulumi-hugo

go 1.16

require (
	github.com/pulumi/pulumi-hugo v0.0.0-20211015193555-271ef1f67093 // indirect
)

// Add this line to tell Hugo to use your local clone of pulumi/pulumi-hugo.
replace github.com/pulumi/pulumi-hugo => ../pulumi-hugo

Tip: If you run make serve-assets from the root of pulumi/pulumi-hugo (in another terminal tab) while also running make serve in this one, the changes you make to the CSS and JavaScript source files in pulumi/pulumi-hugo will be recompiled and reloaded in the browser automatically.

Be sure to remove the replace line before you commit.

Temporarily pulling in content from pulumi/docs

If the change you're working on requires content from pulumi/docs -- e.g., the aforementioned how-to guides -- you may want to be able to see some of that content as you develop. To do that, just copy the files you need from the content folder of pulumi/docs into the content folder of this repository, remembering to remove those files before you commit. For example:

# Copy the AWS how-to guides from a local/sibling clone of pulumi/docs.
cp ../docs/content/registry/packages/aws/how-to-guides ./themes/default/content/registry/packages/aws/

Generating API docs for packages

The API docs for packages can be generated on-demand using the resourcedocsgen tool.

cd tools/resourcedocsgen
go build -o "${GOPATH}/bin/resourcedocsgen" .

Run resourcedocsgen --help for help regarding its use or see the resourcedocsgen README.

Submitting, merging and releasing

Before submitting a pull request, run the linter locally:

make lint

When you're ready to submit a pull request, make sure you've removed anything that doesn't seem to belong (go.mod/go.sum changes, content from pulumi/docs, etc.) and submit the PR in the usual way.

If you're doing work in another repository that's associated with the changes in your PR, you can "pin" your PR branch to another module repository branch by pointing Hugo to that branch. To do that, use hugo mod get and pass a reference to the target branch:

hugo mod get github.com/pulumi/pulumi-hugo@my-special-branch

This will modify go.mod and go.sum accordingly and result in a PR preview that incorporates your changes from the other branch. Just be sure to remove these changes before you're ready to merge.

If you would like to generate API docs for packages beyond AWS and Aiven (the docs available in PR previews by default), add the package name you would like docs for in this file. Be sure to remove these changes before merging.

Once your PR is approved and merged into the default branch of this repository, an automated process that runs on pulumi/docs will detect your changes and produce a PR and integration build containing content from all other Hugo modules. Once that PR build completes and is approved and merged into pulumi/docs, your changes will be deployed to https://pulumi.com.