atc

README

atc

air traffic control - web ui and build scheduler

by NATS Press Office

about

atc is the brain of Concourse. It's responsible for scheduling builds across the cluster of workers, providing the API for the system, as well as serving the web interface.

It can be scaled horizontally behind a load balancer in order to scale the system.

Documentation

Index

• Constants
• Variables
• type AggregatePlan
• type Build
• type BuildStatus
• type ComposePlan
• type Condition
  • func (c *Condition) UnmarshalYAML(unmarshal func(interface{}) error) error
• type ConditionalPlan
• type Conditions
  • func (cs Conditions) SatisfiedBy(successful bool) bool
• type Config
  • func (config Config) JobIsPublic(jobName string) (bool, error)
• type Duration
  • func (d *Duration) UnmarshalYAML(unmarshal func(interface{}) error) error
• type Event
• type EventType
• type EventVersion
• type GetPlan
• type GroupConfig
• type GroupConfigs
  • func (groups GroupConfigs) Lookup(name string) (GroupConfig, bool)
• type HijackInput
• type HijackOutput
• type HijackProcessSpec
• type HijackTTYSpec
• type HijackWindowSize
• type HookedComposePlan
• type Job
• type JobConfig
  • func (config JobConfig) GetSerialGroups() []string
  • func (config JobConfig) Inputs() []JobInput
  • func (config JobConfig) IsSerial() bool
  • func (config JobConfig) Outputs() []JobOutput
• type JobConfigs
  • func (jobs JobConfigs) Lookup(name string) (JobConfig, bool)
• type JobInput
• type JobInputConfig
  • func (config JobInputConfig) Name() string
• type JobOutput
• type JobOutputConfig
  • func (config JobOutputConfig) PerformOn() []Condition
• type LogLevel
• type MetadataField
• type Params
• type Pipe
• type Pipeline
• type Plan
• type PlanConfig
  • func (config PlanConfig) Name() string
  • func (config PlanConfig) ResourceName() string
• type PlanSequence
• type PutGetPlan
• type PutPlan
  • func (plan PutPlan) GetPlan() GetPlan
• type Resource
• type ResourceConfig
• type ResourceConfigs
  • func (resources ResourceConfigs) Lookup(name string) (ResourceConfig, bool)
• type Source
• type Tags
• type TaskConfig
  • func (a TaskConfig) Merge(b TaskConfig) TaskConfig
  • func (config TaskConfig) Validate() error
• type TaskInputConfig
• type TaskPlan
• type TaskRunConfig
• type TimeoutPlan
• type TryPlan
• type Version
• type Worker
• type WorkerResourceType

Constants

const (
	SaveConfig = "SaveConfig"
	GetConfig  = "GetConfig"

	Hijack = "Hijack"

	CreateBuild = "CreateBuild"
	ListBuilds  = "ListBuilds"
	BuildEvents = "BuildEvents"
	AbortBuild  = "AbortBuild"

	GetJob        = "GetJob"
	ListJobs      = "ListJobs"
	ListJobBuilds = "ListJobBuilds"
	GetJobBuild   = "GetJobBuild"
	PauseJob      = "PauseJob"
	UnpauseJob    = "UnpauseJob"

	ListResources          = "ListResources"
	EnableResourceVersion  = "EnableResourceVersion"
	DisableResourceVersion = "DisableResourceVersion"
	PauseResource          = "PauseResource"
	UnpauseResource        = "UnpauseResource"

	ListPipelines   = "ListPipelines"
	DeletePipeline  = "DeletePipeline"
	OrderPipelines  = "OrderPipelines"
	PausePipeline   = "PausePipeline"
	UnpausePipeline = "UnpausePipeline"

	CreatePipe = "CreatePipe"
	WritePipe  = "WritePipe"
	ReadPipe   = "ReadPipe"

	RegisterWorker = "RegisterWorker"
	ListWorkers    = "ListWorkers"

	SetLogLevel = "SetLogLevel"
	GetLogLevel = "GetLogLevel"

	DownloadCLI = "DownloadCLI"
)

const ConfigVersionHeader = "X-Concourse-Config-Version"

const DefaultPipelineName = "main"

Variables

