plugins: Update Packer plugin documentation with details for remote plugin docs (#10718)
* Add instructions for registering remote plugin documentation * Add documentation to plugins page about tiers and namespaces * Update tiers * Update website/content/docs/plugins/creation/index.mdx Co-authored-by: Megan Marsh <megan@hashicorp.com> * Add missing section for single-component install Co-authored-by: Megan Marsh <megan@hashicorp.com>
This commit is contained in:
Wilken Rivera
GitHub
parent
3ac5046260
commit
1e27138857
|
|
@ -10,7 +10,7 @@ to match Terraform Registry tier labels.
|
|||
background: var(--background-color);
|
||||
border-radius: 3px;
|
||||
display: inline-flex;
|
||||
margin: 40px 8px 8px 0;
|
||||
margin: 0;
|
||||
padding: 1px 8px 2px 8px;
|
||||
vertical-align: baseline;
|
||||
|
||||
|
|
@ -27,6 +27,12 @@ to match Terraform Registry tier labels.
|
|||
}
|
||||
}
|
||||
|
||||
/* add margin-top to separate from the adjacent
|
||||
search bar present on docs pages */
|
||||
:global(.g-search) + .root {
|
||||
margin-top: 40px;
|
||||
}
|
||||
|
||||
.text {
|
||||
/* composes */
|
||||
composes: g-type-body-small-strong from global;
|
||||
|
|
@ -46,3 +52,4 @@ to match Terraform Registry tier labels.
|
|||
}
|
||||
}
|
||||
}
|
||||
|
||||
|
|
|
|||
|
|
@ -64,6 +64,7 @@ download and installation via `packer init`, whereas the single-component plugin
|
|||
is not.
|
||||
|
||||
<Tabs>
|
||||
|
||||
<Tab heading="Multi-component Plugin (recommended) ">
|
||||
|
||||
```go
|
||||
|
|
@ -115,6 +116,7 @@ the following components available:
|
|||
* the `my-bar` provisioner
|
||||
|
||||
</Tab>
|
||||
|
||||
<Tab heading="Single Component Plugin (deprecated)">
|
||||
|
||||
```go
|
||||
|
|
@ -217,12 +219,115 @@ for help with this step)
|
|||
- `PASSPHRASE` - The passphrase for your GPG private key.
|
||||
5. Push a new valid version tag (e.g. `v1.2.3`) to test that the GitHub Actions
|
||||
releaser is working. The tag must be a valid
|
||||
[Semantic Version](https://semver.org/) preceded with a `v`. Once the tag is
|
||||
pushed, the github actions you just configured will automatically build release
|
||||
binaries that Packer can download using `packer init`. For more details on how
|
||||
[Semantic Version](https://semver.org/) preceded with a `v`. Once the tag is pushed, the github actions you just configured will automatically build release binaries that Packer can download using `packer init`. For more details on how
|
||||
to install a plugin using `packer init`, see the
|
||||
[init docs](/docs/commands/init).
|
||||
|
||||
### Registering Plugin Documentation
|
||||
|
||||
~> 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).
|
||||
|
||||
`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](https://packer.io/docs).
|
||||
|
||||
The registration process requires the creation of a `.docs-artifacts` directory and a sidebar navigation file `docs-nav.json` 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/tree/main/.docs-artifacts).
|
||||
|
||||
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/packer), which the needed configuration pulling in the remote documentation.
|
||||
|
||||
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](/docs/plugins#tiers-and-namespaces).
|
||||
|
||||
To register a plugin follow one of the following setups
|
||||
|
||||
<Tabs>
|
||||
<Tab heading="Registering Using GitHub Actions">
|
||||
|
||||
Documentation for a plugin is maintained within the `docs` directory and served on GitHub.
|
||||
|
||||
A GitHub workflow has been added to [packer-plugin-scaffolding](https://github.com/hashicorp/packer-plugin-scaffolding/tree/main/docs) that
|
||||
can be used generate a documentation structure that can be consumed remotely by https://packer.io. See the full workflow at [generated-docs-artifacts.yml](https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/.github/workflows/generate-docs-artifacts.yml)
|
||||
|
||||
The GitHub workflow will automatically create the `.docs-artifacts` directory with the generated sidebar navigation file, and open a new pull-request against the default configured branch to be merged by the maintainer.
|
||||
|
||||
By default the workflow is configured to trigger on the creation of tags beginning with `'v*` to ensure that documentation gets updated for each release. Updates to the plugin documentation will get pulled in at the time of the next Packer website deployment.
|
||||
|
||||
After merging the generated files to the default branch for the plugin repository.
|
||||
|
||||
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 [docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json).
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Docker",
|
||||
"path": "docker",
|
||||
"repo": "hashicorp/packer-plugin-docker",
|
||||
}
|
||||
```
|
||||
|
||||
#### Required fields
|
||||
|
||||
`title`: The name of the plugin to be displayed in the sidebar - See [naming conventions](#naming-conventions)
|
||||
|
||||
`path`: The path name for the documentation page, which is usually the lower case version of `title` (e.g https
|
||||
|
||||
`repo`: The full name of the GitHub repository (i.e org/repo-name)
|
||||
|
||||
#### Optional fields
|
||||
|
||||
`branch`: The name of the default branch of the repository. Defaults to main.
|
||||
|
||||
`artifactDir`: The location of the docs artifacts directory in the remote repository. Defaults to `.doc-artifacts`.
|
||||
|
||||
|
||||
</Tab>
|
||||
<Tab heading="Registering Manually">
|
||||
|
||||
|
||||
The documentation structure needed for registering a plugin's documentation can be generated manually, but it is
|
||||
encouraged to use the action on release events so that documentation stays up to date.
|
||||
|
||||
If your local development environment has a supported version (v10.0.0+) of [node](https://nodejs.org/en/) and a
|
||||
supported version (>=5.2.0) [npm](https://www.npmjs.com/) installed, in the plugin root directory, you can run:
|
||||
|
||||
|
||||
```shell-session
|
||||
> npx -p @hashicorp/packer-docs-artifacts generate
|
||||
```
|
||||
|
||||
The generated files will be placed under `PLUGIN_ROOT/.doc-artifacts`; this directory contains all the docs
|
||||
and respective navigation information needed for including the plugin docs under [packer.io/docs/](https://packer.io/docs).
|
||||
|
||||
After merging the generated files to the default branch for the plugin repository.
|
||||
|
||||
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 [docs-remote-navigation.js](https://github.com/hashicorp/packer/blob/master/website/data/docs-remote-plugins.json).
|
||||
|
||||
```json
|
||||
{
|
||||
"title": "Docker",
|
||||
"path": "docker",
|
||||
"repo": "hashicorp/packer-plugin-docker",
|
||||
}
|
||||
```
|
||||
|
||||
#### Required fields
|
||||
|
||||
`title`: The name of the plugin to be displayed in the sidebar - See [naming conventions](#naming-conventions)
|
||||
|
||||
`path`: The path name for the documentation page, which is usually the lower case version of `title` (e.g https
|
||||
|
||||
`repo`: The full name of the GitHub repository (i.e org/repo-name)
|
||||
|
||||
#### Optional fields
|
||||
|
||||
`branch`: The name of the default branch of the repository. Defaults to main.
|
||||
|
||||
`artifactDir`: The location of the docs artifacts directory in the remote repository. Defaults to `.doc-artifacts`.
|
||||
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
||||
### Plugin Development Tips and FAQs
|
||||
|
||||
#### Naming Conventions
|
||||
|
|
|
|||
|
|
@ -36,6 +36,16 @@ applications running. One of those applications is the core; the rest are
|
|||
plugins -- one plugin process is launched for each component used in a Packer
|
||||
build.
|
||||
|
||||
## Tiers and Namespaces
|
||||
|
||||
Packer plugins are published and maintained by a variety of sources, including HashiCorp, and the Packer community. The Packer website uses tiers and badges to denote the source of a provider. Additionally, namespaces are used to help users identify the organization or publisher responsible for the integration, as shown in the table below.
|
||||
|
||||
|
||||
| Tier | Description | Namespace |
|
||||
| ---------| ------------| ----------|
|
||||
| <PluginTierLabel tier="official" /> |Official plugins are owned and maintained by HashiCorp. | hashicorp |
|
||||
| <PluginTierLabel tier="community" /> | Community providers are published by individual maintainers, groups of maintainers, or other members of the Packer community.| Third-party organization or maintainer's individual account |
|
||||
|
||||
## Installing Plugins
|
||||
|
||||
Currently, you do not need to install plugins for builder, provisioner, or
|
||||
|
|
@ -203,7 +213,7 @@ will avoid conflicting with other plugins for other tools, like Terraform.
|
|||
The easiest way to manually install a plugin is to name it correctly, then place
|
||||
it in the proper directory. To name a plugin correctly, make sure the binary is
|
||||
named `packer-plugin-NAME`. For example, `packer-plugin-amazon` for a "plugin"
|
||||
binary named "amazon". This binary will make one or more plugins available to
|
||||
binary named "amazon". This binary will make one or more components available to
|
||||
use. Valid types for plugins are down this page.
|
||||
|
||||
Once the plugin is named properly, Packer automatically discovers plugins in
|
||||
|
|
@ -231,7 +241,7 @@ later, it will take precedence over one found earlier.
|
|||
|
||||
The valid types for plugins are:
|
||||
|
||||
- `plugin` - A plugin binary that can contain one or more of each Packer plugin
|
||||
- `plugin` - A plugin binary that can contain one or more of each Packer component
|
||||
type.
|
||||
|
||||
- `builder` - Plugins responsible for building images for a specific
|
||||
|
|
@ -246,5 +256,48 @@ The valid types for plugins are:
|
|||
</Tab>
|
||||
<Tab heading="manually (single-component plugin)">
|
||||
|
||||
The easiest way to manually install a plugin is to name it correctly, then place
|
||||
it in the proper directory. To name a plugin correctly, make sure the binary is
|
||||
named `packer-COMPONENT-NAME`. For example, `packer-provisioner-comment` for a "plugin"
|
||||
binary named "comment". This binary will make a single provisioner named `comment` available to
|
||||
use. Valid types for plugins are down this page.
|
||||
|
||||
Once the plugin is named properly, Packer automatically discovers plugins in
|
||||
the following directories in the given order. If a conflicting plugin is found
|
||||
later, it will take precedence over one found earlier.
|
||||
|
||||
1. The directory where `packer` is, or the executable directory.
|
||||
|
||||
2. The `$HOME/.packer.d/plugins` directory, if `$HOME` is defined (unix)
|
||||
|
||||
3. The `%APPDATA%/packer.d/plugins` if `%APPDATA%` is defined (windows)
|
||||
|
||||
4. The `%USERPROFILE%/packer.d/plugins` if `%USERPROFILE%` is defined
|
||||
(windows)
|
||||
|
||||
5. The current working directory.
|
||||
|
||||
6. The directory defined in the env var `PACKER_PLUGIN_PATH`. There can be more
|
||||
than one directory defined; for example, `~/custom-dir-1:~/custom-dir-2`.
|
||||
Separate directories in the PATH string using a colon (`:`) on posix systems and
|
||||
a semicolon (`;`) on windows systems. The above example path would be able to
|
||||
find a provisioner named `packer-provisioner-foo` in either
|
||||
`~/custom-dir-1/packer-provisioner-foo` or
|
||||
`~/custom-dir-2/packer-provisioner-foo`.
|
||||
|
||||
The valid types for plugins are:
|
||||
|
||||
- `plugin` - A plugin binary that can contain one or more of each Packer component
|
||||
type.
|
||||
|
||||
- `builder` - Plugins responsible for building images for a specific
|
||||
platform.
|
||||
|
||||
- `post-processor` - A post-processor responsible for taking an artifact from
|
||||
a builder and turning it into something else.
|
||||
|
||||
- `provisioner` - A provisioner to install software on images created by a
|
||||
builder.
|
||||
|
||||
</Tab>
|
||||
</Tabs>
|
||||
|
|
|
|||
Loading…
Reference in New Issue