empire

package module
v0.0.0-...-30eb747 Latest Latest
Warning

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

 Go to latest Published: Mar 16, 2021 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.

Auth Flow

The current authentication model used by emp login relies on a deprecated GitHub endpoint that is scheduled to be deactivated in November 2020. Therefore both the client and the server need to be updated to support the web authentication flow

The web flow works like this

  1. The user runs a command like emp web-login
  2. The client starts up a HTTP listener on a free local port
  3. The client opens a browser window on the local machine to $EMPIRE_API_URL/oauth/start?port=?????
    • The port parameter specifies where the client is listening
  4. The browser executes a GET against the URL
  5. The Empire server sees the request and constructs an OAuth request URL that will hit the GitHub OAuth endpoint and returns it as a redirect
  6. The browser makes the request to the GitHub auth endpoint, which shows the UI a request to authorize the application
    • If they've previously authorized it will just immediately grant the request
  7. GitHub redirects the browser back to the redirect URL specified in the configuration, meaning back to the Empire server
  8. The Empire server receives the browser request and can now perform the code exchange to turn the provided code into an actual authentication token
    • This is just like it would have received from the old endpoint. However, it's not usable yet because it still isn't in the possession of the client, only the browser
  9. The Empire server now redirects the browser back to localhost on the original port provided by the client
  10. The client receives the token, but can't use it directly. The Empire server expects it to be wrapped in a JSON Web Token that only the server can create.
  11. The client can now make a request directly to the Empire server (its first in this sequence) providing the token and requesting a JSON Web Token in response
  12. The client stores the received token just as it would have with the response to an emp login command
  13. The client is authenticated

In theory the Empire server could construct the JWT directly after the code exchange and push that directly to the client, but the abstraction doesn't really seem to easily support that flow

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 

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

	// If this is non-nil, the app was deleted at this time.
	DeletedAt *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 

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 

type Certs map[string]string

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

func (*Certs) Scan 

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

Scan implements the sql.Scanner interface.

func (Certs) Value 

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

Value implements the driver.Value interface.

type CertsAttachOpts 

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)

func MustParseCommand 

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 

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 

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 

type CommandNotAllowedError struct {
	Command Command
}

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

func (*CommandNotAllowedError) Error 

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 

type CreateEvent struct {
	User    string
	Name    string
	Message string
}

CreateEvent is triggered when a user creates a new application.

func (CreateEvent) Event 

func (e CreateEvent) Event() string

func (CreateEvent) String 

func (e CreateEvent) String() string

type CreateOpts 

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 

func (opts CreateOpts) Event() CreateEvent

func (CreateOpts) Validate 

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

type DB 

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 

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

NewDB wraps a sql.DB instance as a DB.

func OpenDB 

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

OpenDB returns a new gorm.DB instance.

func (*DB) CheckSchemaVersion 

func (db *DB) CheckSchemaVersion() error

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

func (*DB) Debug 

func (db *DB) Debug()

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

func (*DB) IsHealthy 

func (db *DB) IsHealthy() error

IsHealthy checks that we can connect to the database.

func (*DB) MigrateUp 

func (db *DB) MigrateUp() error

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

func (*DB) Reset 

func (db *DB) Reset() error

Reset resets the database to a pristine state.

func (*DB) SchemaVersion 

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

SchemaVersion returns the current schema version.

type DeployEvent 

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 

func (e DeployEvent) Event() string

func (DeployEvent) GetApp 

func (e DeployEvent) GetApp() *App

func (DeployEvent) String 

func (e DeployEvent) String() string

type DeployOpts 

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 

func (opts DeployOpts) Event() DeployEvent

func (DeployOpts) Validate 

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

type DeploymentStream 

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 

func NewDeploymentStream(w io.Writer) *DeploymentStream

NewDeploymentStream wraps the io.Writer as a DeploymentStream.

func (*DeploymentStream) Error 

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 

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

Publish implements the scheduler.StatusStream interface.

func (*DeploymentStream) Status 

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

Status writes a simple status update to the jsonmessage stream.

type DestroyEvent 

type DestroyEvent struct {
	User    string
	App     string
	Message string
}

DestroyEvent is triggered when a user destroys an application.

func (DestroyEvent) Event 

func (e DestroyEvent) Event() string

func (DestroyEvent) String 

func (e DestroyEvent) String() string

type DestroyOpts 

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 

func (opts DestroyOpts) Event() DestroyEvent

func (DestroyOpts) Validate 

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 

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

AppsFind finds the first app matching the query.

func (*Empire) CertsAttach 

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

CertsAttach attaches an SSL certificate to the app.

func (*Empire) Config 

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

Config returns the current Config for a given app.

func (*Empire) Create 

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 

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 

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 

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 

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 

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 

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 

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 

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

Scale scales an apps processes.

func (*Empire) Set 

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 

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 

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

Streamlogs streams logs from an app.

func (*Empire) Tasks 

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

Tasks returns the Tasks for the given app.

type Event 

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 

