Repository files navigation

Deploy serverless containers to the cloud from your command line

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

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

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

If you'd like to install the latest prerelease, use this command:

curl -s get-fargate.turnerlabs.io | RELEASE=develop sh

By default, fargate usesus-east-1 as this is the single region where AWSFargate is available. The CLI accepts a --region parameter for future use andwill honorAWS_REGION andAWS_DEFAULT_REGION environment settings. Note thatspecifying a region where all required services aren't available will return anerror.

See theRegion Table for a breakdown of what services areavailable in which regions.

fargate is built using theAWS SDK for Go which looks for credentialsin the following locations:

1. Environment Variables

2. Shared Credentials File

3. EC2 Instance Profile

For more information seeSpecifying Credentials inthe AWS SDK for Go documentation.

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-clusterservice:my-servicetask:my-taskrule:my-event-ruleverbose:falsenocolor:true

• Services
• Tasks
• Events

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

• list
• deploy
• info
• logs
• ps
• scale
• env set
• env unset
• env list
• update
• restart

fargate service list

List services

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

Deploy new image to service

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

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

Deploy image, environment variables, and secrets defined in adocker compose file to service

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

Secrets can be defined as key-value pairs under the docker compose file extension fieldx-fargate-secrets. To use extension fields, the compose file version must be at least2.4 for the 2.x series or at least3.7 for the 3.x series.

This allows you to rundocker-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 thelabelaws.ecs.fargate.deploy: 1 to indicate which container you would like to deploy. For example:

version:"3.7"services:web:build:.image:1234567890.dkr.ecr.us-east-1.amazonaws.com/my-service:0.1.0ports:    -80:5000environment:FOO:barBAZ:bamenv_file:    -hidden.envx-fargate-secrets:QUX:arn:key:ssm:us-east-1:000000000000:parameter/path/to/my_parameterlabels:aws.ecs.fargate.deploy:1redis:image:redis

fargate service info

Inspect service

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

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

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-timeusing the --follow option. Logs are prefixed by their log stream name which isin 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 IDvia the --task flag. Pass --task with a task ID multiple times in order toretrieve logs from multiple specific tasks.

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

• Duration (e.g. -1h [one hour ago], -1h10m30s [one hour, ten minutes, andthirty 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 termsto search for log messages that include all terms. See theCloudWatch Logsdocumentation for more details.

--time includes the log timestamp in the output

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

fargate service ps

List running tasks for a service

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 scaleexpression. A scale expression can either be an absolute number or a deltaspecified with a sign such as +5 or -2.

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

Set environment variables and secrets

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

Each --env and --secret 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 wantliteral leading whitespace in the value. Additionally, the "key" side must bea legal shell identifier, which means it must start with an ASCII letter A-Z orunderscore and consist of only letters, digits, and underscores.

The "value" in "key=value" for each --secret flag should reference the ARN to the AWS Secrets Manager secret or AWS Systems Manager Parameter Store parameter.

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

Unset environment variables and secrets

Unsets the environment variable or secret specified via the --key flag. Specify --key witha key name multiple times to unset multiple variables.

fargate service env list

Show environment variables

fargate service update [--cpu <cpu-units>] [--memory <MiB>]

Update service configuration

CPU and memory settings are specified as CPU units and mebibytes respectivelyusing the --cpu and --memory flags. Every 1024 CPU units is equivilent to asingle vCPU. AWS Fargate only supports certain combinations of CPU and memoryconfigurations:

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

fargate service restart

Restart service

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

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

• register
• describe
• logs

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

Registers a newtask definition for the specified docker image, environment variables, or secrets 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 specifiedvia the --image flag.

The environment variables can be specified using one or many--env flags or the--env-file flag.

The secrets can be specified using one or many--secret flags or the--secret-file flag.

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

Registers a newTask Definition using theimage,environment variables, and secrets defined in a docker compose file. Note that environments variables are replaced with what's in the compose file.

Secrets can be defined as key-value pairs under the docker compose file extension fieldx-fargate-secrets. To use extension fields, the compose file version must be at least2.4 for the 2.x series or at least3.7 for the 3.x series.

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

fargate task describe

The describe command describes aTask Definition inDocker Compose format. The Docker image, environment variables, secrets, and target port are the mapped elements.

This command can be useful for looking at changes made by thetask register,service deploy, orservice env set commands. It can also be useful for running a task definition locally for debugging or troubleshooting purposes.

fargate task describe -t my-app> docker-compose.ymldocker-compose up

You can specify the task definition family by using afargate.yml file, theFARGATE_TASK envvar, or usingthe-t flag, including an optional revision number.

fargate task describe -t my-appfargate task describe -t my-app:42

Example output:

version:"3.7"services:app:image:1234567890.dkr.ecr.us-east-1.amazonaws.com/my-app:1.0ports:    -published:8080target:8080environment:AWS_REGION:us-east-1ENVIRONMENT:devFOO:barx-fargate-secrets:KEY:arn:key:ssm:us-east-1:000000000000:parameter/path/to/my_parameterlabels:aws.ecs.fargate.deploy:"1"

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>wheretask is specified via--task, or fargate.yml, or environment variableoptions

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

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

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 taskID via the--task flag. Pass--task with a task ID multiple times in order toretrieve logs from multiple specific tasks.

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

• Duration (e.g. -1h [one hour ago], -1h10m30s [one hour, ten minutes, andthirty 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 termsto 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

Theevents command provides subcommands for working withCloudWatch Events (scheduled tasks, etc.)

• 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'sEcsParameters.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}