config

package
v0.6.0 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Oct 11, 2018 License: Apache-2.0 Imports: 15 Imported by: 0

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

Examples

Constants

View Source 
const CurrentVersion string = "v3"

CurrentVersion declares the currently supported config version.

View Source 
const DefaultConfig = `---
lives:
  in: /srv/app
  as: somebody
  uid: 65533
  gid: 65533
runs:
  as: runuser
  uid: 900
  gid: 900`

DefaultConfig contains YAML that is applied before the user's configuration.

View Source 
const LocalLibPrefix = "/opt/lib"

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

View Source 
const PythonLibPrefix = LocalLibPrefix + "/python"

PythonLibPrefix is the path to installed dependency wheels.

View Source 
const PythonSiteBin = PythonSitePackages + "/bin"

PythonSiteBin is the path to installed Python packages bin files.

View Source 
const PythonSitePackages = PythonLibPrefix + "/site-packages"

PythonSitePackages is the path to installed Python packages.

Variables

This section is empty.

Functions

func HumanizeValidationError added in v0.2.0 

func HumanizeValidationError(err error) string

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

func IsValidationError added in v0.2.0 

func IsValidationError(err error) bool

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

func ResolveIncludes added in v0.3.0 

func ResolveIncludes(config *Config, name string) ([]string, error)

ResolveIncludes iterates over and recurses through a given variant's includes to build a flat slice of variant names in the correct order by which they should be expanded/merged. It checks for both the existence of included variants and maintains a recursion stack to protect against infinite loops.

Variant names found at a greater depth of recursion are first and siblings last, the order in which config should be merged.

Example 
package main

import (
	"fmt"

	"gerrit.wikimedia.org/r/blubber/config"
)

func main() {
	cfg, _ := config.ReadConfig([]byte(`---
    version: v3
    variants:
      varA: { includes: [varB, varC] }
      varB: { includes: [varD, varE] }
      varC: {}
      varD: { includes: [varF] }
      varE: {}
      varF: {}`))

	includes, _ := config.ResolveIncludes(cfg, "varA")

	fmt.Printf("%v\n", includes)

}

Output:

[varF varD varE varB varC varA]

func ResolveYAMLPath added in v0.3.0 

func ResolveYAMLPath(path string, cfg interface{}) (interface{}, error)

ResolveYAMLPath returns the config value found at the given YAML-ish namespace/path (e.g. "variants.production.runs.as").

func Validate added in v0.2.0 

func Validate(config interface{}) 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.

PhaseInstall

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

type BuilderConfig added in v0.4.0 

type BuilderConfig struct {
	Command      []string `yaml:"command"`
	Requirements []string `yaml:"requirements"`
}

BuilderConfig contains configuration for the definition of an arbitrary build command and the files required to successfully execute the command.

func (BuilderConfig) InstructionsForPhase added in v0.4.0 

