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 ¶
- Constants
- type Compressordeprecated
- type Meta
- type Mutator
- func (m *Mutator) Add(ctx context.Context, mediaType string, r io.Reader, history *ispec.History, ...) (_ ispec.Descriptor, Err error)
- func (m *Mutator) AddExisting(ctx context.Context, desc ispec.Descriptor, history *ispec.History, ...) error
- func (m *Mutator) Annotations(ctx context.Context) (map[string]string, error)
- func (m *Mutator) Commit(ctx context.Context) (_ casext.DescriptorPath, Err error)
- func (m *Mutator) Config(ctx context.Context) (ispec.Image, error)
- func (m *Mutator) Manifest(ctx context.Context) (ispec.Manifest, error)
- func (m *Mutator) Meta(ctx context.Context) (Meta, error)
- func (m *Mutator) PickDefaultCompressAlgorithm(ctx context.Context) (Compressor, error)
- func (m *Mutator) Set(ctx context.Context, config ispec.ImageConfig, meta Meta, ...) error
Constants ¶
const UmociUncompressedBlobSizeAnnotation = "ci.umo.uncompressed_blob_size"
UmociUncompressedBlobSizeAnnotation is an umoci-specific annotation to provide information in descriptors to compressed blobs about the size of the underlying uncompressed blob for users that need that information. Note that this annotation value should be treated as a hint -- an attacker could create an image that has a dummy UmociUncompressedBlobSizeAnnotation value for a zip-bomb blob.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type Compressor
deprecated
added in
v0.4.7
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.
Deprecated: The compression algorithm logic has been moved to blobcompress to unify the media-type compression handling for both compression and decompression. Please switch to blobcompress.Algorithm.
var ( // NoopCompressor provides no compression. NoopCompressor Compressor = blobcompress.Noop // GzipCompressor provides gzip compression. GzipCompressor Compressor = blobcompress.Gzip // ZstdCompressor provides zstd compression. ZstdCompressor Compressor = blobcompress.Zstd )
Deprecated: The compression algorithm logic has been moved to blobcompress to unify the media-type compression handling for both compression and decompression. Please switch to blobcompress.
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,omitzero"`
// 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,omitzero"`
// Architecture is the CPU architecture which the binaries in this image
// are built to run on.
Architecture string `json:"architecture"`
// Variant is the variant of the CPU architecture which the binaries in
// this image are built to run on.
Variant string `json:"variant"`
// 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 ¶
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, annotations map[string]string) (_ ispec.Descriptor, Err 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) AddExisting ¶ added in v0.5.0
func (m *Mutator) AddExisting(ctx context.Context, desc ispec.Descriptor, history *ispec.History, diffID digest.Digest) error
AddExisting adds a blob that already exists to the layer, using the user specified DiffID. It currently checks that the layer exists, but does not validate the DiffID.
func (*Mutator) Annotations ¶
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 ¶
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 ¶
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 ¶ added in v0.4.7
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 ¶
Meta returns the current (cached) image metadata, which should be used as the source for any modifications of the configuration using Set.
func (*Mutator) PickDefaultCompressAlgorithm ¶ added in v0.5.0
func (m *Mutator) PickDefaultCompressAlgorithm(ctx context.Context) (Compressor, error)
PickDefaultCompressAlgorithm returns the best option for the compression algorithm for new layers. The main preference is to use re-use whatever the most recent layer's compression algorithm is (for those we support). As a final fallback, we use blobcompress.Default.
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.
Source Files