empire

package module
v0.13.0-clearcare-2 Latest Latest
Warning

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

 Go to latest Published: Jul 24, 2019 License: BSD-2-Clause Imports: 26 Imported by: 0

README

Empire

readthedocs badge Circle CI Slack Status

Empire

Empire is a control layer on top of Amazon EC2 Container Service (ECS) that provides a Heroku like workflow. It conforms to a subset of the Heroku Platform API, which means you can use the same tools and processes that you use with Heroku, but with all the power of EC2 and Docker.

Empire is targeted at small to medium sized startups that are running a large number of microservices and need more flexibility than what Heroku provides. You can read the original blog post about why we built empire on the Remind engineering blog.

Quickstart

Install

To use Empire, you'll need to have an ECS cluster running. See the quickstart guide for more information.

Architecture

Empire aims to make it trivially easy to deploy a container based microservices architecture, without all of the complexities of managing systems like Mesos or Kubernetes. ECS takes care of much of that work, but Empire attempts to enhance the interface to ECS for deploying and maintaining applications, allowing you to deploy Docker images as easily as:

$ emp deploy remind101/acme-inc:master
Heroku API compatibility

Empire supports a subset of the Heroku Platform API, which means any tool that uses the Heroku API can probably be used with Empire, if the endpoint is supported.

As an example, you can use the hk CLI with Empire like this:

$ HEROKU_API_URL=<empire_url> hk ...

However, the best user experience will be by using the emp command, which is a fork of hk with Empire specific features.

Routing

Empire's routing layer is backed by internal ELBs. Any application that specifies a web process will get an internal ELB attached to its associated ECS Service. When a new version of the app is deployed, ECS manages spinning up the new versions of the process, waiting for old connections to drain, then killing the old release.

When a new internal ELB is created, an associated CNAME record will be created in Route53 under the internal TLD, which means you can use DNS for service discovery. If we deploy an app named feed then it will be available at http://feed within the ECS cluster.

Apps default to only being exposed internally, unless you add a custom domain to them. Adding a custom domain will create a new external ELB for the ECS service.

Deploying

Any tagged Docker image can be deployed to Empire as an app. Empire doesn't enforce how you tag your Docker images, but we recommend tagging the image with the git sha that it was built from (any any immutable identifier), and deploying that.

When you deploy a Docker image to Empire, it will extract a Procfile from the WORKDIR. Like Heroku, you can specify different process types that compose your service (e.g. web and worker), and scale them individually. Each process type in the Procfile maps directly to an ECS Service.

Contributing

Pull requests are more than welcome! For help with setting up a development environment, see CONTRIBUTING.md

Community

We have a google group, empire-dev, where you can ask questions and engage with the Empire community.

You can also join our Slack team for discussions and support.

Documentation

Overview

Package empire provides the core internal API to Empire. This provides a simple API for performing actions like creating applications, setting environment variables and performing deployments.

Consumers of this API are usually in-process control layers, like the Heroku Platform API compatibility layer, and the GitHub Deployments integration, which can be found under the server package.

Example 
package main

import (
	"fmt"

	"github.com/remind101/empire"
	"github.com/remind101/empire/dbtest"
)

func main() {
	// Open a postgres connection.
	db, _ := empire.OpenDB(*dbtest.DatabaseURL)

	// Migrate the database schema.
	_ = db.MigrateUp()

	// Initialize a new Empire instance.
	e := empire.New(db)

	// Run operations against Empire.
	apps, _ := e.Apps(empire.AppsQuery{})
	fmt.Println(apps)
}

Output:

[]

Index

Examples

Constants

View Source 
const (
	DefaultInstancePortPoolStart = 9000
	DefaultInstancePortPoolEnd   = 10000
)
View Source 
const DBDriver = "postgres"

Empire only supports postgres at the moment.

View Source 
const (
	// GenericProcessName is the process name for `emp run` processes not defined in the procfile.
	GenericProcessName = "run"
)
View Source 
const Procfile = "Procfile"

Procfile is the name of the Procfile file that Empire will use to determine the process formation.

View Source 
const Version = "0.13.0"

The version of Empire.

Variables

View Source 
var (
	Constraints1X = Constraints{constraints.CPUShare(256), constraints.Memory(512 * MB), constraints.Nproc(256)}
	Constraints2X = Constraints{constraints.CPUShare(512), constraints.Memory(1 * GB), constraints.Nproc(512)}
	ConstraintsPX = Constraints{constraints.CPUShare(1024), constraints.Memory(6 * GB), 0}

	// NamedConstraints maps a heroku dynos size to a Constraints.
	NamedConstraints = map[string]Constraints{
		"1X": Constraints1X,
		"2X": Constraints2X,
		"PX": ConstraintsPX,
	}

	// DefaultConstraints defaults to 1X process size.
	DefaultConstraints = Constraints1X
)
View Source 
var (
	ErrDomainInUse        = errors.New("Domain currently in use by another app.")
	ErrDomainAlreadyAdded = errors.New("Domain already added to this app.")
	ErrDomainNotFound     = errors.New("Domain could not be found.")
	ErrUserName           = errors.New("Name is required")
	ErrNoReleases         = errors.New("no releases")
	// ErrInvalidName is used to indicate that the app name is not valid.
	ErrInvalidName = &ValidationError{
		errors.New("An app name must be alphanumeric and dashes only, 3-30 chars in length."),
	}
)

Various errors that may be returned.

View Source 
var DefaultQuantities = map[string]int{
	"web": 1,
}

DefaultQuantities maps a process type to the default number of instances to run.

View Source 
var DefaultSchema = &Schema{
	InstancePortPool: &InstancePortPool{
		Start: DefaultInstancePortPoolStart,
		End:   DefaultInstancePortPoolEnd,
	},
}