var Routes = rata.Routes{
	{Path: "/api/v1/pipelines/:pipeline_name/config", Method: "PUT", Name: SaveConfig},
	{Path: "/api/v1/pipelines/:pipeline_name/config", Method: "GET", Name: GetConfig},

	{Path: "/api/v1/builds", Method: "POST", Name: CreateBuild},
	{Path: "/api/v1/builds", Method: "GET", Name: ListBuilds},
	{Path: "/api/v1/builds/:build_id/events", Method: "GET", Name: BuildEvents},
	{Path: "/api/v1/builds/:build_id/abort", Method: "POST", Name: AbortBuild},
	{Path: "/api/v1/hijack", Method: "POST", Name: Hijack},

	{Path: "/api/v1/pipelines/:pipeline_name/jobs", Method: "GET", Name: ListJobs},
	{Path: "/api/v1/pipelines/:pipeline_name/jobs/:job_name", Method: "GET", Name: GetJob},
	{Path: "/api/v1/pipelines/:pipeline_name/jobs/:job_name/builds", Method: "GET", Name: ListJobBuilds},
	{Path: "/api/v1/pipelines/:pipeline_name/jobs/:job_name/builds/:build_name", Method: "GET", Name: GetJobBuild},
	{Path: "/api/v1/pipelines/:pipeline_name/jobs/:job_name/pause", Method: "PUT", Name: PauseJob},
	{Path: "/api/v1/pipelines/:pipeline_name/jobs/:job_name/unpause", Method: "PUT", Name: UnpauseJob},

	{Path: "/api/v1/pipelines", Method: "GET", Name: ListPipelines},
	{Path: "/api/v1/pipelines/:pipeline_name", Method: "DELETE", Name: DeletePipeline},
	{Path: "/api/v1/pipelines/ordering", Method: "PUT", Name: OrderPipelines},
	{Path: "/api/v1/pipelines/:pipeline_name/pause", Method: "PUT", Name: PausePipeline},
	{Path: "/api/v1/pipelines/:pipeline_name/unpause", Method: "PUT", Name: UnpausePipeline},

	{Path: "/api/v1/pipelines/:pipeline_name/resources", Method: "GET", Name: ListResources},
	{Path: "/api/v1/pipelines/:pipeline_name/resources/:resource_name/versions/:resource_version_id/enable", Method: "PUT", Name: EnableResourceVersion},
	{Path: "/api/v1/pipelines/:pipeline_name/resources/:resource_name/versions/:resource_version_id/disable", Method: "PUT", Name: DisableResourceVersion},
	{Path: "/api/v1/pipelines/:pipeline_name/resources/:resource_name/pause", Method: "PUT", Name: PauseResource},
	{Path: "/api/v1/pipelines/:pipeline_name/resources/:resource_name/unpause", Method: "PUT", Name: UnpauseResource},

	{Path: "/api/v1/pipes", Method: "POST", Name: CreatePipe},
	{Path: "/api/v1/pipes/:pipe_id", Method: "PUT", Name: WritePipe},
	{Path: "/api/v1/pipes/:pipe_id", Method: "GET", Name: ReadPipe},

	{Path: "/api/v1/workers", Method: "GET", Name: ListWorkers},
	{Path: "/api/v1/workers", Method: "POST", Name: RegisterWorker},

	{Path: "/api/v1/log-level", Method: "GET", Name: GetLogLevel},
	{Path: "/api/v1/log-level", Method: "PUT", Name: SetLogLevel},

	{Path: "/api/v1/cli", Method: "GET", Name: DownloadCLI},
}

Types

type AggregatePlan

type AggregatePlan []Plan

type Build

type Build struct {
	ID      int    `json:"id"`
	Name    string `json:"name"`
	Status  string `json:"status"`
	JobName string `json:"job_name"`
	URL     string `json:"url"`
}

type BuildStatus

type BuildStatus string

const (
	StatusStarted   BuildStatus = "started"
	StatusSucceeded BuildStatus = "succeeded"
	StatusFailed    BuildStatus = "failed"
	StatusErrored   BuildStatus = "errored"
	StatusAborted   BuildStatus = "aborted"
)

type ComposePlan

type ComposePlan struct {
	A Plan `json:"a"`
	B Plan `json:"b"`
}

type Condition

type Condition string

const (
	ConditionSuccess Condition = "success"
	ConditionFailure Condition = "failure"
)

func (*Condition) UnmarshalYAML

