imgutil

package module
v0.0.0-...-186f89b Latest Latest
Warning

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

 Go to latest Published: Jun 5, 2024 License: Apache-2.0 Imports: 25 Imported by: 20

README

imgutil

Build results

Helpful utilities for working with images

Development

To format:

$ make format

To run tests:

$ make test

Documentation

Index

Constants

This section is empty.

Variables

View Source 
var (
	ErrManifestUndefined = errors.New("encountered unexpected error while parsing image: manifest or index manifest is nil")
	ErrUnknownMediaType  = func(format types.MediaType) error {
		return fmt.Errorf("unsupported media type encountered in image: '%s'", format)
	}
)
View Source 
var NormalizedDateTime = time.Date(1980, time.January, 1, 0, 0, 1, 0, time.UTC)

Functions

func EnsureMediaTypesAndLayers 

func EnsureMediaTypesAndLayers(image v1.Image, requestedTypes MediaTypes, mutateLayer func(idx int, layer v1.Layer) (v1.Layer, error)) (v1.Image, bool, error)

EnsureMediaTypesAndLayers replaces the provided image with a new image that has the desired media types. It does this by constructing a manifest and config from the provided image, and adding the layers from the provided image to the new image with the right media type. If requested types are missing or default, it does nothing. While adding the layers, each layer can be additionally mutated by providing a "mutate layer" function.

func FromBaseImage 

func FromBaseImage(name string) func(*ImageOptions)

FromBaseImage loads the provided image as the manifest, config, and layers for the working image. If the image is not found, it does nothing.

func FromBaseIndex 

func FromBaseIndex(name string) func(*IndexOptions) error

FromBaseIndex sets the name to use when loading the index. It used to either construct the path (if using layout) or the repo name (if using remote). If the index is not found, it does nothing.

func FromBaseIndexInstance 

func FromBaseIndexInstance(index v1.ImageIndex) func(options *IndexOptions) error

FromBaseIndexInstance sets the provided image index as the working image index.

func GetConfigFile 

func GetConfigFile(image v1.Image) (*v1.ConfigFile, error)

func GetManifest 

func GetManifest(image v1.Image) (*v1.Manifest, error)

func GetTransport 

func GetTransport(insecure bool) http.RoundTripper

func MakeFileSafeName 

func MakeFileSafeName(ref string) string

MakeFileSafeName Change a reference name string into a valid file name Ex: cnbs/sample-package:hello-multiarch-universe to cnbs_sample-package-hello-multiarch-universe

func NewEmptyDockerIndex 

func NewEmptyDockerIndex() v1.ImageIndex

func NormalizedHistory 

func NormalizedHistory(history []v1.History, nLayers int) []v1.History

func PreserveLayers 

func PreserveLayers(_ int, layer v1.Layer) (v1.Layer, error)

func WithConfig 

func WithConfig(c *v1.Config) func(*ImageOptions)

WithConfig lets a caller provided a `config` object for the working image.

func WithCreatedAt 

func WithCreatedAt(t time.Time) func(*ImageOptions)

WithCreatedAt lets a caller set the "created at" timestamp for the working image when saved. If not provided, the default is NormalizedDateTime.

func WithDefaultPlatform 

func WithDefaultPlatform(p Platform) func(*ImageOptions)

WithDefaultPlatform provides the default Architecture/OS/OSVersion if no base image is provided, or if the provided image inputs (base and previous) are manifest lists.

func WithHistory 

func WithHistory() func(*ImageOptions)

WithHistory if provided will configure the image to preserve history when saved (including any history from the base image if valid).

func WithInsecure 

func WithInsecure() func(options *IndexOptions) error

WithInsecure if true pulls and pushes the image to an insecure registry.

func WithKeychain 

func WithKeychain(keychain authn.Keychain) func(options *IndexOptions) error

WithKeychain fetches Index from registry with keychain

func WithMediaType 

func WithMediaType(mediaType types.MediaType) func(options *IndexOptions) error

WithMediaType specifies the media type for the image index.

func WithMediaTypes 

func WithMediaTypes(m MediaTypes) func(*ImageOptions)

WithMediaTypes lets a caller set the desired media types for the manifest and config (including layers referenced in the manifest) to be either OCI media types or Docker media types.

func WithPreviousImage 

func WithPreviousImage(name string) func(*ImageOptions)

WithPreviousImage loads an existing image as the source for reusable layers. Use with ReuseLayer(). If the image is not found, it does nothing.

func WithPurge 

func WithPurge(purge bool) func(options *IndexOptions) error

WithPurge if true deletes the index from the local filesystem after pushing