DefaultSchema is the default Schema that will be used to migrate the database if none is provided.

View Source 
var NamePattern = regexp.MustCompile(`^[a-z][a-z0-9-]{2,30}$`)

NamePattern is a regex pattern that app names must conform to.

View Source 
var NullEventStream = EventStreamFunc(func(event Event) error {
	return nil
})

NullEventStream an events service that does nothing.

Functions

This section is empty.

Types

type AllowedCommands added in v0.11.0 

type AllowedCommands int

AllowedCommands specifies what commands are allowed to be Run with Empire. 

const (
	// AllowCommandAny will allow any command to be run.
	AllowCommandAny AllowedCommands = iota
	// AllowCommandProcfile will only allow commands specified in the
	// Procfile (the key itself) to be run. Any other command will return an
	// error.
	AllowCommandProcfile
)

type App 

type App struct {
	// A unique uuid that identifies the application.
	ID string

	// The name of the application.
	Name string

	// If provided, the Docker repo that this application is linked to.
	// Deployments to Empire, which don't specify an application, will use
	// this field to determine what app an image should be deployed to.
	Repo *string

	// Valid values are exposePrivate and exposePublic.
	Exposure string

	// Maps a process name to an SSL certificate to use for the SSL listener
	// of the load balancer.
	Certs Certs

	// The time that this application was created.
	CreatedAt *time.Time

	// Maintenance defines whether the app is in maintenance mode or not.
	Maintenance bool
}

App represents an Empire application.

func (*App) BeforeCreate 

func (a *App) BeforeCreate() error

func (*App) IsValid 

func (a *App) IsValid() error

IsValid returns an error if the app isn't valid.

type AppEvent added in v0.10.1 

type AppEvent interface {
	Event
	GetApp() *App
}

AppEvent is an Event that relates to a specific App.

type AppsQuery 

type AppsQuery struct {
	// If provided, an App ID to find.
	ID *string

	// If provided, finds apps matching the given name.
	Name *string

	// If provided, finds apps with the given repo attached.
	Repo *string
}

AppsQuery is a scope implementation for common things to filter releases by.

type Certs added in v0.12.0 

type Certs map[string]string

Certs maps a process name to a certificate to use for any SSL listeners.

func (*Certs) Scan added in v0.12.0 

func (c *Certs) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Certs) Value added in v0.12.0 

func (c Certs) Value() (driver.Value, error)

Value implements the driver.Value interface.

type CertsAttachOpts added in v0.12.0 

type CertsAttachOpts struct {
	// The certificate to attach.
	Cert string
	// The app to attach the cert to.
	App *App

	// An optional process to attach the cert to. If not provided, "web"
	// will be used.
	Process string
}

type Command 

type Command []string

Command represents a command and it's arguments. For example:

Example 
cmd := Command{"/bin/ls", "-h"}
fmt.Println(cmd)

Output:

func MustParseCommand added in v0.10.1 

func MustParseCommand(command string) Command

MustParseCommand parses the string into a Command, panicing if there's an error. This method should only be used in tests for convenience.

func ParseCommand added in v0.10.1 

func ParseCommand(command string) (Command, error)

ParseCommand parses a string into a Command, taking quotes and other shell words into account. For example:

Example 
cmd1, _ := ParseCommand(`/bin/ls -h`)
cmd2, _ := ParseCommand(`/bin/echo 'hello world'`)
fmt.Printf("%#v\n", cmd1)
fmt.Printf("%#v\n", cmd2)

Output:

empire.Command{"/bin/ls", "-h"}
empire.Command{"/bin/echo", "hello world"}

func (*Command) Scan 

func (c *Command) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Command) String added in v0.10.1 

func (c Command) String() string

String returns the string reprsentation of the command.

func (Command) Value 

func (c Command) Value() (driver.Value, error)

Value implements the driver.Value interface.

type CommandNotAllowedError added in v0.11.0 

type CommandNotAllowedError struct {
	Command Command
}

An error that is returned when a command is not whitelisted to be Run.

func (*CommandNotAllowedError) Error added in v0.11.0 

func (c *CommandNotAllowedError) Error() string

Error implements the error interface.

type Config 

type Config struct {
	// A unique uuid representing this Config.
	ID string

	// The environment variables in this config.
	Vars Vars

	// The id of the app that this config relates to.
	AppID string

	// The app that this config relates to.
	App *App
}

Config represents a collection of environment variables.

type ConfigsQuery 

type ConfigsQuery struct {
	// If provided, returns finds the config with the given id.
	ID *string

	// If provided, filters configs for the given app.
	App *App
}

ConfigsQuery is a scope implementation for common things to filter releases by.

type Constraints 

type Constraints constraints.Constraints

Constraints aliases the constraints.Constraints type to implement the json.Unmarshaller interface.

func (Constraints) String 

func (c Constraints) String() string

func (*Constraints) UnmarshalJSON 

func (c *Constraints) UnmarshalJSON(b []byte) error

type CreateEvent added in v0.10.0 

type CreateEvent struct {
	User    string
	Name    string
	Message string
}

CreateEvent is triggered when a user creates a new application.

func (CreateEvent) Event added in v0.10.0 

func (e CreateEvent) Event() string

func (CreateEvent) String added in v0.10.0 

func (e CreateEvent) String() string

type CreateOpts added in v0.10.0 

type CreateOpts struct {
	// User performing the action.
	User *User

	// Name of the application.
	Name string

	// Commit message
	Message string
}

CreateOpts are options that are provided when creating a new application.

func (CreateOpts) Event added in v0.10.0 

func (opts CreateOpts) Event() CreateEvent

func (CreateOpts) Validate added in v0.10.1 

