Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Backport of Document process for registering a plugin as a Packer Integration into stable-website #12745

Conversation

hc-github-team-packer
Copy link
Collaborator

Backport

This PR is auto-generated from #12702 to be assessed for backporting due to the inclusion of the label backport/website.

The below text is copied from the body of the original PR.


Original PR had no description content.


Overview of commits

lbajolet-hashicorp and others added 30 commits May 30, 2023 17:20
On HCP, multiproject support was GA'd recently, but Packer does not
support the feature yet.

To avoid clients being surprised if they encounter an error with this
feature enabled, we add an advisory related to this feature not being
supported for now, but planned for later.
With HCP supporting multi-projects now, Packer needs to take it into
account when picking a project from an organisation.

This commit adds two cases:

1. multiple projects are defined, none is supplied through
   HCP_PROJECT_ID: in this case we will default to the oldest project
   defined for the organisation.

2. we supply HCP_PROJECT_ID: in this case, we pick the project with the
   corresponding ID, and use it for publishing metadata.
* docs: add a paragraph on fingerprint generation

Since version 1.9.0+ changed the way Packer generates fingerprints for
HCP Packer, we add a small paragraph to explain how it used to be
generated before, and how it changed in this version.

* Apply suggestions from code review

---------

Co-authored-by: Wilken Rivera <wilken@hashicorp.com>
Remove the check-legacy-links-format.yml workflow. These checks are now included as part of our
content conformance checks that run on PRs with documentation content changes.
Packer will try to discover installed plugins in all of the directories
defined by packer.KnowPluginFolders. In a previous release logic was
added to scan nested directories in order to load plugins installed by
`packer plugins install`. This change resulted in a nested directory
scan for each folder within the KnownPluginFolders slice.

This change reduces the nested directory scan to only the directories
where plugins would have been installed using `packer plugins install`
* PACKER_PLUGIN_PATH takes precedence over all
#12476)

* Update external plugin documentation source

The Parallels plugin for Packer is now maintained by the Parallels team, under
their respective GitHub org. This changes updates the source address for
the external plugin that should be used for pulling new plugin
documentation.

* Removed packer-plugin-parallels for list of vendored plugins
Packer checks a number of directories for plugins upon initialization,
with the introduction of multi-component plugins and underlying changes
to the Packer SDK the ordering changed slightly. These changes update
the related documentation to reflect the new ordering, and adds a plugin
loading ordering section to the docs to help users discover how plugin
loading works.

Include in this change are updates to the PACKER_CONFIG_DIR environment
variables to reflect the XDG base directory specification used as the
default Packer configuration directory layout.

* Update website/content/docs/configure.mdx
When the config file header was reworked, an erroneous link was
included and placed so close to the header that it was rendered verbatim
in the final documentation page.

By adding an extra empty line in between the anchor link and the header,
this renders correctly.
In HCL2, if a template contains a `required_plugins' block, but the
required plugins are not installed, we print a warning.

Prior to this commit, this was reported as an error once per missing
plugin, which was redundant.
This commit changes that by gathering all the missing plugins once, and
printing them as a bullet list, so the message isn't redundant anymore.
Since the `discoverExternalComponents' function was defined but not
called anywhere, it is dead code, and can be safely removed from the
codebase.
Since bundled plugins will be removed in an upcoming version of Packer,
this commit adds a new warning message whenever a template uses one such
plugin.

This warning has been implemented on build, validate, console and the
inspect subcommands.

In addition to warning about the upcoming change and potential issue
this will cause, this warning message proposes solutions to the user so
they know what they'll have to do in order not to rely on those bundled
plugins later.
When a legacy JSON template references built-in plugins, we add them to
the resulting template as a `required_plugins' block in HCL2.
The Makefile would check for executable files inside the Packer
repository, and produce errors if one was detected and not explicitely
whitelisted through the `EXECUTABLE_FILES' Makefile variable.