func WithTags 

func WithTags(tags ...string) func(options *IndexOptions) error

WithTags sets the destination tags for the index when pushed

func WithXDGRuntimePath 

func WithXDGRuntimePath(xdgPath string) func(options *IndexOptions) error

WithXDGRuntimePath Saves the Index to the '`xdgPath`/manifests'

Types

type CNBImageCore 

type CNBImageCore struct {
	// required
	v1.Image // the working image
	// contains filtered or unexported fields
}

CNBImageCore wraps a v1.Image and provides most of the methods necessary for the image to satisfy the Image interface. Specific implementations may choose to override certain methods, and will need to supply the methods that are omitted, such as Identifier() and Found(). The working image could be any v1.Image, but in practice will start off as a pointer to a local.v1ImageFacade (or similar).

func NewCNBImage 

func NewCNBImage(options ImageOptions) (*CNBImageCore, error)

func (*CNBImageCore) AddLayer 

func (i *CNBImageCore) AddLayer(path string) error

func (*CNBImageCore) AddLayerWithDiffID 

func (i *CNBImageCore) AddLayerWithDiffID(path, _ string) error

func (*CNBImageCore) AddLayerWithDiffIDAndHistory 

func (i *CNBImageCore) AddLayerWithDiffIDAndHistory(path, _ string, history v1.History) error

func (*CNBImageCore) AddLayerWithHistory 

func (i *CNBImageCore) AddLayerWithHistory(layer v1.Layer, history v1.History) error

func (*CNBImageCore) AddOrReuseLayerWithHistory 

func (i *CNBImageCore) AddOrReuseLayerWithHistory(path string, diffID string, history v1.History) error

func (*CNBImageCore) AnnotateRefName 

func (i *CNBImageCore) AnnotateRefName(refName string) error

func (*CNBImageCore) Annotations 

func (i *CNBImageCore) Annotations() (map[string]string, error)

func (*CNBImageCore) Architecture 

func (i *CNBImageCore) Architecture() (string, error)

TBD Deprecated: Architecture

func (*CNBImageCore) CreatedAt 

func (i *CNBImageCore) CreatedAt() (time.Time, error)

TBD Deprecated: CreatedAt

func (*CNBImageCore) Entrypoint 

func (i *CNBImageCore) Entrypoint() ([]string, error)

TBD Deprecated: Entrypoint

func (*CNBImageCore) Env 

func (i *CNBImageCore) Env(key string) (string, error)

func (*CNBImageCore) GetAnnotateRefName 

func (i *CNBImageCore) GetAnnotateRefName() (string, error)

func (*CNBImageCore) GetLayer 

func (i *CNBImageCore) GetLayer(diffID string) (io.ReadCloser, error)

func (*CNBImageCore) History 

func (i *CNBImageCore) History() ([]v1.History, error)

TBD Deprecated: History

func (*CNBImageCore) Label 

func (i *CNBImageCore) Label(key string) (string, error)

TBD Deprecated: Label

func (*CNBImageCore) Labels 

func (i *CNBImageCore) Labels() (map[string]string, error)

TBD Deprecated: Labels

func (*CNBImageCore) ManifestSize 

func (i *CNBImageCore) ManifestSize() (int64, error)

TBD Deprecated: ManifestSize

func (*CNBImageCore) MutateConfigFile 

func (i *CNBImageCore) MutateConfigFile(withFunc func(c *v1.ConfigFile)) error

func (*CNBImageCore) OS 

func (i *CNBImageCore) OS() (string, error)

TBD Deprecated: OS

func (*CNBImageCore) OSFeatures 

func (i *CNBImageCore) OSFeatures() ([]string, error)

func (*CNBImageCore) OSVersion 

func (i *CNBImageCore) OSVersion() (string, error)

TBD Deprecated: OSVersion

func (*CNBImageCore) PreviousImageHasLayer 

func (i *CNBImageCore) PreviousImageHasLayer(diffID string) (bool, error)

func (*CNBImageCore) Rebase 

func (i *CNBImageCore) Rebase(baseTopLayerDiffID string, withNewBase Image) error

func (*CNBImageCore) RemoveLabel 

func (i *CNBImageCore) RemoveLabel(key string) error

func (*CNBImageCore) ReuseLayer 

func (i *CNBImageCore) ReuseLayer(diffID string) error

func (*CNBImageCore) ReuseLayerWithHistory 

func (i *CNBImageCore) ReuseLayerWithHistory(diffID string, history v1.History) error

func (*CNBImageCore) SetAnnotations 