func (opts CreateOpts) Validate(e *Empire) error

type DB added in v0.10.0 

type DB struct {
	// Schema is the Schema instance that will be used to migrate the
	// database to the latest schema. The zero value is DefaultSchema.
	Schema *Schema

	*gorm.DB
	// contains filtered or unexported fields
}

DB wraps a gorm.DB and provides the datastore layer for Empire.

func NewDB added in v0.13.0 

func NewDB(conn *sql.DB) (*DB, error)

NewDB wraps a sql.DB instance as a DB.

func OpenDB added in v0.10.0 

func OpenDB(uri string) (*DB, error)

OpenDB returns a new gorm.DB instance.

func (*DB) CheckSchemaVersion added in v0.11.0 

func (db *DB) CheckSchemaVersion() error

CheckSchemaVersion verifies that the actual database schema matches the version that this version of Empire expects.

func (*DB) Debug added in v0.10.0 

func (db *DB) Debug()

Debug puts the db in debug mode, which logs all queries.

func (*DB) IsHealthy added in v0.10.0 

func (db *DB) IsHealthy() error

IsHealthy checks that we can connect to the database.

func (*DB) MigrateUp added in v0.10.0 

func (db *DB) MigrateUp() error

MigrateUp migrates the database to the latest version of the schema.

func (*DB) Reset added in v0.10.0 

func (db *DB) Reset() error

Reset resets the database to a pristine state.

func (*DB) SchemaVersion added in v0.11.0 

func (db *DB) SchemaVersion() (int, error)

SchemaVersion returns the current schema version.

type DeployEvent added in v0.10.0 

type DeployEvent struct {
	User        string
	App         string
	Image       string
	Environment string
	Release     int
	Message     string
	// contains filtered or unexported fields
}

DeployEvent is triggered when a user deploys a new image to an app.

func (DeployEvent) Event added in v0.10.0 

func (e DeployEvent) Event() string

func (DeployEvent) GetApp added in v0.10.1 

func (e DeployEvent) GetApp() *App

func (DeployEvent) String added in v0.10.0 

func (e DeployEvent) String() string

type DeployOpts added in v0.11.0 

type DeployOpts struct {
	// User the user that is triggering the deployment.
	User *User

	// App is the app that is being deployed to.
	App *App

	// Image is the image that's being deployed.
	Image image.Image

	// Environment is the environment where the image is being deployed
	Environment string

	// Output is a DeploymentStream where deployment output and events will
	// be streamed in jsonmessage format.
	Output *DeploymentStream

	// Commit message
	Message string

	// Stream boolean for whether or not a status stream should be created.
	Stream bool
}

DeployOpts represents options that can be passed when deploying to an application.

func (DeployOpts) Event added in v0.11.0 

func (opts DeployOpts) Event() DeployEvent

func (DeployOpts) Validate added in v0.11.0 

func (opts DeployOpts) Validate(e *Empire) error

type DeploymentStream added in v0.11.0 

type DeploymentStream struct {
	*jsonmessage.Stream
}

DeploymentStream provides a wrapper around an io.Writer for writing jsonmessage statuses, and implements the scheduler.StatusStream interface.

func NewDeploymentStream added in v0.11.0 

func NewDeploymentStream(w io.Writer) *DeploymentStream

NewDeploymentStream wraps the io.Writer as a DeploymentStream.

func (*DeploymentStream) Error added in v0.11.0 

func (w *DeploymentStream) Error(err error) error

Error writes the error to the jsonmessage stream. The error that is provided is also returned, so that Error() can be used in return values.

func (*DeploymentStream) Publish added in v0.11.0 

func (w *DeploymentStream) Publish(status twelvefactor.Status) error

Publish implements the scheduler.StatusStream interface.

func (*DeploymentStream) Status added in v0.11.0 

func (w *DeploymentStream) Status(message string) error

Status writes a simple status update to the jsonmessage stream.

type DestroyEvent added in v0.10.0 

type DestroyEvent struct {
	User    string
	App     string
	Message string
}

DestroyEvent is triggered when a user destroys an application.

func (DestroyEvent) Event added in v0.10.0 

func (e DestroyEvent) Event() string

func (DestroyEvent) String added in v0.10.0 

func (e DestroyEvent) String() string

type DestroyOpts added in v0.10.0 

type DestroyOpts struct {
	// User performing the action.
	User *User

	// The associated app.
	App *App

	// Commit message
	Message string
}

DestroyOpts are options provided when destroying an application.

func (DestroyOpts) Event added in v0.10.0 

func (opts DestroyOpts) Event() DestroyEvent

func (DestroyOpts) Validate added in v0.10.1 

func (opts DestroyOpts) Validate(e *Empire) error

type Domain 

type Domain struct {
	ID        string
	Hostname  string
	CreatedAt *time.Time

	AppID string
	App   *App
}

func (*Domain) BeforeCreate 

func (d *Domain) BeforeCreate() error

type DomainsQuery 

type DomainsQuery struct {
	// If provided, finds domains matching the given hostname.
	Hostname *string

	// If provided, filters domains belonging to the given app.
	App *App
}

DomainsQuery is a scope implementation for common things to filter releases by.

type Empire 

type Empire struct {
	DB *DB

	// Scheduler is the backend scheduler used to run applications.
	Scheduler Scheduler

	// LogsStreamer is the backend used to stream application logs.
	LogsStreamer LogsStreamer

	// ImageRegistry is used to interract with container images.
	ImageRegistry ImageRegistry

	// Environment represents the environment this Empire server is responsible for
	Environment string

	// EventStream service for publishing Empire events.
	EventStream

	// RunRecorder is used to record the logs from interactive runs.
	RunRecorder RunRecorder

	// MessagesRequired is a boolean used to determine if messages should be required for events.
	MessagesRequired bool

	// Configures what type of commands are allowed to be run with the Run
	// method. The zero value allows all commands to be run.
	AllowedCommands AllowedCommands
	// contains filtered or unexported fields
}

