dockerfile

Documentation

Overview

Package dockerfile implements utilities related to Dockerfile processing.

Index

• func LoadAndResolve(dockerfile, pins string) ([]byte, error)
• func Resolve(in []byte, resolver Resolver) (out []byte, err error)
• func WritePins(w io.Writer, p *Pins) error
• type Pin
  • func IsMissingPinErr(err error) *Pin
  • func NormalizePin(p Pin, requireDigest bool) (Pin, error)
  • func PinFromString(image string) (Pin, error)
  • func (p *Pin) ImageRef() string
• type Pins
  • func ReadPins(r io.Reader) (*Pins, error)
  • func (p *Pins) Add(pin Pin) error
  • func (p *Pins) Resolver() Resolver
  • func (p *Pins) Visit(cb func(p *Pin) error) error
• type Resolver

Functions

func LoadAndResolve

func LoadAndResolve(dockerfile, pins string) ([]byte, error)

LoadAndResolve implements high-level logic of resolving tags in a Dockerfile using a database loaded from a Pins YAML file.

'dockefile' must point to some existing Dockerfile on disk. It will be loaded, its body passed through Resolve(...) function, and returned.

'pins' should either point to a Pins YAML (see Pins struct), or should be an empty string (in which case the Dockerfile MUST use digests only, so there's nothing to resolve).

func Resolve

func Resolve(in []byte, resolver Resolver) (out []byte, err error)

Resolve returns a copy of the Dockerfile with image tags resolved to concrete digests.

Understands only the following constructs currently:

• FROM <image> [AS <name>] (assumes "latest" tag)
• FROM <image>[:<tag>] [AS <name>] (resolves the given tag)
• FROM <image>[@<digest>] [AS <name>] (passes the definition through)

In particular does not understand ARGs, e.g. "FROM base:${CODE_VERSION}" is not supported. Returns an error with unrecognized line in this case.

Returns the body of the resolved docker file.

func WritePins

func WritePins(w io.Writer, p *Pins) error

WritePins generates YAML with pins.

Entries are normalized and sorted.

Types

type Pin

type Pin struct {
	Comment string `yaml:"comment,omitempty"` // arbitrary string, for humans
	Image   string `yaml:"image"`             // required
	Tag     string `yaml:"tag,omitempty"`     // default is "latest"
	Digest  string `yaml:"digest"`            // required
	Freeze  string `yaml:"freeze,omitempty"`  // if set, don't update in pins-update
}

Pin is a single "(image name, tag) => digest" pin.

func IsMissingPinErr

func IsMissingPinErr(err error) *Pin

IsMissingPinErr returns true if 'err' is an error produced by ResolveTag.

It may be wrapped. Returns a pin that ResolveTag was unable to resolve.

func NormalizePin

func NormalizePin(p Pin, requireDigest bool) (Pin, error)

NormalizePin returns a copy of 'p' with defaults populated.

Expands abbreviated image names into full references,

func PinFromString

func PinFromString(image string) (Pin, error)

PinFromString takes <image>[:<tag>] reference and converts it to Pin struct.

func (*Pin) ImageRef

func (p *Pin) ImageRef() string

ImageRef returns "<image>:<tag>" string.

type Pins

type Pins struct {
	Pins []Pin `yaml:"pins"`
}

Pins is a mapping (image name, tag) => digest.

func ReadPins

func ReadPins(r io.Reader) (*Pins, error)

ReadPins loads and validates YAML file with pins.

func (*Pins) Add

func (p *Pins) Add(pin Pin) error

Add adds or updates a pin (which should already be resolved).

func (*Pins) Resolver

func (p *Pins) Resolver() Resolver

Resolver returns a Resolver that uses a snapshot of Pins as a source.

func (*Pins) Visit

func (p *Pins) Visit(cb func(p *Pin) error) error

Visit calls 'cb' concurrently for all pins.

The callback can mutate any pin fields except Image and Tag (doing so will panic).

Calls the callback even for pins that are marked as frozen. The callback should handle this itself (e.g. by logging and skipping them).

Returns a multi-error with all errors that happened.

type Resolver

type Resolver interface {
	// ResolveTag resolves a single image tag into a digest.
	//
	// 'image' and 'tag' here come from "FROM <image>[:<tag>]" line in
	// the Dockerfile verbatim, except 'tag' is set to "latest" if using the brief
	// "FROM <image>" form and 'image' is never "scratch" ("FROM scratch" lines
	// are treated as magical).
	//
	// The result is expected to be "sha256:<hex>". The "FROM" line will be
	// transformed into "FROM <image>@<digest> ...".
	ResolveTag(image, tag string) (digest string, err error)
}

Resolver knows how to resolve (image, tag) pairs into an image digest.