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

Overview

* This file is a little bit strange. The problem is that we want to do * daemonized containers with liblxc, but we can't spawn containers in threaded * environments (i.e. golang), with go-lxc. So instead, we embed some C into * our program that catches execution before golang starts. This way, we can do * a tiny C program to actually spawn the container. * * We do this in the "stacker" package so that if anyone uses the library, the * re-exec will actually work. Of course, this is slightly impolite, but what * can you do.

Index

• Constants
• Variables
• func Build(opts *BuildArgs) error
• func Download(cacheDir string, url string) (string, error)
• 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 LookupConfig(oci casext.Engine, desc ispec.Descriptor) (ispec.Image, error)
• func LookupManifest(oci casext.Engine, tag string) (ispec.Manifest, 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, considerTimestamps bool) (*Apply, error)
  • func (a *Apply) DoApply() error
• type BaseLayerOpts
• type BuildArgs
• type BuildCache
  • func OpenCache(config StackerConfig, oci casext.Engine, 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 (
	MediaTypeLayerSquashfs = "application/vnd.oci.image.layer.squashfs"
)

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

Variables

var (
	IdmapSet *idmap.IdmapSet
)

Functions

func Build

func Build(opts *BuildArgs) error

func Download

func Download(cacheDir string, url string) (string, error)

download with caching support in the specified cache dir.

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 LookupConfig

func LookupConfig(oci casext.Engine, desc ispec.Descriptor) (ispec.Image, error)

func LookupManifest

func LookupManifest(oci casext.Engine, tag string) (ispec.Manifest, 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, considerTimestamps bool) (*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       casext.Engine
	LayerType string
}

type BuildArgs

type BuildArgs struct {
	Config                  StackerConfig
	LeaveUnladen            bool
	StackerFile             string
	NoCache                 bool
	Substitute              []string
	OnRunFailure            string
	ApplyConsiderTimestamps bool
	LayerType               string
}

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 casext.Engine, 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)