func (bc BuilderConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects instructions into the build related to builder commands and required files.

PhasePreInstall

Creates directories for requirements files, copies in requirements files, and runs the builder command.

func (*BuilderConfig) Merge added in v0.4.0 

func (bc *BuilderConfig) Merge(bc2 BuilderConfig)

Merge takes another BuilderConfig and merges its fields into this one's, overwriting the builder command.

type CommonConfig 

type CommonConfig struct {
	Base       string        `yaml:"base" validate:"omitempty,baseimage"` // name/path to base image
	Apt        AptConfig     `yaml:"apt"`                                 // APT related
	Node       NodeConfig    `yaml:"node"`                                // Node related
	Python     PythonConfig  `yaml:"python"`                              // Python related
	Builder    BuilderConfig `yaml:"builder"`                             // Builder related
	Lives      LivesConfig   `yaml:"lives"`                               // application owner/dir
	Runs       RunsConfig    `yaml:"runs"`                                // runtime environment
	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"`
	VersionConfig `yaml:",inline"`
}

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 new Config struct.

func ReadConfigFile 

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

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

type Enforcement added in v0.3.0 

type Enforcement struct {
	Path string `yaml:"path"`
	Rule string `yaml:"rule"`
}

Enforcement represents a policy rule and config path on which to apply it.

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 LivesConfig added in v0.3.0 

type LivesConfig struct {
	In         string `yaml:"in" validate:"omitempty,abspath"` // application directory
	UserConfig `yaml:",inline"`
}

LivesConfig holds configuration fields related to the livesship of installed dependencies and application files.

func (LivesConfig) InstructionsForPhase added in v0.3.0 

func (lives LivesConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects build instructions related to creation of the application lives.

PhasePrivileged

Creates LocalLibPrefix directory and application lives's user home directory, creates the lives user and its group, and sets up directory permissions.

func (*LivesConfig) Merge added in v0.3.0 

func (lives *LivesConfig) Merge(lives2 LivesConfig)

Merge takes another LivesConfig and overwrites this struct's fields.

type NodeConfig 

type NodeConfig struct {
	Requirements []string `yaml:"requirements"`                     // install requirements from given files
	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.

PhasePreInstall

Installs Node package dependencies declared in requirements files into the application directory. 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, setting the environment according to the configuration.

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 requirements files.

type Policy added in v0.3.0 

type Policy struct {
	Enforcements []Enforcement `yaml:"enforcements"`
}

Policy validates a number of rules against a given configuration.

func ReadPolicy added in v0.3.0 

func ReadPolicy(data []byte) (*Policy, error)

ReadPolicy unmarshals the given YAML bytes into a new Policy struct.

func ReadPolicyFromURI added in v0.3.0 

func ReadPolicyFromURI(uri string) (*Policy, error)

ReadPolicyFromURI fetches the policy file from the given URL or file path and loads its contents with ReadPolicy.

func (Policy) Validate added in v0.3.0 

func (pol Policy) Validate(config Config) error

Validate checks the given config against all policy enforcements.

type PythonConfig added in v0.3.0 

type PythonConfig struct {
	Version      string   `yaml:"version"`      // Python binary to use when installing dependencies
	Requirements []string `yaml:"requirements"` // install requirements from given files
}

PythonConfig holds configuration fields related to pre-installation of project dependencies via PIP.

func (PythonConfig) InstructionsForPhase added in v0.3.0 

func (pc PythonConfig) InstructionsForPhase(phase build.Phase) []build.Instruction

InstructionsForPhase injects instructions into the build related to Python dependency installation.

PhasePrivileged

Ensures that the newest versions of setuptools, wheel, tox, and pip are installed.

PhasePreInstall

Sets up Python wheels under the shared library directory (/opt/lib/python) for dependencies found in the declared requirements files. Installing dependencies during the build.PhasePreInstall phase allows a compiler implementation (e.g. Docker) to produce cache-efficient output so only changes to the given requirements files will invalidate these steps of the image build.

Injects build.Env instructions for PIP_WHEEL_DIR and PIP_FIND_LINKS that will cause future executions of `pip install` (and by extension, `tox`) to consider packages from the shared library directory first.

PhasePostInstall

Injects a build.Env instruction for PIP_NO_INDEX that will cause future executions of `pip install` and `tox` to consider _only_ packages from the shared library directory, helping to speed up image builds by reducing network requests from said commands.

func (*PythonConfig) Merge added in v0.3.0 

func (pc *PythonConfig) Merge(pc2 PythonConfig)

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

func (PythonConfig) RequirementsArgs added in v0.3.0 

func (pc PythonConfig) RequirementsArgs() []string

RequirementsArgs returns the configured requirements as pip `-r` arguments.

type RunsConfig 

type RunsConfig struct {
	UserConfig  `yaml:",inline"`
	Insecurely  Flag              `yaml:"insecurely"`                     // runs user owns application files
	Environment map[string]string `yaml:"environment" validate:"envvars"` // environment variables
}

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

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 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 UserConfig added in v0.3.0 

type UserConfig struct {
	As  string `yaml:"as" validate:"omitempty,username"` // user name
	UID uint   `yaml:"uid"`                              // user ID
	GID uint   `yaml:"gid"`                              // group ID
}

UserConfig holds configuration fields related to a user account.

func (*UserConfig) Merge added in v0.3.0 

func (user *UserConfig) Merge(user2 UserConfig)

Merge takes another UserConfig and overwrites this struct's fields.

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, copying of application files, and all common configuration.

PhaseInstall

If VariantConfig.Copies is not set, copy in application files. 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.

type VersionConfig added in v0.4.0 

type VersionConfig struct {
	Version string `yaml:"version" validate:"required,currentversion"`
}

VersionConfig contains a single field that allows for validation of the config version independent from an entire Config struct.

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.