Documentation
¶
Overview ¶
Package manifest defines structure of YAML files with target definitions.
Index ¶
Constants ¶
This section is empty.
Variables ¶
This section is empty.
Functions ¶
This section is empty.
Types ¶
type BuildStep ¶
type BuildStep struct {
// Dest specifies a location to put the result into.
//
// Applies to `copy`, `go_build` and `go_gae_bundle` steps.
//
// Usually prefixed with "${contextdir}/" to indicate it is relative to
// the context directory.
//
// Optional in the original YAML, always populated after Manifest is parsed.
// See individual *BuildStep structs for defaults.
Dest string `yaml:"dest,omitempty"`
// Cwd is a working directory to run the command in.
//
// Applies to `run` and `go_build` steps.
//
// Default is ${inputsdir}, ${contextdir} or ${manifestdir}, whichever is set.
Cwd string `yaml:"cwd,omitempty"`
CopyBuildStep `yaml:",inline"` // copy a file or directory into the output
GoBuildStep `yaml:",inline"` // build go binary using "go build"
RunBuildStep `yaml:",inline"` // run a command that modifies the checkout
GoGAEBundleBuildStep `yaml:",inline"` // bundle Go source code for GAE
// contains filtered or unexported fields
}
BuildStep is one local build operation.
It takes a local checkout and produces one or more output files put into the context directory.
This struct is a "case class" with union of all supported build step kinds. The chosen "case" is returned by Concrete() method.
func (*BuildStep) Concrete ¶
func (bs *BuildStep) Concrete() ConcreteBuildStep
Concrete returns a pointer to some concrete populated *BuildStep.
type CloudBuildConfig ¶
type CloudBuildConfig struct {
Project string `yaml:"project"` // name of Cloud Project to use for builds
Docker string `yaml:"docker"` // version of "docker" tool to use for builds
}
CloudBuildConfig contains configuration of Cloud Build infrastructure.
type ConcreteBuildStep ¶
type ConcreteBuildStep interface {
String() string // used for human logs only, doesn't have to encode all details
// contains filtered or unexported methods
}
ConcreteBuildStep is implemented by various *BuildStep structs.
type CopyBuildStep ¶
type CopyBuildStep struct {
// Copy is a path to copy files from.
//
// Should start with either "${contextdir}/", "${inputsdir}/" or
// "${manifestdir}/" to indicate the root path.
//
// Can either be a directory or a file. Whatever it is, it will be put into
// the output as Dest. By default Dest is "${contextdir}/<basename of Copy>"
// (i.e. we copy Copy into the root of the context dir).
Copy string `yaml:"copy,omitempty"`
}
CopyBuildStep indicates we want to copy a file or directory.
Doesn't materialize copies on disk, just puts them directly into the output file set.
func (*CopyBuildStep) String ¶
func (s *CopyBuildStep) String() string
type GoBuildStep ¶
type GoBuildStep struct {
// GoBinary specifies a go command binary to build.
//
// This is a path (relative to GOPATH) to some 'main' package. It will be
// built roughly as:
//
// $ CGO_ENABLED=0 GOOS=linux GOARCH=amd64 go build <go_binary> -o <dest>
//
// Where <dest> is taken from Dest and it must be under the context directory.
// It is set to "${contextdir}/<go package name>" by default.
GoBinary string `yaml:"go_binary,omitempty"`
}
GoBuildStep indicates we want to build a go command binary.
Doesn't materialize the build output on disk, just puts it directly into the output file set.
func (*GoBuildStep) String ¶
func (s *GoBuildStep) String() string
type GoGAEBundleBuildStep ¶
type GoGAEBundleBuildStep struct {
// GoGAEBundle is path to GAE module YAML.
GoGAEBundle string `yaml:"go_gae_bundle,omitempty"`
}
GoGAEBundleBuildStep can be used to prepare a tarball with Go GAE app source.
Given a path to a GAE module yaml (that should reside in a directory with some `main` go package), it:
- Copies all files in the modules directory (including all non-go files) to `_gopath/src/<its import path>`
- Copies all *.go code with transitive dependencies to `_gopath/src/`.
- Makes `Dest` a symlink pointing to `_gopath/src/<import path>`.
This ensures "gcloud app deploy" eventually can upload all *.go files needed to deploy a module.
func (*GoGAEBundleBuildStep) String ¶
func (s *GoGAEBundleBuildStep) String() string
type Infra ¶
type Infra struct {
// Storage specifies Google Storage location to store *.tar.gz tarballs
// produced after executing all local build steps.
//
// Expected format is "gs://<bucket>/<prefix>". Tarballs will be stored as
// "gs://<bucket>/<prefix>/<name>/<sha256>.tar.gz", where <name> comes from
// the manifest and <sha256> is a hex sha256 digest of the tarball.
//
// The bucket should exist already. Its contents is trusted, i.e. if there's
// an object with desired <sha256>.tar.gz there already, it won't be replaced.
//
// Required when using Cloud Build.
Storage string `yaml:"storage"`
// Registry is a Cloud Registry to push images to e.g. "gcr.io/something".
//
// If empty, images will be built and then just discarded (will not be pushed
// anywhere). Useful to verify Dockerfile is working without accumulating
// cruft.
Registry string `yaml:"registry"`
// CloudBuild contains configuration of Cloud Build infrastructure.
CloudBuild CloudBuildConfig `yaml:"cloudbuild"`
// Notify indicates what downstream services to notify once the image is
// built.
//
// It is not interpreted by cloudbuildhelper itself, just passed as is to
// the JSON output of `build` command. Callers (usually the images_builder
// recipe) know meaning of this field.
Notify []NotifyConfig `yaml:"notify"`
}
Infra contains configuration of build infrastructure to use: Google Storage bucket, Cloud Build project, etc.
type Manifest ¶
type Manifest struct {
// Name is the name of this target, required.
//
// When building Docker images it is an image name (without registry or any
// tags).
Name string `yaml:"name"`
// ManifestDir is a directory that contains this manifest file.
//
// Populated when it is loaded.
ManifestDir string `yaml:"-"`
// Extends is a unix-style path (relative to this YAML file) to a manifest
// used as a base.
//
// Optional.
//
// Such base manifests usually contain definitions shared by many files, such
// as "imagepins" and "infra".
//
// Dicts are merged (recursively), lists are joined (base entries first).
Extends string `yaml:"extends,omitempty"`
// Dockerfile is a unix-style path to the image's Dockerfile, relative to this
// YAML file.
//
// Presence of this field indicates that the manifest describes how to build
// a docker image. If its missing, docker related subcommands won't work.
//
// All images referenced in this Dockerfile are resolved into concrete digests
// via an external file. See ImagePins field for more information.
Dockerfile string `yaml:"dockerfile,omitempty"`
// ContextDir is a unix-style path to the directory to use as a basis for
// the build. The path is relative to this YAML file.
//
// All files there end up available to the remote builder (e.g. a docker
// daemon will see this directory as a context directory when building
// the image).
//
// All symlinks there are resolved to their targets. Only +w and +x file mode
// bits are preserved (all files have 0444 mode by default, +w adds additional
// 0200 bit and +x adds additional 0111 bis). All other file metadata (owners,
// setuid bits, modification times) are ignored.
//
// The default value depends on whether Dockerfile is set. If it is, then
// ContextDir defaults to the directory with Dockerfile. Otherwise the context
// directory is assumed to be empty.
ContextDir string `yaml:"contextdir,omitempty"`
// InputsDir is an optional directory that can be used to reference files
// consumed by build steps (as "${inputsdir}/path").
//
// Unlike ContextDir, its full content does not automatically end up in the
// output.
InputsDir string `yaml:"inputsdir,omitempty"`
// ImagePins is a unix-style path to the YAML file with pre-resolved mapping
// from (docker image, tag) pair to the corresponding docker image digest.
//
// The path is relative to the manifest YAML file. It should point to a YAML
// file with the following structure:
//
// pins:
// - image: <img>
// tag: <tag>
// digest: sha256:<sha256>
// - image: <img>
// tag: <tag>
// digest: sha256:<sha256>
// ...
//
// See dockerfile.Pins struct for more details.
//
// This file will be used to rewrite the input Dockerfile to reference all
// images (in "FROM ..." lines) only by their digests. This is useful for
// reproducibility of builds.
//
// Only following forms of "FROM ..." statement are allowed:
// * FROM <image> [AS <name>] (assumes "latest" tag)
// * FROM <image>[:<tag>] [AS <name>] (resolves the given tag)
// * FROM <image>[@<digest>] [AS <name>] (passes the definition through)
//
// In particular ARGs in FROM line (e.g. "FROM base:${CODE_VERSION}") are
// not supported.
//
// If not set, the Dockerfile must use only digests to begin with, i.e.
// all FROM statements should have form "FROM <image>@<digest>".
//
// Ignored if Dockerfile field is not set.
ImagePins string `yaml:"imagepins,omitempty"`
// Deterministic is true if Dockerfile (with all "FROM" lines resolved) can be
// understood as a pure function of inputs in ContextDir, i.e. it does not
// depend on the state of the world.
//
// Examples of things that make Dockerfile NOT deterministic:
// * Using "apt-get" or any other remote calls to non-pinned resources.
// * Cloning repositories from "master" ref (or similar).
// * Fetching external resources using curl or wget.
//
// When building an image marked as deterministic, the builder will calculate
// a hash of all inputs (including resolve Dockerfile itself) and check
// whether there's already an image built from them. If there is, the build
// will be skipped completely and the existing image reused.
//
// Images marked as non-deterministic are always rebuilt and reuploaded, even
// if nothing in ContextDir has changed.
Deterministic *bool `yaml:"deterministic,omitempty"`
// Infra is configuration of the build infrastructure to use: Google Storage
// bucket, Cloud Build project, etc.
//
// Keys are names of presets (like "dev", "prod"). What preset is used is
// controlled via "-infra" command line flag (defaults to "dev").
Infra map[string]Infra `yaml:"infra"`
// Build defines a series of local build steps.
//
// Each step may add more files to the context directory. The actual
// `contextdir` directory on disk won't be modified. Files produced here are
// stored in a temp directory and the final context directory is constructed
// from the full recursive copy of `contextdir` and files emitted here.
Build []*BuildStep `yaml:"build,omitempty"`
}
Manifest is a definition of what to build, how and where.
Comments here describe the structure of the manifest file on disk. In the loaded form all paths use filepath.Separator as a directory separator.
func Load ¶
Load loads the manifest from the given path, traversing all "extends" links.
After the manifest is loaded, its fields (like ContextDir) can be manipulated (e.g. to set defaults), after which all "${dir}/" references in build steps must be resolved by a call to RenderSteps.
func (*Manifest) RenderSteps ¶
RenderSteps replaces "${dir}/" in paths in steps with actual values.
type NotifyConfig ¶
type NotifyConfig map[string]interface{}
NotifyConfig is a single item in `notify` list.
It is just an arbitrary YAML dict not interpreted by the cloudbuildhelper.
type RunBuildStep ¶
type RunBuildStep struct {
// Run indicates a command to run along with all its arguments.
//
// Strings that start with "${contextdir}/", "${inputsdir}/" or
// "${manifestdir}/" will be rendered as absolute paths.
Run []string `yaml:"run,omitempty"`
// Outputs is a list of files or directories to put into the output.
//
// They are something that `run` should be generating.
//
// They are expected to be under "${contextdir}". A single output entry
// "${contextdir}/generated/file" is equivalent to a copy step that "picks up"
// the generated file:
// - copy: ${contextdir}/generated/file
// dest: ${contextdir}/generated/file
//
// If outputs are generated outside of the context directory, use `copy` steps
// explicitly.
Outputs []string
}
RunBuildStep indicates we want to run some arbitrary command.
The command may modify the checkout or populate the context dir.
func (*RunBuildStep) String ¶
func (s *RunBuildStep) String() string
Source Files
Click to show internal directories.
Click to hide internal directories.