amazon-ecs-agent

module
v1.9.0 Latest Latest
Warning

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

Go to latest
Published: May 2, 2016 License: Apache-2.0, BSD-2-Clause, BSD-3-Clause, + 2 more

README

Amazon ECS Container Agent

Build Status

The Amazon ECS Container Agent is software developed for Amazon EC2 Container Service (Amazon ECS).

It runs on Container Instances and starts containers on behalf of Amazon ECS.

Usage

The best source of information on running this software is the AWS Documentation.

On the Amazon Linux AMI

On the Amazon Linux AMI, we provide an init package which can be used via sudo yum install ecs-init && sudo start ecs. This is the recommended way to run it in this environment.

On Other AMIs

The Amazon ECS Container Agent may also be run in a Docker container on an EC2 Instance with a recent Docker version installed. A Docker image is available in our Docker Hub Repository.

Note: The below command should work on most AMIs, but the cgroup and execdriver path may differ in some cases

$ mkdir -p /var/log/ecs /etc/ecs /var/lib/ecs/data
$ touch /etc/ecs/ecs.config
$ docker run --name ecs-agent \
    --restart on-failure:10 -d \
    -v /var/run/docker.sock:/var/run/docker.sock \
    -v /var/log/ecs:/log \
    -v /var/lib/ecs/data:/data \
    -v /var/lib/docker:/var/lib/docker \
    -v /sys/fs/cgroup:/sys/fs/cgroup:ro \
    -v /var/run/docker/execdriver/native:/var/lib/docker/execdriver/native:ro \
    -p 127.0.0.1:51678:51678 \
    --env-file /etc/ecs/ecs.config \
    -e ECS_LOGFILE=/log/ecs-agent.log \
    -e ECS_DATADIR=/data/ \
    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 (v1.5.0) running.

This will produce an image tagged amazon/ecs-container-agent:make 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]
ECS_RESERVED_PORTS_UDP [53, 123] An array of UDP ports that should be marked as unavailable for scheduling on this Container Instance. []
ECS_ENGINE_AUTH_TYPE "docker" | "dockercfg" What type of auth data is stored in the ECS_ENGINE_AUTH_DATA key
ECS_ENGINE_AUTH_DATA See documentation Docker auth data formatted as defined by ECS_ENGINE_AUTH_TYPE.
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> The level of detail that should be logged info
ECS_LOGFILE /ecs-agent.log The location where logs should be written. Log level is controlled by ECS_LOGLEVEL blank
ECS_CHECKPOINT <true | false> Whether to checkpoint state to the DATADIR specified below true if ECS_DATADIR is explicitly set to a non-empty value; false otherwise
ECS_DATADIR /data/ The container path where state is checkpointed for use across agent restarts. /data/
ECS_UPDATES_ENABLED <true | false> Whether to exit for an updater to apply updates when requested false
ECS_UPDATE_DOWNLOAD_DIR /cache Where to place update tarballs within the container
ECS_DISABLE_METRICS <true | false> Whether to disable metrics gathering for tasks. false
ECS_DOCKER_GRAPHPATH /var/lib/docker Used to create the path to the state file of containers launched. The state file is used to read utilization metrics of containers. /var/lib/docker
AWS_SESSION_TOKEN The Session Token used for temporary credentials. Taken from EC2 Instance Metadata
ECS_RESERVED_MEMORY 32 Memory, in MB, to reserve for use by things other than containers managed by ECS. 0
ECS_AVAILABLE_LOGGING_DRIVERS ["json-file","syslog"] Which logging drivers are available on the Container Instance. ["json-file"]
ECS_DISABLE_PRIVILEGED true Whether launching privileged containers is disabled on the Container Instance. false
ECS_SELINUX_CAPABLE true Whether SELinux is available on the Container Instance. false
ECS_APPARMOR_CAPABLE true Whether AppArmor is available on the Container Instance. false
ECS_ENGINE_TASK_CLEANUP_WAIT_DURATION 10m Time to wait to delete containers for a stopped task. If set to less than 1 minute, the value will be ignored. 3h
Persistence

When running the Amazon ECS Container Agent in production, its datadir should be persisted between runs of the Docker container. If this data is not persisted, the Amazon ECS Agent will register a new Container Instance ARN on each launch and will not be able to update the state of tasks it previously ran.

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 the ECS_LOGLEVEL environment variable, if present.

Contributing

Contributions and feedback are welcome! Proposals and Pull Requests will be considered and responded to. Please see the CONTRIBUTING.md file for more information.

Amazon Web Services does not currently provide support for modified copies of this software.

License

The Amazon ECS Container Agent is licensed under the Apache 2.0 License.

Directories

