README
mutate
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
.
Documentation
Overview ¶
Package mutate provides facilities for mutating v1.Images of any kind.
Index ¶
- func Append(base v1.Image, adds ...Addendum) (v1.Image, error)
- func AppendLayers(base v1.Image, layers ...v1.Layer) (v1.Image, error)
- func AppendManifests(base v1.ImageIndex, adds ...IndexAddendum) v1.ImageIndex
- func Canonical(img v1.Image) (v1.Image, error)
- func Config(base v1.Image, cfg v1.Config) (v1.Image, error)
- func ConfigFile(base v1.Image, cfg *v1.ConfigFile) (v1.Image, error)
- func CreatedAt(base v1.Image, created v1.Time) (v1.Image, error)
- func Extract(img v1.Image) io.ReadCloser
- func IndexMediaType(idx v1.ImageIndex, mt types.MediaType) v1.ImageIndex
- func MediaType(img v1.Image, mt types.MediaType) v1.Image
- func Rebase(orig, oldBase, newBase v1.Image) (v1.Image, error)
- func RemoveManifests(base v1.ImageIndex, matcher match.Matcher) v1.ImageIndex
- func Time(img v1.Image, t time.Time) (v1.Image, error)
- type Addendum
- type Appendable
- type IndexAddendum
Constants ¶
Variables ¶
Functions ¶
func AppendLayers ¶
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 ¶
Canonical is a helper function to combine Time and configFile to remove any randomness during a docker build.
func ConfigFile ¶
ConfigFile mutates the provided v1.Image to have the provided v1.ConfigFile
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 RemoveManifests ¶
func RemoveManifests(base v1.ImageIndex, matcher match.Matcher) v1.ImageIndex
RemoveManifests removes any descriptors that match the match.Matcher.
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.