cloudformation

Documentation

Overview

Package cloudformation implements the Scheduler interface for ECS by using CloudFormation to provision and update resources.

Index

• Constants
• Variables
• func HostedZone(config client.ConfigProvider, hostedZoneID string) (*route53.HostedZone, error)
• type EmpireTemplate
  • func (t *EmpireTemplate) Build(app *scheduler.App) (interface{}, error)
  • func (t *EmpireTemplate) ContainerDefinition(app *scheduler.App, p *scheduler.Process) *ecs.ContainerDefinition
  • func (t *EmpireTemplate) Execute(w io.Writer, data interface{}) error
  • func (t *EmpireTemplate) Validate() error
• type MigrationScheduler
  • func NewMigrationScheduler(db *sql.DB, c *Scheduler, e *ecs.Scheduler) *MigrationScheduler
  • func (s *MigrationScheduler) Backend(appID string) (scheduler.Scheduler, error)
  • func (s *MigrationScheduler) Instances(ctx context.Context, appID string) ([]*scheduler.Instance, error)
  • func (s *MigrationScheduler) Migrate(ctx context.Context, app *scheduler.App, state, desiredState string) error
  • func (s *MigrationScheduler) Remove(ctx context.Context, appID string) error
  • func (s *MigrationScheduler) Run(ctx context.Context, app *scheduler.App, process *scheduler.Process, ...) error
  • func (s *MigrationScheduler) Scale(ctx context.Context, appID, process string, instances uint) error
  • func (s *MigrationScheduler) Stop(ctx context.Context, id string) error
  • func (s *MigrationScheduler) Submit(ctx context.Context, app *scheduler.App) error
• type ScaleOptions
• type Scheduler
  • func NewScheduler(db *sql.DB, config client.ConfigProvider) *Scheduler
  • func (s *Scheduler) Instances(ctx context.Context, app string) ([]*scheduler.Instance, error)
  • func (s *Scheduler) Remove(ctx context.Context, appID string) error
  • func (m *Scheduler) Run(ctx context.Context, app *scheduler.App, process *scheduler.Process, ...) error
  • func (s *Scheduler) Scale(ctx context.Context, appID string, process string, instances uint) error
  • func (s *Scheduler) ScaleWithOptions(ctx context.Context, appID string, process string, instances uint, ...) error
  • func (s *Scheduler) Services(appID string) (map[string]string, error)
  • func (s *Scheduler) Stop(ctx context.Context, instanceID string) error
  • func (s *Scheduler) Submit(ctx context.Context, app *scheduler.App) error
  • func (s *Scheduler) SubmitWithOptions(ctx context.Context, app *scheduler.App, opts SubmitOptions) error
• type SubmitOptions
• type Template

Constants

const (
	// For HTTP/HTTPS/TCP services, we allocate an ELB and map it's instance port to
	// the container port. This is the port that processes within the container
	// should bind to. This value is also exposed to the container through the PORT
	// environment variable.
	ContainerPort = 8080
)

const (
	MaxDescribeTasks = 100
)

ECS limits

const (
	MaxTemplateSize = 460800 // bytes
)

CloudFormation limits

See http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cloudformation-limits.html

const MigrationEnvVar = "EMPIRE_SCHEDULER_MIGRATION"

This is the environment variable in the application that determines what step of the migration we should transition to. A basic migration flow would look like:

1. `emp set EMPIRE_SCHEDULER_MIGRATION=step1`: CloudFormation stack is created without any DNS changes.
2. User removes the old CNAME manually in the AWS Console, then sets the `DNS` parameter in the CloudFormation stack to `true`.
3. `emp set EMPIRE_SCHEDULER_MIGRATION=step2`: The old AWS resources are removed.
4. `emp unset EMPIRE_SCHEDULER_MIGRATION`: All done.

Variables

var DefaultStackNameTemplate = template.Must(template.New("stack_name").Parse("{{.Name}}"))

DefaultStackNameTemplate is the default text/template for generating a CloudFormation stack name for an app.

var ErrMigrating = errors.New("app is currently being migrated to a CloudFormation stack. Sit tight...")

ErrMigrating is returned when the application is being migrated.

Functions

func HostedZone

func HostedZone(config client.ConfigProvider, hostedZoneID string) (*route53.HostedZone, error)

HostedZone returns the HostedZone for the ZoneID.

Types

type EmpireTemplate

type EmpireTemplate struct {
	// By default, the JSON will not have any whitespace or newlines, which
	// helps prevent templates from going over the maximum size limit. If
	// you care about readability, you can set this to true.
	NoCompress bool

	// The ECS cluster to run the services in.
	Cluster string

	// The hosted zone to add CNAME's to.
	HostedZone *route53.HostedZone

	// The ID of the security group to assign to internal load balancers.
	InternalSecurityGroupID string

	// The ID of the security group to assign to external load balancers.
	ExternalSecurityGroupID string

	// The Subnet IDs to assign when creating internal load balancers.
	InternalSubnetIDs []string

	// The Subnet IDs to assign when creating external load balancers.
	ExternalSubnetIDs []string

	// The name of the ECS Service IAM role.
	ServiceRole string

	// The ARN of the SNS topic to provision instance ports.
	CustomResourcesTopic string

	LogConfiguration *ecs.LogConfiguration
}

This implements the Template interface to create a suitable CloudFormation template for an Empire app.

func (*EmpireTemplate) Build

func (t *EmpireTemplate) Build(app *scheduler.App) (interface{}, error)

Build builds a Go representation of a CloudFormation template for the app.

func (*EmpireTemplate) ContainerDefinition

