stacker

README

stacker

Stacker is a tool for building OCI images via a declarative yaml format.

Installation

Stacker has various build and runtime dependencies.

Usage

See the tutorial for a short introduction to how to use stacker.

See the stacker.yaml specification for full details on the stacker.yaml specification.

Documentation

Index

• Constants
• Variables
• func GetBaseLayer(o BaseLayerOpts, sf *Stackerfile) error
• func GitVersion(path string) (string, error)
• func Grab(sc StackerConfig, name string, source string) error
• func Import(c StackerConfig, name string, imports []string) error
• func MakeLoopbackBtrfs(loopback string, size int64, uid int, dest string) error
• func MaybeRunInUserns(userCmd []string, msg string) error
• func Run(sc StackerConfig, name string, command string, l *Layer, onFailure string, ...) error
• func RunInUserns(userCmd []string, msg string) error
• type Apply
  • func NewApply(sf *Stackerfile, opts BaseLayerOpts, storage Storage) (*Apply, error)
  • func (a *Apply) DoApply() error
• type BaseLayerOpts
• type BuildCache
  • func OpenCache(config StackerConfig, oci *umoci.Layout, sf *Stackerfile) (*BuildCache, error)
  • func (c *BuildCache) Lookup(name string) (*CacheEntry, bool)
  • func (c *BuildCache) Put(name string, blob ispec.Descriptor) error
• type CacheEntry
• type ImageSource
  • func (is *ImageSource) ParseTag() (string, error)
• type ImportHash
• type ImportType
  • func (it ImportType) IsDir() bool
• type Layer
  • func (l *Layer) ParseBinds() ([]string, error)
  • func (l *Layer) ParseCmd() ([]string, error)
  • func (l *Layer) ParseEntrypoint() ([]string, error)
  • func (l *Layer) ParseFullCommand() ([]string, error)
  • func (l *Layer) ParseImport() ([]string, error)
  • func (l *Layer) ParseRun() ([]string, error)
• type StackerConfig
• type Stackerfile
  • func NewStackerfile(stackerfile string, substitutions []string) (*Stackerfile, error)
  • func (s *Stackerfile) DependencyOrder() ([]string, error)
  • func (sf *Stackerfile) Get(name string) (*Layer, bool)
  • func (sf *Stackerfile) Len() int
• type Storage
  • func NewStorage(c StackerConfig) (Storage, error)

Constants

const (
	MediaTypeImageBtrfsLayer  = "application/vnd.cisco.image.layer.btrfs"
	GitVersionAnnotation      = "ws.tycho.stacker.git_version"
	StackerContentsAnnotation = "ws.tycho.stacker.stacker_yaml"
)

const (
	DockerType  = "docker"
	TarType     = "tar"
	OCIType     = "oci"
	BuiltType   = "built"
	ScratchType = "scratch"
)

const (
	ReasonableDefaultPath = "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin"
)

Variables

var (
	IdmapSet *idmap.IdmapSet
)

Functions

func GetBaseLayer

func GetBaseLayer(o BaseLayerOpts, sf *Stackerfile) error

func GitVersion

func GitVersion(path string) (string, error)

Git version generates a version string similar to what git describe --always does, with -dirty on the end if the git repo had local changes.

func Grab

func Grab(sc StackerConfig, name string, source string) error

func Import

func Import(c StackerConfig, name string, imports []string) error

func MakeLoopbackBtrfs

func MakeLoopbackBtrfs(loopback string, size int64, uid int, dest string) error

MakeLoopbackBtrfs creates a btrfs filesystem mounted at dest out of a loop device and allows the specified uid to delete subvolumes on it.

func MaybeRunInUserns

func MaybeRunInUserns(userCmd []string, msg string) error

A wrapper which runs things in a userns if we're an unprivileged user with an idmap, or runs things on the host if we're root and don't.

func Run

func Run(sc StackerConfig, name string, command string, l *Layer, onFailure string, stdin io.Reader) error

func RunInUserns

func RunInUserns(userCmd []string, msg string) error

Types

type Apply

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

func NewApply

func NewApply(sf *Stackerfile, opts BaseLayerOpts, storage Storage) (*Apply, error)

func (*Apply) DoApply

func (a *Apply) DoApply() error

type BaseLayerOpts

type BaseLayerOpts struct {
	Config StackerConfig
	Name   string
	Target string
	Layer  *Layer
	Cache  *BuildCache
	OCI    *umoci.Layout
}

type BuildCache

type BuildCache struct {
	Cache   map[string]CacheEntry `json:"cache"`
	Version int                   `json:"version"`
	// contains filtered or unexported fields
}

func OpenCache

func OpenCache(config StackerConfig, oci *umoci.Layout, sf *Stackerfile) (*BuildCache, error)

func (*BuildCache) Lookup

func (c *BuildCache) Lookup(name string) (*CacheEntry, bool)

func (*BuildCache) Put

func (c *BuildCache) Put(name string, blob ispec.Descriptor) error

type CacheEntry

type CacheEntry struct {
	// The manifest that this corresponds to.
	Blob ispec.Descriptor

	// A map of the import url to the base64 encoded result of mtree walk
	// or sha256 sum of a file, depending on what Type is.
	Imports map[string]ImportHash

	// The name of this layer as it was built. Useful for the BuildOnly
	// case to make sure it still exists, and for printing error messages.
	Name string

	// The layer to cache
	Layer *Layer

	// If the layer is of type "built", this is a hash of the base layer's
	// CacheEntry, which contains a hash of its imports. If there is a
	// mismatch with the current base layer's CacheEntry, the layer should
	// be rebuilt.
	Base string
}

type ImageSource

type ImageSource struct {
	Type     string `yaml:"type"`
	Url      string `yaml:"url"`
	Tag      string `yaml:"tag"`
	Insecure bool   `yaml:"insecure"`
}

func (*ImageSource) ParseTag

func (is *ImageSource) ParseTag() (string, error)

type ImportHash

type ImportHash struct {
	// Unfortuantely, mtree doesn't work if you just pass it a single file,
	// so we use the sha256sum of the file, or the mtree encoding if it's a
	// directory. This indicates which.
	Type ImportType
	Hash string
}

type ImportType

type ImportType int

const (
	ImportFile ImportType = iota
	ImportDir  ImportType = iota
)

func (ImportType) IsDir

func (it ImportType) IsDir() bool

type Layer

type Layer struct {
	From        *ImageSource      `yaml:"from"`
	Import      interface{}       `yaml:"import"`
	Run         interface{}       `yaml:"run"`
	Cmd         interface{}       `yaml:"cmd"`
	Entrypoint  interface{}       `yaml:"entrypoint"`
	FullCommand interface{}       `yaml:"full_command"`
	Environment map[string]string `yaml:"environment"`
	Volumes     []string          `yaml:"volumes"`
	Labels      map[string]string `yaml:"labels"`
	WorkingDir  string            `yaml:"working_dir"`
	BuildOnly   bool              `yaml:"build_only"`
	Binds       interface{}       `yaml:"binds"`
	Apply       []string          `yaml:"apply"`
}

func (*Layer) ParseBinds

func (l *Layer) ParseBinds() ([]string, error)

func (*Layer) ParseCmd

func (l *Layer) ParseCmd() ([]string, error)

func (*Layer) ParseEntrypoint

func (l *Layer) ParseEntrypoint() ([]string, error)

func (*Layer) ParseFullCommand

func (l *Layer) ParseFullCommand() ([]string, error)

func (*Layer) ParseImport

func (l *Layer) ParseImport() ([]string, error)

func (*Layer) ParseRun

func (l *Layer) ParseRun() ([]string, error)

type StackerConfig

type StackerConfig struct {
	StackerDir string
	OCIDir     string
	RootFSDir  string
}

StackerConfig is a struct that contains global (or widely used) stacker config options.

type Stackerfile

type Stackerfile struct {
	// AfterSubstitutions is the contents of the stacker file after
	// substitutions (i.e., the content that is actually used by stacker).
	AfterSubstitutions string
	// contains filtered or unexported fields
}

func NewStackerfile

func NewStackerfile(stackerfile string, substitutions []string) (*Stackerfile, error)

NewStackerfile creates a new stackerfile from the given path. substitutions is a list of KEY=VALUE pairs of things to substitute. Note that this is explicitly not a map, because the substitutions are performed one at a time in the order that they are given.

func (*Stackerfile) DependencyOrder

func (s *Stackerfile) DependencyOrder() ([]string, error)

func (*Stackerfile) Get

func (sf *Stackerfile) Get(name string) (*Layer, bool)

func (*Stackerfile) Len

func (sf *Stackerfile) Len() int

type Storage

type Storage interface {
	Name() string
	Create(path string) error
	Snapshot(source string, target string) error
	Restore(source string, target string) error
	Delete(path string) error
	Detach() error
}

func NewStorage

func NewStorage(c StackerConfig) (Storage, error)