config

Documentation

Overview

Package config provides the internal representation of Blubber configuration parsed from YAML. Each configuration type may implement its own hooks for injecting build instructions into the compiler.

Index

• Constants
• func HumanizeValidationError(err error) string
• func IsValidationError(err error) bool
• func Validate(config Config) error
• type AptConfig
  • func (apt AptConfig) InstructionsForPhase(phase build.Phase) []build.Instruction
  • func (apt *AptConfig) Merge(apt2 AptConfig)
• type ArtifactsConfig
  • func (ac ArtifactsConfig) InstructionsForPhase(phase build.Phase) []build.Instruction
• type CommonConfig
  • func (cc *CommonConfig) InstructionsForPhase(phase build.Phase) []build.Instruction
  • func (cc *CommonConfig) Merge(cc2 CommonConfig)
  • func (cc *CommonConfig) PhaseCompileableConfig() []build.PhaseCompileable
• type Config
  • func ReadConfig(data []byte) (*Config, error)
  • func ReadConfigFile(path string) (*Config, error)
• type Flag
  • func (flag *Flag) Merge(flag2 Flag)
  • func (flag *Flag) UnmarshalYAML(unmarshal func(interface{}) error) error
• type NodeConfig
  • func (nc NodeConfig) InstructionsForPhase(phase build.Phase) []build.Instruction
  • func (nc *NodeConfig) Merge(nc2 NodeConfig)
• type RunsConfig
  • func (run RunsConfig) Home() string
  • func (run RunsConfig) InstructionsForPhase(phase build.Phase) []build.Instruction
  • func (run *RunsConfig) Merge(run2 RunsConfig)
• type VariantConfig
  • func ExpandVariant(config *Config, name string) (*VariantConfig, error)
  • func (vc *VariantConfig) InstructionsForPhase(phase build.Phase) []build.Instruction
  • func (vc *VariantConfig) Merge(vc2 VariantConfig)
  • func (vc *VariantConfig) VariantDependencies() []string

Constants

const LocalLibPrefix = "/opt/lib"

LocalLibPrefix declares the shared directory into which application level dependencies will be installed.

Functions

func HumanizeValidationError

func HumanizeValidationError(err error) string

HumanizeValidationError transforms the given validator.ValidationErrors into messages more likely to be understood by human beings.

func IsValidationError

func IsValidationError(err error) bool

IsValidationError tests whether the given error is a validator.ValidationErrors and can be safely iterated over as such.

func Validate

func Validate(config Config) error

Validate runs all validations defined for config fields against the given Config value. If the returned error is not nil, it will contain a user-friendly message describing all invalid field values.

Types

type AptConfig

type AptConfig struct {
	Packages []string `yaml:"packages" validate:"dive,debianpackage"`
}

AptConfig represents configuration pertaining to package installation from existing APT sources.

func (AptConfig) InstructionsForPhase

