Skip to content

Commit

Permalink
backport of commit 72bc6c8
Browse files Browse the repository at this point in the history
  • Loading branch information
@nywilken
nywilken committed Dec 5, 2023
1 parent 9dd2148 commit 78580a4
Show file tree
Hide file tree
Showing 2 changed files with 42 additions and 73 deletions.
21 changes: 21 additions & 0 deletions .github/ISSUE_TEMPLATE/plugin_integration.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,21 @@
---
name: Plugin Integration Request
about: Open request to add your plugin as a Packer integration (https://developer.hashicorp.com/packer/integrations)
labels: integration-request
---

#### Description

A written description of your plugin along with a link to the plugin repository.

#### Integration Tier
<!--- By default all integrations are registered as community integrations.
HashiCorp Technology partners https://www.hashicorp.com/partners/find-a-partner will be registered as a partner once verified. --->

#### Checklist
- [] Has valid [`metadata.hcl`](https://github.com/hashicorp/integration-template) file in plugin repository.
- [] Has added integration scripts [packer-plugin-scaffolding](https://github.com/hashicorp/packer-plugin-scoffolding) to plugin repository.
- [] Has added top-level integration README.md file to plugin `docs` directory.
- [] All plugins components have one README.md describing their usage.
- [] Has a fully synced `.web-docs` directory ready for publishing to the integrations portal.

94 changes: 21 additions & 73 deletions website/content/docs/plugins/creation/index.mdx
View file
Original file line number Diff line number Diff line change
Expand Up @@ -214,87 +214,35 @@ Here's what you need to create releases using GitHub Actions:
to install a plugin using `packer init`, see the
[init docs](/packer/docs/commands/init).

## Registering Plugin Documentation
## Registering Plugins

~> Note: Registering a remote plugin's plugin documentation requires the use of [Packer's plugin docs configuration](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs).
~> Note: Registering a remote as an integration requires the use of [Packer's plugin docs configuration](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs).

`packer init` allows users to require and install remote Packer plugins, those not bundled with Packer core, that have been published to GitHub automatically.
To help with the discovery of remote Packer plugins on GitHub, plugins maintainers can choose to register plugin documentation for each component directly on the [Packer Documentation Page](/packer/docs).
`packer init` allows users to require and install remote Packer plugins published to GitHub.
To help with the discovery of remote Packer plugins, plugins maintainers can choose to register their plugin as a [Packer Integration](/packer/integrations).

The registration process requires the creation of a `docs.zip` file archive containing the `.mdx` files for each of the plugin components in the remote plugin's repository. A working example can be seen at the [packer-plugin-docker repository](https://github.com/hashicorp/packer-plugin-docker/releases/latest).
The registration process requires [metadata configuration](https://github.com/hashicorp/integration-template#metadata-configuration) be added to your plugin repository for configuring the Packer integration pipeline and plugin documentation for rendering
on the [Packer Integrations](/packer/integrations) portal.

Once in place the remote plugin can be added to Packer's website builds by opening a pull-request against [hashicorp/packer](https://github.com/hashicorp/packer), with the needed configuration for pulling in the remote documentation.
The following steps are required for registering your plugin as an integration

Remote plugins will have their components listed under the respected types (i.e builders, provisioners, etc) using the names specified in the remote block configuration, and labeled with their respective [tier and namespace](/packer/docs/plugins#tiers-and-namespaces).
1. Update your plugin documentation structure according to the templated defined with the [Packer Plugin Scaffolding template].
New plugins generated from this template may have the necessary structure in place. If so you can jump to step 4.
1. For the integrations library, only one top-level README per integration is supported. Any top-level index.mdx files that exist
within a plugins existing documentation will need to migrate to a top-level README.
1. Update your top-level integration README to include a description, plugin installation steps, available components section, and, any, additional sections
needed to inform users on how to work with your integration. Refer to [Packer scaffolding plugin](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/docs/README.md) for an example.
1. Update the top-level README for each of the components within your integration to follow the structure defined in the scaffolding template.
1. Open a request for integration issue with the Packer team - [Open Request](https://github.com/hashicorp/packer/issues/new/choose).
Please provide all the requested information to help expedite the integration request.

To register a plugin follow one of the following setups
By opening an integration request, you are asking a member of the to Packer team to review your plugin integration configuration, plugin documentation,
and, finally, to open an internal pull-request to finalize the integration setup.

<Tabs>
<Tab heading="Generating docs.zip on plugin release">

Documentation for a plugin is maintained within the `docs` directory and served on GitHub.

To include plugin docs on the website, a global pre-hook has been added to the main scaffolding [.goreleaser.yml](https://github.com/hashicorp/packer-plugin-scaffolding/blob/42e5b0b1e575879b0477cb6d4291e027f4d92f85/.goreleaser.yml#L10) file, that if uncommented will generate and include a docs.zip file as part of the plugin release.

The `docs.zip` file contains all of the `.mdx` files under the plugins root `docs/` directory that the website can consume remotely.

</Tab>

<Tab heading="Manually generating docs.zip">

You can generate the required documentation structure manually by creating a zip file called `docs.zip` of the docs directory and including that zip file in the plugin release.

```/bin/bash
[[ -d docs/ ]] && zip -r docs.zip docs/
```

</Tab>
</Tabs>

Once the first `docs.zip` file has been included into a release you will need to open a one time pull-request against [hashicorp/packer](https://github.com/hashicorp/packer) to register the plugin docs.

This is done by adding the block below for the respective plugin to the file [website/data/plugins-manifest.json](https://github.com/hashicorp/packer/blob/main/website/data/plugins-manifest.json).

```json
{
"title": "Scaffolding",
"path": "scaffolding",
"repo": "hashicorp/packer-plugin-scaffolding",
"version": "latest",
"sourceBranch": "main"
}
```

If a plugin maintainer wishes to only include a specific version of released docs, then the `"version"` key in the above configuration should be set to a released version of the plugin. Otherwise it should be set to `"latest"`.

The `"sourceBranch"` key in the above configuration ensures potential contributors can link back to source files in the plugin repository from the Packer docs site. If a `"sourceBranch"` value is not present, it will default to `"main"`.

### Testing Plugin Documentation

Before publishing the `docs.zip` file, you might want to preview your documentation changes.
We provide a mechanism that allows to preview how the docs will look like within
the Packer documentation.

Follow the next steps to get the Packer website running and preview the documentation changes:

- Get the [Packer source code](https://github.com/hashicorp/packer). Our website code is under the [website folder](https://github.com/hashicorp/packer/tree/main/website).
- Generate the `docs.zip` file. You can find above the steps to do so.
- Add the `zipFile` attribute to the plugin entry in `plugins-manifest.json`. The value should be the full path of the `docs.zip` generated. For example:

```json
{
"title": "Scaffolding",
"path": "scaffolding",
"repo": "hashicorp/packer-plugin-scaffolding",
"version": "latest",
"sourceBranch": "main",
"zipFile": "/Users/myuser/Packer/plugins/packer-plugin-scaffolding/docs.zip"
}
```
Plugin integrations will be listed as a [Packer Integration](/packer/integrations), with details on how to install and use your the plugin.

- Go to the [website folder](https://github.com/hashicorp/packer/tree/main/website).
In the website README, follow the steps to [run the website with node](https://github.com/hashicorp/packer/tree/main/website#with-node).
- Once the website is up and running, the plugin documentation should be available in `http://localhost:3000/docs`.
Plugin integrations, once deployed, can be updated manually, or automatically upon a new release, by the plugin authors. Changes to the defined documentation structure
or parent repository should be communicated to the Packer team to ensure a working integration pipeline.

## Plugin Development Tips and FAQs

Expand Down

0 comments on commit 78580a4

Please sign in to comment.