func (i *CNBImageCore) SetAnnotations(annotations map[string]string) error

func (*CNBImageCore) SetArchitecture 

func (i *CNBImageCore) SetArchitecture(architecture string) error

TBD Deprecated: SetArchitecture

func (*CNBImageCore) SetCmd 

func (i *CNBImageCore) SetCmd(cmd ...string) error

TBD Deprecated: SetCmd

func (*CNBImageCore) SetCreatedAtAndHistory 

func (i *CNBImageCore) SetCreatedAtAndHistory() error

func (*CNBImageCore) SetEntrypoint 

func (i *CNBImageCore) SetEntrypoint(ep ...string) error

TBD Deprecated: SetEntrypoint

func (*CNBImageCore) SetEnv 

func (i *CNBImageCore) SetEnv(key, val string) error

func (*CNBImageCore) SetHistory 

func (i *CNBImageCore) SetHistory(histories []v1.History) error

TBD Deprecated: SetHistory

func (*CNBImageCore) SetLabel 

func (i *CNBImageCore) SetLabel(key, val string) error

func (*CNBImageCore) SetOS 

func (i *CNBImageCore) SetOS(osVal string) error

func (*CNBImageCore) SetOSFeatures 

func (i *CNBImageCore) SetOSFeatures(osFeatures []string) error

func (*CNBImageCore) SetOSVersion 

func (i *CNBImageCore) SetOSVersion(osVersion string) error

TBD Deprecated: SetOSVersion

func (*CNBImageCore) SetVariant 

func (i *CNBImageCore) SetVariant(variant string) error

TBD Deprecated: SetVariant

func (*CNBImageCore) SetWorkingDir 

func (i *CNBImageCore) SetWorkingDir(dir string) error

TBD Deprecated: SetWorkingDir

func (*CNBImageCore) TopLayer 

func (i *CNBImageCore) TopLayer() (string, error)

func (*CNBImageCore) UnderlyingImage 

func (i *CNBImageCore) UnderlyingImage() v1.Image

UnderlyingImage is used to expose a v1.Image from an imgutil.Image, which can be useful in certain situations (such as rebase).

func (*CNBImageCore) Variant 

func (i *CNBImageCore) Variant() (string, error)

TBD Deprecated: Variant

func (*CNBImageCore) WorkingDir 

func (i *CNBImageCore) WorkingDir() (string, error)

TBD Deprecated: WorkingDir

type CNBIndex 

type CNBIndex struct {
	// required
	v1.ImageIndex // the working image index
	// local options
	XdgPath string
	// push options
	KeyChain authn.Keychain
	RepoName string
}

func NewCNBIndex 

func NewCNBIndex(repoName string, options IndexOptions) (*CNBIndex, error)

func (*CNBIndex) AddManifest 

func (h *CNBIndex) AddManifest(image v1.Image)

AddManifest adds an image to the index.

func (*CNBIndex) Annotations 

func (h *CNBIndex) Annotations(digest name.Digest) (annotations map[string]string, err error)

Annotations return the `Annotations` of an Image with given Digest. Returns an error if no Image/Index found with given Digest. For Docker images and Indexes it returns an error.

func (*CNBIndex) Architecture 

func (h *CNBIndex) Architecture(digest name.Digest) (arch string, err error)

Architecture return the Architecture of an Image/Index based on given Digest. Returns an error if no Image/Index found with given Digest.

func (*CNBIndex) DeleteDir 

func (h *CNBIndex) DeleteDir() error

DeleteDir removes the index from the local filesystem if it exists.

func (*CNBIndex) Image 

func (h *CNBIndex) Image(hash v1.Hash) (v1.Image, error)

func (*CNBIndex) Inspect 

func (h *CNBIndex) Inspect() (string, error)

Inspect Displays IndexManifest.

func (*CNBIndex) OS 

func (h *CNBIndex) OS(digest name.Digest) (os string, err error)

OS returns `OS` of an existing Image.

func (*CNBIndex) OSFeatures 

func (h *CNBIndex) OSFeatures(digest name.Digest) (osFeatures []string, err error)

OSFeatures returns the `OSFeatures` of an Image with given Digest. Returns an error if no Image/Index found with given Digest.

func (*CNBIndex) OSVersion 

func (h *CNBIndex) OSVersion(digest name.Digest) (osVersion string, err error)

OSVersion returns the `OSVersion` of an Image with given Digest. Returns an error if no Image/Index found with given Digest.

func (*CNBIndex) Push 

func (h *CNBIndex) Push(ops ...IndexOption) error

Push Publishes ImageIndex to the registry assuming every image it referes exists in registry.