func (c *Condition) UnmarshalYAML(unmarshal func(interface{}) error) error

type ConditionalPlan

type ConditionalPlan struct {
	Conditions Conditions `json:"conditions"`
	Plan       Plan       `json:"plan"`
}

type Conditions

type Conditions []Condition

func (Conditions) SatisfiedBy

func (cs Conditions) SatisfiedBy(successful bool) bool

type Config

type Config struct {
	Groups    GroupConfigs    `yaml:"groups" json:"groups" mapstructure:"groups"`
	Resources ResourceConfigs `yaml:"resources" json:"resources" mapstructure:"resources"`
	Jobs      JobConfigs      `yaml:"jobs" json:"jobs" mapstructure:"jobs"`
}

func (Config) JobIsPublic

func (config Config) JobIsPublic(jobName string) (bool, error)

type Duration

type Duration time.Duration

func (*Duration) UnmarshalYAML

func (d *Duration) UnmarshalYAML(unmarshal func(interface{}) error) error

type Event

type Event interface {
	EventType() EventType
	Version() EventVersion
	Censored() Event
}

type EventType

type EventType string

type EventVersion

type EventVersion string

semantic version for an individual event.

minor bumps are expected to be backwards-compatible, meaning clients can interpret them via the older handlers, and they can unmarshal into the new version trivially.

ATC will always emit the highest possible minor version for an event. this is so that we don't have to maintain copies of the event every time there's a minor bump.

an example of a minor bump would be an additive change, i.e. a new field.

major bumps are backwards-incompatible.

an example of a major bump would be the changing or removal of a field.

type GetPlan

type GetPlan struct {
	Type     string   `json:"type"`
	Name     string   `json:"name,omitempty"`
	Resource string   `json:"resource"`
	Pipeline string   `json:"pipeline"`
	Source   Source   `json:"source"`
	Params   Params   `json:"params,omitempty"`
	Version  Version  `json:"version,omitempty"`
	Tags     Tags     `json:"tags,omitempty"`
	Timeout  Duration `json:"timeout,omitempty"`
}

type GroupConfig

type GroupConfig struct {
	Name      string   `yaml:"name" json:"name" mapstructure:"name"`
	Jobs      []string `yaml:"jobs,omitempty" json:"jobs,omitempty" mapstructure:"jobs"`
	Resources []string `yaml:"resources,omitempty" json:"resources,omitempty" mapstructure:"resources"`
}

type GroupConfigs

type GroupConfigs []GroupConfig

func (GroupConfigs) Lookup

func (groups GroupConfigs) Lookup(name string) (GroupConfig, bool)

type HijackInput

type HijackInput struct {
	Stdin   []byte         `json:"stdin,omitempty"`
	TTYSpec *HijackTTYSpec `json:"tty,omitempty"`
}

type HijackOutput

type HijackOutput struct {
	Stdout     []byte `json:"stdout,omitempty"`
	Stderr     []byte `json:"stderr,omitempty"`
	Error      string `json:"error,omitempty"`
	ExitStatus *int   `json:"exit_status,omitempty"`
}

type HijackProcessSpec

type HijackProcessSpec struct {
	Path string   `json:"path"`
	Args []string `json:"args"`
	Env  []string `json:"env"`
	Dir  string   `json:"dir"`

	Privileged bool   `json:"privileged"`
	User       string `json:"user"`

	TTY *HijackTTYSpec `json:"tty"`
}

type HijackTTYSpec

type HijackTTYSpec struct {
	WindowSize HijackWindowSize `json:"window_size"`
}

type HijackWindowSize

type HijackWindowSize struct {
	Columns int `json:"columns"`
	Rows    int `json:"rows"`
}

type HookedComposePlan

type HookedComposePlan struct {
	Step         Plan `json:"step"`
	OnSuccess    Plan `json:"on_success"`
	OnFailure    Plan `json:"on_failure"`
	OnCompletion Plan `json:"on_completion"`
	Next         Plan `json:"next"`
}

type Job

type Job struct {
	Name          string `json:"name"`
	URL           string `json:"url"`
	Paused        bool   `json:"paused,omitempty"`
	NextBuild     *Build `json:"next_build"`
	FinishedBuild *Build `json:"finished_build"`

	Inputs  []JobInput  `json:"inputs"`
	Outputs []JobOutput `json:"outputs"`

	Groups []string `json:"groups"`
}

