image

package
v0.5.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Jun 18, 2024 License: MPL-2.0 Imports: 4 Imported by: 23

Documentation

Overview

Package image allows for the management of image metadata that can be stored in a HCP Packer registry.

Index

Examples

Constants

View Source
const ArtifactStateURI = "par.artifact.metadata"

ArtifactStateURI represents the key used by Packer when querying a packersdk.Artifact for Image metadata that a particular component would like to have stored on the HCP Packer Registry.

Variables

This section is empty.

Functions

func SetLabels

func SetLabels(md map[string]interface{}) func(*Image) error

SetLabels takes metadata, and returns a ArtifactOverrideFunc that can be used to set metadata for an existing Image. The incoming metadata `md` will be filtered only for keys whose values are of type string. If you wish to override this behavior you may create your own ArtifactOverrideFunc for manipulating and setting Image metadata.

Example
package main

import (
	"fmt"

	"github.com/hashicorp/packer-plugin-sdk/packer/registry/image"
)

type simpleArtifact struct {
	image_id string
}

func (a *simpleArtifact) BuilderId() string {
	return "example.happycloud"
}

func (a *simpleArtifact) Files() []string {
	return nil
}

func (a *simpleArtifact) Id() string {
	return a.image_id
}

func (a *simpleArtifact) String() string {
	return fmt.Sprintf("Imported image URL: %s", a.Id())
}

func (a *simpleArtifact) State(name string) interface{} {
	return nil
}

func (a *simpleArtifact) Destroy() error {
	return nil
}

func main() {
	a := &simpleArtifact{
		image_id: "service-id-123",
	}

	hcimage, _ := image.FromArtifact(a, image.SetLabels(map[string]interface{}{"kernel": "4.0", "python": "3.5"}))
	fmt.Printf("%v", hcimage.Labels)
}
Output:

map[kernel:4.0 python:3.5]

func WithID

func WithID(id string) func(*Image) error

WithID takes a id, and returns a ArtifactOverrideFunc that can be used to override the ImageId for an existing Image.

func WithProvider

func WithProvider(name string) func(*Image) error

WithProvider takes a name, and returns a ArtifactOverrideFunc that can be used to override the ProviderName for an existing Image.

Example
package main

import (
	"fmt"

	"github.com/hashicorp/packer-plugin-sdk/packer/registry/image"
)

type simpleArtifact struct {
	image_id string
}

func (a *simpleArtifact) BuilderId() string {
	return "example.happycloud"
}

func (a *simpleArtifact) Files() []string {
	return nil
}

func (a *simpleArtifact) Id() string {
	return a.image_id
}

func (a *simpleArtifact) String() string {
	return fmt.Sprintf("Imported image URL: %s", a.Id())
}

func (a *simpleArtifact) State(name string) interface{} {
	return nil
}

func (a *simpleArtifact) Destroy() error {
	return nil
}

func main() {
	a := &simpleArtifact{
		image_id: "service-id-123",
	}

	// This example also includes an override for the ProviderRegion to illustrate how ArtifactOverrideFunc(s) can be chained.
	hcimage, _ := image.FromArtifact(a, image.WithProvider("happycloud"), image.WithRegion("west"))
	fmt.Printf("%#v", *hcimage)
}
Output:

image.Image{ImageID:"service-id-123", ProviderName:"happycloud", ProviderRegion:"west", Labels:map[string]string{}, SourceImageID:""}

func WithRegion

func WithRegion(region string) func(*Image) error

WithRegion takes a region, and returns a ArtifactOverrideFunc that can be used to override the ProviderRegion for an existing Image.

func WithSourceID added in v0.2.6

func WithSourceID(id string) func(*Image) error

WithSourceID takes a id, and returns a ArtifactOverrideFunc that can be used to override the SourceImageId for an existing Image.

Example
package main

import (
	"fmt"

	"github.com/hashicorp/packer-plugin-sdk/packer/registry/image"
)

type simpleArtifact struct {
	image_id string
}

func (a *simpleArtifact) BuilderId() string {
	return "example.happycloud"
}

func (a *simpleArtifact) Files() []string {
	return nil
}

func (a *simpleArtifact) Id() string {
	return a.image_id
}

func (a *simpleArtifact) String() string {
	return fmt.Sprintf("Imported image URL: %s", a.Id())
}

func (a *simpleArtifact) State(name string) interface{} {
	return nil
}

func (a *simpleArtifact) Destroy() error {
	return nil
}

func main() {
	a := &simpleArtifact{
		image_id: "service-id-123",
	}

	// This example also includes an override for the ProviderRegion to illustrate how ArtifactOverrideFunc(s) can be chained.
	hcimage, _ := image.FromArtifact(a, image.WithProvider("happycloud"), image.WithRegion("west"), image.WithSourceID("ami-12345"))
	fmt.Printf("%#v", *hcimage)
}
Output:

image.Image{ImageID:"service-id-123", ProviderName:"happycloud", ProviderRegion:"west", Labels:map[string]string{}, SourceImageID:"ami-12345"}

Types

type ArtifactOverrideFunc

type ArtifactOverrideFunc func(*Image) error