It will only push the IndexManifest to registry.

func (*CNBIndex) RemoveManifest 

func (h *CNBIndex) RemoveManifest(digest name.Digest) (err error)

RemoveManifest removes an image with a given digest from the index.

func (*CNBIndex) SaveDir 

func (h *CNBIndex) SaveDir() error

SaveDir will locally save the index.

func (*CNBIndex) SetAnnotations 

func (h *CNBIndex) SetAnnotations(digest name.Digest, annotations map[string]string) (err error)

func (*CNBIndex) SetArchitecture 

func (h *CNBIndex) SetArchitecture(digest name.Digest, arch string) (err error)

func (*CNBIndex) SetOS 

func (h *CNBIndex) SetOS(digest name.Digest, os string) (err error)

func (*CNBIndex) SetVariant 

func (h *CNBIndex) SetVariant(digest name.Digest, osVariant string) (err error)

func (*CNBIndex) Variant 

func (h *CNBIndex) Variant(digest name.Digest) (osVariant string, err error)

Variant return the `Variant` of an Image. Returns an error if no Image/Index found with given Digest.

type ErrLayerNotFound 

type ErrLayerNotFound struct {
	DiffID string
}

func (ErrLayerNotFound) Error 

func (e ErrLayerNotFound) Error() string

type Identifier 

type Identifier fmt.Stringer

type Image 

type Image interface {
	WithEditableManifest
	WithEditableConfig
	WithEditableLayers

	// Found reports if image exists in the image store with `Name()`.
	Found() bool
	Identifier() (Identifier, error)
	// Kind exposes the type of image that backs the imgutil.Image implementation.
	// It could be `local`, `remote`, or `layout`.
	Kind() string
	Name() string
	UnderlyingImage() v1.Image
	// Valid returns true if the image is well-formed (e.g. all manifest layers exist on the registry).
	Valid() bool

	Delete() error
	Rename(name string)
	// Save saves the image as `Name()` and any additional names provided to this method.
	Save(additionalNames ...string) error
	// SaveAs ignores the image `Name()` method and saves the image according to name & additional names provided to this method
	SaveAs(name string, additionalNames ...string) error
	// SaveFile saves the image as a docker archive and provides the filesystem location
	SaveFile() (string, error)
}

type ImageIndex 

type ImageIndex interface {
	Annotations(digest name.Digest) (annotations map[string]string, err error)
	Architecture(digest name.Digest) (arch string, err error)
	OS(digest name.Digest) (os string, err error)
	OSFeatures(digest name.Digest) (osFeatures []string, err error)
	OSVersion(digest name.Digest) (osVersion string, err error)
	Variant(digest name.Digest) (osVariant string, err error)

	SetAnnotations(digest name.Digest, annotations map[string]string) (err error)
	SetArchitecture(digest name.Digest, arch string) (err error)
	SetOS(digest name.Digest, os string) (err error)
	SetVariant(digest name.Digest, osVariant string) (err error)

	Inspect() (string, error)
	AddManifest(image v1.Image)
	RemoveManifest(digest name.Digest) error

	Push(ops ...IndexOption) error
	SaveDir() error
	DeleteDir() error
}

ImageIndex an Interface with list of Methods required for creation and manipulation of v1.IndexManifest

type ImageOption 

type ImageOption func(*ImageOptions)

type ImageOptions 

type ImageOptions struct {
	BaseImageRepoName     string
	PreviousImageRepoName string
	Config                *v1.Config
	CreatedAt             time.Time
	MediaTypes            MediaTypes
	Platform              Platform
	PreserveHistory       bool
	LayoutOptions
	RemoteOptions

	// These options must be specified in each implementation's image constructor
	BaseImage     v1.Image
	PreviousImage v1.Image
}

type IndexOption 

type IndexOption func(options *IndexOptions) error

type IndexOptions 

type IndexOptions struct {
	BaseIndexRepoName string
	MediaType         types.MediaType
	LayoutIndexOptions
	RemoteIndexOptions
	IndexPushOptions

	// These options must be specified in each implementation's image index constructor
	BaseIndex v1.ImageIndex
}

type IndexPushOptions 

type IndexPushOptions struct {
	Purge           bool
	DestinationTags []string
}

type LayoutIndexOptions 

type LayoutIndexOptions struct {
	XdgPath string
}

type LayoutOptions 

type LayoutOptions struct {
	PreserveDigest bool
	WithoutLayers  bool
}

type MediaTypes 

type MediaTypes int
const (
	MissingTypes MediaTypes = iota
	DefaultTypes
	OCITypes
	DockerTypes
)

