Documentation
¶
Overview ¶
Package image allows for the management of image metadata that can be stored in a HCP Packer registry.
Index ¶
Examples ¶
Constants ¶
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 ¶
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 ¶
WithID takes a id, and returns a ArtifactOverrideFunc that can be used to override the ImageId for an existing Image.
func WithProvider ¶
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 ¶
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
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 ¶
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:""}
Source Files