README

mutate

GoDoc

The v1.Image, v1.ImageIndex, and v1.Layer interfaces provide only accessor methods, so they are essentially immutable. If you want to change something about them, you need to produce a new instance of that interface.

A common use case for this library is to read an image from somewhere (a source), change something about it, and write the image somewhere else (a sink).

Graphically, this looks something like:

Mutations

This is obviously not a comprehensive set of useful transformations (PRs welcome!), but a rough summary of what the mutate package currently does:

Config and ConfigFile

These allow you to change the image configuration, e.g. to change the entrypoint, environment, author, etc.

Time, Canonical, and CreatedAt

These are useful in the context of reproducible builds, where you may want to strip timestamps and other non-reproducible information.

Append, AppendLayers, and AppendManifests

These functions allow the extension of a v1.Image or v1.ImageIndex with new layers or manifests.

For constructing an image FROM scratch, see the empty package.

MediaType and IndexMediaType

Sometimes, it is necessary to change the media type of an image or index, e.g. to appease a registry with strict validation of images (looking at you, GCR).

Rebase

Rebase has its own README.

This is the underlying implementation of crane rebase.

Extract

Extract will flatten an image filesystem into a single tar stream, respecting whiteout files.

This is the underlying implementation of crane export.

Expand ▾ Collapse ▴

Documentation

Overview

    Package mutate provides facilities for mutating v1.Images of any kind.

    Index

    Constants

    This section is empty.

    Variables

    This section is empty.

    Functions

    func Append 

    func Append(base v1.Image, adds ...Addendum) (v1.Image, error)

      Append will apply the list of addendums to the base image

      func AppendLayers 

      func AppendLayers(base v1.Image, layers ...v1.Layer) (v1.Image, error)

        AppendLayers applies layers to a base image.

        func AppendManifests 

        func AppendManifests(base v1.ImageIndex, adds ...IndexAddendum) v1.ImageIndex

          AppendManifests appends a manifest to the ImageIndex.

          func Canonical 

          func Canonical(img v1.Image) (v1.Image, error)

            Canonical is a helper function to combine Time and configFile to remove any randomness during a docker build.

            func Config 

            func Config(base v1.Image, cfg v1.Config) (v1.Image, error)

              Config mutates the provided v1.Image to have the provided v1.Config

              func ConfigFile 

              func ConfigFile(base v1.Image, cfg *v1.ConfigFile) (v1.Image, error)

                ConfigFile mutates the provided v1.Image to have the provided v1.ConfigFile

                func CreatedAt 

                func CreatedAt(base v1.Image, created v1.Time) (v1.Image, error)

                  CreatedAt mutates the provided v1.Image to have the provided v1.Time

                  func Extract 

                  func Extract(img v1.Image) io.ReadCloser

                    Extract takes an image and returns an io.ReadCloser containing the image's flattened filesystem.

                    Callers can read the filesystem contents by passing the reader to tar.NewReader, or io.Copy it directly to some output.

                    If a caller doesn't read the full contents, they should Close it to free up resources used during extraction.

                    func IndexMediaType 

                    func IndexMediaType(idx v1.ImageIndex, mt types.MediaType) v1.ImageIndex

                      IndexMediaType modifies the MediaType() of the given index.

                      func MediaType 

                      func MediaType(img v1.Image, mt types.MediaType) v1.Image

                        MediaType modifies the MediaType() of the given image.

                        func Rebase 

                        func Rebase(orig, oldBase, newBase v1.Image) (v1.Image, error)

                          Rebase returns a new v1.Image where the oldBase in orig is replaced by newBase.

                          func RemoveManifests 

                          func RemoveManifests(base v1.ImageIndex, matcher match.Matcher) v1.ImageIndex

                            RemoveManifests removes any descriptors that match the match.Matcher.

                            func Time 

                            func Time(img v1.Image, t time.Time) (v1.Image, error)

                              Time sets all timestamps in an image to the given timestamp.

                              Types

                              type Addendum 

                              type Addendum struct {
	Layer       v1.Layer
	History     v1.History
	URLs        []string
	Annotations map[string]string
	MediaType   types.MediaType
}

                                Addendum contains layers and history to be appended to a base image

                                type Appendable 

                                type Appendable interface {
	MediaType() (types.MediaType, error)
	Digest() (v1.Hash, error)
	Size() (int64, error)
}

                                  Appendable is an interface that represents something that can be appended to an ImageIndex. We need to be able to construct a v1.Descriptor in order to append something, and this is the minimum required information for that.

                                  type IndexAddendum 

                                  type IndexAddendum struct {
	Add Appendable
	v1.Descriptor
}

                                    IndexAddendum represents an appendable thing and all the properties that we may want to override in the resulting v1.Descriptor.

                                    Source Files

                                    View all