spec

Documentation

Index

• func Validate(s Spec) error
• type Backends
• type Clear
• type Configuration
• type Copy
• type From
  • func (f From) Reference() string
• type Packages
• type Port
  • func (p Port) String() string
• type Protocol
  • func (p Protocol) String() string
• type ProtocolWrapper
  • func (w *ProtocolWrapper) UnmarshalText(text []byte) error
• type Security
• type Spec
  • func Fill(s Spec) Spec
• type SpecialFiles
• type This
  • func (t This) Reference() string
• type User

Functions

func Validate

func Validate(s Spec) error

Validate asserts that a spec is complete and satisfies domain-specific constraints.

Types

type Backends

type Backends struct {
	// Identity of the package manager in the working container
	Package pckg.BackendWrapper

	// Identity of the user-space utility for managing users and groups in the
	// working container
	User user.BackendWrapper

	// Identity of the implementation of the find utility in the working
	// container
	Find find.BackendWrapper
}

Backends holds the choices of implementations of operations in the working container.

type Clear

type Clear struct {
	// Clear all annotations
	Annotations bool

	// Clear the author
	Author bool

	// Clear the command
	Command bool `toml:"cmd"`

	// Unset all environment variables
	Environment bool `toml:"env"`

	// Clear the entrypoint
	Entrypoint bool `toml:"ep"`

	// Clear all labels
	Labels bool

	// Close all exposed ports
	Ports bool
}

Clear holds toggles for clearing configuration inherited from the base image.

type Configuration

type Configuration struct {
	// Set or update one or more annotations
	Annotations map[string]string

	// Provide contact information for the image maintainer
	Author string

	// Set the default command (or the parameters, if an entrypoint is set)
	Command []string `toml:"cmd"`

	// Describe how the image was built
	CreatedBy string `toml:"created-by"`

	// Set the entrypoint
	Entrypoint []string `toml:"ep"`

	// Set or update one or more environment variables
	Environment map[string]string `toml:"env"`

	// Set or update one or more labels
	Labels map[string]string

	// Expose one or more network ports
	Ports []Port

	// Set the default directory in which the entrypoint or command should run
	WorkDir string `toml:"work-dir"`

	// Toggles for clearing configuration inherited from the base image
	Clear Clear
}

Configuration holds configuration options for the image to be built from the working container, as defined in the OCIv1 Image Format specification.

type Copy

type Copy struct {
	// Context directory for the files to copy over to the working container
	Base string

	// Absolute path to the destination on the working container's file system
	Destination string `toml:"dest"`

	// Paths to source files on the host's file system; may contain
	// gitignore-style glob patterns
	Sources []string `toml:"srcs"`

	// Source files in the base directory to exclude from the copy operation;
	// may contain gitignore-style glob patterns
	Excludes []string

	// Set the mode of the copied files to this integer
	Mode uint32

	// Transfer ownership of the copied files to this user
	Owner string

	// Remove all SUID and SGID bits from the files copied to the working container
	RemoveS bool `toml:"remove-s"`
}

Copy holds instructions and options for copying one or more files from the host's file system to the working container's file system.

type From

type From struct {
	// Image name comprising a fully qualified domain and path
	Repository string

	// Human-readable identifier for a manifest in the repository
	Tag string

	// Unique identifer for the contents of the base image
	Digest string

	// Linux-based distro for this image
	Distro linux.DistroWrapper
}

From holds information about the base image.

func (From) Reference

func (f From) Reference() string

Reference returns a string representation of the canonical reference to the base image.

type Packages

type Packages struct {
	// Upgrade pre-installed packages
	Upgrade bool

	// Install one or more packages
	Install []string

	// Clean package caches after upgrading or installing packages
	Clean bool
}

Packages contains instructions for the package management backend.

type Port

type Port struct {
	// Port number
	Number uint16

	// Choice of transport-layer network protocol
	Protocol ProtocolWrapper
}

Port holds a combination of a port number and choice of transport-layer network protocol.

func (Port) String

func (p Port) String() string

String returns a string representation of the port.

type Protocol

type Protocol uint

Protocol is a unique identifier for a transport-layer network protocol. The zero value represents an unknown protocol.

const (
	TCP Protocol = 1 << iota
	UDP
)

func (Protocol) String

func (p Protocol) String() string

String returns a string containing the stylized name of the protocol.

type ProtocolWrapper

type ProtocolWrapper struct {
	Protocol
}

ProtocolWrapper wraps Protocol to facilitate its parsing from serialized data.

func (*ProtocolWrapper) UnmarshalText

func (w *ProtocolWrapper) UnmarshalText(text []byte) error

UnmarshalText decodes the protocol from a UTF-8-encoded string.

type Security

type Security struct {
	// Options for handling real files with a SUID or SGID bit
	SpecialFiles SpecialFiles `toml:"special-files"`
}

Security holds security-related options for the working container.

type Spec

type Spec struct {
	// Information about the base image
	From From

	// Information about the image we'll be committing
	This This

	// Instructions for the package management backend
	Packages Packages

	// Information about the sole unprivileged Linux user in the working
	// container
	User *User

	// Instructions and options for copying one or more files from the host's
	// file system to the working container's file system
	Copy []Copy

	// Security options for the working container
	Security Security

	// Configuration for the working container
	Config Configuration

	// Choices of implementations of operations in the working container
	Backends Backends
}

Spec holds the options for the build and defines the structure of spec files.

func Fill

func Fill(s Spec) Spec

Fill populates empty optional fields in a spec using information encoded by required fields in the spec.

type SpecialFiles

type SpecialFiles struct {
	// Unset the SUID and SGID bits on all files that have one
	RemoveS bool `toml:"remove-s"`

	// Absolute paths to files whose SUID and SGID bits should be preserved
	Excludes []string
}

SpecialFiles holds options for handling real files in the working container that carry a SUID or SGID bit.

type This

type This struct {
	// Desired image name comprising a fully qualified domain and path
	Repository string

	// Human-readable identifier for the image
	Tag string

	// Preserve the image history and timestamps of the files in the working
	// container's file system
	KeepHistory bool `toml:"keep-history"`
}

This holds information about the image we'll be committing.

func (This) Reference

func (t This) Reference() string

Reference returns a string representation of the image's tagged reference.

type User

type User struct {
	// Human-readable identifier
	Name string

	// Linux user ID (UID)
	//
	// The default value of 0 tells the program to delegate the choice of UID
	// to the user-space utility responsible for user creation.
	//
	// If not 0, then it must be an integer between 1000 and 60000, inclusive.
	ID uint32 `toml:"id"`

	// Create a user group
	UserGroup bool `toml:"user-group"`

	// Groups to which to add the user
	Groups []string

	// GECOS field text
	//
	// The default value of nil tells the program to defer the choice of content
	// to the user-space utility responsible for user creation.
	Comment *string

	// Create a home directory for the user in /home
	CreateHome bool `toml:"create-home"`
}

User holds information about the sole unprivileged Linux user to be created in the working container.