type EventStream interface {
	PublishEvent(Event) error
}

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

func AsyncEvents 

func AsyncEvents(e EventStream) EventStream

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

type EventStreamFunc 

type EventStreamFunc func(Event) error

EventStreamFunc is a function that implements the Events interface.

func (EventStreamFunc) PublishEvent 

func (fn EventStreamFunc) PublishEvent(event Event) error

type FakeScheduler 

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

func NewFakeScheduler 

func NewFakeScheduler() *FakeScheduler

func (*FakeScheduler) Remove 

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

func (*FakeScheduler) Restart 

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

func (*FakeScheduler) Run 

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

func (*FakeScheduler) Stop 

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

func (*FakeScheduler) Submit 

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

func (*FakeScheduler) Tasks 

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 

func (f Formation) IsValid() error

IsValid returns nil if all of the Processes are valid.

func (Formation) Merge 

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 

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

Scan implements the sql.Scanner interface.

func (Formation) Value 

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

Value implements the driver.Value interface.

type Host 

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

Host represents the host of the task

type ImageRegistry 

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 

type IncompatibleSchemaError struct {
	SchemaVersion         int
	ExpectedSchemaVersion int
}

IncompatibleSchemaError is an error that gets returned from CheckSchemaVersion.

func (*IncompatibleSchemaError) Error 

func (e *IncompatibleSchemaError) Error() string

Error implements the error interface.

type InstancePortPool 

type InstancePortPool struct {
	Start, End uint
}

type LogsStreamer 

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

type MaintenanceEvent 

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

func (MaintenanceEvent) Event 

func (e MaintenanceEvent) Event() string

func (MaintenanceEvent) GetApp 

func (e MaintenanceEvent) GetApp() *App

func (MaintenanceEvent) String 

func (e MaintenanceEvent) String() string

type MessageRequiredError 

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 

func (e *MessageRequiredError) Error() string

type MultiEventStream 

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 

func (streams MultiEventStream) PublishEvent(e Event) error

type NoCertError 

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 

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 

func (p *Process) Constraints() Constraints

Constraints returns a constraints.Constraints from this Process definition.

func (*Process) IsValid 

func (p *Process) IsValid() error

IsValid returns nil if the Process is valid.

func (*Process) SetConstraints 

func (p *Process) SetConstraints(c Constraints)

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

type ProcessUpdate 

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 

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 

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

ProcfileExtractorFunc implements the ProcfileExtractor interface.

func (ProcfileExtractorFunc) ExtractProcfile 

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 

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 

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 

func (e RestartEvent) Event() string

func (RestartEvent) GetApp 

func (e RestartEvent) GetApp() *App

func (RestartEvent) String 

func (e RestartEvent) String() string

type RestartOpts 

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 

func (opts RestartOpts) Event() RestartEvent

func (RestartOpts) Validate 

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

type RollbackEvent 

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 

func (e RollbackEvent) Event() string

func (RollbackEvent) GetApp 

func (e RollbackEvent) GetApp() *App

func (RollbackEvent) String 

func (e RollbackEvent) String() string

type RollbackOpts 

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 

func (opts RollbackOpts) Event() RollbackEvent

func (RollbackOpts) Validate 

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

type RunEvent 

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 

func (e RunEvent) Event() string

func (*RunEvent) Finish 

func (e *RunEvent) Finish()

func (RunEvent) GetApp 

func (e RunEvent) GetApp() *App

func (RunEvent) String 

func (e RunEvent) String() string

type RunOpts 

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 

func (opts RunOpts) Event() RunEvent

func (RunOpts) Validate 

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

type RunRecorder 

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 

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 

func (e ScaleEvent) Event() string

func (ScaleEvent) GetApp 

func (e ScaleEvent) GetApp() *App

func (ScaleEvent) String 

func (e ScaleEvent) String() string

type ScaleEventUpdate 

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

type ScaleOpts 

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 

func (opts ScaleOpts) Event() ScaleEvent

func (ScaleOpts) Validate 

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

type Scheduler 

type Scheduler twelvefactor.Scheduler

type Schema 

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 

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 

func (e SetEvent) Event() string

func (SetEvent) GetApp 

func (e SetEvent) GetApp() *App

func (SetEvent) String 

func (e SetEvent) String() string

type SetMaintenanceModeOpts 

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 

func (opts SetMaintenanceModeOpts) Event() MaintenanceEvent

func (SetMaintenanceModeOpts) Validate 

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

type SetOpts 

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 

func (opts SetOpts) Event() SetEvent

func (SetOpts) Validate 

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 

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

Formation returns a new Formation built from the extracted Procfile.

func (*Slug) ParsedProcfile 

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

ParsedProcfile returns the parsed Procfile.

type Task 

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 

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.
internal
jwt
Package jwt is a Go implementation of JSON Web Tokens: http://self-issued.info/docs/draft-jones-json-web-token.html
 Package jwt is a Go implementation of JSON Web Tokens: http://self-issued.info/docs/draft-jones-json-web-token.html
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.
realip
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.