type JobConfig

type JobConfig struct {
	Name         string   `yaml:"name" json:"name" mapstructure:"name"`
	Public       bool     `yaml:"public,omitempty" json:"public,omitempty" mapstructure:"public"`
	Serial       bool     `yaml:"serial,omitempty" json:"serial,omitempty" mapstructure:"serial"`
	SerialGroups []string `yaml:"serial_groups,omitempty" json:"serial_groups,omitempty" mapstructure:"serial_groups"`

	Privileged     bool        `yaml:"privileged,omitempty" json:"privileged,omitempty" mapstructure:"privileged"`
	TaskConfigPath string      `yaml:"build,omitempty" json:"build,omitempty" mapstructure:"build"`
	TaskConfig     *TaskConfig `yaml:"config,omitempty" json:"config,omitempty" mapstructure:"config"`

	InputConfigs  []JobInputConfig  `yaml:"inputs,omitempty" json:"inputs,omitempty" mapstructure:"inputs"`
	OutputConfigs []JobOutputConfig `yaml:"outputs,omitempty" json:"outputs,omitempty" mapstructure:"outputs"`

	Plan PlanSequence `yaml:"plan,omitempty" json:"plan,omitempty" mapstructure:"plan"`
}

func (JobConfig) GetSerialGroups

func (config JobConfig) GetSerialGroups() []string

func (JobConfig) Inputs

func (config JobConfig) Inputs() []JobInput

func (JobConfig) IsSerial

func (config JobConfig) IsSerial() bool

func (JobConfig) Outputs

func (config JobConfig) Outputs() []JobOutput

type JobConfigs

type JobConfigs []JobConfig

func (JobConfigs) Lookup

func (jobs JobConfigs) Lookup(name string) (JobConfig, bool)

type JobInput

type JobInput struct {
	Name     string   `json:"name"`
	Resource string   `json:"resource"`
	Passed   []string `json:"passed,omitempty"`
	Trigger  bool     `json:"trigger"`
}

type JobInputConfig

type JobInputConfig struct {
	RawName  string   `yaml:"name,omitempty" json:"name,omitempty" mapstructure:"name"`
	Resource string   `yaml:"resource" json:"resource" mapstructure:"resource"`
	Params   Params   `yaml:"params,omitempty" json:"params,omitempty" mapstructure:"params"`
	Passed   []string `yaml:"passed,omitempty" json:"passed,omitempty" mapstructure:"passed"`
	Trigger  bool     `yaml:"trigger" json:"trigger" mapstructure:"trigger"`
}

func (JobInputConfig) Name

func (config JobInputConfig) Name() string

type JobOutput

type JobOutput struct {
	Name     string `json:"name"`
	Resource string `json:"resource"`
}

type JobOutputConfig

type JobOutputConfig struct {
	Resource string `yaml:"resource" json:"resource" mapstructure:"resource"`
	Params   Params `yaml:"params,omitempty" json:"params,omitempty" mapstructure:"params"`

	// e.g. [success, failure]; default [success]
	RawPerformOn []Condition `yaml:"perform_on,omitempty" json:"perform_on,omitempty" mapstructure:"perform_on"`
}

func (JobOutputConfig) PerformOn

func (config JobOutputConfig) PerformOn() []Condition

type LogLevel

type LogLevel string

const (
	LogLevelInvalid LogLevel = ""
	LogLevelDebug   LogLevel = "debug"
	LogLevelInfo    LogLevel = "info"
	LogLevelError   LogLevel = "error"
	LogLevelFatal   LogLevel = "fatal"
)

type MetadataField

type MetadataField struct {
	Name  string `json:"name"`
	Value string `json:"value"`
}

type Params

type Params map[string]interface{}

type Pipe

type Pipe struct {
	ID string `json:"id"`
}

type Pipeline

type Pipeline struct {
	Name   string `json:"name"`
	URL    string `json:"url"`
	Paused bool   `json:"paused"`
}

type Plan

