mutate

Documentation

Overview

Package mutate implements various functionality to allow for the modification of container images in a much higher-level fashion than available from github.com/opencontainers/umoci/oci/cas. In particular, this library should be viewed as a wrapper around github.com/opencontainers/umoci/oci/cas that provides many convenience functions.

Index

• type Compressor
• type Meta
• type Mutator
  • func New(engine cas.Engine, src casext.DescriptorPath) (*Mutator, error)
  • func (m *Mutator) Add(ctx context.Context, mediaType string, r io.Reader, history *ispec.History, ...) (ispec.Descriptor, error)
  • func (m *Mutator) Annotations(ctx context.Context) (map[string]string, error)
  • func (m *Mutator) Commit(ctx context.Context) (casext.DescriptorPath, error)
  • func (m *Mutator) Config(ctx context.Context) (ispec.ImageConfig, error)
  • func (m *Mutator) Manifest(ctx context.Context) (ispec.Manifest, error)
  • func (m *Mutator) Meta(ctx context.Context) (Meta, error)
  • func (m *Mutator) Set(ctx context.Context, config ispec.ImageConfig, meta Meta, ...) error

Types

type Compressor

type Compressor interface {
	// Compress sets up the streaming compressor for this compression type.
	Compress(io.Reader) (io.ReadCloser, error)

	// MediaTypeSuffix returns the suffix to be added to the layer to
	// indicate what compression type is used, e.g. "gzip", or "" for no
	// compression.
	MediaTypeSuffix() string
}

Compressor is an interface which users can use to implement different compression types.

var GzipCompressor Compressor = gzipCompressor{}

GzipCompressor provides gzip compression.

var NoopCompressor Compressor = noopCompressor{}

NoopCompressor provides no compression.

var ZstdCompressor Compressor = zstdCompressor{}

ZstdCompressor provides zstd compression.

type Meta

type Meta struct {
	// Created defines an ISO-8601 formatted combined date and time at which
	// the image was created.
	Created time.Time `json:"created,omitempty"`

	// Author defines the name and/or email address of the person or entity
	// which created and is responsible for maintaining the image.
	Author string `json:"author,omitempty"`

	// Architecture is the CPU architecture which the binaries in this image
	// are built to run on.
	Architecture string `json:"architecture"`

	// OS is the name of the operating system which the image is built to run
	// on.
	OS string `json:"os"`
}

Meta is a wrapper around the "safe" fields in ispec.Image, which can be modified by users and have no effect on a Mutator or the validity of an image.

type Mutator

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

Mutator is a wrapper around a cas.Engine instance, and is used to mutate a given image (described by a manifest) in a high-level fashion. It handles creating all necessary blobs and modfying other blobs. In order for changes to be committed you must call .Commit().

TODO: Implement manifest list support.

func New

func New(engine cas.Engine, src casext.DescriptorPath) (*Mutator, error)

New creates a new Mutator for the given descriptor (which _must_ have a MediaType of ispec.MediaTypeImageManifest.

func (*Mutator) Add

func (m *Mutator) Add(ctx context.Context, mediaType string, r io.Reader, history *ispec.History, compressor Compressor) (ispec.Descriptor, error)

Add adds a layer to the image, by reading the layer changeset blob from the provided reader. The stream must not be compressed, as it is used to generate the DiffIDs for the image metatadata. The provided history entry is appended to the image's history and should correspond to what operations were made to the configuration.

func (*Mutator) Annotations

func (m *Mutator) Annotations(ctx context.Context) (map[string]string, error)

Annotations returns the set of annotations in the current manifest. This does not include the annotations set in ispec.ImageConfig.Labels. This should be used as the source for any modifications of the annotations using Set.

func (*Mutator) Commit

func (m *Mutator) Commit(ctx context.Context) (casext.DescriptorPath, error)

Commit writes all of the temporary changes made to the configuration, metadata and manifest to the engine. It then returns a new manifest descriptor (which can be used in place of the source descriptor provided to New).

func (*Mutator) Config

func (m *Mutator) Config(ctx context.Context) (ispec.ImageConfig, error)

Config returns the current (cached) image configuration, which should be used as the source for any modifications of the configuration using Set.

func (*Mutator) Manifest

func (m *Mutator) Manifest(ctx context.Context) (ispec.Manifest, error)

Manifest returns the current (cached) image manifest. This is what will be appended to when any additional Add() calls are made, and what will be Commit()ed if no further changes are made.

func (*Mutator) Meta

func (m *Mutator) Meta(ctx context.Context) (Meta, error)

Meta returns the current (cached) image metadata, which should be used as the source for any modifications of the configuration using Set.

func (*Mutator) Set

func (m *Mutator) Set(ctx context.Context, config ispec.ImageConfig, meta Meta, annotations map[string]string, history *ispec.History) error

Set sets the image configuration and metadata to the given values. The provided ispec.History entry is appended to the image's history and should correspond to what operations were made to the configuration.