Empire provides the core public API for Empire. Refer to the package documentation for details.

func New 

func New(db *DB) *Empire

New returns a new Empire instance.

func (*Empire) Apps 

func (e *Empire) Apps(q AppsQuery) ([]*App, error)

Apps returns all Apps.

func (*Empire) AppsFind added in v0.10.0 

func (e *Empire) AppsFind(q AppsQuery) (*App, error)

AppsFind finds the first app matching the query.

func (*Empire) CertsAttach added in v0.10.0 

func (e *Empire) CertsAttach(ctx context.Context, opts CertsAttachOpts) error

CertsAttach attaches an SSL certificate to the app.

func (*Empire) Config added in v0.10.0 

func (e *Empire) Config(app *App) (*Config, error)

Config returns the current Config for a given app.

func (*Empire) Create added in v0.10.0 

func (e *Empire) Create(ctx context.Context, opts CreateOpts) (*App, error)

Create creates a new app.

func (*Empire) Deploy 

func (e *Empire) Deploy(ctx context.Context, opts DeployOpts) (*Release, error)

Deploy deploys an image and streams the output to w.

func (*Empire) Destroy added in v0.10.0 

func (e *Empire) Destroy(ctx context.Context, opts DestroyOpts) error

Destroy destroys an app.

func (*Empire) Domains 

func (e *Empire) Domains(q DomainsQuery) ([]*Domain, error)

Domains returns all domains matching the query.

func (*Empire) DomainsCreate 

func (e *Empire) DomainsCreate(ctx context.Context, domain *Domain) (*Domain, error)

DomainsCreate adds a new Domain for an App.

func (*Empire) DomainsDestroy 

func (e *Empire) DomainsDestroy(ctx context.Context, domain *Domain) error

DomainsDestroy removes a Domain for an App.

func (*Empire) DomainsFind added in v0.10.0 

func (e *Empire) DomainsFind(q DomainsQuery) (*Domain, error)

DomainsFind returns the first domain matching the query.

func (*Empire) IsHealthy 

func (e *Empire) IsHealthy() error

IsHealthy returns true if Empire is healthy, which means it can connect to the services it depends on.

func (*Empire) ListScale added in v0.10.1 

func (e *Empire) ListScale(ctx context.Context, app *App) (Formation, error)

ListScale lists the current scale settings for a given App

func (*Empire) Releases 

func (e *Empire) Releases(q ReleasesQuery) ([]*Release, error)

Releases returns all Releases for a given App.

func (*Empire) ReleasesFind added in v0.10.0 

func (e *Empire) ReleasesFind(q ReleasesQuery) (*Release, error)

ReleasesFind returns the first releases for a given App.

func (*Empire) Reset 

func (e *Empire) Reset() error

Reset resets empire.

func (*Empire) Restart added in v0.10.0 

func (e *Empire) Restart(ctx context.Context, opts RestartOpts) error

Restart restarts processes matching the given prefix for the given Release. If the prefix is empty, it will match all processes for the release.

func (*Empire) Rollback added in v0.10.0 

func (e *Empire) Rollback(ctx context.Context, opts RollbackOpts) (*Release, error)

Rollback rolls an app back to a specific release version. Returns a new release.

func (*Empire) Run added in v0.10.0 

func (e *Empire) Run(ctx context.Context, opts RunOpts) error

Run runs a one-off process for a given App and command.

func (*Empire) Scale added in v0.10.0 

func (e *Empire) Scale(ctx context.Context, opts ScaleOpts) ([]*Process, error)

Scale scales an apps processes.

func (*Empire) Set added in v0.10.0 

func (e *Empire) Set(ctx context.Context, opts SetOpts) (*Config, error)

Set applies the new config vars to the apps current Config, returning the new Config. If the app has a running release, a new release will be created and run.

func (*Empire) SetMaintenanceMode added in v0.13.0 

func (e *Empire) SetMaintenanceMode(ctx context.Context, opts SetMaintenanceModeOpts) error

SetMaintenanceMode enables or disables "maintenance mode" on the app. When an app is in maintenance mode, all processes will be scaled down to 0. When taken out of maintenance mode, all processes will be scaled up back to their existing values.

func (*Empire) StreamLogs added in v0.9.2 

func (e *Empire) StreamLogs(app *App, w io.Writer, duration time.Duration) error

Streamlogs streams logs from an app.

func (*Empire) Tasks added in v0.10.0 

func (e *Empire) Tasks(ctx context.Context, app *App) ([]*Task, error)

Tasks returns the Tasks for the given app.

type Event added in v0.10.0 

type Event interface {
	// Returns the name of the event.
	Event() string

	// Returns a human readable string about the event.
	String() string
}

Event represents an event triggered within Empire.

type EventStream added in v0.10.0 

type EventStream interface {
	PublishEvent(Event) error
}

EventStream is an interface for publishing events that happen within Empire.

func AsyncEvents added in v0.10.0 

func AsyncEvents(e EventStream) EventStream

AsyncEvents returns a new AsyncEventStream that will buffer upto 100 events before applying backpressure.

type EventStreamFunc added in v0.10.0 

type EventStreamFunc func(Event) error

EventStreamFunc is a function that implements the Events interface.

func (EventStreamFunc) PublishEvent added in v0.10.0 

func (fn EventStreamFunc) PublishEvent(event Event) error

type FakeScheduler added in v0.13.0 