type Plan struct {
	Compose       *ComposePlan       `json:"compose,omitempty"`
	Aggregate     *AggregatePlan     `json:"aggregate,omitempty"`
	Get           *GetPlan           `json:"get,omitempty"`
	Put           *PutPlan           `json:"put,omitempty"`
	Task          *TaskPlan          `json:"task,omitempty"`
	Conditional   *ConditionalPlan   `json:"conditional,omitempty"`
	PutGet        *PutGetPlan        `json:"putget,omitempty"`
	HookedCompose *HookedComposePlan `json:"hooked_compose,omitempty"`
	Try           *TryPlan           `json:"try,omitempty"`
	Timeout       *TimeoutPlan       `json:"timeout,omitempty"`
}

type PlanConfig

type PlanConfig struct {
	// makes the Plan conditional
	// conditions on which to perform a nested sequence
	Conditions *Conditions `yaml:"conditions,omitempty" json:"conditions,omitempty" mapstructure:"conditions"`

	// compose a nested sequence of plans
	// name of the nested 'do'
	RawName string `yaml:"name,omitempty" json:"name,omitempty" mapstructure:"name"`

	// a nested chain of steps to run
	Do *PlanSequence `yaml:"do,omitempty" json:"do,omitempty" mapstructure:"do"`

	// corresponds to an Aggregate plan, keyed by the name of each sub-plan
	Aggregate *PlanSequence `yaml:"aggregate,omitempty" json:"aggregate,omitempty" mapstructure:"aggregate"`

	// corresponds to Get and Put resource plans, respectively
	// name of 'input', e.g. bosh-stemcell
	Get string `yaml:"get,omitempty" json:"get,omitempty" mapstructure:"get"`
	// jobs that this resource must have made it through
	Passed []string `yaml:"passed,omitempty" json:"passed,omitempty" mapstructure:"passed"`
	// whether to trigger based on this resource changing
	Trigger bool `yaml:"trigger,omitempty" json:"trigger,omitempty" mapstructure:"trigger"`

	// name of 'output', e.g. rootfs-tarball
	Put string `yaml:"put,omitempty" json:"put,omitempty" mapstructure:"put"`

	// corresponding resource config, e.g. aws-stemcell
	Resource string `yaml:"resource,omitempty" json:"resource,omitempty" mapstructure:"resource"`

	// corresponds to a Task plan
	// name of 'task', e.g. unit, go1.3, go1.4
	Task string `yaml:"task,omitempty" json:"task,omitempty" mapstructure:"task"`
	// run task privileged
	Privileged bool `yaml:"privileged,omitempty" json:"privileged,omitempty" mapstructure:"privileged"`
	// task config path, e.g. foo/build.yml
	TaskConfigPath string `yaml:"file,omitempty" json:"file,omitempty" mapstructure:"file"`
	// inlined task config
	TaskConfig *TaskConfig `yaml:"config,omitempty" json:"config,omitempty" mapstructure:"config"`

	// used by Get and Put for specifying params to the resource
	Params Params `yaml:"params,omitempty" json:"params,omitempty" mapstructure:"params"`

	// used by Put to specify params for the subsequent Get
	GetParams Params `yaml:"get_params,omitempty" json:"get_params,omitempty" mapstructure:"get_params"`

	// used by any step to specify which workers are eligible to run the step
	Tags Tags `yaml:"tags,omitempty" json:"tags,omitempty" mapstructure:"tags"`

	// used by any step to run something when the step reports a failure
	Failure *PlanConfig `yaml:"on_failure,omitempty" json:"on_failure,omitempty" mapstructure:"on_failure"`

	// used on any step to always execute regardless of the step's completed state
	Ensure *PlanConfig `yaml:"ensure,omitempty" json:"ensure,omitempty" mapstructure:"ensure"`

	// used on any step to execute on successful completion of the step
	Success *PlanConfig `yaml:"on_success,omitempty" json:"on_success,omitempty" mapstructure:"on_success"`

	// used on any step to swallow failures and errors
	Try *PlanConfig `yaml:"try,omitempty" json:"try,omitempty" mapstructure:"try"`

	// used on any step to interrupt the step after a given duration
	Timeout Duration `yaml:"timeout,omitempty" json:"timeout,omitempty" mapstructure:"timeout"`
}

A PlanConfig is a flattened set of configuration corresponding to a particular Plan, where Source and Version are populated lazily.

func (PlanConfig) Name

func (config PlanConfig) Name() string

func (PlanConfig) ResourceName

func (config PlanConfig) ResourceName() string

