README
¶
Amazon ECS Container Agent
The Amazon ECS Container Agent is software developed for the Amazon EC2 Container Service.
It runs on Container Instances and starts containers on behalf of Amazon ECS.
Basic Usage
Docker Image
The Amazon ECS Container Agent should be run in a docker container and may be downloaded from our Docker Hub Repository. Documentation on running it properly may be found on the Repository page.
tl;dr: On an Amazon ECS Container Instance
touch /etc/ecs/ecs.configmkdir -p /var/log/ecsdocker run --name ecs-agent -d -v /var/run/docker.sock:/var/run/docker.sock -v /var/log/ecs:/log -p 127.0.0.1:51678:51678 --env-file /etc/ecs/ecs.config -e ECS_LOGFILE=/log/ecs-agent.log amazon/amazon-ecs-agent.
See also the Advanced Usage section below.
Building and Running from source
Please note, running the Amazon ECS Container Agent outside of Amazon EC2 is not supported
Docker Image
The Amazon ECS Container Agent may be built by simply typing make with the Docker
daemon running.
This will produce an image tagged amazon/ecs-container-agent:development which
you may run as described above.
Standalone
The Amazon ECS Container Agent may also be run outside of a docker container as a go binary. This is not recommended for production, but it can be useful for development or easier integration with your local Go tools.
The following commands will run it outside of Docker:
make gobuild
./out/amazon-ecs-agent
Make Targets
The following targets are available. Each may be run with make <target>.
| Make Target | Description |
|---|---|
release |
(Default) release builds the agent within a docker container and and packages it into a scratch-based image |
gobuild |
gobuild runs a normal go build of the agent and stores the binary in ./out/amazon-ecs-agent |
static |
static runs go build to produce a static binary in ./out/amazon-ecs-agent |
test |
test runs all tests using go test |
test-in-docker |
test-in-docker runs all tests inside a docker container |
clean |
clean removes build artifacts. Note: this does not remove docker images |
Advanced Usage
The Amazon ECS Container Agent supports a number of configuration options, most of which should be set through environment variables.
Environment Variables
The following environment variables are available. All of them are optional. They are listed in a general order of likelihood that a user may want to configure them as something other than the defaults.
| Environment Key | Example Value(s) | Description | Default Value |
|---|---|---|---|
ECS_CLUSTER |
clusterName | The cluster this agent should check into. | default |
ECS_RESERVED_PORTS |
[22, 80, 5000, 8080] |
An array of ports that should be marked as unavailable for scheduling on this Container Instance. | [22, 2375, 2376, 51678] |
AWS_DEFAULT_REGION |
<us-west-2>|<us-east-1>|… | The region to be used in API requests as well as to infer the correct backend host. | Taken from EC2 Instance Metadata |
AWS_ACCESS_KEY_ID |
AKIDEXAMPLE | The Access Key used by the agent for all calls. | Taken from EC2 Instance Metadata |
AWS_SECRET_ACCESS_KEY |
EXAMPLEKEY | The Secret Key used by the agent for all calls. | Taken from EC2 Instance Metadata |
DOCKER_HOST |
unix:///var/run/docker.sock | Used to create a connection to the Docker daemon; behaves similarly to this environment variable as used by the Docker client | unix:///var/run/docker.sock |
ECS_LOGLEVEL |
<crit> | <error> | <warn> | <info> | <debug> | What level to log at on stdout. | warn |
ECS_LOGFILE |
/ecs-agent.log | The path to output full debugging info to. If blank, no logs will be written to file. If set, logs at debug level (regardless of ECS_LOGLEVEL) will be written to that file. | blank |
ECS_BACKEND_HOST |
ecs.us-east-1.amazonaws.com | The host to make backend api calls against. | ecs.REGION.amazonaws.com |
ECS_BACKEND_PORT |
443 | The associated port to make backend api calls with. | 443 |
AWS_SESSION_TOKEN |
The Session Token used for temporary credentials. | Taken from EC2 Instance Metadata |
Flags
The agent also supports the following flags:
-k— The agent will not requre valid SSL certificates for the services it communicates with.-loglevel— Options:[<crit>|<error>|<warn>|<info>|<debug>]. The agent will output on stdout at the given level. This is overridden by theECS_LOGLEVELenvironment variable, if present.
Contributing
Contributions and feedback are welcome! Proposals and Pull Requests will be considered and responded to.
License
The Amazon ECS Container Agent is licensed under the Apache 2.0 License.
Directories
¶
| Path | Synopsis |
|---|---|
|
Godeps/_workspace/src/github.com/docker/docker/pkg/pools
Package pools provides a collection of pools which provide various data types with buffers.
|
Package pools provides a collection of pools which provide various data types with buffers. |
|
Godeps/_workspace/src/github.com/fsouza/go-dockerclient
Package docker provides a client for the Docker remote API.
|
Package docker provides a client for the Docker remote API. |
|
Godeps/_workspace/src/github.com/fsouza/go-dockerclient/testing
Package testing provides a fake implementation of the Docker API, useful for testing purpose.
|
Package testing provides a fake implementation of the Docker API, useful for testing purpose. |
|
Godeps/_workspace/src/github.com/gorilla/context
Package context stores values shared during a request lifetime.
|
Package context stores values shared during a request lifetime. |
|
Godeps/_workspace/src/github.com/gorilla/mux
Package gorilla/mux implements a request router and dispatcher.
|
Package gorilla/mux implements a request router and dispatcher. |
|
Godeps/_workspace/src/github.com/gorilla/websocket
Package websocket implements the WebSocket protocol defined in RFC 6455.
|
Package websocket implements the WebSocket protocol defined in RFC 6455. |
|
Godeps/_workspace/src/github.com/gorilla/websocket/examples/autobahn
Command server is a test server for the Autobahn WebSockets Test Suite.
|
Command server is a test server for the Autobahn WebSockets Test Suite. |
|
Godeps/_workspace/src/gopkg.in/inconshreveable/log15.v2
Package log15 provides an opinionated, simple toolkit for best-practice logging that is both human and machine readable.
|
Package log15 provides an opinionated, simple toolkit for best-practice logging that is both human and machine readable. |
|
Godeps/_workspace/src/gopkg.in/inconshreveable/log15.v2/stack
Package stack implements utilities to capture, manipulate, and format call stacks.
|
Package stack implements utilities to capture, manipulate, and format call stacks. |
|
ecs_client/codec/codec
The codec package defines how to read and write data from the wire
|
The codec package defines how to read and write data from the wire |
|
engine
The DockerTaskEngine is an abstraction over the DockerGoClient so that it does not have to know about tasks, only containers
|
The DockerTaskEngine is an abstraction over the DockerGoClient so that it does not have to know about tasks, only containers |
|
handlers
Handlers for V1
|
Handlers for V1 |