type FakeScheduler struct {
	sync.Mutex
	// contains filtered or unexported fields
}

func NewFakeScheduler added in v0.13.0 

func NewFakeScheduler() *FakeScheduler

func (*FakeScheduler) Remove added in v0.13.0 

func (m *FakeScheduler) Remove(ctx context.Context, appID string) error

func (*FakeScheduler) Restart added in v0.13.0 

func (m *FakeScheduler) Restart(ctx context.Context, appID string, ss twelvefactor.StatusStream) error

func (*FakeScheduler) Run added in v0.13.0 

func (m *FakeScheduler) Run(ctx context.Context, app *twelvefactor.Manifest) error

func (*FakeScheduler) Stop added in v0.13.0 

func (m *FakeScheduler) Stop(ctx context.Context, instanceID string) error

func (*FakeScheduler) Submit added in v0.13.0 

func (m *FakeScheduler) Submit(ctx context.Context, app *twelvefactor.Manifest, ss twelvefactor.StatusStream) error

func (*FakeScheduler) Tasks added in v0.13.0 

func (m *FakeScheduler) Tasks(ctx context.Context, appID string) ([]*twelvefactor.Task, error)

type Formation 

type Formation map[string]Process

Formation represents a collection of named processes and their configuration.

func (Formation) IsValid added in v0.11.0 

func (f Formation) IsValid() error

IsValid returns nil if all of the Processes are valid.

func (Formation) Merge added in v0.10.1 

func (f Formation) Merge(other Formation) Formation

Merge merges in the existing quantity and constraints from the old Formation into this Formation.

func (*Formation) Scan added in v0.10.1 

func (f *Formation) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Formation) Value added in v0.10.1 

func (f Formation) Value() (driver.Value, error)

Value implements the driver.Value interface.

type Host added in v0.12.0 

type Host struct {
	// the host id
	ID string
}

Host represents the host of the task

type ImageRegistry added in v0.13.0 

type ImageRegistry interface {
	ProcfileExtractor

	// Resolve should resolve an image to an "immutable" reference of the
	// image.
	Resolve(context.Context, image.Image, *jsonmessage.Stream) (image.Image, error)
}

ImageRegistry represents something that can interact with container images.

type IncompatibleSchemaError added in v0.11.0 

type IncompatibleSchemaError struct {
	SchemaVersion         int
	ExpectedSchemaVersion int
}

IncompatibleSchemaError is an error that gets returned from CheckSchemaVersion.

func (*IncompatibleSchemaError) Error added in v0.11.0 

func (e *IncompatibleSchemaError) Error() string

Error implements the error interface.

type InstancePortPool added in v0.13.0 

type InstancePortPool struct {
	Start, End uint
}

type LogsStreamer added in v0.9.2 

type LogsStreamer interface {
	StreamLogs(*App, io.Writer, time.Duration) error
}

type MaintenanceEvent added in v0.13.0 

type MaintenanceEvent struct {
	User        string
	App         string
	Maintenance bool
	Message     string
	// contains filtered or unexported fields
}

func (MaintenanceEvent) Event added in v0.13.0 

func (e MaintenanceEvent) Event() string

func (MaintenanceEvent) GetApp added in v0.13.0 

func (e MaintenanceEvent) GetApp() *App

func (MaintenanceEvent) String added in v0.13.0 

func (e MaintenanceEvent) String() string

type MessageRequiredError added in v0.10.1 

type MessageRequiredError struct{}

MessageRequiredError is an error implementation, which is returned by Empire when a commit message is required for the operation.

func (*MessageRequiredError) Error added in v0.10.1 

func (e *MessageRequiredError) Error() string

type MultiEventStream added in v0.10.1 

type MultiEventStream []EventStream

MultiEventStream is an EventStream implementation that publishes the event to multiple EventStreams, returning any errors after publishing to all streams.

func (MultiEventStream) PublishEvent added in v0.10.1 

func (streams MultiEventStream) PublishEvent(e Event) error

type NoCertError added in v0.12.0 

type NoCertError struct {
	Process string
}

NoCertError is returned when the Procfile specifies an https/ssl listener but there is no attached certificate.

func (*NoCertError) Error added in v0.12.0 

func (e *NoCertError) Error() string

type Port 

type Port struct {
	Host      int    `json:"Host"`
	Container int    `json:"Container"`
	Protocol  string `json:"Protocol"`
}

type Process 

type Process struct {
	// Command is the command to run.
	Command Command `json:"Command,omitempty"`

	// Signifies that this is a named one off command and not a long lived
	// service.
	NoService bool `json:"Run,omitempty"`

	// Quantity is the desired number of instances of this process.
	Quantity int `json:"Quantity,omitempty"`

	// The memory constraints, in bytes.
	Memory constraints.Memory `json:"Memory,omitempty"`

	// The amount of CPU share to give.
	CPUShare constraints.CPUShare `json:"CPUShare,omitempty"`

	// The allow number of unix processes within the container.
	Nproc constraints.Nproc `json:"Nproc,omitempty"`

	// A cron expression. If provided, the process will be run as a
	// scheduled task.
	Cron *string `json:"cron,omitempty"`

	// Port mappings from container to load balancer.
	Ports []Port `json:"Ports,omitempty"`

	// An process specific environment variables.
	Environment map[string]string `json:"Environment,omitempty"`

	// ECS specific parameters.
	ECS *procfile.ECS `json:"ECS,omitempty"`
}

Process holds configuration information about a Process.

func (*Process) Constraints added in v0.10.1 

func (p *Process) Constraints() Constraints

Constraints returns a constraints.Constraints from this Process definition.

func (*Process) IsValid added in v0.11.0 

func (p *Process) IsValid() error

IsValid returns nil if the Process is valid.

