mirror of
https://github.com/hashicorp/packer.git
synced 2026-04-28 17:51:16 -04:00
Document process for registering a plugin as a Packer Integration
This commit is contained in:
Wilken Rivera
Lucas Bajolet
parent
4d5f1a3607
commit
c0de07c32e
2 changed files with 42 additions and 73 deletions
21
.github/ISSUE_TEMPLATE/plugin_integration.md
vendored
Normal file
21
.github/ISSUE_TEMPLATE/plugin_integration.md
vendored
Normal file
|
|
@ -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.
|
||||
|
||||
|
|
@ -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">
|
||||
Plugin integrations will be listed as a [Packer Integration](/packer/integrations), with details on how to install and use your the plugin.
|
||||
|
||||
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"
|
||||
}
|
||||
```
|
||||
|
||||
- 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
|
||||
|
||||
|
|
|
|||
Loading…
Reference in a new issue