vinci

README

Vinci

Declarative and Reproducible Container Images

• Declarative: An image built with vinci is not 'run', it's assembled using the layer specs.
• Reproducible: All possible steps are designed to always return exactly the same layers, given the same inputs (for the mathematically inclined: this is a pure function).

Examples

The following examples shows how to create a very simple image, printing 'Hello, World' when executed as a container. When assembled with vinci, it will have the digest sha256:95ee59c6c44c8de465a6e78661edd90d7fe7e52b4db15e8539a528ce5a1f7551.

spec-version: v1
image: registry.gitlab.com/thriqon/vinci/simplest
config:
  entrypoint:
    - /cat
    - /message
layers:
  - file:
      path: /cat
      source: ./busybox
  - file:
      path: /message
      mode: 0444
      contents: |
        Hello, World!

Quickstart

Fetch vinci from the latest build:

wget 'https://gitlab.com/thriqon/vinci/-/jobs/artifacts/master/raw/vinci?job=build' && chmod 0755 vinci

License

Vinci is licensed under the Apache License 2.0. See the file called LICENSE for more information.

Documentation

Index

• Constants
• Variables
• func AcquireToken(ctx context.Context, name string) error
• func BaseDir(ctx context.Context) string
• func Cache(ctx context.Context) cache.Cache
• func Client(ctx context.Context) *client.Client
• func L(ctx context.Context) hclog.Logger
• func ReleaseToken(ctx context.Context)
• type BuildConfig
  • func (bc BuildConfig) BuildV1(ctx context.Context, conf configv1.SingleImageConfigFile) (client.ManifestRef, error)
• type CombinableSpec
• type CombinedSpec
  • func (cs CombinedSpec) EnsureInCache(bc context.Context) ([]imagev1.Descriptor, error)
• type FileLayerSpec
  • func NewFileLayerSpecV1(flsc v1config.FileLayerSpec) (FileLayerSpec, error)
  • func (fls FileLayerSpec) EnsureInCache(ctx context.Context) ([]imagev1.Descriptor, error)
  • func (fls FileLayerSpec) ProvideAsTarEntries(ctx context.Context, w *tar.Writer) error
• type ImportOCISpec
  • func (ios ImportOCISpec) EnsureInCache(ctx context.Context) ([]imagev1.Descriptor, error)
• type ImportSpec
  • func (is ImportSpec) EnsureInCache(ctx context.Context) ([]imagev1.Descriptor, error)
• type Spec
  • func AsSpec(c configv1.LayerSpec) (Spec, error)
  • func NewCombinedSpec(s []configv1.LayerSpec) (Spec, error)
  • func NewImportOCISpecV1(ref string) (Spec, error)
  • func NewImportSpecV1(path string) (Spec, error)

Constants

const (
	MediaTypeImageIndexDockerVendor = "application/vnd.docker.distribution.manifest.list.v2+json"
	MediaTypeConfigDockerVendor     = "application/vnd.docker.container.image.v1+json"
)

const DefaultParallelWorkers = 2

DefaultParallelWorkers is the number of jobs to execute in parallel if no override in the BuildConfig has been set.

const LayerID = "layerID"

Variables

var (
	ErrReferenceNotByDigest = errors.New("reference not by digest")
	ErrCorruptImportedImage = errors.New("corrupt import image")
	ErrNoCompatibleImage    = errors.New("no compatible image found")
)

var ErrUninterpretableValue = errors.New("unable to interpret value")

Functions

func AcquireToken

func AcquireToken(ctx context.Context, name string) error

AcquireToken blocks until a slot from the contexts semaphore is reserved. The semaphore is initialized with the ParallelWorkers setting in the BuildConfig. The given name is used to enrich the logs.

func BaseDir

func BaseDir(ctx context.Context) string

BaseDir extracts the directory serving as base for all relative path calculations from the given context. It panics if there is no base dir set.

func Cache

func Cache(ctx context.Context) cache.Cache

Cache extracts the Cache instance from the given context. If there is no Cache stored in the context, it panics.

func Client

func Client(ctx context.Context) *client.Client

Client extracts the Client pointer from the given context. If there is no Client stored in the context, it panics.

func L

func L(ctx context.Context) hclog.Logger

L extracts the hclog.Logger from the given context. It wraps hclog.FromContext to provide a consistent interface.

func ReleaseToken

func ReleaseToken(ctx context.Context)

ReleaseToken releases a slot reserved by AcquireToken. It is an error to release a token that was never acquired (this is not enforced by this method).

Types

type BuildConfig

type BuildConfig struct {
	Client *client.Client
	Cache  cache.Cache

	BaseDir string

	ParallelWorkers int

	TagPrefix string
}

func (BuildConfig) BuildV1

func (bc BuildConfig) BuildV1(ctx context.Context, conf configv1.SingleImageConfigFile) (client.ManifestRef, error)

type CombinableSpec

type CombinableSpec interface {
	Spec

	ProvideAsTarEntries(context.Context, *tar.Writer) error
}

type CombinedSpec

type CombinedSpec []CombinableSpec

CombinedSpec 'flattens' multiple combinable specs into one layer. For example, this allows to copy a set of files in a shared layer.

func (CombinedSpec) EnsureInCache

func (cs CombinedSpec) EnsureInCache(bc context.Context) ([]imagev1.Descriptor, error)

EnsureInCache calls all subspecs in turn and stores the resulting layer in the cache.

type FileLayerSpec

type FileLayerSpec struct {
	Path     string
	Mode     int
	Contents string
	Source   string
}

func NewFileLayerSpecV1

func NewFileLayerSpecV1(flsc v1config.FileLayerSpec) (FileLayerSpec, error)

func (FileLayerSpec) EnsureInCache

func (fls FileLayerSpec) EnsureInCache(ctx context.Context) ([]imagev1.Descriptor, error)

func (FileLayerSpec) ProvideAsTarEntries

func (fls FileLayerSpec) ProvideAsTarEntries(ctx context.Context, w *tar.Writer) error

type ImportOCISpec

type ImportOCISpec struct {
	Ref client.ManifestRef
}

func (ImportOCISpec) EnsureInCache

func (ios ImportOCISpec) EnsureInCache(ctx context.Context) ([]imagev1.Descriptor, error)

type ImportSpec

type ImportSpec struct {
	Path string
}

func (ImportSpec) EnsureInCache

func (is ImportSpec) EnsureInCache(ctx context.Context) ([]imagev1.Descriptor, error)

type Spec

type Spec interface {
	EnsureInCache(context.Context) ([]imagev1.Descriptor, error)
}

func AsSpec

func AsSpec(c configv1.LayerSpec) (Spec, error)

func NewCombinedSpec

func NewCombinedSpec(s []configv1.LayerSpec) (Spec, error)

func NewImportOCISpecV1

func NewImportOCISpecV1(ref string) (Spec, error)

func NewImportSpecV1

func NewImportSpecV1(path string) (Spec, error)