Path Synopsis
Godeps/_workspace/src/github.com/aws/aws-sdk-go/aws
Package aws provides core functionality for making requests to AWS services.
Package aws provides core functionality for making requests to AWS services.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/aws/awserr
Package awserr represents API error interface accessors for the SDK.
Package awserr represents API error interface accessors for the SDK.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/aws/credentials
Package credentials provides credential retrieval and management
Package credentials provides credential retrieval and management
Godeps/_workspace/src/github.com/aws/aws-sdk-go/aws/defaults
Package defaults is a collection of helpers to retrieve the SDK's default configuration and handlers.
Package defaults is a collection of helpers to retrieve the SDK's default configuration and handlers.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/aws/ec2metadata
Package ec2metadata provides the client for making API calls to the EC2 Metadata service.
Package ec2metadata provides the client for making API calls to the EC2 Metadata service.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/aws/session
Package session provides a way to create service clients with shared configuration and handlers.
Package session provides a way to create service clients with shared configuration and handlers.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/endpoints
Package endpoints validates regional endpoints for services.
Package endpoints validates regional endpoints for services.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/model/api
Package api represents API abstractions for rendering service generated files.
Package api represents API abstractions for rendering service generated files.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/protocol/ec2query
Package ec2query provides serialisation of AWS EC2 requests and responses.
Package ec2query provides serialisation of AWS EC2 requests and responses.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/protocol/json/jsonutil
Package jsonutil provides JSON serialisation of AWS requests and responses.
Package jsonutil provides JSON serialisation of AWS requests and responses.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/protocol/jsonrpc
Package jsonrpc provides JSON RPC utilities for serialisation of AWS requests and responses.
Package jsonrpc provides JSON RPC utilities for serialisation of AWS requests and responses.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/protocol/query
Package query provides serialisation of AWS query requests, and responses.
Package query provides serialisation of AWS query requests, and responses.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/protocol/rest
Package rest provides RESTful serialization of AWS requests and responses.
Package rest provides RESTful serialization of AWS requests and responses.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/protocol/xml/xmlutil
Package xmlutil provides XML serialisation of AWS requests and responses.
Package xmlutil provides XML serialisation of AWS requests and responses.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/private/signer/v4
Package v4 implements signing for AWS V4 signer
Package v4 implements signing for AWS V4 signer
Godeps/_workspace/src/github.com/aws/aws-sdk-go/service/cloudwatch
Package cloudwatch provides a client for Amazon CloudWatch.
Package cloudwatch provides a client for Amazon CloudWatch.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/service/cloudwatchlogs
Package cloudwatchlogs provides a client for Amazon CloudWatch Logs.
Package cloudwatchlogs provides a client for Amazon CloudWatch Logs.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/service/ec2
Package ec2 provides a client for Amazon Elastic Compute Cloud.
Package ec2 provides a client for Amazon Elastic Compute Cloud.
Godeps/_workspace/src/github.com/aws/aws-sdk-go/service/ec2/ec2iface
Package ec2iface provides an interface for the Amazon Elastic Compute Cloud.
Package ec2iface provides an interface for the Amazon Elastic Compute Cloud.
Godeps/_workspace/src/github.com/cihub/seelog
Package seelog implements logging functionality with flexible dispatching, filtering, and formatting.
Package seelog implements logging functionality with flexible dispatching, filtering, and formatting.
Godeps/_workspace/src/github.com/docker/libcontainer
Temporary API endpoint for libcontainer while the full API is finalized (api.go).
Temporary API endpoint for libcontainer while the full API is finalized (api.go).
Godeps/_workspace/src/github.com/docker/libcontainer/integration
integration is used for integration testing of libcontainer
integration is used for integration testing of libcontainer
Godeps/_workspace/src/github.com/docker/libcontainer/netlink
Packet netlink provide access to low level Netlink sockets and messages.
Packet netlink provide access to low level Netlink sockets and messages.
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/external/github.com/Sirupsen/logrus
Package logrus is a structured logger for Go, completely API compatible with the standard library logger.
Package logrus is a structured logger for Go, completely API compatible with the standard library logger.
Godeps/_workspace/src/github.com/fsouza/go-dockerclient/external/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/external/github.com/docker/go-units
Package units provides helper function to parse and print size and time units in human-readable format.
Package units provides helper function to parse and print size and time units in human-readable format.
Godeps/_workspace/src/github.com/fsouza/go-dockerclient/external/golang.org/x/net/context
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.
Godeps/_workspace/src/github.com/fsouza/go-dockerclient/external/golang.org/x/sys/unix
Package unix contains an interface to the low-level operating system primitives.
Package unix contains an interface to the low-level operating system primitives.
Godeps/_workspace/src/github.com/go-ini/ini
Package ini provides INI file read and write functionality in Go.
Package ini provides INI file read and write functionality in Go.
Godeps/_workspace/src/github.com/golang/mock/gomock
GoMock - a mock framework for Go.
GoMock - a mock framework for Go.
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/github.com/pborman/uuid
The uuid package generates and inspects UUIDs.
The uuid package generates and inspects UUIDs.
Godeps/_workspace/src/golang.org/x/net/context
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.
Package context defines the Context type, which carries deadlines, cancelation signals, and other request-scoped values across API boundaries and between processes.
Godeps/_workspace/src/golang.org/x/tools/go/ast/astutil
Package astutil contains common utilities for working with the Go AST.
Package astutil contains common utilities for working with the Go AST.
Godeps/_workspace/src/golang.org/x/tools/imports
Package imports implements a Go pretty-printer (like package "go/format") that also adds or removes import statements as necessary.
Package imports implements a Go pretty-printer (like package "go/format") that also adds or removes import statements as necessary.
acs/client
Package acsclient wraps the generated aws-sdk-go client to provide marshalling and unmarshalling of data over a websocket connection in the format expected by ACS.
Package acsclient wraps the generated aws-sdk-go client to provide marshalling and unmarshalling of data over a websocket connection in the format expected by ACS.
acs/handler
Package handler deals with appropriately reacting to all ACS messages as well as maintaining the connection to ACS.
Package handler deals with appropriately reacting to all ACS messages as well as maintaining the connection to ACS.
acs/update_handler
Package updater handles requests to update the agent.
Package updater handles requests to update the agent.
acs/update_handler/os
Package os provides interfaces around the 'os', 'io', and 'ioutil' functions so that may be mocked out appropriately
Package os provides interfaces around the 'os', 'io', and 'ioutil' functions so that may be mocked out appropriately
api
api/testutils
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.
config
Package config handles loading configuration data, warning on missing data, and setting sane defaults.
Package config handles loading configuration data, warning on missing data, and setting sane defaults.
ec2
ecr
Package ecr helps generate clients to talk to the ECR API
Package ecr helps generate clients to talk to the ECR API
engine
The 'engine' package contains code for interacting with container-running backends and handling events from them.
The 'engine' package contains code for interacting with container-running backends and handling events from them.
engine/dockerauth
Package dockerauth handles storing auth configuration information for Docker registries.
Package dockerauth handles storing auth configuration information for Docker registries.
engine/dockeriface
Package dockeriface contains an interface for go-dockerclient matching the subset used by the agent
Package dockeriface contains an interface for go-dockerclient matching the subset used by the agent
engine/dockerstate/testutils
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.
engine/emptyvolume
Package emptyvolume contains some information related to the 'emptyvolumes'
Package emptyvolume contains some information related to the 'emptyvolumes'
engine/testutils
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.
Package testutils contains files that are used in tests but not elsewhere and thus can be excluded from the final executable.
handlers
Package handlers deals with the agent introspection api.
Package handlers deals with the agent introspection api.
httpclient
Package httpclient provides a thin, but testable, wrapper around http.Client.
Package httpclient provides a thin, but testable, wrapper around http.Client.
sighandlers
sighandlers handle signals and behave appropriately.
sighandlers handle signals and behave appropriately.
sighandlers/exitcodes
Package exitcodes defines agent exit codes
Package exitcodes defines agent exit codes
statemanager
Package statemanager implements simple constructs for saving and restoring state from disk.
Package statemanager implements simple constructs for saving and restoring state from disk.
utils/atomic
Package atomic implements higher level constructs on top of the stdlib atomic package
Package atomic implements higher level constructs on top of the stdlib atomic package
utils/sync
Package sync is an analogue to the stdlib sync package.
Package sync is an analogue to the stdlib sync package.
utils/ttime
Package ttime implements a testable alternative to the Go "time" package.
Package ttime implements a testable alternative to the Go "time" package.
version
Package version contains constants to indicate the current version of the agent.
Package version contains constants to indicate the current version of the agent.
wsclient
Package wsclient wraps the generated aws-sdk-go client to provide marshalling and unmarshalling of data over a websocket connection in the format expected by backend.
Package wsclient wraps the generated aws-sdk-go client to provide marshalling and unmarshalling of data over a websocket connection in the format expected by backend.
misc
netkitten
Netkitten is a slimmed down netcat intended to make our integ tests able to run containers lighter than busybox+netcat, but still be able to do suitably complex network testing.
Netkitten is a slimmed down netcat intended to make our integ tests able to run containers lighter than busybox+netcat, but still be able to do suitably complex network testing.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL