diff --git a/website/components/plugin-tier-label/style.module.css b/website/components/plugin-tier-label/style.module.css index fe4e19381..4ebe4a397 100644 --- a/website/components/plugin-tier-label/style.module.css +++ b/website/components/plugin-tier-label/style.module.css @@ -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. } } } + diff --git a/website/content/docs/plugins/creation/index.mdx b/website/content/docs/plugins/creation/index.mdx index ccb23b4c3..4c4e7c3f1 100644 --- a/website/content/docs/plugins/creation/index.mdx +++ b/website/content/docs/plugins/creation/index.mdx @@ -64,6 +64,7 @@ download and installation via `packer init`, whereas the single-component plugin is not. + ```go @@ -115,6 +116,7 @@ the following components available: * the `my-bar` provisioner + ```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 + + + + +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`. + + + + + + +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`. + + + + + ### Plugin Development Tips and FAQs #### Naming Conventions diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index eba39a35d..07b10ab56 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -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 | +| ---------| ------------| ----------| +| |Official plugins are owned and maintained by HashiCorp. | hashicorp | +| | 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: +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. +