upstream/packer
1
0
Fork 0
mirror of https://github.com/hashicorp/packer.git synced 2026-06-08 16:22:15 -04:00
Code Issues Projects Releases Packages Wiki Activity Actions 4

document the plugin-getter.Get interface (#11196)

Browse source
This commit is contained in:
Adrien Delorme 2021-08-11 16:32:38 +02:00 committed by GitHub
parent a534c743cf
commit 689c7763d4
No known key found for this signature in database
GPG key ID: 4AEE18F83AFDEB23
1 changed files with 46 additions and 4 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

50
packer/plugin-getter/plugins.go
View file

@ -273,10 +273,52 @@ func (gp *GetOptions) Version() string {
// A Getter helps get the appropriate files to download a binary.
type Getter interface {
// Get:
// * 'releases'
// * 'sha256'
// * 'binary'
// Get allows Packer to know more information about releases of a plugin in
// order to decide which version to install. Get behaves similarly to an
// HTTP server. Packer will stream responses from get in order to do what's
// needed. In order to minimize the amount of requests done, Packer is
// strict on filenames and we highly recommend on automating releases.
// In the future, Packer will make it possible to ship plugin getters as
// binaries this is why Packer streams from the output of get, which will
// then be a command.
//
// * 'releases', get 'releases' should return the complete list of Releases
// in JSON format following the format of the Release struct. It is also
// possible to read GetOptions to filter for a smaller response. Some
// getters don't. Packer will then decide the highest compatible
// version of the plugin to install by using the sha256 function.
//
// * 'sha256', get 'sha256' should return a SHA256SUMS txt file. It will be
// called with the highest possible & user allowed version from get
// 'releases'. Packer will check if the release has a binary matching what
// Packer can install and use. If so, get 'binary' will be called;
// otherwise, lower versions will be checked.
// For version 1.0.0 of the 'hashicorp/amazon' builder, the GitHub getter
// will fetch the following URL:
// https://github.com/hashicorp/packer-plugin-amazon/releases/download/v1.0.0/packer-plugin-amazon_v1.0.0_SHA256SUMS
// This URL can be parameterized to the following one:
// https://github.com/{plugin.path}/releases/download/{plugin.version}/packer-plugin-{plugin.name}_{plugin.version}_SHA256SUMS
// If Packer is running on Linux AMD 64, then Packer will check for the
// existence of a packer-plugin-amazon_v1.0.0_x5.0_linux_amd64 checksum in
// that file. This filename can be parameterized to the following one:
// packer-plugin-{plugin.name}_{plugin.version}_x{proto_ver.major}.{proto_ver._minor}_{os}_{arch}
//
// See
// https://github.com/hashicorp/packer-plugin-scaffolding/blob/main/.goreleaser.yml
// and
// https://www.packer.io/docs/plugins/creation#plugin-development-basics
// to learn how to create and automate your releases and for docs on
// plugin development basics.
//
// * get 'zip' is called once we know what version we want and that it is
// compatible with the OS and Packer. Zip expects an io stream of a zip
// file containing a binary. For version 1.0.0 of the 'hashicorp/amazon'
// builder and on darwin_amd64, the GitHub getter will fetch the
// following ZIP:
// https://github.com/hashicorp/packer-plugin-amazon/releases/download/v1.0.0/packer-plugin-amazon_v1.0.0_x5.0_darwin_amd64.zip
// this zip is expected to contain a
// packer-plugin-amazon_v1.0.0_x5.0_linux_amd64 file that will be checksum
// verified then copied to the correct plugin location.
Get(what string, opts GetOptions) (io.ReadCloser, error)
}