ArtifactOverrideFunc represents a transformation func that can be applied to a non-nil *Image. See WithID, WithRegion functions for examples.

type Image

type Image struct {
	// ImageID is a unique reference identifier stored on the HCP Packer registry
	// that can be used to get back the built artifact of a builder or post-processor.
	ImageID string
	// ProviderName represents the name of the top level cloud or service where the built artifact resides.
	// For example "aws, azure, docker, gcp, and vsphere".
	ProviderName string
	// ProviderRegion represents the location of the built artifact.
	// For cloud providers region usually maps to a cloud region or zone, but for things like the file builder,
	// S3 bucket or vsphere cluster region can represent a path on the upstream datastore, or cluster.
	ProviderRegion string
	// Labels represents additional details about an image that a builder or post-processor may with to provide for a given build.
	// Any additional metadata will be made available as build labels within a HCP Packer registry iteration.
	Labels map[string]string
	// SourceImageID is the cloud image id of the image that was used as the
	// source for this image. If set, the HCP Packer registry will be able
	// link the parent and child images for ancestry visualizations and
	// dependency tracking.
	SourceImageID string
}

Image represents the metadata for some Artifact in the HCP Packer Registry.

func FromArtifact

func FromArtifact(a packer.Artifact, opts ...ArtifactOverrideFunc) (*Image, error)

FromArtifact returns an *Image that can be used by Packer core for publishing to the HCP Packer Registry. By default FromArtifact will use the a.BuilderID() as the ProviderName, and the a.Id() as the ImageID that should be tracked within the HCP Packer Registry. No Region is selected by default as region varies per builder. The use of one or more ArtifactOverrideFunc can be used to override any of the defaults used.

Example
package main

import (
	"fmt"

	"github.com/hashicorp/packer-plugin-sdk/packer/registry/image"
)

type simpleArtifact struct {
	image_id string
}

func (a *simpleArtifact) BuilderId() string {
	return "example.happycloud"
}

func (a *simpleArtifact) Files() []string {
	return nil
}

func (a *simpleArtifact) Id() string {
	return a.image_id
}

func (a *simpleArtifact) String() string {
	return fmt.Sprintf("Imported image URL: %s", a.Id())
}

func (a *simpleArtifact) State(name string) interface{} {
	return nil
}

func (a *simpleArtifact) Destroy() error {
	return nil
}

func main() {

	a := &simpleArtifact{
		image_id: "service-id-123",
	}

	hcimage, _ := image.FromArtifact(a)
	fmt.Printf("%#v", *hcimage)
}
Output:

image.Image{ImageID:"service-id-123", ProviderName:"example.happycloud", ProviderRegion:"", Labels:map[string]string{}, SourceImageID:""}

func FromMappedData

func FromMappedData(mappedData interface{}, f func(key, value interface{}) (*Image, error)) ([]*Image, error)

FromMappedData calls f sequentially for each key and value present in mappedData to create a []*Image as the final return value. If there is an error in calling f, FromMappedData will stop processing mapped items and result in a nil slice, with the said error.

FromMappedData will make its best attempt to convert the input map into map[interface{}]interface{} before calling f(k,v). The func f is responsible for type asserting the expected type for the key and value before trying to create an Image from it.

Example
package main

import (
	"errors"
	"fmt"
	"sort"
	"strings"

	"github.com/hashicorp/packer-plugin-sdk/packer/registry/image"
)

type artifact struct {
	images map[string]string
}

func (a *artifact) BuilderId() string {
	return "example.happycloud"
}

func (a *artifact) Files() []string {
	return nil
}

func (a *artifact) Id() string {
	parts := make([]string, 0, len(a.images))
	for loc, id := range a.images {
		parts = append(parts, loc+":"+id)
	}
	sort.Strings(parts)
	return strings.Join(parts, ",")
}

func (a *artifact) String() string {
	return a.Id()
}

func (a *artifact) State(name string) interface{} {
	return nil
}

func (a *artifact) Destroy() error {
	return nil
}

func main() {
	a := &artifact{
		images: map[string]string{
			"west": "happycloud-1",
			"east": "happycloud-2",
		},
	}

	f := func(key, value interface{}) (*image.Image, error) {
		v, ok := value.(string)
		if !ok {
			return nil, errors.New("for happycloud maps value should always be string")
		}
		k, ok := key.(string)
		if !ok {
			return nil, errors.New("for happycloud maps key should always be string")
		}

		img := image.Image{ProviderName: "happycloud", ProviderRegion: k, ImageID: v}
		return &img, nil
	}

	hcimages, _ := image.FromMappedData(a.images, f)
	for _, hcimage := range hcimages {
		fmt.Printf("%#v\n", *hcimage)
	}
}
Output:

image.Image{ImageID:"happycloud-1", ProviderName:"happycloud", ProviderRegion:"west", Labels:map[string]string(nil), SourceImageID:""}
image.Image{ImageID:"happycloud-2", ProviderName:"happycloud", ProviderRegion:"east", Labels:map[string]string(nil), SourceImageID:""}

func (*Image) String

func (i *Image) String() string

String returns string representation of Image

func (*Image) Validate

func (i *Image) Validate() error

Validate checks that the Image i contains a non-empty ImageID and ProviderName.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL