Skip to content
Deploy serverless containers to the cloud from your command line
Branch: master
Clone or download
Pull request Compare This branch is 36 commits ahead, 24 commits behind jpignata:master.
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
.circleci fixes build version (#5) May 2, 2018
acm
cloudwatchevents
cloudwatchlogs
cmd
console
doc/website Add CircleCI badge Feb 21, 2018
dockercompose support for deploying a docker-compose.yml (closes #3) (#8) May 4, 2018
ec2
ecs
elbv2
servicediscovery add service discovery to service info cmd (#21) Aug 22, 2018
sts
.gitignore
CHANGELOG.md
CONTRIBUTING.md
Gopkg.lock implements events target command (closes #25) (#26) Nov 6, 2018
Gopkg.toml implements events target command (closes #25) (#26) Nov 6, 2018
LICENSE Include full license Feb 5, 2018
Makefile
README.md adds --time and --no-prefix to service logs (#29) Nov 6, 2018
fargate.png
main.go

README.md

Fargate CLI

Deploy serverless containers to the cloud from your command line

CircleCI GoDoc

fargate

fargate is a command-line interface to deploy containers to AWS Fargate. Using fargate, developers can easily operate fargate services including things like: deploying applications (images and environment variables), monitoring deployments, viewing container logs, restarting and scaling.

Install

You can install the CLI with a curl utility script or by downloading the binary from the releases page. Once installed you'll get the fargate command.

curl -s get-fargate.turnerlabs.io | sh

Usage

Configuration

Region

By default, fargate uses us-east-1 as this is the single region where AWS Fargate is available. The CLI accepts a --region parameter for future use and will honor AWS_REGION and AWS_DEFAULT_REGION environment settings. Note that specifying a region where all required services aren't available will return an error.

See the Region Table for a breakdown of what services are available in which regions.

Credentials

fargate is built using the AWS SDK for Go which looks for credentials in the following locations:

  1. Environment Variables

  2. Shared Credentials File

  3. EC2 Instance Profile

For more information see Specifying Credentials in the AWS SDK for Go documentation.

Options

There are several ways to specify parameters. Each item takes precedence over the item below it:

  1. CLI arguments (e.g., --cluster my-cluster)

  2. Environment Variables (e.g., FARGATE_CLUSTER=my-cluster)

  3. fargate.yml (e.g., below)

cluster: my-cluster
service: my-service
task: my-task
rule: my-event-rule
verbose: false
nocolor: true

Global Flags

Flag Short Default Description
--cluster -c ECS cluster name
--region us-east-1 AWS region
--no-color false Disable color output
--verbose -v false Verbose output

Commands

Services

Services manage long-lived instances of your containers that are run on AWS Fargate. If your container exits for any reason, the service scheduler will restart your containers and ensure your service has the desired number of tasks running. Services can be used in concert with a load balancer to distribute traffic amongst the tasks in your service.

Flags
Flag Short Default Description
--service -s ECS service name
fargate service list
fargate service list

List services

fargate service deploy
fargate service deploy [--image <docker-image>]

Deploy new image to service

The Docker container image to use in the service can be specified via the --image flag.

fargate service deploy [--file docker-compose.yml]

Deploy image and environment variables defined in a docker compose file to service

Deploy a docker image and environment variables defined in a docker compose file together as a single unit. Note that environments variables are replaced with what's in the compose file.

This allows you to run docker-compose up locally to run your app the same way it will run in AWS. Note that while the docker-compose yaml configuration supports numerous options, only the image and environment variables are deployed to fargate. If the docker compose file defines more than one container, you can use the label aws.ecs.fargate.deploy: 1 to indicate which container you would like to deploy. For example:

version: '3'
services:
  web:
    build: .
    image: 1234567890.dkr.ecr.us-east-1.amazonaws.com/my-service:0.1.0
    ports:
    - 80:5000
    environment:
      FOO: bar
      BAZ: bam
    env_file:
    - hidden.env
    labels:
      aws.ecs.fargate.deploy: 1
  redis:
    image: redis
fargate service info
fargate service info 

Inspect service

Show extended information for a service including load balancer configuration, active deployments, and environment variables.

Deployments show active versions of your service that are running. Multiple deployments are shown if a service is transitioning due to a deployment or update to configuration such a CPU, memory, or environment variables.

fargate service logs
fargate service logs [--follow] [--start <time-expression>] [--end <time-expression>]
                     [--filter <filter-expression>] [--task <task-id>]
                     [--time] [--no-prefix]

Show logs from tasks in a service

Return either a specific segment of service logs or tail logs in real-time using the --follow option. Logs are prefixed by their log stream name which is in the format of "fargate/<service-name>/<task-id>."

Follow will continue to run and return logs until interrupted by Control-C. If --follow is passed --end cannot be specified.

Logs can be returned for specific tasks within a service by passing a task ID via the --task flag. Pass --task with a task ID multiple times in order to retrieve logs from multiple specific tasks.

A specific window of logs can be requested by passing --start and --end options with a time expression. The time expression can be either a duration or a timestamp:

  • Duration (e.g. -1h [one hour ago], -1h10m30s [one hour, ten minutes, and thirty seconds ago], 2h [two hours from now])
  • Timestamp with optional timezone in the format of YYYY-MM-DD HH:MM:SS [TZ]; timezone will default to UTC if omitted (e.g. 2017-12-22 15:10:03 EST)

You can filter logs for specific term by passing a filter expression via the --filter flag. Pass a single term to search for that term, pass multiple terms to search for log messages that include all terms. See the CloudWatch Logs documentation for more details.

--time includes the log timestamp in the output

--no-prefix excludes the log stream prefix from the output

fargate service ps
fargate service ps

List running tasks for a service

fargate service scale
fargate service scale <scale-expression>

Scale number of tasks in a service

Changes the number of desired tasks to be run in a service by the given scale expression. A scale expression can either be an absolute number or a delta specified with a sign such as +5 or -2.

fargate service env set
fargate service env set [--env <key=value>] [--file <pathname>]

Set environment variables

At least one environment variable must be specified via either the --env or --file flags. You may specify any number of variables on the command line by repeating --env before each one, or else place multiple variables in a text file, one per line, and specify the filename with --file.

Each --env parameter string or line in the file must be of the form "key=value", with no quotation marks and no whitespace around the "=" unless you want literal leading whitespace in the value. Additionally, the "key" side must be a legal shell identifier, which means it must start with an ASCII letter A-Z or underscore and consist of only letters, digits, and underscores.

fargate service env unset
fargate service env unset --key <key-name>

Unset environment variables

Unsets the environment variable specified via the --key flag. Specify --key with a key name multiple times to unset multiple variables.

fargate service env list
fargate service env list

Show environment variables

fargate service update
Flag Short Default Description
--cpu Amount of cpu units to allocate for each task
--memory -m Amount of MiB to allocate for each task
fargate service update [--cpu <cpu-units>] [--memory <MiB>]

Update service configuration

CPU and memory settings are specified as CPU units and mebibytes respectively using the --cpu and --memory flags. Every 1024 CPU units is equivilent to a single vCPU. AWS Fargate only supports certain combinations of CPU and memory configurations:

CPU (CPU Units) Memory (MiB)
256 512, 1024, or 2048
512 1024 through 4096 in 1GiB increments
1024 2048 through 8192 in 1GiB increments
2048 4096 through 16384 in 1GiB increments
4096 8192 through 30720 in 1GiB increments

At least one of --cpu or --memory must be specified.

fargate service restart
fargate service restart 

Restart service

Creates a new set of tasks for the service and stops the previous tasks. This is useful if your service needs to reload data cached from an external source, for example.

Tasks

Flags
Flag Short Default Description
--task -t Task Definition Family

Tasks are one-time executions of your container. Instances of your task are run until you manually stop them either through AWS APIs, the AWS Management Console, or until they are interrupted for any reason.

fargate task register
fargate task register [--image <docker-image>] [-e KEY=value -e KEY2=value] [--env-file dev.env]

Registers a new task definition for the specified docker image or environment variables based on the latest revision of the task family and returns the new revision number.

The Docker container image to use in the new Task Definition can be specified via the --image flag.

fargate task register [--file docker-compose.yml]

Registers a new Task Definition using the image and environment variables defined in a docker compose file. Note that environments variables are replaced with what's in the compose file.

If the docker compose file defines more than one container, you can use the label aws.ecs.fargate.deploy: 1 to indicate which container you would like to deploy.

fargate task logs
fargate task logs [--follow] [--start <time-expression>] [--end <time-expression>]
                  [--filter <filter-expression>] [--task <task-id>] 
                  [--container-name] [--time] [--no-prefix]

Show logs from tasks

Assumes a cloudwatch log group with the following convention: fargate/task/<task> where task is specified via --task, or fargate.yml, or environment variable options

Return either a specific segment of task logs or tail logs in real-time using the --follow option. Logs are prefixed by their log stream name which is in the format of fargate/<container-name>/<task-id>.

--container-name allows you to specifiy the container within the task definition to get logs for (defaults to app)

Follow will continue to run and return logs until interrupted by Control-C. If --follow is passed --end cannot be specified.

Logs can be returned for specific tasks by passing a task ID via the --task flag. Pass --task with a task ID multiple times in order to retrieve logs from multiple specific tasks.

A specific window of logs can be requested by passing --start and --end options with a time expression. The time expression can be either a duration or a timestamp:

  • Duration (e.g. -1h [one hour ago], -1h10m30s [one hour, ten minutes, and thirty seconds ago], 2h [two hours from now])
  • Timestamp with optional timezone in the format of YYYY-MM-DD HH:MM:SS [TZ]; timezone will default to UTC if omitted (e.g. 2017-12-22 15:10:03 EST)

You can filter logs for specific term by passing a filter expression via the --filter flag. Pass a single term to search for that term, pass multiple terms to search for log messages that include all terms.

--time includes the log timestamp in the output

--no-prefix excludes the log stream prefix from the output

Events

Flags
Flag Short Default Description
--rule -r CloudWatch Events Rule

The events command provides subcommands for working with CloudWatch Events (scheduled tasks, etc.)

fargate events target
fargate events target --revision <revision>

"Deploys" (causes the next event rule invocation to run the new version) a task definition revision to a CloudWatch Event Rule by updating the rule target's EcsParameters.TaskDefinitionArn.

A typical CI/CD system might do something like:

REVISION=$(fargate task register -i 123456789.dkr.ecr.us-east-1.amazonaws.com/my-app:${VERSION}-${CIRCLE_BUILD_NUM} -e FOO=bar)
fargate events target -r ${REVISION}
You can’t perform that action at this time.