func GetPreferredMediaTypes 

func GetPreferredMediaTypes(options ImageOptions) MediaTypes

func (MediaTypes) ConfigType 

func (t MediaTypes) ConfigType() types.MediaType

func (MediaTypes) LayerType 

func (t MediaTypes) LayerType() types.MediaType

func (MediaTypes) ManifestType 

func (t MediaTypes) ManifestType() types.MediaType

type Platform 

type Platform struct {
	Architecture string
	OS           string
	Variant      string
	OSVersion    string
}

Platform represents the target arch/os/variant/os_version for an image construction and querying.

type RegistrySetting 

type RegistrySetting struct {
	Insecure bool
}

type RemoteIndexOptions 

type RemoteIndexOptions struct {
	Keychain authn.Keychain
	Insecure bool
}

type RemoteOptions 

type RemoteOptions struct {
	RegistrySettings    map[string]RegistrySetting
	AddEmptyLayerOnSave bool
}

type SaveDiagnostic 

type SaveDiagnostic struct {
	ImageName string
	Cause     error
}

type SaveError 

type SaveError struct {
	Errors []SaveDiagnostic
}

func (SaveError) Error 

func (e SaveError) Error() string

type StringSet 

type StringSet struct {
	// contains filtered or unexported fields
}

func NewStringSet 

func NewStringSet() *StringSet

func (*StringSet) Add 

func (s *StringSet) Add(str string)

func (*StringSet) Remove 

func (s *StringSet) Remove(str string)

func (*StringSet) StringSlice 

func (s *StringSet) StringSlice() (slice []string)

type TaggableIndex 

type TaggableIndex struct {
	*v1.IndexManifest
}

TaggableIndex any ImageIndex with RawManifest method.

func NewTaggableIndex 

func NewTaggableIndex(manifest *v1.IndexManifest) *TaggableIndex

func (*TaggableIndex) Digest 

func (t *TaggableIndex) Digest() (v1.Hash, error)

Digest returns the Digest of the IndexManifest if present. Else generate a new Digest.

func (*TaggableIndex) MediaType 

func (t *TaggableIndex) MediaType() (types.MediaType, error)

MediaType returns the MediaType of the IndexManifest.

func (*TaggableIndex) RawManifest 

func (t *TaggableIndex) RawManifest() ([]byte, error)

RawManifest returns the bytes of IndexManifest.

func (*TaggableIndex) Size 

func (t *TaggableIndex) Size() (int64, error)

Size returns the Size of IndexManifest if present. Calculate the Size of empty.

type WithEditableConfig 

type WithEditableConfig interface {
	Architecture() (string, error)
	CreatedAt() (time.Time, error)
	Entrypoint() ([]string, error)
	Env(key string) (string, error)
	History() ([]v1.History, error)
	Label(string) (string, error)
	Labels() (map[string]string, error)
	OS() (string, error)
	OSFeatures() ([]string, error)
	OSVersion() (string, error)
	RemoveLabel(string) error
	Variant() (string, error)
	WorkingDir() (string, error)

	SetArchitecture(string) error
	SetCmd(...string) error
	SetEntrypoint(...string) error
	SetEnv(string, string) error
	SetHistory([]v1.History) error
	SetLabel(string, string) error
	SetOS(string) error
	SetOSFeatures([]string) error
	SetOSVersion(string) error
	SetVariant(string) error
	SetWorkingDir(string) error
}

type WithEditableLayers 

type WithEditableLayers interface {

	// GetLayer retrieves layer by diff id. Returns a reader of the uncompressed contents of the layer.
	GetLayer(diffID string) (io.ReadCloser, error)
	// TopLayer returns the diff id for the top layer
	TopLayer() (string, error)

	AddLayer(path string) error
	AddLayerWithDiffID(path, diffID string) error
	AddLayerWithDiffIDAndHistory(path, diffID string, history v1.History) error
	AddOrReuseLayerWithHistory(path, diffID string, history v1.History) error
	Rebase(string, Image) error
	ReuseLayer(diffID string) error
	ReuseLayerWithHistory(diffID string, history v1.History) error
}

type WithEditableManifest 

type WithEditableManifest interface {
	Annotations() (map[string]string, error)
	Digest() (v1.Hash, error)
	GetAnnotateRefName() (string, error)
	ManifestSize() (int64, error)
	MediaType() (types.MediaType, error)

	AnnotateRefName(refName string) error
	SetAnnotations(map[string]string) error
}

Source Files

View all Source files

Directories

Path Synopsis
sparse

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.