Fargate CLI
Screencast
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:
-
Environment Variables
-
Shared Credentials File
-
EC2 Instance Profile
For more information see Specifying Credentials in
the AWS SDK for Go documentation.
Commands
Global Flags
Flag |
Default |
Description |
--cluster |
fargate |
ECS cluster name |
--region |
us-east-1 |
AWS region |
--no-color |
false |
Disable color output |
--verbose |
false |
Verbose output |
Tasks
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 fargate task stop
, or until they are interrupted for any reason.
fargate task list
fargate task list
List running task groups
fargate task run
fargate task run <task-group-name> [--num <count>] [--cpu <cpu-units>] [--memory <MiB>]
[--image <docker-image>] [--env <key=value>]
[--task-role <task-role>] [--subnet-id <subnet-id>]
[--security-group-id <security-group-id>]
Run new tasks
You must specify a task group name in order to interact with the task(s) in
subsequent commands to view logs, stop and inspect tasks. Task group names do
not have to be unique -- multiple configurations of task instances can be
started with the same task group.
Multiple instances of a task can be run by specifying a number in the --num
flag. If no number is specified, a single task instance will be run.
CPU and memory settings can be optionally 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 |
If not specified, fargate will launch minimally sized tasks at 0.25 vCPU (256
CPU units) and 0.5GB (512 MiB) of memory.
The Docker container image to use in the task can be optionally specified via
the --image flag. If not specified, fargate will build a new Docker container
image from the current working directory and push it to Amazon ECR in a
repository named for the task group. If the current working directory is a git
repository, the container image will be tagged with the short ref of the HEAD
commit. If not, a timestamp in the format of YYYYMMDDHHMMSS will be used.
Environment variables can be specified via the --env flag. Specify --env with a
key=value parameter multiple times to add multiple variables.
Security groups can optionally be specified for the task by passing the
--security-group-id flag with a security group ID. To add multiple security
groups, pass --security-group-id with a security group ID multiple times. If
--security-group-id is omitted, a permissive security group will be applied to
the task.
By default, the task will be created in the default VPC and attached to the
default VPC subnets for each availability zone. You can override this by
specifying explicit subnets by passing the --subnet-id flag with a subnet ID.
A task role can be optionally specified via the --task-role flag by providing
eith a full IAM role ARN or the name of an IAM role. The tasks will be able to
assume this role.
fargate task info
fargate task info <task-group-name> [--task <task-id>]
Inspect tasks
Shows extended information for each running task within a task group or for
specific tasks specified with the --task flag. Information includes environment
variables which could differ between tasks in a task group. To inspect multiple
specific tasks within a task group specific --task with a task ID multiple
times.
fargate task ps
fargate task ps <task-group-name>
List running tasks
fargate task logs
fargate task logs <task-group-name> [--follow] [--start <time-expression>] [--end <time-expression>]
[--filter <filter-expression>] [--task <task-id>]
Show logs from tasks
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/<task-group-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 task group 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.
fargate task stop
fargate task stop <task-group-name> [--task <task-id>]
Stop tasks
Stops all tasks within a task group if run with only a task group name or stops
individual tasks if one or more tasks are passed via the --task flag. Specify
--task with a task ID parameter multiple times to stop multiple specific tasks.
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.
fargate service list
fargate service list
List services
fargate service create
fargate service create <service name> [--cpu <cpu units>] [--memory <MiB>] [--port <port-expression>]
[--lb <load-balancer-name>] [--rule <rule-expression>]
[--image <docker-image>] [--env <key=value>] [--num <count>]
[--task-role <task-role>] [--subnet-id <subnet-id>]
[--security-group-id <security-group-id>]
Create a new service
CPU and memory settings can be optionally 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 |
If not specified, fargate will launch minimally sized tasks at 0.25 vCPU (256
CPU units) and 0.5GB (512 MiB) of memory.
The Docker container image to use in the service can be optionally specified
via the --image flag. If not specified, fargate will build a new Docker
container image from the current working directory and push it to Amazon ECR in
a repository named for the task group. If the current working directory is a
git repository, the container image will be tagged with the short ref of the
HEAD commit. If not, a timestamp in the format of YYYYMMDDHHMMSS will be used.
To use the service with a load balancer, a port must be specified when the
service is created. Specify a port by passing the --port flag and a port
expression of protocol:port-number. For example, if the service listens on port
80 and uses HTTP, specify HTTP:80. Valid protocols are HTTP, HTTPS, and TCP.
You can only specify a single port.
Services can optionally be configured to use a load balancer. To put a load
balancer in front a service, pass the --lb flag with the name of a load
balancer. If you specify a load balancer, you must also specify a port via the
--port flag to which the load balancer should forward requests. Optionally,
Application Load Balancers can be configured to route HTTP/HTTPS traffic to the
service based upon a rule. Rules are configured by passing one or more rules by
specifying the --rule flag along with a rule expression. Rule expressions are
in the format of TYPE=VALUE. Type can either be PATH or HOST. PATH matches the
PATH of the request and HOST matches the requested hostname in the HTTP
request. Both PATH and HOST types can include up to three wildcard characters:
* to match multiple characters and ? to match a single character. If rules are
omitted, the service will be the load balancer's default action.
Environment variables can be specified via the --env flag. Specify --env with a
key=value parameter multiple times to add multiple variables.
Specify the desired count of tasks the service should maintain by passing the
--num flag with a number. If you omit this flag, fargate will configure a
service with a desired number of tasks of 1.
Security groups can optionally be specified for the service by passing the
--security-group-id flag with a security group ID. To add multiple security
groups, pass --security-group-id with a security group ID multiple times. If
--security-group-id is omitted, a permissive security group will be applied to
the service.
By default, the service will be created in the default VPC and attached
to the default VPC subnets for each availability zone. You can override this by
specifying explicit subnets by passing the --subnet-id flag with a subnet ID.
A task role can be optionally specified via the --task-role flag by providing
eith a full IAM role ARN or the name of an IAM role. The tasks run by the
service will be able to assume this role.
fargate service deploy
fargate service deploy <service-name> [--image <docker-image>]
Deploy new image to service
The Docker container image to use in the service can be optionally specified
via the --image flag. If not specified, fargate will build a new Docker
container image from the current working directory and push it to Amazon ECR in
a repository named for the task group. If the current working directory is a
git repository, the container image will be tagged with the short ref of the
HEAD commit. If not, a timestamp in the format of YYYYMMDDHHMMSS will be used.
fargate service info
fargate service info <service-name>
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 <service-name> [--follow] [--start <time-expression>] [--end <time-expression>]
[--filter <filter-expression>] [--task <task-id>]
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.
fargate service ps
fargate service ps <service-name>
List running tasks for a service
fargate service scale
fargate service scale <service-name> <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 <service-name> --env <key=value>
Set environment variables
At least one environment variable must be specified via the --env flag. Specify
--env with a key=value parameter multiple times to add multiple variables.
fargate service env unset
fargate service env unset <service-name> --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 <service-name>
Show environment variables
fargate service update
fargate service update <service-name> [--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 <service-name>
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.
fargate service destroy
fargate service destroy <service-name>
Destroy service
In order to destroy a service, it must first be scaled to 0 running tasks.
Load Balancers
Load balancers distribute incoming traffic between the tasks within a service
for HTTP/HTTPS and TCP applications. HTTP/HTTPS load balancers can route to
multiple services based upon rules you specify when you create a new service.
fargate lb list
fargate lb list
List load balancers
fargate lb create
fargate lb create <load-balancer-name> --port <port-expression> [--certificate <certificate-name>]
[--subnet-id <subnet-id>] [--security-group-id <security-group-id>]
[--scheme <lb-scheme>]
Create a load balancer
At least one port must be specified for the load balancer listener via the
--port flag and a port expression of protocol:port-number. For example, if you
wanted an HTTP load balancer to listen on port 80, you would specify HTTP:80.
Valid protocols are HTTP, HTTPS, and TCP. You can specify multiple listeners by
passing the --port flag with a port expression multiple times. You cannot mix
TCP ports with HTTP/HTTPS ports on a single load balancer.
You can optionally include certificates to secure HTTPS ports by passed the
--certificate flag along with a certificate name. This option can be specified
multiple times to add additional certificates to a single load balancer which
uses Service Name Identification (SNI) to select the appropriate certificate
for the request.
By default, the load balancer will be created in the default VPC and attached
to the default VPC subnets for each availability zone. You can override this by
specifying explicit subnets by passing the --subnet-id flag with a subnet ID.
HTTP/HTTPS load balancers require at least two subnets attached while a TCP
load balancer requires only one. You may only specify a single subnet from each
availability zone.
Security groups can optionally be specified for HTTP/HTTPS load balancers by
passing the --security-group-id flag with a security group ID. To add multiple
security groups, pass --security-group-id with a security group ID multiple
times. If --security-group-id is omitted, a permissive security group will be
applied to the load balancer.
You can also choose the scheme type for load balancer via the --scheme flag.
By default, load balancers are internet-facing.
fargate lb destroy
fargate lb destroy <load-balancer-name>
Destroy load balancer
fargate lb alias
fargate lb alias <load-balancer-name> <hostname>
Create a load balancer alias record
Create an alias record to the load balancer for domains that are hosted within
Amazon Route 53 and within the same AWS account. If you're using another DNS
provider or host your domains in a different account, you will need to manually
create this record.
fargate lb info
fargate lb info <load-balancer-name>
Inspect load balancer
Returns extended information about a load balancer including a list of
listeners, rules, and certificates in use by the load balancer.
Certificates
Certificates are TLS certificates issued by or imported into AWS Certificate
Manager for use in securing traffic between load balancers and end users. ACM
provides TLS certificates free of charge for use within AWS resources.
fargate certificate list
fargate certificate list
List certificates
fargate certificate import
fargate certificate import <domain-name> --certificate <filename> --key <filename> [--chain <filename>]
Import a certificate
Upload a certificate from a certificate file, a private key file, and optionally
an intermediate certificate chain file. The files must be PEM-encoded and the
private key must not be encrypted or protected by a passphrase. See the
AWS Certificate Manager documentation for more details.
fargate certificate request
fargate certificate request <domain-name> [--alias <domain-name>]
Request a certificate
Certificates can be for a fully qualified domain name (e.g. www.example.com) or
a wildcard domain name (e.g. *.example.com). You can add aliases to a
certificate by specifying additional domain names via the --alias flag. To add
multiple aliases, pass --alias multiple times. By default, AWS Certificate
Manager has a limit of 10 domain names per certificate, but this limit can be
raised by AWS support.
fargate certificate info
fargate certificate info <domain-name>
Inspect certificate
Show extended information for a certificate. Includes each validation for the
certificate which shows DNS records which must be created to validate domain
ownership.
fargate certificate validate
fargate certificate validate <domain-name>
Validate certificate ownership
fargate will automatically create DNS validation record to verify ownership for
any domain names that are hosted within Amazon Route 53. If your certificate
has aliases, a validation record will be attempted per alias. Any records whose
domains are hosted in other DNS hosting providers or in other DNS accounts
and cannot be automatically validated will have the necessary records output.
These records are also available in fargate certificate info \<domain-name>
.
AWS Certificate Manager may take up to several hours after the DNS records are
created to complete validation and issue the certificate.
fargate certificate destroy
fargate certificate destroy <domain-name>
Destroy certificate
In order to destroy a certificate, it must not be in use by any load balancers or
any other AWS resources.