func (*Process) SetConstraints added in v0.10.1 

func (p *Process) SetConstraints(c Constraints)

SetConstraints sets the memory/cpu/nproc for this Process to the given constraints.

type ProcessUpdate added in v0.11.0 

type ProcessUpdate struct {
	// The process to scale.
	Process string

	// The desired quantity of processes.
	Quantity int

	// If provided, new memory and CPU constraints for the process.
	Constraints *Constraints
}

type ProcfileError 

type ProcfileError struct {
	Err error
}

Example instance: Procfile doesn't exist

func (*ProcfileError) Error 

func (e *ProcfileError) Error() string

type ProcfileExtractor added in v0.10.0 

type ProcfileExtractor interface {
	// ExtractProcfile should return extracted a Procfile from an image, returning
	// it's YAML representation.
	ExtractProcfile(context.Context, image.Image, *jsonmessage.Stream) ([]byte, error)
}

ProcfileExtractor represents something that can extract a Procfile from an image.

type ProcfileExtractorFunc added in v0.10.1 

type ProcfileExtractorFunc func(context.Context, image.Image, *jsonmessage.Stream) ([]byte, error)

ProcfileExtractorFunc implements the ProcfileExtractor interface.

func (ProcfileExtractorFunc) ExtractProcfile added in v0.13.0 

func (fn ProcfileExtractorFunc) ExtractProcfile(ctx context.Context, image image.Image, w *jsonmessage.Stream) ([]byte, error)

type Release 

type Release struct {
	// A unique uuid to identify this release.
	ID string

	// An auto incremented ID for this release, scoped to the application.
	Version int

	// The id of the application that this release relates to.
	AppID string

	// The application that this release relates to.
	App *App

	// The id of the config that this release uses.
	ConfigID string

	// The config that this release uses.
	Config *Config

	// The id of the slug that this release uses.
	SlugID string

	// The Slug that this release uses.
	Slug *Slug

	// The process formation to use.
	Formation Formation

	// A description for the release. Usually contains the reason for why
	// the release was created (e.g. deployment, config changes, etc).
	Description string

	// The time that this release was created.
	CreatedAt *time.Time
}

Release is a combination of a Config and a Slug, which form a deployable release. Releases are generally considered immutable, the only operation that changes a release is when altering the Quantity or Constraints inside the Formation.

func (*Release) BeforeCreate 

func (r *Release) BeforeCreate() error

BeforeCreate sets created_at before inserting.

func (*Release) Procfile added in v0.12.0 

func (r *Release) Procfile() (procfile.Procfile, error)

Procfile returns the Procfile that generated this Release.

type ReleasesQuery 

type ReleasesQuery struct {
	// If provided, an app to filter by.
	App *App

	// If provided, a version to filter by.
	Version *int

	// If provided, uses the limit and sorting parameters specified in the range.
	Range headerutil.Range
}

ReleasesQuery is a scope implementation for common things to filter releases by.

func (ReleasesQuery) DefaultRange 

func (q ReleasesQuery) DefaultRange() headerutil.Range

DefaultRange returns the default headerutil.Range used if values aren't provided.

type RestartEvent added in v0.10.0 

type RestartEvent struct {
	User    string
	App     string
	PID     string
	Message string
	// contains filtered or unexported fields
}

RestartEvent is triggered when a user restarts an application.

func (RestartEvent) Event added in v0.10.0 

func (e RestartEvent) Event() string

func (RestartEvent) GetApp added in v0.10.1 

func (e RestartEvent) GetApp() *App

func (RestartEvent) String added in v0.10.0 

func (e RestartEvent) String() string

type RestartOpts added in v0.10.0 

type RestartOpts struct {
	// User performing the action.
	User *User

	// The associated app.
	App *App

	// If provided, a PID that will be killed. Generally used for killing
	// detached processes.
	PID string

	// Commit message
	Message string
}

RestartOpts are options provided when restarting an app.

func (RestartOpts) Event added in v0.10.0 

func (opts RestartOpts) Event() RestartEvent

func (RestartOpts) Validate added in v0.10.1 

func (opts RestartOpts) Validate(e *Empire) error

type RollbackEvent added in v0.10.0 

type RollbackEvent struct {
	User    string
	App     string
	Version int
	Message string
	// contains filtered or unexported fields
}

RollbackEvent is triggered when a user rolls back to an old version.

func (RollbackEvent) Event added in v0.10.0 

func (e RollbackEvent) Event() string

func (RollbackEvent) GetApp added in v0.10.1 

func (e RollbackEvent) GetApp() *App

func (RollbackEvent) String added in v0.10.0 

func (e RollbackEvent) String() string

type RollbackOpts added in v0.10.0 

type RollbackOpts struct {
	// The user performing the action.
	User *User

	// The associated app.
	App *App

	// The release version to rollback to.
	Version int

	// Commit message
	Message string
}

RollbackOpts are options provided when rolling back to an old release.

func (RollbackOpts) Event added in v0.10.0 

func (opts RollbackOpts) Event() RollbackEvent

func (RollbackOpts) Validate added in v0.10.1 

func (opts RollbackOpts) Validate(e *Empire) error

type RunEvent added in v0.10.0 

type RunEvent struct {
	User     string
	App      string
	Command  Command
	URL      string
	Attached bool
	Message  string
	Finished bool
	// contains filtered or unexported fields
}

RunEvent is triggered when a user starts or stops a one off process.

func (RunEvent) Event added in v0.10.0 

func (e RunEvent) Event() string

func (*RunEvent) Finish added in v0.11.0 

func (e *RunEvent) Finish()

func (RunEvent) GetApp added in v0.10.1 

func (e RunEvent) GetApp() *App

func (RunEvent) String added in v0.10.0 