func (t *EmpireTemplate) ContainerDefinition(app *scheduler.App, p *scheduler.Process) *ecs.ContainerDefinition

ContainerDefinition generates an ECS ContainerDefinition for a process.

func (*EmpireTemplate) Execute

func (t *EmpireTemplate) Execute(w io.Writer, data interface{}) error

Execute builds the template, and writes it to w.

func (*EmpireTemplate) Validate

func (t *EmpireTemplate) Validate() error

Validate checks that all of the expected values are provided.

type MigrationScheduler

type MigrationScheduler struct {
	// contains filtered or unexported fields
}

This is a scheduler.Scheduler implementation that wraps the newer cloudformation.Scheduler and the older ecs.Scheduler to migrate applications over the the new CloudFormation based scheduler.

It uses a sql table to determine what scheduling backend should be used. Apps can be migrated from the ecs scheduler to the cloudformation scheduler by using the Migrate function.

func NewMigrationScheduler

func NewMigrationScheduler(db *sql.DB, c *Scheduler, e *ecs.Scheduler) *MigrationScheduler

NewMigrationScheduler returns a new MigrationSchedeuler instance.

func (*MigrationScheduler) Backend

func (s *MigrationScheduler) Backend(appID string) (scheduler.Scheduler, error)

Backend returns the scheduling backend to use for the given app.

func (*MigrationScheduler) Instances

func (s *MigrationScheduler) Instances(ctx context.Context, appID string) ([]*scheduler.Instance, error)

func (*MigrationScheduler) Migrate

func (s *MigrationScheduler) Migrate(ctx context.Context, app *scheduler.App, state, desiredState string) error

Migrate submits the app to the CloudFormation scheduler, waits for the stack to successfully create, then removes the old API managed resources using the ECS scheduler.

func (*MigrationScheduler) Remove

func (s *MigrationScheduler) Remove(ctx context.Context, appID string) error

func (*MigrationScheduler) Run

func (s *MigrationScheduler) Run(ctx context.Context, app *scheduler.App, process *scheduler.Process, in io.Reader, out io.Writer) error

func (*MigrationScheduler) Scale

func (s *MigrationScheduler) Scale(ctx context.Context, appID, process string, instances uint) error

func (*MigrationScheduler) Stop

func (s *MigrationScheduler) Stop(ctx context.Context, id string) error

func (*MigrationScheduler) Submit

func (s *MigrationScheduler) Submit(ctx context.Context, app *scheduler.App) error

type ScaleOptions

type ScaleOptions struct {
	// Done is a channel that is sent on when the stack is fully created or
	// updated.
	Done chan error
}

type Scheduler

type Scheduler struct {
	// Template is a text/template that will be executed using the
	// twelvefactor.Manifest as data. This template should return a valid
	// CloudFormation JSON template.
	Template Template

	// The ECS cluster to run tasks in.
	Cluster string

	// The name of the bucket to store templates in.
	Bucket string

	// A text/template that will generate the stack name for the app. This
	// template will be executed with a scheduler.App as it's data.
	StackNameTemplate *template.Template

	// Any additional tags to add to stacks.
	Tags []*cloudformation.Tag
	// contains filtered or unexported fields
}

Scheduler implements the scheduler.Scheduler interface using CloudFormation to provision resources.

func NewScheduler

func NewScheduler(db *sql.DB, config client.ConfigProvider) *Scheduler

NewScheduler returns a new Scheduler instance.

func (*Scheduler) Instances

func (s *Scheduler) Instances(ctx context.Context, app string) ([]*scheduler.Instance, error)

Instances returns all of the running tasks for this application.

func (*Scheduler) Remove

func (s *Scheduler) Remove(ctx context.Context, appID string) error

Remove removes the CloudFormation stack for the given app.

func (*Scheduler) Run

func (m *Scheduler) Run(ctx context.Context, app *scheduler.App, process *scheduler.Process, in io.Reader, out io.Writer) error

Run registers a TaskDefinition for the process, and calls RunTask.

func (*Scheduler) Scale

func (s *Scheduler) Scale(ctx context.Context, appID string, process string, instances uint) error

Scale scales the ECS service for the given process to the desired number of instances.

func (*Scheduler) ScaleWithOptions

func (s *Scheduler) ScaleWithOptions(ctx context.Context, appID string, process string, instances uint, opts ScaleOptions) error

func (*Scheduler) Services

func (s *Scheduler) Services(appID string) (map[string]string, error)

Services returns a map that maps the name of the process (e.g. web) to the ARN of the associated ECS service.

func (*Scheduler) Stop

func (s *Scheduler) Stop(ctx context.Context, instanceID string) error

Stop stops the given ECS task.

func (*Scheduler) Submit

func (s *Scheduler) Submit(ctx context.Context, app *scheduler.App) error

Submit creates (or updates) the CloudFormation stack for the app.

func (*Scheduler) SubmitWithOptions

func (s *Scheduler) SubmitWithOptions(ctx context.Context, app *scheduler.App, opts SubmitOptions) error

SubmitWithOptions submits (or updates) the CloudFormation stack for the app.

type SubmitOptions

type SubmitOptions struct {
	// Done is a channel that is sent on when the stack is fully created or
	// updated.
	Done chan error

	// When true, does not make any changes to DNS. This is only used when
	// migrating to this scheduler
	NoDNS bool
}

SubmitOptions are options provided to SubmitWithOptions.

type Template

type Template interface {
	Execute(wr io.Writer, data interface{}) error
}

Template represents something that can generate a stack body. Conveniently the same interface as text/template.Template.