type PlanSequence

type PlanSequence []PlanConfig

A PlanSequence corresponds to a chain of Compose plan, with an implicit `on: [success]` after every Task plan.

type PutGetPlan

type PutGetPlan struct {
	Head Plan `json:"put"`
	Rest Plan `json:"rest"`
}

type PutPlan

type PutPlan struct {
	Type      string   `json:"type"`
	Name      string   `json:"name,omitempty"`
	Resource  string   `json:"resource"`
	Pipeline  string   `json:"pipeline"`
	Source    Source   `json:"source"`
	Params    Params   `json:"params,omitempty"`
	GetParams Params   `json:"get_params,omitempty"`
	Tags      Tags     `json:"tags,omitempty"`
	Timeout   Duration `json:"timeout,omitempty"`
}

func (PutPlan) GetPlan

func (plan PutPlan) GetPlan() GetPlan

type Resource

type Resource struct {
	Name   string   `json:"name"`
	Type   string   `json:"type"`
	Groups []string `json:"groups"`
	URL    string   `json:"url"`

	Paused bool `json:"paused,omitempty"`

	FailingToCheck bool   `json:"failing_to_check,omitempty"`
	CheckError     string `json:"check_error,omitempty"`
}

type ResourceConfig

type ResourceConfig struct {
	Name string `yaml:"name" json:"name" mapstructure:"name"`

	Type   string `yaml:"type" json:"type" mapstructure:"type"`
	Source Source `yaml:"source" json:"source" mapstructure:"source"`
}

type ResourceConfigs

type ResourceConfigs []ResourceConfig

func (ResourceConfigs) Lookup

func (resources ResourceConfigs) Lookup(name string) (ResourceConfig, bool)

type Source

type Source map[string]interface{}

type Tags

type Tags []string

type TaskConfig

type TaskConfig struct {
	// The platform the task must run on (e.g. linux, windows).
	Platform string `json:"platform,omitempty" yaml:"platform,omitempty"`

	// Additional tags to influence which workers the task can run on.
	Tags []string `json:"tags,omitempty"  yaml:"tags,omitempty"`

	// Optional string specifying an image to use for the build. Depending on the
	// platform, this may or may not be required (e.g. Windows/OS X vs. Linux).
	Image string `json:"image,omitempty"   yaml:"image,omitempty"`

	// Parameters to pass to the task via environment variables.
	Params map[string]string `json:"params,omitempty"  yaml:"params,omitempty"`

	// Script to execute.
	Run TaskRunConfig `json:"run,omitempty"     yaml:"run,omitempty"`

	// The set of (logical, name-only) inputs required by the task.
	Inputs []TaskInputConfig `json:"inputs,omitempty"  yaml:"inputs,omitempty"`
}

func (TaskConfig) Merge

func (a TaskConfig) Merge(b TaskConfig) TaskConfig

func (TaskConfig) Validate

func (config TaskConfig) Validate() error

type TaskInputConfig

type TaskInputConfig struct {
	Name string `json:"name" yaml:"name"`
	Path string `json:"path,omitempty" yaml:"path"`
}

type TaskPlan

type TaskPlan struct {
	Name string `json:"name,omitempty"`

	Privileged bool     `json:"privileged"`
	Tags       Tags     `json:"tags,omitempty"`
	Timeout    Duration `json:"timeout,omitempty"`

	ConfigPath string      `json:"config_path,omitempty"`
	Config     *TaskConfig `json:"config,omitempty"`
}

type TaskRunConfig

type TaskRunConfig struct {
	Path string   `json:"path" yaml:"path"`
	Args []string `json:"args,omitempty" yaml:"args"`
}

type TimeoutPlan

type TimeoutPlan struct {
	Step     Plan     `json: "step"`
	Duration Duration `json:"duration"`
}

type TryPlan

type TryPlan struct {
	Step Plan `json: "step"`
}

type Version

type Version map[string]interface{}

type Worker

type Worker struct {
	Addr string `json:"addr"`

	ActiveContainers int `json:"active_containers"`

	ResourceTypes []WorkerResourceType `json:"resource_types"`

	Platform string   `json:"platform"`
	Tags     []string `json:"tags"`
}

type WorkerResourceType

type WorkerResourceType struct {
	Type  string `json:"type"`
	Image string `json:"image"`
}