func (e RunEvent) String() string

type RunOpts added in v0.10.0 

type RunOpts struct {
	// User performing this action.
	User *User

	// Related app.
	App *App

	// The command to run.
	Command Command

	// Commit message
	Message string

	// Input/Output streams. The caller is responsible for closing these
	// streams.
	Stdin          io.Reader
	Stdout, Stderr io.Writer

	// Extra environment variables to set.
	Env map[string]string

	// Optional memory/cpu/nproc constraints.
	Constraints *Constraints
}

RunOpts are options provided when running an attached/detached process.

func (RunOpts) Event added in v0.10.0 

func (opts RunOpts) Event() RunEvent

func (RunOpts) Validate added in v0.10.1 

func (opts RunOpts) Validate(e *Empire) error

type RunRecorder added in v0.10.1 

type RunRecorder func() (io.Writer, error)

RunRecorder is a function that returns an io.Writer that will be written to to record Stdout and Stdin of interactive runs.

type ScaleEvent added in v0.10.0 

type ScaleEvent struct {
	User    string
	App     string
	Updates []*ScaleEventUpdate
	Message string
	// contains filtered or unexported fields
}

ScaleEvent is triggered when a manual scaling event happens.

func (ScaleEvent) Event added in v0.10.0 

func (e ScaleEvent) Event() string

func (ScaleEvent) GetApp added in v0.10.1 

func (e ScaleEvent) GetApp() *App

func (ScaleEvent) String added in v0.10.0 

func (e ScaleEvent) String() string

type ScaleEventUpdate added in v0.11.0 

type ScaleEventUpdate struct {
	Process             string
	Quantity            int
	PreviousQuantity    int
	Constraints         Constraints
	PreviousConstraints Constraints
}

type ScaleOpts added in v0.10.0 

type ScaleOpts struct {
	// User that's performing the action.
	User *User

	// The associated app.
	App *App

	Updates []*ProcessUpdate

	// Commit message
	Message string
}

ScaleOpts are options provided when scaling a process.

func (ScaleOpts) Event added in v0.10.0 

func (opts ScaleOpts) Event() ScaleEvent

func (ScaleOpts) Validate added in v0.10.1 

func (opts ScaleOpts) Validate(e *Empire) error

type Scheduler added in v0.13.0 

type Scheduler twelvefactor.Scheduler

type Schema added in v0.13.0 

type Schema struct {
	// For legacy ELB's (not ALB) Empire manages a pool of host ports to
	// ensure that all applications have a unique port on the EC2 instance.
	// This option specifies the beginning and end of that range.
	InstancePortPool *InstancePortPool
}

type SetEvent added in v0.10.0 

type SetEvent struct {
	User    string
	App     string
	Changed []string
	Message string
	// contains filtered or unexported fields
}

SetEvent is triggered when environment variables are changed on an application.

func (SetEvent) Event added in v0.10.0 

func (e SetEvent) Event() string

func (SetEvent) GetApp added in v0.10.1 

func (e SetEvent) GetApp() *App

func (SetEvent) String added in v0.10.0 

func (e SetEvent) String() string

type SetMaintenanceModeOpts added in v0.13.0 

type SetMaintenanceModeOpts struct {
	// User performing the action.
	User *User

	// The associated app.
	App *App

	// Wheather maintenance mode should be enabled or not.
	Maintenance bool

	// Commit message
	Message string
}

func (SetMaintenanceModeOpts) Event added in v0.13.0 

func (opts SetMaintenanceModeOpts) Event() MaintenanceEvent

func (SetMaintenanceModeOpts) Validate added in v0.13.0 

func (opts SetMaintenanceModeOpts) Validate(e *Empire) error

type SetOpts added in v0.10.0 

type SetOpts struct {
	// User performing the action.
	User *User

	// The associated app.
	App *App

	// The new vars to merge into the old config.
	Vars Vars

	// Commit message
	Message string
}

SetOpts are options provided when setting new config vars on an app.

func (SetOpts) Event added in v0.10.0 

func (opts SetOpts) Event() SetEvent

func (SetOpts) Validate added in v0.10.1 

func (opts SetOpts) Validate(e *Empire) error

type Slug 

type Slug struct {
	// A unique uuid that identifies this slug.
	ID string

	// The Docker image that this slug is for.
	Image image.Image

	// The raw Procfile that was extracted from the Docker image.
	Procfile []byte
}

Slug represents a container image with the extracted ProcessType.

func (*Slug) Formation added in v0.10.1 

func (s *Slug) Formation() (Formation, error)

Formation returns a new Formation built from the extracted Procfile.

func (*Slug) ParsedProcfile added in v0.12.0 

func (s *Slug) ParsedProcfile() (procfile.Procfile, error)

ParsedProcfile returns the parsed Procfile.

type Task added in v0.10.0 

type Task struct {
	// The name of the task.
	Name string

	// The name of the process that this task is for.
	Type string

	// The task id
	ID string

	// The host of the task
	Host Host

	// The command that this task is running.
	Command Command

	// The state of the task.
	State string

	// The time that the state was recorded.
	UpdatedAt time.Time

	// The constraints of the Process.
	Constraints Constraints
}

Task represents a running process.

type User 

type User struct {
	// Name is the users username.
	Name string `json:"name"`

	// GitHubToken is a GitHub access token.
	GitHubToken string `json:"-"`
}

User represents a user of Empire.

func (*User) IsValid added in v0.10.1 

func (u *User) IsValid() error

IsValid returns nil if the User is valid.

type ValidationError 

type ValidationError struct {
	Err error
}

ValidationError is returned when a model is not valid.

func (*ValidationError) Error 

func (e *ValidationError) Error() string

type Variable 

