From 51980ca573be4c0f06f51d7fd6984255a2d63925 Mon Sep 17 00:00:00 2001 From: "dependabot[bot]" <49699333+dependabot[bot]@users.noreply.github.com> Date: Thu, 15 Sep 2022 12:31:34 -0400 Subject: [PATCH 1/3] Bump actions/stale from 5.1.1 to 5.2.0 (#11989) Bumps [actions/stale](https://github.com/actions/stale) from 5.1.1 to 5.2.0. - [Release notes](https://github.com/actions/stale/releases) - [Changelog](https://github.com/actions/stale/blob/main/CHANGELOG.md) - [Commits](https://github.com/actions/stale/compare/v5.1.1...v5.2.0) --- updated-dependencies: - dependency-name: actions/stale dependency-type: direct:production update-type: version-update:semver-minor ... Signed-off-by: dependabot[bot] Signed-off-by: dependabot[bot] Co-authored-by: dependabot[bot] <49699333+dependabot[bot]@users.noreply.github.com> --- .github/workflows/auto-close-stale-issues.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/workflows/auto-close-stale-issues.yml b/.github/workflows/auto-close-stale-issues.yml index 545583fd6..91d24bca0 100644 --- a/.github/workflows/auto-close-stale-issues.yml +++ b/.github/workflows/auto-close-stale-issues.yml @@ -14,7 +14,7 @@ jobs: pull-requests: write # for actions/stale to close stale PRs runs-on: ubuntu-latest steps: - - uses: actions/stale@v5.1.1 + - uses: actions/stale@v5.2.0 with: repo-token: ${{ secrets.GITHUB_TOKEN }} days-before-issue-stale: 23 From 11e71729f187bad76d28f1701cf2c56e7b912c0f Mon Sep 17 00:00:00 2001 From: Wilken Rivera Date: Thu, 15 Sep 2022 12:31:52 -0400 Subject: [PATCH 2/3] Remove Oracle plugin from the list of vendored plugins (#11983) The latest release of the Oracle plugin for Packer removed Solaris from its list of supported platforms. Since Packer still releases binaries for Solaris the Oracle plugin will no longer be bundled and distributed within the Packer binary. Practitioners relying on the plugin can continue using the plugin by installing it manually using either the `packer init` or `packer plugins install` commands. --- command/vendored_plugins.go | 4 ---- go.mod | 3 --- go.sum | 8 -------- scripts/upgrade_plugins.sh | 1 - 4 files changed, 16 deletions(-) diff --git a/command/vendored_plugins.go b/command/vendored_plugins.go index c945a191f..5ddf9edc1 100644 --- a/command/vendored_plugins.go +++ b/command/vendored_plugins.go @@ -49,8 +49,6 @@ import ( ncloudbuilder "github.com/hashicorp/packer-plugin-ncloud/builder/ncloud" oneandonebuilder "github.com/hashicorp/packer-plugin-oneandone/builder/oneandone" openstackbuilder "github.com/hashicorp/packer-plugin-openstack/builder/openstack" - oracleclassicbuilder "github.com/hashicorp/packer-plugin-oracle/builder/classic" - oracleocibuilder "github.com/hashicorp/packer-plugin-oracle/builder/oci" parallelsisobuilder "github.com/hashicorp/packer-plugin-parallels/builder/parallels/iso" parallelspvmbuilder "github.com/hashicorp/packer-plugin-parallels/builder/parallels/pvm" profitbricksbuilder "github.com/hashicorp/packer-plugin-profitbricks/builder/profitbricks" @@ -115,8 +113,6 @@ var VendoredBuilders = map[string]packersdk.Builder{ "ncloud": new(ncloudbuilder.Builder), "oneandone": new(oneandonebuilder.Builder), "openstack": new(openstackbuilder.Builder), - "oracle-classic": new(oracleclassicbuilder.Builder), - "oracle-oci": new(oracleocibuilder.Builder), "profitbricks": new(profitbricksbuilder.Builder), "proxmox": new(proxmoxiso.Builder), "proxmox-iso": new(proxmoxiso.Builder), diff --git a/go.mod b/go.mod index c342a248b..6c89c1720 100644 --- a/go.mod +++ b/go.mod @@ -80,7 +80,6 @@ require ( github.com/hashicorp/packer-plugin-ncloud v1.0.3 github.com/hashicorp/packer-plugin-oneandone v1.0.1 github.com/hashicorp/packer-plugin-openstack v1.0.1 - github.com/hashicorp/packer-plugin-oracle v1.0.2 github.com/hashicorp/packer-plugin-parallels v1.0.3 github.com/hashicorp/packer-plugin-profitbricks v1.0.2 github.com/hashicorp/packer-plugin-proxmox v1.0.8 @@ -184,7 +183,6 @@ require ( github.com/hashicorp/go-getter/s3/v2 v2.1.0 // indirect github.com/hashicorp/go-hclog v0.16.2 // indirect github.com/hashicorp/go-immutable-radix v1.3.1 // indirect - github.com/hashicorp/go-oracle-terraform v0.17.0 // indirect github.com/hashicorp/go-retryablehttp v0.7.0 // indirect github.com/hashicorp/go-rootcerts v1.0.2 // indirect github.com/hashicorp/go-safetemp v1.0.0 // indirect @@ -224,7 +222,6 @@ require ( github.com/modern-go/reflect2 v1.0.1 // indirect github.com/nu7hatch/gouuid v0.0.0-20131221200532-179d4d0c4d8d // indirect github.com/olekukonko/tablewriter v0.0.5 // indirect - github.com/oracle/oci-go-sdk/v36 v36.2.0 // indirect github.com/pkg/errors v0.9.1 // indirect github.com/pmezard/go-difflib v1.0.0 // indirect github.com/profitbricks/profitbricks-sdk-go v4.0.2+incompatible // indirect diff --git a/go.sum b/go.sum index 5e677ee04..8ec08beba 100644 --- a/go.sum +++ b/go.sum @@ -311,7 +311,6 @@ github.com/go-git/go-git/v5 v5.4.2/go.mod h1:gQ1kArt6d+n+BGd+/B/I74HwRTLhth2+zti github.com/go-gl/glfw v0.0.0-20190409004039-e6da0acd62b1/go.mod h1:vR7hzQXu2zJy9AVAgeJqvqgH9Q5CA+iKCZ2gyEVpxRU= github.com/go-gl/glfw/v3.3/glfw v0.0.0-20191125211704-12ad95a8df72/go.mod h1:tQ2UAYgL5IevRw8kRxooKSPJfGvJ9fJQFa0TUsXzTg8= github.com/go-gl/glfw/v3.3/glfw v0.0.0-20200222043503-6f7a984d4dc4/go.mod h1:tQ2UAYgL5IevRw8kRxooKSPJfGvJ9fJQFa0TUsXzTg8= -github.com/go-ini/ini v1.62.0 h1:7VJT/ZXjzqSrvtraFp4ONq80hTcRQth1c9ZnQ3uNQvU= github.com/go-kit/kit v0.8.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as= github.com/go-kit/kit v0.9.0/go.mod h1:xBxKIO96dXMWWy0MnWVtmwkA9/13aqxPnvrjFYMA2as= github.com/go-ldap/ldap/v3 v3.1.3/go.mod h1:3rbOH3jRS2u6jg2rJnKAMLE/xQyCKIveG2Sa/Cohzb8= @@ -618,8 +617,6 @@ github.com/hashicorp/go-multierror v1.0.0/go.mod h1:dHtQlpGsu+cZNNAkkCN/P3hoUDHh github.com/hashicorp/go-multierror v1.1.0/go.mod h1:spPvp8C1qA32ftKqdAHm4hHTbPw+vmowP0z+KUhOZdA= github.com/hashicorp/go-multierror v1.1.1 h1:H5DkEtf6CXdFp0N0Em5UCwQpXMWke8IA0+lD48awMYo= github.com/hashicorp/go-multierror v1.1.1/go.mod h1:iw975J/qwKPdAO1clOe2L8331t/9/fmwbPZ6JB6eMoM= -github.com/hashicorp/go-oracle-terraform v0.17.0 h1:gFiaeKf9MXLobhv7uqzPuDFULL6ymJpw1NJCXwSOgJ4= -github.com/hashicorp/go-oracle-terraform v0.17.0/go.mod h1:09jT3Y/OIsjTjQ2+3bkVNPDKqWcGIYYvjB2BEKVUdvc= github.com/hashicorp/go-plugin v1.0.1/go.mod h1:++UyYGoz3o5w9ZzAdZxtQKrWWP+iqPBn3cQptSMzBuY= github.com/hashicorp/go-retryablehttp v0.5.3/go.mod h1:9B5zBasrRhHXnJnui7y6sL7es7NDiJgTc6Er0maI1Xs= github.com/hashicorp/go-retryablehttp v0.6.2/go.mod h1:gEx6HMUGxYYhJScX7W1Il64m6cc2C1mDaW3NQ9sY1FY= @@ -699,8 +696,6 @@ github.com/hashicorp/packer-plugin-oneandone v1.0.1 h1:6rnqSWSve4XB+im1MYfgdGnyD github.com/hashicorp/packer-plugin-oneandone v1.0.1/go.mod h1:9alSvlih9aE4Pebnnw7CmfmOyKKjnAxbxXZN9yFCCsE= github.com/hashicorp/packer-plugin-openstack v1.0.1 h1:R4Iw0Vx/o14e2GRbKypwsR1B21z6CkaISX+KqwtLuTo= github.com/hashicorp/packer-plugin-openstack v1.0.1/go.mod h1:i5qn9aUabJM9mjhpXS81hFSuDjJYA2kOi0vLlo3VGsE= -github.com/hashicorp/packer-plugin-oracle v1.0.2 h1:9hGXPgrtovhqIKFtvE6gPNDDVZ/WzYw/CqgZmAKdP6w= -github.com/hashicorp/packer-plugin-oracle v1.0.2/go.mod h1:FUG3IN2d6BDH1hKbeTu6qwpzJSbMe6wa3WNYBE6eoFQ= github.com/hashicorp/packer-plugin-parallels v1.0.3 h1:smypphUCEj3arCdlvbNtZvGC1ujsUSRtN1MBvZHt/w8= github.com/hashicorp/packer-plugin-parallels v1.0.3/go.mod h1:Q842nvosVmP5FnYozk8ZZj93HGIan19jHTxGeteBCb0= github.com/hashicorp/packer-plugin-profitbricks v1.0.2 h1:wAlTRm1A39T9hferxFtKaLCDmlsqA9cU7dTQtMLcvKQ= @@ -928,8 +923,6 @@ github.com/opencontainers/runc v0.0.0-20190115041553-12f6a991201f/go.mod h1:qT5X github.com/opencontainers/runc v0.1.1/go.mod h1:qT5XzbpPznkRYVz/mWwUaVBUv2rmF59PVA73FjuZG0U= github.com/opencontainers/runtime-spec v0.1.2-0.20190507144316-5b71a03e2700/go.mod h1:jwyrGlmzljRJv/Fgzds9SsS/C5hL+LL3ko9hs6T5lQ0= github.com/opentracing/opentracing-go v1.1.0/go.mod h1:UkNAQd3GIcIGf0SeVgPpRdFStlNbqXla1AfSYxPUl2o= -github.com/oracle/oci-go-sdk/v36 v36.2.0 h1:oBaN/FnBDy3ohMyVZ/rKfekYxnyksG2KK0YAhT5HSnk= -github.com/oracle/oci-go-sdk/v36 v36.2.0/go.mod h1:t8Y/M3Lh8X4BOJhtThJKe1skRTg7qom7oWyHiNjo4RM= github.com/packer-community/winrmcp v0.0.0-20180921211025-c76d91c1e7db h1:9uViuKtx1jrlXLBW/pMnhOfzn3iSEdLase/But/IZRU= github.com/packer-community/winrmcp v0.0.0-20180921211025-c76d91c1e7db/go.mod h1:f6Izs6JvFTdnRbziASagjZ2vmf55NSIkC/weStxCHqk= github.com/pascaldekloe/goe v0.0.0-20180627143212-57f6aae5913c/go.mod h1:lzWF7FIEvWOWxwDKqyGYQf6ZUaNfKdP144TG7ZOy1lc= @@ -1620,7 +1613,6 @@ gopkg.in/gemnasium/logrus-airbrake-hook.v2 v2.1.2/go.mod h1:Xk6kEKp8OKb+X14hQBKW gopkg.in/ini.v1 v1.42.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= gopkg.in/ini.v1 v1.62.0 h1:duBzk771uxoUuOlyRLkHsygud9+5lrlGjdFBb4mSKDU= gopkg.in/ini.v1 v1.62.0/go.mod h1:pNLf8WUiyNEtQjuu5G5vTm06TEv9tsIgeAvK8hOrP4k= -gopkg.in/jarcoal/httpmock.v1 v1.0.0-20181117152235-275e9df93516 h1:H6trpavCIuipdInWrab8l34Mf+GGVfphniHostMdMaQ= gopkg.in/resty.v1 v1.12.0/go.mod h1:mDo4pnntr5jdWRML875a/NmxYqAlA73dVijT2AXvQQo= gopkg.in/square/go-jose.v2 v2.3.1/go.mod h1:M9dMgbHiYLoDGQrXy7OpJDJWiKiU//h+vD76mk0e1AI= gopkg.in/square/go-jose.v2 v2.5.1/go.mod h1:M9dMgbHiYLoDGQrXy7OpJDJWiKiU//h+vD76mk0e1AI= diff --git a/scripts/upgrade_plugins.sh b/scripts/upgrade_plugins.sh index 5bc6b1e99..f2c7335c0 100755 --- a/scripts/upgrade_plugins.sh +++ b/scripts/upgrade_plugins.sh @@ -26,7 +26,6 @@ declare -a plugins=( "hashicorp/packer-plugin-lxd" "hashicorp/packer-plugin-ncloud" "hashicorp/packer-plugin-openstack" - "hashicorp/packer-plugin-oracle" "hashicorp/packer-plugin-oneandone" "hashicorp/packer-plugin-parallels" "hashicorp/packer-plugin-profitbricks" From d4b03769f2a923a7a3a659430488fad456dd1ad6 Mon Sep 17 00:00:00 2001 From: Laura Pacilio <83350965+laurapacilio@users.noreply.github.com> Date: Thu, 15 Sep 2022 18:12:37 -0400 Subject: [PATCH 3/3] Update plugin docs - devdot launch (#11978) * Separate install instructions; add to external plugins * Remove duplicate external plugin link; modify overiew page * Remove unnecessary partials; clean up plugin overview page * cleaning up plugin explanations * final language updates * modify external plugin overview page * Update website/content/docs/plugins/index.mdx Co-authored-by: Wilken Rivera * Update website/content/docs/plugins/install-plugins.mdx Co-authored-by: Wilken Rivera * Move HCP Support to under developing plugins * Link HCP Packer support to other dev pages; fix overviews * clean up more language and links * Add External Plugins link to docs sidebar under plugin section * Update website/data/docs-nav-data.json Co-authored-by: Wilken Rivera --- .../docs/plugins/creation/custom-builders.mdx | 31 ++++++-------- .../plugins/creation/custom-datasources.mdx | 16 ++++---- .../creation/custom-post-processors.mdx | 17 ++++---- .../plugins/creation/custom-provisioners.mdx | 16 ++++---- .../plugins/{ => creation}/hcp-support.mdx | 10 ++--- .../content/docs/plugins/creation/index.mdx | 40 ++++++++----------- website/content/docs/plugins/index.mdx | 26 +++++------- .../plugins/install-plugins.mdx} | 36 ++++++++++------- .../partials/plugins/how-plugins-work.mdx | 13 ------ website/content/plugins/index.mdx | 18 ++------- website/data/docs-nav-data.json | 24 ++++++----- website/data/plugins-nav-data.json | 3 +- 12 files changed, 107 insertions(+), 143 deletions(-) rename website/content/docs/plugins/{ => creation}/hcp-support.mdx (85%) rename website/content/{partials/plugins/installing-plugins.mdx => docs/plugins/install-plugins.mdx} (89%) delete mode 100644 website/content/partials/plugins/how-plugins-work.mdx diff --git a/website/content/docs/plugins/creation/custom-builders.mdx b/website/content/docs/plugins/creation/custom-builders.mdx index 8e0430095..bc6383fa6 100644 --- a/website/content/docs/plugins/creation/custom-builders.mdx +++ b/website/content/docs/plugins/creation/custom-builders.mdx @@ -7,25 +7,18 @@ page_title: Custom Builders - Extending # Custom Builders -Packer Builders are the components of Packer responsible for creating a -virtual machine, bringing it to a point where it can be provisioned, and then -turning that provisioned virtual machine into a machine image. Several builders -are officially maintained and distributed by the HashiCorp Packer team -- among -these are builders for creating images on Amazon EC2, VMware, Google -Compute Engine, and many more. You can find documentation for how to use these -official builders [here](/docs/builders). It is also possible to write custom -builders using the Packer plugin interface, and this page documents how to do -that. - -Prior to reading this page, you should read the page on [plugin development -basics](/docs/extending/plugins). - -~> **Warning!** This is an advanced topic. If you're new to Packer, we -recommend getting comfortable with using Packer and its officially maintained -plugins before you dive into writing plugins of your own. - -Custom plugins are written in [Go](https://go.dev/), so this guide -assumes that you have some familiarity with that programming language. +Packer builders are responsible for creating a virtual machine, setting the virtual machine up for provisioning, and then turning that provisioned virtual machine into a machine image. We officially maintain and distribute several builders, including builders to create images on Amazon EC2, VMware, Google +Compute Engine, and many more. Refer to the [Builders](/docs/builders) documentation for details. + +This page explains how to use the Packer plugin interface to write custom builders. If you want your builder to support HashiCorp Cloud Platform (HCP) Packer, you should also review the [HCP Packer Support](/docs/plugins/creation/hcp-support) documentation. + +~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins. + +## Before You Begin + +We recommend reviewing the following resources before you begin development: +- [Developing Plugins - Overview](/docs/plugins/creation) +- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language. ## The Interface diff --git a/website/content/docs/plugins/creation/custom-datasources.mdx b/website/content/docs/plugins/creation/custom-datasources.mdx index 8c9f09682..ad23e6dea 100644 --- a/website/content/docs/plugins/creation/custom-datasources.mdx +++ b/website/content/docs/plugins/creation/custom-datasources.mdx @@ -7,18 +7,18 @@ page_title: Custom Data Sources - Extending # Custom Data Sources -Packer Data Sources are the components of Packer that allow data to be fetched for use within the configuration. -Use of data sources allows a build to use information defined outside of Packer. An example of -data source is the [amazon-ami data source](/docs/datasources/amazon/ami), which outputs the data of a fetched Amazon AMI. - -Prior to reading this page, it is assumed you have read the page on [plugin -development basics](/docs/plugins). +Packer data sources let Packer fetch data to use within the configuration, including information defined outside of Packer. For example, the [amazon-ami data source](/docs/datasources/amazon/ami), outputs the data from an Amazon AMI. Data Source plugins implement the `packersdk.Datasource` interface and are registered within a plugin Set with `set.RegisterDatasource(...)` function and served using the `set.Run()`. -~> **Warning!** This is an advanced topic. If you're new to Packer, we -recommend getting a bit more comfortable before you dive into writing plugins. +~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins. + +## Before You Begin + +We recommend reviewing the following resources before you begin development: +- [Developing Plugins - Overview](/docs/plugins/creation) +- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language. ## The Interface diff --git a/website/content/docs/plugins/creation/custom-post-processors.mdx b/website/content/docs/plugins/creation/custom-post-processors.mdx index 9c290e7ec..734abb785 100644 --- a/website/content/docs/plugins/creation/custom-post-processors.mdx +++ b/website/content/docs/plugins/creation/custom-post-processors.mdx @@ -9,8 +9,7 @@ page_title: Custom Post-Processors - Extending # Custom Post-Processors -Packer Post-processors are the components of Packer that transform one artifact -into another, for example by compressing files, or uploading them. +Packer post-processors transform one artifact into another. For example, a post-processor might compress or upload files. In the compression example, the transformation would be taking an artifact with a set of files, compressing those files, and returning a new artifact with only @@ -18,14 +17,18 @@ a single file (the compressed archive). For the upload example, the transformation would be taking an artifact with some set of files, uploading those files, and returning an artifact with a single ID: the URL of the upload. -Prior to reading this page, it is assumed you have read the page on [plugin -development basics](/docs/extending/plugins). - Post-processor plugins implement the [`packer.PostProcessor`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#PostProcessor) interface and are served using the `plugin.ServePostProcessor` function. -~> **Warning!** This is an advanced topic. If you're new to Packer, we -recommend getting a bit more comfortable before you dive into writing plugins. +This page explains how to implement and serve custom post-processors. If you want your post-processor to support HashiCorp Cloud Platform (HCP) Packer, you should also review the [HCP Packer Support](/docs/plugins/creation/hcp-support) documentation. + +~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins. + +## Before You Begin + +We recommend reviewing the following resources before you begin development: +- [Developing Plugins - Overview](/docs/plugins/creation) +- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language. ## The Interface diff --git a/website/content/docs/plugins/creation/custom-provisioners.mdx b/website/content/docs/plugins/creation/custom-provisioners.mdx index 3085ac28b..1947d7934 100644 --- a/website/content/docs/plugins/creation/custom-provisioners.mdx +++ b/website/content/docs/plugins/creation/custom-provisioners.mdx @@ -13,20 +13,20 @@ page_title: Custom Provisioners - Extending # Custom Provisioners -Packer Provisioners are the components of Packer that install and configure -software into a running machine prior to turning that machine into an image. An -example of a provisioner is the [shell +Packer provisioners install and configure software into a running machine prior to turning that machine into an image. For example, the [shell provisioner](/docs/provisioners/shell), which runs shell scripts within the machines. -Prior to reading this page, it is assumed you have read the page on [plugin -development basics](/docs/extending/plugins). - Provisioner plugins implement the [`packer.Provisioner`](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer#Provisioner) interface and are served using the `plugin.ServeProvisioner` function. -~> **Warning!** This is an advanced topic. If you're new to Packer, we -recommend getting a bit more comfortable before you dive into writing plugins. +~> **Warning:** This is an advanced topic that requires strong knowledge of Packer and Packer plugins. + +## Before You Begin + +We recommend reviewing the following resources before you begin development: +- [Developing Plugins - Overview](/docs/plugins/creation) +- The [Go](https://go.dev/) language. You must write custom plugins in Go, so this guide assumes you are familiar with the language. ## The Interface diff --git a/website/content/docs/plugins/hcp-support.mdx b/website/content/docs/plugins/creation/hcp-support.mdx similarity index 85% rename from website/content/docs/plugins/hcp-support.mdx rename to website/content/docs/plugins/creation/hcp-support.mdx index eb424baeb..eb5d469b8 100644 --- a/website/content/docs/plugins/hcp-support.mdx +++ b/website/content/docs/plugins/creation/hcp-support.mdx @@ -9,14 +9,12 @@ page_title: HCP Packer Support ~> **Note:** HCP Packer is under active development, and we suggest plugin maintainers to keep up with the SDK changes for more on HCP Packer support. -~> **Note:** If you're looking to develop a new plugin, please refer first to the [developing -plugins](/docs/plugins/creation#developing-plugins) page. +This page explains how to update a custom plugin so that it can publish image metadata to the [HCP Packer registry](https://cloud.hashicorp.com/docs/packer). Refer to [Custom Builders](/docs/plugins/creation/custom-builders) and [Custom Post-Processors](/docs/plugins/creation/custom-post-processors) for details about creating an external Packer plugin. -HCP Packer support allows for the management of image metadata that can be stored in a HCP Packer registry. -Before pushing metadata to the HCP Packer registry, Packer will use the [`par.artifact.metadata` key](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-constants) -to query a builder artifact for the Image metadata that a particular component would like to have stored in the registry. +Before pushing metadata to the HCP Packer registry, Packer uses the [`par.artifact.metadata` key](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image#pkg-constants) +to query a builder artifact for the image metadata that a particular component would like to have stored in the registry. -For details and usage examples on management of image metadata, see the [Documentation](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image). +For details and examples of how to manage image metadata, refer to the [HCP Packer GitHub documentation](https://pkg.go.dev/github.com/hashicorp/packer-plugin-sdk/packer/registry/image). ## Builder Artifact diff --git a/website/content/docs/plugins/creation/index.mdx b/website/content/docs/plugins/creation/index.mdx index 1e6951bed..93b265234 100644 --- a/website/content/docs/plugins/creation/index.mdx +++ b/website/content/docs/plugins/creation/index.mdx @@ -6,27 +6,19 @@ description: | page_title: Extending --- -# Extending Packer +# Developing Plugins -Packer is designed to be extensible, and supports plugins that allow you to -create and use custom builders, provisioners, post-processors, and data sources. -To learn more about developing these different types of components, please -choose a link from the sidebar. To learn more about the general plugin -architecture, stay on this page. +Packer is extensible and supports plugins that let you +create and use custom builders, provisioners, post-processors, and data sources. This page explains how to develop Packer plugins. Before you begin, we recommend reviewing the Packer documentation and the instructions for [installing external plugins](/docs/plugins/install-plugins). -## Developing Plugins +~> **Warning** This is an advanced topic. You should have strong knowledge of Packer before you start writing plugins. -This page will document how you can develop your own Packer plugins. Prior to -reading this, you should be comfortable with Packer and know the -basics of [how plugins work from a user standpoint](/docs/plugins). +## Language Requirements -Packer plugins must be written in [Go](https://go.dev/), so you should also -be familiar with the language. +You must write Packer plugins in [Go](https://go.dev/). -~> **Warning!** This is an advanced topic. If you're new to Packer, we -recommend getting a bit more comfortable before you dive into writing plugins. -### Plugin System Architecture +## Plugin System Architecture A Packer plugin is just a Go binary. Instead of loading plugins directly into a running application, Packer runs each plugin as a _separate application_. @@ -34,7 +26,7 @@ The multiple separate Packer plugin processes communicate with the Core using an RPC defined in the packer-plugin SDK. The Packer core itself is responsible launching and cleaning up the plugin processes. -### Plugin Development Basics +## Plugin Development Basics The components that can be created and used in a Packer plugin are builders, provisioners, post-processors, and data sources. @@ -163,7 +155,7 @@ the Packer codebase will continue to improve, potentially breaking APIs along the way until there is a stable release. By locking your dependencies, your plugins will continue to work with the version of Packer you lock to. -### Logging and Debugging +## Logging and Debugging Plugins can use the standard Go `log` package to log. Anything logged using this will be available in the Packer log files automatically. The Packer log is @@ -222,7 +214,7 @@ Here's what you need to create releases using GitHub Actions: to install a plugin using `packer init`, see the [init docs](/docs/commands/init). -### Registering Plugin Documentation +## 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). @@ -277,7 +269,7 @@ If a plugin maintainer wishes to only include a specific version of released doc 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 +### 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 @@ -304,9 +296,9 @@ Follow the next steps to get the Packer website running and preview the document 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 Development Tips and FAQs +## Plugin Development Tips and FAQs -#### Working Examples +### Working Examples Here's a non-exhaustive list of Packer plugins that you can check out: @@ -316,7 +308,7 @@ Here's a non-exhaustive list of Packer plugins that you can check out: Looking at their code will give you good examples. -#### Naming Conventions +### Naming Conventions It is standard practice to name the resulting plugin application in the format of `packer-plugin-NAME`. For example, if you're building a new builder for @@ -324,7 +316,7 @@ CustomCloud, it would be standard practice to name the resulting plugin `packer-plugin-customcloud`. This naming convention helps users identify the scope of a plugin. -#### Testing Plugins +### Testing Plugins Making your unpublished plugin available to Packer is possible by either: @@ -337,7 +329,7 @@ builder or source without needing to have a `required_plugin` block. This is extremely useful during development. -#### Distributing Plugins +### Distributing Plugins We recommend that you use a tool like the GoReleaser in order to cross-compile your plugin for every platform that Packer supports, since Go applications are diff --git a/website/content/docs/plugins/index.mdx b/website/content/docs/plugins/index.mdx index b0b80497f..513198b3c 100644 --- a/website/content/docs/plugins/index.mdx +++ b/website/content/docs/plugins/index.mdx @@ -1,6 +1,6 @@ --- description: | - Packer Plugins allow new functionality to be added to Packer without modifying + Packer plugins let you add Packer functionality without modifying the core source code. Packer plugins are able to add new builders, provisioners, hooks, and more. page_title: Plugins @@ -8,22 +8,14 @@ page_title: Plugins # Packer Plugins -Packer Plugins allow new functionality to be added to Packer without modifying -the core source code. **Packer plugins** are able to add new components to -Packer, such as **builders**, **provisioners**, **post-processors**, and **data -sources**. +Packer plugins are separate, standalone applications that perform tasks during each build. -This page documents how to install plugins. You can find a list of available -plugins in the [Plugins section](/plugins). +During a `packer build`, the process list shows `packer-` prefixed applications. One of those applications is the Packer binary, and the rest are plugins. Packer launches one plugin process for each component in the build. -If you're interested in developing plugins, see the [developing -plugins](/docs/plugins/creation#developing-plugins) page. +The Packer binary has a set of built-in plugins that it can find and run automatically. You can also define a list of external plugins in your template for Packer to run and communicate with throughout the build. These external plugins extend Packer functionality without modifying the core source code. -If you're a plugin maintainer interested in supporting HCP Packer, see the [HCP -support](/docs/plugins/hcp-support) page. - -@include "plugins/how-plugins-work.mdx" - -@include "plugins/plugin-tiers-and-namespaces.mdx" - -@include "plugins/installing-plugins.mdx" +Refer to the following plugin documentation: +- **Built-in Plugins:** Use [builders](/docs/builders) to create machines and images, [data sources](/docs/datasources) to fetch data, [provisioners](/docs/provisioners) to install and configure machine images, and [post-processors](/docs/post-processors) to perform additional tasks after provisioning +- **External Plugins:** Review the documentation for [available external plugins](/plugins) not included with the Packer binary +- **Installing Plugins:** [Installation Guides](/docs/plugins/install-plugins) to add external plugins to your Packer template and install the binaries +- **Developing Plugins:** Get started [creating custom external plugins](/docs/plugins/creation) \ No newline at end of file diff --git a/website/content/partials/plugins/installing-plugins.mdx b/website/content/docs/plugins/install-plugins.mdx similarity index 89% rename from website/content/partials/plugins/installing-plugins.mdx rename to website/content/docs/plugins/install-plugins.mdx index b0df5efc5..4e5c55165 100644 --- a/website/content/partials/plugins/installing-plugins.mdx +++ b/website/content/docs/plugins/install-plugins.mdx @@ -1,17 +1,23 @@ -## Installing Plugins +--- +description: | + Install external Packer plugins that extend Packer functionality. +page_title: Install Plugins +--- -Currently, you do not need to install plugins for builder, provisioner, or -post-processor components documented on the Packer website; these components -ship with the Packer core and Packer automatically knows how to find and launch -them. These instructions are for installing custom components that are not -bundled with the Packer core. +# Installing Plugins -The below tabs reference "multi-component" and "single-component" plugins. If -you are not sure what kind of plugin you are trying to install, the easiest way -to find out is to check the name. If the name starts with `packer-plugin-`, then -it is a multi-component plugin. If the name starts with a prefix that actually -says the component type (e.g. `packer-provisioner-` or `packer-builder`), then -it is a single-component plugin. +Packer plugins are separate, standalone applications that perform tasks during each build. + +You do not need to install the builder, provisioner, or +post-processor components that ship with the Packer binary. Packer automatically knows how to find and launch these built-in plugins. + +This page explains how to install custom external plugins. Refer to [External Plugins](/plugins) for a list of available plugins and their documentation. + +## Installation Guides + +Choose the tab that corresponds to the type of plugin you want to install. If you are not sure, check the plugin's name. +- Multi-component plugin names have the prefix `packer-plugin-`. +- Single-component plugin names have a prefix containing the component type, like `packer-provisioner-` or `packer-builder`. @@ -23,7 +29,7 @@ types will keep on being detected but Packer cannot install them automatically. If a plugin you use has not been upgraded to use the multi-component plugin architecture, contact your maintainer to request an upgrade. -### Create a required_plugins block +## Create a required_plugins block 1. Add a [`required_plugins`](/docs/templates/hcl_templates/blocks/packer#specifying-plugin-requirements) @@ -62,7 +68,7 @@ Each plugin has two identifiers: - A unique **local name**, which is used everywhere else in a Packer configuration. -### Local Names +## Local Names Local names allow you to access the components of a plugin and must be unique per configuration. @@ -258,4 +264,4 @@ The valid types for plugins are: builder. - + \ No newline at end of file diff --git a/website/content/partials/plugins/how-plugins-work.mdx b/website/content/partials/plugins/how-plugins-work.mdx deleted file mode 100644 index 0c90a0a85..000000000 --- a/website/content/partials/plugins/how-plugins-work.mdx +++ /dev/null @@ -1,13 +0,0 @@ -## How Plugins Work - -Packer plugins are completely separate, standalone applications that the core -of Packer starts and communicates with. Even the components that ship with the -Packer core (core builders, provisioners, and post-processors) are implemented -in a similar way and run as though they are standalone plugins. - -These plugin applications aren't meant to be run manually. Instead, Packer core -launches and communicates with them. The next time you run a Packer build, -look at your process list and you should see a handful of `packer-` prefixed -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. diff --git a/website/content/plugins/index.mdx b/website/content/plugins/index.mdx index 637d101a6..0ed8e857a 100644 --- a/website/content/plugins/index.mdx +++ b/website/content/plugins/index.mdx @@ -4,22 +4,10 @@ description: | page_title: Packer plugins --- -# Packer plugins +# External Packer Plugins -Packer Plugins allow new functionality to be added to Packer without modifying -the core source code. Packer plugins are able to add new components to Packer, -such as builders, provisioners, post-processors, and data sources. +External Packer plugins are standalone applications that extend Packer functionality without modifying the core source code. Plugins can add new components to Packer, such as builders, provisioners, post-processors, and data sources. Refer to [Packer Plugins](/docs/plugins) for details about installing and developing external plugins. -This page documents how to use plugins. - -If you're interested in developing plugins, see the [developing -plugins](/docs/plugins/creation#developing-plugins) page. - -On the left hand side of this page, you can find the available Packer plugins, -not all of them are 'official'. - -@include "plugins/how-plugins-work.mdx" +This section contains the documentation for available external Packer plugins. @include "plugins/plugin-tiers-and-namespaces.mdx" - -@include "plugins/installing-plugins.mdx" diff --git a/website/data/docs-nav-data.json b/website/data/docs-nav-data.json index 7eb4f8300..142baae0d 100644 --- a/website/data/docs-nav-data.json +++ b/website/data/docs-nav-data.json @@ -803,10 +803,6 @@ } ] }, - { - "title": "External Plugins", - "href": "/plugins" - }, { "divider": true }, @@ -822,14 +818,22 @@ "divider": true }, { - "title": "Packer Plugins", + "title": "Plugins", "routes": [ { "title": "Overview", "path": "plugins" }, { - "title": "Extending Packer", + "title": "Installing Plugins", + "path": "plugins/install-plugins" + }, + { + "title": "External Plugins", + "href": "/plugins" + }, + { + "title": "Developing Plugins", "routes": [ { "title": "Overview", @@ -850,12 +854,12 @@ { "title": "Custom Data Sources", "path": "plugins/creation/custom-datasources" + }, + { + "title": "HCP Packer Support", + "path": "plugins/creation/hcp-support" } ] - }, - { - "title": "HCP Packer Support", - "path": "plugins/hcp-support" } ] }, diff --git a/website/data/plugins-nav-data.json b/website/data/plugins-nav-data.json index e7c89da48..e82e0e2c1 100644 --- a/website/data/plugins-nav-data.json +++ b/website/data/plugins-nav-data.json @@ -1,6 +1,7 @@ [ + { "heading": "External Plugins" }, { - "title": "About External Plugins", + "title": "Overview", "path": "" }, {