func (apt AptConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects build instructions that will install the declared packages during the privileged phase.

PhasePrivileged

Updates the APT cache, installs configured packages, and cleans up.

func (*AptConfig) Merge

func (apt *AptConfig) Merge(apt2 AptConfig)

Merge takes another AptConfig and combines the packages declared within with the packages of this AptConfig.

type ArtifactsConfig

type ArtifactsConfig struct {
	From        string `yaml:"from" validate:"required,variantref"` // source variant from which to copy
	Source      string `yaml:"source" validate:"required"`          // source variant path from which to copy
	Destination string `yaml:"destination" validate:"required"`     // destination path within current variant
}

ArtifactsConfig declares files and directories to be copied from one variant's container to another during the build.

The most common use of such "multi-stage" builds is to compile and test software using one variant image that contains a comprehensive set of development dependencies, and copy the software binaries or production only source files over into a smaller image that contains only production dependencies. For a shorthand configuration of this precise pattern, use VariantConfig.Copies.

func (ArtifactsConfig) InstructionsForPhase

func (ac ArtifactsConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects instructions into the given build phase that copy configured artifacts.

PhasePostInstall

Injects build.CopyFrom instructions for the configured source and destination paths.

type CommonConfig

type CommonConfig struct {
	Base         string     `yaml:"base" validate:"omitempty,baseimage"` // name/path to base image
	Apt          AptConfig  `yaml:"apt"`                                 // APT related configuration
	Node         NodeConfig `yaml:"node"`                                // Node related configuration
	Runs         RunsConfig `yaml:"runs"`                                // runtime environment configuration
	SharedVolume Flag       `yaml:"sharedvolume"`                        // define a volume for application
	EntryPoint   []string   `yaml:"entrypoint"`                          // entry-point executable
}

CommonConfig holds the configuration fields common to both the root config and each configured variant.

func (*CommonConfig) InstructionsForPhase

func (cc *CommonConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects instructions into the given build phase for each member field that supports it.

func (*CommonConfig) Merge

func (cc *CommonConfig) Merge(cc2 CommonConfig)

Merge takes another CommonConfig and merges its fields this one's.

func (*CommonConfig) PhaseCompileableConfig

func (cc *CommonConfig) PhaseCompileableConfig() []build.PhaseCompileable

PhaseCompileableConfig returns all fields that implement build.PhaseCompileable in the order that their instructions should be injected.

type Config

type Config struct {
	CommonConfig `yaml:",inline"`
	Variants     map[string]VariantConfig `yaml:"variants" validate:"variants,dive"`
}

Config holds the root fields of a Blubber configuration.

func ReadConfig

func ReadConfig(data []byte) (*Config, error)

ReadConfig unmarshals the given YAML bytes into a Config struct.

func ReadConfigFile

func ReadConfigFile(path string) (*Config, error)

ReadConfigFile unmarshals the given YAML file contents into a Config struct.

type Flag

type Flag struct {
	True bool
	// contains filtered or unexported fields
}

Flag represents a nullable boolean value that is considered null until either parsed from YAML or merged in from another Flag value.

func (*Flag) Merge

func (flag *Flag) Merge(flag2 Flag)

Merge takes another flag and, if set, merged its boolean value into this one.

func (*Flag) UnmarshalYAML

func (flag *Flag) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements yaml.Unmarshaler to parse the underlying boolean value and detect that the Flag should no longer be considered null.

type NodeConfig

type NodeConfig struct {
	Dependencies Flag   `yaml:"dependencies"`                     // install dependencies declared in package.json
	Env          string `yaml:"env" validate:"omitempty,nodeenv"` // environment name ("production" install)
}

NodeConfig holds configuration fields related to the Node environment and whether/how to install NPM packages.

func (NodeConfig) InstructionsForPhase

func (nc NodeConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects instructions into the build related to Node dependency installation and setting of the NODE_ENV, NODE_PATH, and PATH environment variables.

PhasePreInstall

Installs Node package dependencies declared in package.json into the shared library directory (/opt/lib). Only production related packages are install if NodeConfig.Env is set to "production" in which case `npm dedupe` is also run. Installing dependencies during the build.PhasePreInstall phase allows a compiler implementation (e.g. Docker) to produce cache-efficient output so only changes to package.json will invalidate these steps of the image build.

PhasePostInstall

Injects build.Env instructions for NODE_ENV, NODE_PATH, and PATH, setting the environment according to the configuration, ensuring that packages installed during build.PhasePreInstall are found by Node, and that any installed binaries are found by shells.

func (*NodeConfig) Merge

func (nc *NodeConfig) Merge(nc2 NodeConfig)

Merge takes another NodeConfig and merges its fields into this one's, overwriting both the environment and dependencies flag.

type RunsConfig

type RunsConfig struct {
	In          string            `yaml:"in" validate:"omitempty,abspath"`  // working directory
	As          string            `yaml:"as" validate:"omitempty,username"` // unprivileged user
	UID         uint              `yaml:"uid"`                              // unprivileged user ID
	GID         uint              `yaml:"gid"`                              // unprivileged group ID
	Environment map[string]string `yaml:"environment" validate:"envvars"`   // environment variables
}

RunsConfig holds configuration fields related to the application's runtime environment.

func (RunsConfig) Home

func (run RunsConfig) Home() string

Home returns the home directory for the configured user, or /root if no user is set.

func (RunsConfig) InstructionsForPhase

func (run RunsConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects build instructions related to the runtime configuration.

PhasePrivileged

Creates LocalLibPrefix directory and unprivileged user home directory, creates the unprivileged user and its group, and sets up directory permissions.

PhasePrivilegeDropped

Injects build.Env instructions for the user home directory and all names/values defined by RunsConfig.Environment.

func (*RunsConfig) Merge

func (run *RunsConfig) Merge(run2 RunsConfig)

Merge takes another RunsConfig and overwrites this struct's fields. All fields except Environment are overwritten if set. The latter is an additive merge.

type VariantConfig

type VariantConfig struct {
	Includes     []string          `yaml:"includes" validate:"dive,variantref"`    // other variants
	Copies       string            `yaml:"copies" validate:"omitempty,variantref"` // copy artifacts from variant
	Artifacts    []ArtifactsConfig `yaml:"artifacts" validate:"dive"`              // artifact configuration
	CommonConfig `yaml:",inline"`
}

VariantConfig holds configuration fields for each defined build variant.

func ExpandVariant

func ExpandVariant(config *Config, name string) (*VariantConfig, error)

ExpandVariant merges a named variant with a config. It also attempts to recursively expand any included variants in the expanded variant.

func (*VariantConfig) InstructionsForPhase

func (vc *VariantConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects build instructions related to artifact copying, volume definition or copying of application files, and all common configuration.

PhaseInstall

If VariantConfig.Copies is not set, either copy in application files or define a shared volume. Otherwise, delegate to ArtifactsConfig.InstructionsForPhase.

func (*VariantConfig) Merge

func (vc *VariantConfig) Merge(vc2 VariantConfig)

Merge takes another VariantConfig and overwrites this struct's fields. Artifacts are merged additively.

func (*VariantConfig) VariantDependencies

func (vc *VariantConfig) VariantDependencies() []string

VariantDependencies returns all unique names of other variants that are referenced in the VariantConfig.Artifacts configuration.