type Variable string

Variable represents the name of an environment variable.

type Vars 

type Vars map[Variable]*string

Vars represents a variable -> value mapping.

func (*Vars) Scan 

func (v *Vars) Scan(src interface{}) error

Scan implements the sql.Scanner interface.

func (Vars) Value 

func (v Vars) Value() (driver.Value, error)

Value implements the driver.Value interface.

Source Files

View all Source files

Directories

Path Synopsis
cmd
emp
emp/hkclient
empire
cli
Package cli provides test helpers for testing the emp CLI against an Empire environment.
 Package cli provides test helpers for testing the emp CLI against an Empire environment.
events
app
Package app provides an empire.EventStream implementation that publishs events to the app's kinesis stream if available.
 Package app provides an empire.EventStream implementation that publishs events to the app's kinesis stream if available.
sns
Package sns provides an empire.EventStream implementation that publishes events to SNS.
 Package sns provides an empire.EventStream implementation that publishes events to SNS.
stdout
Package stdout provides an empire.EventStream implementation that publishes events to stdout.
 Package stdout provides an empire.EventStream implementation that publishes events to stdout.
internal
jwt
Package jwt is a Go implementation of JSON Web Tokens: http://self-issued.info/docs/draft-jones-json-web-token.html See README.md for more info.
 Package jwt is a Go implementation of JSON Web Tokens: http://self-issued.info/docs/draft-jones-json-web-token.html See README.md for more info.
jwt/test
migrate
Package migrate provides a dead simple Go package for performing sql migrations using database/sql.
 Package migrate provides a dead simple Go package for performing sql migrations using database/sql.
saml
Package saml contains a partial implementation of the SAML standard in golang.
 Package saml contains a partial implementation of the SAML standard in golang.
saml/testsaml
shellwords
uuid
The uuid package generates and inspects UUIDs.
 The uuid package generates and inspects UUIDs.
pkg
arn
package arn is a Go package for parsing Amazon Resource Names.
 package arn is a Go package for parsing Amazon Resource Names.
base62
Package base62 implements conversion to base62.
 Package base62 implements conversion to base62.
bytesize
package bytesize contains constants for easily switching between different byte sizes.
 package bytesize contains constants for easily switching between different byte sizes.
cloudformation/customresources
Package customresources provides a Go library for building CloudFormation custom resource handlers.
 Package customresources provides a Go library for building CloudFormation custom resource handlers.
constraints
package constraints contains methods for decoding a compact CPU and Memory constraints format.
 package constraints contains methods for decoding a compact CPU and Memory constraints format.
dockerauth
dockerutil
headerutil
heroku
Package heroku is a client interface to the Heroku API.
 Package heroku is a client interface to the Heroku API.
hijack
httpmock
image
Package image contains methods and helpers for parsing the docker image format.
 Package image contains methods and helpers for parsing the docker image format.
jsonmessage
Package jsonmessage is a stripped down version of github.com/docker/docker/pkg/jsonmessage without any transitive dependencies.
 Package jsonmessage is a stripped down version of github.com/docker/docker/pkg/jsonmessage without any transitive dependencies.
pg/lock
stdcopy
stream
Package stream provides types that make it easier to perform streaming.
 Package stream provides types that make it easier to perform streaming.
stream/http
Package http provides streaming implementations of various net/http types.
 Package http provides streaming implementations of various net/http types.
timex
troposphere
Package troposphere is a Go version of the Python package and provides Go primitives for building CloudFormation templates.
 Package troposphere is a Go version of the Python package and provides Go primitives for building CloudFormation templates.
Package procfile provides methods for parsing standard and extended Procfiles.
 Package procfile provides methods for parsing standard and extended Procfiles.
internal/yaml
Package yaml implements YAML support for the Go language.
 Package yaml implements YAML support for the Go language.
scheduler
cloudformation
Package cloudformation implements the Scheduler interface for ECS by using CloudFormation to provision and update resources.
 Package cloudformation implements the Scheduler interface for ECS by using CloudFormation to provision and update resources.
docker
Package docker implements the Scheduler interface backed by the Docker API.
 Package docker implements the Scheduler interface backed by the Docker API.
kubernetes
Package kubernetes implements the Scheduler interface backed by Kubernetes.
 Package kubernetes implements the Scheduler interface backed by Kubernetes.
Package server provides an http.Handler implementation that includes the Heroku Platform API compatibility layer, GitHub Deployments integration and a simple health check.
 Package server provides an http.Handler implementation that includes the Heroku Platform API compatibility layer, GitHub Deployments integration and a simple health check.
auth
Package auth contains types for authenticating and authorizing requests.
 Package auth contains types for authenticating and authorizing requests.
auth/github
Package github provides auth.Authentication and auth.Authorizer implementations backed by GitHub users, orgs and teams.
 Package github provides auth.Authentication and auth.Authorizer implementations backed by GitHub users, orgs and teams.
auth/saml
cloudformation
Package cloudformation provides a server for the CloudFormation interface to Empire.
 Package cloudformation provides a server for the CloudFormation interface to Empire.
github
Package github provides an http.Handler implementation that allows Empire to handle GitHub Deployments.
 Package github provides an http.Handler implementation that allows Empire to handle GitHub Deployments.
heroku
Package heroku provides a Heroku Platform API compatible http.Handler implementation for Empire.
 Package heroku provides a Heroku Platform API compatible http.Handler implementation for Empire.
middleware
Package stats provides an interface for instrumenting Empire.
 Package stats provides an interface for instrumenting Empire.
Package scheduler provides the core interface that Empire uses when interacting with a cluster of machines to run tasks.
 Package scheduler provides the core interface that Empire uses when interacting with a cluster of machines to run tasks.

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.