empire

package module
v0.11.0 Latest Latest
Warning

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

 Go to latest Published: Aug 23, 2016 License: BSD-2-Clause Imports: 37 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:latest
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, and deploying that. We have a tool for performing deployments called Tugboat that supports deploying Docker images to Empire.

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.

Caveats

Because docker run does not exec commands within a shell, commands specified within the Procfile will also not be exec'd within a shell. This means that you cannot specify environment variables in the Procfile. The following is not valid:

web: acme-inc server -port=$PORT

If you need to specify environment variables as part of the command, we recommend splitting out your Procfile commands into small bash shims instead:

web: ./bin/web

#!/bin/bash

set -e

exec acme-inc server -port=$PORT

Tests

Unit tests live alongside each go file as _test.go.

There is also a tests directory that contains integration and functional tests that tests the system using the heroku-go client and the emp command.

To get started, run:

$ export GO15VENDOREXPERIMENT=1
$ make bootstrap

The bootstrap command assumes you have a running postgres server. It will create a database called empire using the postgres client connection defaults.

To run the tests:

$ make test

Development

If you want to contribute to Empire, you may end up wanting to run a local instance against an ECS cluster. Doing this is relatively easy:

  1. Ensure that you have the AWS CLI installed and configured.

  2. Ensure that you accepted the terms and conditions for the official ECS AMI:

    https://aws.amazon.com/marketplace/ordering?productId=4ce33fd9-63ff-4f35-8d3a-939b641f1931&ref_=dtl_psb_continue&region=us-east-1

    Also check that the offical ECS AMI ID for US East matches with the one in cloudformation.json: https://github.com/remind101/empire/blob/master/docs/cloudformation.json#L20

  3. Run docker-machine and export the environment variables so Empire can connect:

    $ docker-machine start default
$ eval "$(docker-machine env default)"

  4. Run the bootstrap script, which will create a cloudformation stack, ecs cluster and populate a .env file:

    $ ./bin/bootstrap

  5. Run Empire with docker-compose:

    $ docker-compose up db # Only need to do this the first time, so that the db can initialize.
$ docker-compose up

    NOTE: You might need to run this twice the first time you start it up, to give the postgres container time to initialize.

  6. Install the emp CLI.

Empire will be available at http://$(docker-machine ip default):8080 and you can point the CLI there.

$ export EMPIRE_API_URL=http://$(docker-machine ip default):8080
$ emp deploy remind101/acme-inc
Vendoring

Empire follows Go's convention of vendoring third party dependencies. We use the Go 1.5+ vendor expirement, and manage the ./vendor/ directory via govendor.

When you add a new dependency, be sure to vendor it with govendor:

$ govendor add <package>
Releasing

Perform the following steps when releasing a new version:

  1. Create a new branch release-VERSION.
  2. Bump the version number with make bump (this will add a commit to the branch).
  3. Change HEAD -> VERSION in CHANGELOG.md.
  4. Open a PR to review.
  5. Once merged into master, wait for the Conveyor build to complete.
  6. Finally, tag the commit with the version as v<VERSION>. This will trigger CircleCI to:
    • Tag the image in Docker Hub with the version.
    • Build Linux and OS X versions of the CLI and Daemon.
    • Create a new GitHub Release and upload the artifacts.
  7. Update the new GitHub Release to be human readable.
  8. Open a PR against Homebrew to update the emp CLI: https://github.com/Homebrew/homebrew-core/blob/master/Formula/emp.rb

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"
)

func main() {
	// Open a postgres connection.
	db, _ := empire.OpenDB("postgres://localhost/empire?sslmode=disable")

	// 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 Procfile = "Procfile"

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

View Source 
const Version = "0.11.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 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 AccessToken 

type AccessToken struct {
	// The encoded token.
	Token string

	// The user that this AccessToken belongs to.
	User *User
}

AccessToken represents a token that allow access to the api.

func (*AccessToken) IsValid added in v0.10.1 

func (t *AccessToken) IsValid() error

IsValid returns nil if the AccessToken is valid.

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

	// The name of an SSL cert for the web process of this app.
	Cert string

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

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 Command 

type Command []string

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

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

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 {
	*gorm.DB
	// contains filtered or unexported fields
}

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

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 {
	// contains filtered or unexported fields
}

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 scheduler.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.

func (*DeploymentStream) Write added in v0.11.0 

func (w *DeploymentStream) Write(b []byte) (int, error)

Write implements the io.Writer interface. This allows things like the Docker daemon to write directly to the io.Writer, since it already writes in jsonmessage format.

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

	// Secret is used to sign JWT access tokens.
	Secret []byte

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

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

	// ProcfileExtractor is called during deployments to extract the
	// Formation from the Procfile in the newly deployed image.
	ProcfileExtractor ProcfileExtractor

	// 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) AccessTokensCreate 

func (e *Empire) AccessTokensCreate(accessToken *AccessToken) (*AccessToken, error)

AccessTokensCreate creates a new AccessToken.

func (*Empire) AccessTokensFind 

func (e *Empire) AccessTokensFind(token string) (*AccessToken, error)

AccessTokensFind finds an access token.

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, app *App, cert string) 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) 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 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 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 KinesisLogsStreamer added in v0.10.0 

type KinesisLogsStreamer struct{}

func NewKinesisLogsStreamer added in v0.10.0 

func NewKinesisLogsStreamer() *KinesisLogsStreamer

func (*KinesisLogsStreamer) StreamLogs added in v0.10.0 

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

type LogsStreamer added in v0.9.2 

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

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 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"`
}

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 ProcfileExtractor added in v0.10.0 

type ProcfileExtractor interface {
	Extract(context.Context, image.Image, io.Writer) ([]byte, error)
}

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

func PullAndExtract added in v0.10.0 

func PullAndExtract(c *dockerutil.Client) ProcfileExtractor

PullAndExtract returns a ProcfileExtractor that will pull the image using the docker client, then attempt to extract the the Procfile, or fallback to the CMD directive in the Dockerfile.

type ProcfileExtractorFunc added in v0.10.1 

type ProcfileExtractorFunc func(context.Context, image.Image, io.Writer) ([]byte, error)

func (ProcfileExtractorFunc) Extract added in v0.10.1 

func (fn ProcfileExtractorFunc) Extract(ctx context.Context, image image.Image, w io.Writer) ([]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.

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

	// If provided, input will be read from this.
	Input io.Reader

	// If provided, output will be written to this.
	Output 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.

func RecordTo added in v0.10.1 

func RecordTo(w io.Writer) RunRecorder

RecordTo returns a RunRecorder that writes the log record to the io.Writer

func RecordToCloudWatch added in v0.10.1 

func RecordToCloudWatch(group string, config client.ConfigProvider) RunRecorder

RecordToCloudWatch returns a RunRecorder that writes the log record to CloudWatch Logs.

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

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 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 command
emp/hkclient
empire command
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.
pkg
arn
package arn is a Go package for parsing Amazon Resource Names.
 package arn is a Go package for parsing Amazon Resource Names.
awsutil
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
ecsutil
Package ecsutil is a layer on top of Amazon ECS to provide an app aware ECS client.
 Package ecsutil is a layer on top of Amazon ECS to provide an app aware ECS client.
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.
pg/lock
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.
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.
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.
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.
ecs
Pacakge ecs provides an implementation of the Scheduler interface that uses Amazon EC2 Container Service.
 Pacakge ecs provides an implementation of the Scheduler interface that uses Amazon EC2 Container Service.
ecs/lb
package lb provides an abstraction around creating load balancers.
 package lb provides an abstraction around creating load balancers.
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.
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.

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.