This check was introduced a while back to avoid having executable files
in the repository, but this check can be problematic sometimes because
of how it is written, namely when building the website, which causes a
lot of JS executable files to appear in the hierarchy, and in turn this
causes the shell expansion to fail because of the large number of
arguments.

Since this test is not necessary for Packer to build or test, and since
it implies that we have to maintain the whitelist regex, we remove it
from the Makefile.
Co-authored-by: Lucas Bajolet <105649352+lbajolet-hashicorp@users.noreply.github.com>
Co-authored-by: hashicorp-tsccr[bot] <hashicorp-tsccr[bot]@users.noreply.github.com>
nywilken and others added 22 commits November 29, 2023 14:49
In order to better document packer plugins installation methods, and
since `packer plugins install' is not really manual, we split in two
sections the "manual installation".

As this is legacy, we stop documenting how to install single-component
plugins, and reword the documentation for manually installing a plugin.
This section is redundant with the explanations given above, and can
therefore be removed from the docs.
The current documentation about installing plugins does not explain
(outside of the `packer init' section) how Packer discovers plugins,
what the expected file system hierarchy should be, and the quirk of how
this takes precedence over the rest when `required_plugins' is
specified.

This commit addresses that by reorganising the page to highlight general
usage questions on sources and plugins, and simplifies the tabs below to
only highlight installation methods.
This new flag allows the `packer plugins install' command to install a
plugin from a local binary rather than from Github.

This command will only call `describe' on the plugin, and won't do any
further checks for functionality. The SHA256SUM will be directly
computed from the binary, so as with anything manual and potentially
sourced by the community, extra care should be applied when invoking
this.
The --force option for packer init and packer plugins install enforces
installation of a plugin, even if it is already locally installed.

This will become useful if for some reason a pre-existing plugin
binary/version is already installed, and we want to overwrite it.
To avoid plugins being installed with a specific version when a path is
used for installing a plugin from a locally sourced plugin binary, we
explicitly reject the combination of both a path and a version for
plugins install.
When installing a plugin with packer plugins install --path, we only
accept release versions of a plugin, as otherwise the loading can be
inconsistent if for example a user specifies a required_plugins block in
their template, in which case the plugins will be ignored.

Until we have a simpler loading scheme then, we will reject non-release
versions of plugins to avoid confusion.
Read original binary into memory to fix case when installation
destination and source were the same, resulting in an empty binary.
This change removes the following plugins from the old docs framework, as
they have been fully migrated to the integrations framework.

* ethanmdavidson/packer-plugin-git
* linode/packer-plugin-linode
* parallels/packer-plugin-parallels
* ivoronin/packer-plugin-sshkey
* cirruslabs/packer-plugin-tart
The plugins installed command list installed plugins, and prints out all
their paths and versions.

The results are listed in a list of unique versions, in ascending
order.

When listing plugins outside of a specific identifier however, because
of the insertion in the list works, we only consider the version number,
and ignore all subsequent insertions with the same version.

This causes a problem when we have multiple plugins installed with the
same version, as only the first one that is discovered (typically the
one with lexicographical precedence) gets inserted, and the others are
ignored.

To support such a use case, we change the insertion routine to not only
support versions, but also paths when finding a spot to insert the
installation into.
Copy link

github-actions bot commented Jan 5, 2024

I'm going to lock this pull request because it has been closed for 30 days ⏳. This helps our maintainers find and focus on the active issues.
If you have found a problem that seems related to this change, please open a new issue and complete the issue template so we can capture all the details necessary to investigate further.

@github-actions github-actions bot locked as resolved and limited conversation to collaborators Jan 5, 2024
@lbajolet-hashicorp lbajolet-hashicorp deleted the backport/update/plugin-integration-docs/externally-divine-rattler branch March 7, 2024 19:50
Sign up for free to subscribe to this conversation on GitHub. Already have an account? Sign in.
Labels
None yet
Projects
None yet
Development

Successfully merging this pull request may close these issues.