github.com/awslabs/fargatecli@v0.3.2-0.20210502061925-aa1c09cd404e/README.md (about) 1 # Fargate CLI 2 3 [](https://circleci.com/gh/jpignata/fargate/tree/master) 4 [](https://godoc.org/github.com/awslabs/fargatecli) 5 6 # NOTICE 7 8 :exclamation: :exclamation: :exclamation: Please note that this project is no longer actively maintained. A better option for new Fargate deployments on AWS is [the AWS Copilot CLI](https://github.com/aws/copilot-cli), which is both more featureful, and actively maintained by AWS. :exclamation: :exclamation: :exclamation: 9 10 11 ## Screencast 12 13 [](http://www.youtube.com/watch?v=P6iY6ovhbfc) 14 15 ## Usage 16 17 ### Configuration 18 19 #### Region 20 21 By default, fargate uses *us-east-1*. The CLI accepts a --region parameter and 22 will honor *AWS_REGION* and *AWS_DEFAULT_REGION* environment settings. Note that 23 specifying a region where all required services aren't available will return an 24 error. 25 26 See the [Region Table][region-table] for a breakdown of what services are 27 available in which regions. 28 29 #### Credentials 30 31 fargate is built using the [AWS SDK for Go][go-sdk] which looks for credentials 32 in the following locations: 33 34 1. [Environment Variables][go-env-vars] 35 36 1. [Shared Credentials File][go-shared-credentials-file] 37 38 1. [EC2 Instance Profile][go-iam-roles-for-ec2-instances] 39 40 For more information see [Specifying Credentials][go-specifying-credentials] in 41 the AWS SDK for Go documentation. 42 43 ### Commands 44 45 - [Tasks](#tasks) 46 - [Services](#services) 47 - [Load Balancers](#load-balancers) 48 - [Certificates](#certificates) 49 50 #### Global Flags 51 52 | Flag | Default | Description | 53 | --- | --- | --- | 54 | --cluster | fargate | ECS cluster name | 55 | --region | us-east-1 | AWS region | 56 | --no-color | false | Disable color output | 57 | --verbose | false | Verbose output | 58 59 #### Tasks 60 61 Tasks are one-time executions of your container. Instances of your task are run 62 until you manually stop them either through AWS APIs, the AWS Management 63 Console, or `fargate task stop`, or until they are interrupted for any reason. 64 65 - [list](#fargate-task-list) 66 - [run](#fargate-task-run) 67 - [info](#fargate-task-info) 68 - [ps](#fargate-task-ps) 69 - [logs](#fargate-task-logs) 70 - [stop](#fargate-task-stop) 71 72 ##### fargate task list 73 74 ```console 75 fargate task list 76 ``` 77 78 List running task groups 79 80 ##### fargate task run 81 82 ```console 83 fargate task run <task-group-name> [--num <count>] [--cpu <cpu-units>] [--memory <MiB>] 84 [--image <docker-image>] [--env <key=value>] 85 [--task-role <task-role>] [--subnet-id <subnet-id>] 86 [--security-group-id <security-group-id>] 87 ``` 88 89 Run new tasks 90 91 You must specify a task group name in order to interact with the task(s) in 92 subsequent commands to view logs, stop and inspect tasks. Task group names do 93 not have to be unique -- multiple configurations of task instances can be 94 started with the same task group. 95 96 Multiple instances of a task can be run by specifying a number in the --num 97 flag. If no number is specified, a single task instance will be run. 98 99 CPU and memory settings can be optionally specified as CPU units and mebibytes 100 respectively using the --cpu and --memory flags. Every 1024 CPU units is 101 equivilent to a single vCPU. AWS Fargate only supports certain combinations of 102 CPU and memory configurations: 103 104 | CPU (CPU Units) | Memory (MiB) | 105 | --------------- | ------------------------------------- | 106 | 256 | 512, 1024, or 2048 | 107 | 512 | 1024 through 4096 in 1GiB increments | 108 | 1024 | 2048 through 8192 in 1GiB increments | 109 | 2048 | 4096 through 16384 in 1GiB increments | 110 | 4096 | 8192 through 30720 in 1GiB increments | 111 112 If not specified, fargate will launch minimally sized tasks at 0.25 vCPU (256 113 CPU units) and 0.5GB (512 MiB) of memory. 114 115 The Docker container image to use in the task can be optionally specified via 116 the --image flag. If not specified, fargate will build a new Docker container 117 image from the current working directory and push it to Amazon ECR in a 118 repository named for the task group. If the current working directory is a git 119 repository, the container image will be tagged with the short ref of the HEAD 120 commit. If not, a timestamp in the format of YYYYMMDDHHMMSS will be used. 121 122 Environment variables can be specified via the --env flag. Specify --env with a 123 key=value parameter multiple times to add multiple variables. 124 125 Security groups can optionally be specified for the task by passing the 126 --security-group-id flag with a security group ID. To add multiple security 127 groups, pass --security-group-id with a security group ID multiple times. If 128 --security-group-id is omitted, a permissive security group will be applied to 129 the task. 130 131 By default, the task will be created in the default VPC and attached to the 132 default VPC subnets for each availability zone. You can override this by 133 specifying explicit subnets by passing the --subnet-id flag with a subnet ID. 134 135 A task role can be optionally specified via the --task-role flag by providing 136 eith a full IAM role ARN or the name of an IAM role. The tasks will be able to 137 assume this role. 138 139 ##### fargate task info 140 141 ```console 142 fargate task info <task-group-name> [--task <task-id>] 143 ``` 144 145 Inspect tasks 146 147 Shows extended information for each running task within a task group or for 148 specific tasks specified with the --task flag. Information includes environment 149 variables which could differ between tasks in a task group. To inspect multiple 150 specific tasks within a task group specific --task with a task ID multiple 151 times. 152 153 ##### fargate task ps 154 155 ```console 156 fargate task ps <task-group-name> 157 ``` 158 159 List running tasks 160 161 ##### fargate task logs 162 163 ```console 164 fargate task logs <task-group-name> [--follow] [--start <time-expression>] [--end <time-expression>] 165 [--filter <filter-expression>] [--task <task-id>] 166 ``` 167 168 Show logs from tasks 169 170 Return either a specific segment of task logs or tail logs in real-time using 171 the --follow option. Logs are prefixed by their log stream name which is in the 172 format of "fargate/\<task-group-name>/\<task-id>." 173 174 Follow will continue to run and return logs until interrupted by Control-C. If 175 --follow is passed --end cannot be specified. 176 177 Logs can be returned for specific tasks within a task group by passing a task 178 ID via the --task flag. Pass --task with a task ID multiple times in order to 179 retrieve logs from multiple specific tasks. 180 181 A specific window of logs can be requested by passing --start and --end options 182 with a time expression. The time expression can be either a duration or a 183 timestamp: 184 185 - Duration (e.g. -1h [one hour ago], -1h10m30s [one hour, ten minutes, and 186 thirty seconds ago], 2h [two hours from now]) 187 - Timestamp with optional timezone in the format of YYYY-MM-DD HH:MM:SS [TZ]; 188 timezone will default to UTC if omitted (e.g. 2017-12-22 15:10:03 EST) 189 190 You can filter logs for specific term by passing a filter expression via the 191 --filter flag. Pass a single term to search for that term, pass multiple terms 192 to search for log messages that include all terms. See the [CloudWatch Logs 193 documentation][cwl-filter-expression] for more details. 194 195 ##### fargate task stop 196 197 ```console 198 fargate task stop <task-group-name> [--task <task-id>] 199 ``` 200 201 Stop tasks 202 203 Stops all tasks within a task group if run with only a task group name or stops 204 individual tasks if one or more tasks are passed via the --task flag. Specify 205 --task with a task ID parameter multiple times to stop multiple specific tasks. 206 207 #### Services 208 209 Services manage long-lived instances of your containers that are run on AWS 210 Fargate. If your container exits for any reason, the service scheduler will 211 restart your containers and ensure your service has the desired number of 212 tasks running. Services can be used in concert with a load balancer to 213 distribute traffic amongst the tasks in your service. 214 215 - [list](#fargate-service-list) 216 - [create](#fargate-service-create) 217 - [deploy](#fargate-service-deploy) 218 - [info](#fargate-service-info) 219 - [logs](#fargate-service-logs) 220 - [ps](#fargate-service-ps) 221 - [scale](#fargate-service-scale) 222 - [env set](#fargate-service-env-set) 223 - [env unset](#fargate-service-env-unset) 224 - [env list](#fargate-service-env-list) 225 - [update](#fargate-service-update) 226 - [restart](#fargate-service-restart) 227 - [destroy](#fargate-service-destroy) 228 229 ##### fargate service list 230 231 ```console 232 fargate service list 233 ``` 234 235 List services 236 237 ##### fargate service create 238 239 ```console 240 fargate service create <service name> [--cpu <cpu units>] [--memory <MiB>] [--port <port-expression>] 241 [--lb <load-balancer-name>] [--rule <rule-expression>] 242 [--image <docker-image>] [--env <key=value>] [--num <count>] 243 [--task-role <task-role>] [--subnet-id <subnet-id>] 244 [--security-group-id <security-group-id>] 245 ``` 246 247 Create a new service 248 249 CPU and memory settings can be optionally specified as CPU units and mebibytes 250 respectively using the --cpu and --memory flags. Every 1024 CPU units is 251 equivilent to a single vCPU. AWS Fargate only supports certain combinations of 252 CPU and memory configurations: 253 254 | CPU (CPU Units) | Memory (MiB) | 255 | --------------- | ------------------------------------- | 256 | 256 | 512, 1024, or 2048 | 257 | 512 | 1024 through 4096 in 1GiB increments | 258 | 1024 | 2048 through 8192 in 1GiB increments | 259 | 2048 | 4096 through 16384 in 1GiB increments | 260 | 4096 | 8192 through 30720 in 1GiB increments | 261 262 If not specified, fargate will launch minimally sized tasks at 0.25 vCPU (256 263 CPU units) and 0.5GB (512 MiB) of memory. 264 265 The Docker container image to use in the service can be optionally specified 266 via the --image flag. If not specified, fargate will build a new Docker 267 container image from the current working directory and push it to Amazon ECR in 268 a repository named for the task group. If the current working directory is a 269 git repository, the container image will be tagged with the short ref of the 270 HEAD commit. If not, a timestamp in the format of YYYYMMDDHHMMSS will be used. 271 272 To use the service with a load balancer, a port must be specified when the 273 service is created. Specify a port by passing the --port flag and a port 274 expression of protocol:port-number. For example, if the service listens on port 275 80 and uses HTTP, specify HTTP:80. Valid protocols are HTTP, HTTPS, and TCP. 276 You can only specify a single port. 277 278 Services can optionally be configured to use a load balancer. To put a load 279 balancer in front a service, pass the --lb flag with the name of a load 280 balancer. If you specify a load balancer, you must also specify a port via the 281 --port flag to which the load balancer should forward requests. Optionally, 282 Application Load Balancers can be configured to route HTTP/HTTPS traffic to the 283 service based upon a rule. Rules are configured by passing one or more rules by 284 specifying the --rule flag along with a rule expression. Rule expressions are 285 in the format of TYPE=VALUE. Type can either be PATH or HOST. PATH matches the 286 PATH of the request and HOST matches the requested hostname in the HTTP 287 request. Both PATH and HOST types can include up to three wildcard characters: 288 \* to match multiple characters and ? to match a single character. If rules are 289 omitted, the service will be the load balancer's default action. 290 291 Environment variables can be specified via the --env flag. Specify --env with a 292 key=value parameter multiple times to add multiple variables. 293 294 Specify the desired count of tasks the service should maintain by passing the 295 --num flag with a number. If you omit this flag, fargate will configure a 296 service with a desired number of tasks of 1. 297 298 Security groups can optionally be specified for the service by passing the 299 --security-group-id flag with a security group ID. To add multiple security 300 groups, pass --security-group-id with a security group ID multiple times. If 301 --security-group-id is omitted, a permissive security group will be applied to 302 the service. 303 304 By default, the service will be created in the default VPC and attached 305 to the default VPC subnets for each availability zone. You can override this by 306 specifying explicit subnets by passing the --subnet-id flag with a subnet ID. 307 308 A task role can be optionally specified via the --task-role flag by providing 309 eith a full IAM role ARN or the name of an IAM role. The tasks run by the 310 service will be able to assume this role. 311 312 ##### fargate service deploy 313 314 ```console 315 fargate service deploy <service-name> [--image <docker-image>] 316 ``` 317 318 Deploy new image to service 319 320 The Docker container image to use in the service can be optionally specified 321 via the --image flag. If not specified, fargate will build a new Docker 322 container image from the current working directory and push it to Amazon ECR in 323 a repository named for the task group. If the current working directory is a 324 git repository, the container image will be tagged with the short ref of the 325 HEAD commit. If not, a timestamp in the format of YYYYMMDDHHMMSS will be used. 326 327 ##### fargate service info 328 329 ```console 330 fargate service info <service-name> 331 ``` 332 333 Inspect service 334 335 Show extended information for a service including load balancer configuration, 336 active deployments, and environment variables. 337 338 Deployments show active versions of your service that are running. Multiple 339 deployments are shown if a service is transitioning due to a deployment or 340 update to configuration such a CPU, memory, or environment variables. 341 342 ##### fargate service logs 343 344 ```console 345 fargate service logs <service-name> [--follow] [--start <time-expression>] [--end <time-expression>] 346 [--filter <filter-expression>] [--task <task-id>] 347 ``` 348 349 Show logs from tasks in a service 350 351 Return either a specific segment of service logs or tail logs in real-time 352 using the --follow option. Logs are prefixed by their log stream name which is 353 in the format of "fargate/\<service-name>/\<task-id>." 354 355 Follow will continue to run and return logs until interrupted by Control-C. If 356 --follow is passed --end cannot be specified. 357 358 Logs can be returned for specific tasks within a service by passing a task ID 359 via the --task flag. Pass --task with a task ID multiple times in order to 360 retrieve logs from multiple specific tasks. 361 362 A specific window of logs can be requested by passing --start and --end options 363 with a time expression. The time expression can be either a duration or a 364 timestamp: 365 366 - Duration (e.g. -1h [one hour ago], -1h10m30s [one hour, ten minutes, and 367 thirty seconds ago], 2h [two hours from now]) 368 - Timestamp with optional timezone in the format of YYYY-MM-DD HH:MM:SS [TZ]; 369 timezone will default to UTC if omitted (e.g. 2017-12-22 15:10:03 EST) 370 371 You can filter logs for specific term by passing a filter expression via the 372 --filter flag. Pass a single term to search for that term, pass multiple terms 373 to search for log messages that include all terms. See the [CloudWatch Logs 374 documentation][cwl-filter-expression] for more details. 375 376 ##### fargate service ps 377 378 ```console 379 fargate service ps <service-name> 380 ``` 381 382 List running tasks for a service 383 384 ##### fargate service scale 385 386 ```console 387 fargate service scale <service-name> <scale-expression> 388 ``` 389 390 Scale number of tasks in a service 391 392 Changes the number of desired tasks to be run in a service by the given scale 393 expression. A scale expression can either be an absolute number or a delta 394 specified with a sign such as +5 or -2. 395 396 ##### fargate service env set 397 398 ```console 399 fargate service env set <service-name> --env <key=value> 400 ``` 401 402 Set environment variables 403 404 At least one environment variable must be specified via the --env flag. Specify 405 --env with a key=value parameter multiple times to add multiple variables. 406 407 ##### fargate service env unset 408 409 ```console 410 fargate service env unset <service-name> --key <key-name> 411 ``` 412 413 Unset environment variables 414 415 Unsets the environment variable specified via the --key flag. Specify --key with 416 a key name multiple times to unset multiple variables. 417 418 ##### fargate service env list 419 420 ```console 421 fargate service env list <service-name> 422 ``` 423 424 Show environment variables 425 426 ##### fargate service update 427 428 ```console 429 fargate service update <service-name> [--cpu <cpu-units>] [--memory <MiB>] 430 ``` 431 432 Update service configuration 433 434 CPU and memory settings are specified as CPU units and mebibytes respectively 435 using the --cpu and --memory flags. Every 1024 CPU units is equivilent to a 436 single vCPU. AWS Fargate only supports certain combinations of CPU and memory 437 configurations: 438 439 | CPU (CPU Units) | Memory (MiB) | 440 | --------------- | ------------------------------------- | 441 | 256 | 512, 1024, or 2048 | 442 | 512 | 1024 through 4096 in 1GiB increments | 443 | 1024 | 2048 through 8192 in 1GiB increments | 444 | 2048 | 4096 through 16384 in 1GiB increments | 445 | 4096 | 8192 through 30720 in 1GiB increments | 446 447 At least one of --cpu or --memory must be specified. 448 449 ##### fargate service restart 450 451 ```console 452 fargate service restart <service-name> 453 ``` 454 455 Restart service 456 457 Creates a new set of tasks for the service and stops the previous tasks. This 458 is useful if your service needs to reload data cached from an external source, 459 for example. 460 461 ##### fargate service destroy 462 463 ```console 464 fargate service destroy <service-name> 465 ``` 466 467 Destroy service 468 469 In order to destroy a service, it must first be scaled to 0 running tasks. 470 471 #### Load Balancers 472 473 Load balancers distribute incoming traffic between the tasks within a service 474 for HTTP/HTTPS and TCP applications. HTTP/HTTPS load balancers can route to 475 multiple services based upon rules you specify when you create a new service. 476 477 - [list](#fargate-lb-list) 478 - [create](#fargate-lb-create) 479 - [destroy](#fargate-lb-destroy) 480 - [alias](#fargate-lb-alias) 481 - [info](#fargate-lb-info) 482 483 ##### fargate lb list 484 485 ```console 486 fargate lb list 487 ``` 488 489 List load balancers 490 491 ##### fargate lb create 492 493 ```console 494 fargate lb create <load-balancer-name> --port <port-expression> [--certificate <certificate-name>] 495 [--subnet-id <subnet-id>] [--security-group-id <security-group-id>] 496 [--scheme <lb-scheme>] 497 ``` 498 499 Create a load balancer 500 501 At least one port must be specified for the load balancer listener via the 502 --port flag and a port expression of protocol:port-number. For example, if you 503 wanted an HTTP load balancer to listen on port 80, you would specify HTTP:80. 504 Valid protocols are HTTP, HTTPS, and TCP. You can specify multiple listeners by 505 passing the --port flag with a port expression multiple times. You cannot mix 506 TCP ports with HTTP/HTTPS ports on a single load balancer. 507 508 You can optionally include certificates to secure HTTPS ports by passed the 509 --certificate flag along with a certificate name. This option can be specified 510 multiple times to add additional certificates to a single load balancer which 511 uses Service Name Identification (SNI) to select the appropriate certificate 512 for the request. 513 514 By default, the load balancer will be created in the default VPC and attached 515 to the default VPC subnets for each availability zone. You can override this by 516 specifying explicit subnets by passing the --subnet-id flag with a subnet ID. 517 HTTP/HTTPS load balancers require at least two subnets attached while a TCP 518 load balancer requires only one. You may only specify a single subnet from each 519 availability zone. 520 521 Security groups can optionally be specified for HTTP/HTTPS load balancers by 522 passing the --security-group-id flag with a security group ID. To add multiple 523 security groups, pass --security-group-id with a security group ID multiple 524 times. If --security-group-id is omitted, a permissive security group will be 525 applied to the load balancer. 526 527 You can also choose the scheme type for load balancer via the --scheme flag. 528 By default, load balancers are internet-facing. 529 530 ##### fargate lb destroy 531 532 ```console 533 fargate lb destroy <load-balancer-name> 534 ``` 535 536 Destroy load balancer 537 538 ##### fargate lb alias 539 540 ```console 541 fargate lb alias <load-balancer-name> <hostname> 542 ``` 543 544 Create a load balancer alias record 545 546 Create an alias record to the load balancer for domains that are hosted within 547 Amazon Route 53 and within the same AWS account. If you're using another DNS 548 provider or host your domains in a different account, you will need to manually 549 create this record. 550 551 ##### fargate lb info 552 553 ```console 554 fargate lb info <load-balancer-name> 555 ``` 556 557 Inspect load balancer 558 559 Returns extended information about a load balancer including a list of 560 listeners, rules, and certificates in use by the load balancer. 561 562 563 #### Certificates 564 565 Certificates are TLS certificates issued by or imported into AWS Certificate 566 Manager for use in securing traffic between load balancers and end users. ACM 567 provides TLS certificates free of charge for use within AWS resources. 568 569 - [list](#fargate-certificate-list) 570 - [import](#fargate-certificate-import) 571 - [request](#fargate-certificate-request) 572 - [info](#fargate-certificate-info) 573 - [validate](#fargate-certificate-validate) 574 - [destroy](#fargate-certificate-destroy) 575 576 ##### fargate certificate list 577 578 ```console 579 fargate certificate list 580 ``` 581 582 List certificates 583 584 ##### fargate certificate import 585 586 ```console 587 fargate certificate import <domain-name> --certificate <filename> --key <filename> [--chain <filename>] 588 ``` 589 590 Import a certificate 591 592 Upload a certificate from a certificate file, a private key file, and optionally 593 an intermediate certificate chain file. The files must be PEM-encoded and the 594 private key must not be encrypted or protected by a passphrase. See the 595 [AWS Certificate Manager documentation][acm-import-cert] for more details. 596 597 ##### fargate certificate request 598 599 ```console 600 fargate certificate request <domain-name> [--alias <domain-name>] 601 ``` 602 603 Request a certificate 604 605 Certificates can be for a fully qualified domain name (e.g. www.example.com) or 606 a wildcard domain name (e.g. *.example.com). You can add aliases to a 607 certificate by specifying additional domain names via the --alias flag. To add 608 multiple aliases, pass --alias multiple times. By default, AWS Certificate 609 Manager has a limit of 10 domain names per certificate, but this limit can be 610 raised by AWS support. 611 612 ##### fargate certificate info 613 614 ```console 615 fargate certificate info <domain-name> 616 ``` 617 618 Inspect certificate 619 620 Show extended information for a certificate. Includes each validation for the 621 certificate which shows DNS records which must be created to validate domain 622 ownership. 623 624 ##### fargate certificate validate 625 626 ```console 627 fargate certificate validate <domain-name> 628 ``` 629 630 Validate certificate ownership 631 632 fargate will automatically create DNS validation record to verify ownership for 633 any domain names that are hosted within Amazon Route 53. If your certificate 634 has aliases, a validation record will be attempted per alias. Any records whose 635 domains are hosted in other DNS hosting providers or in other DNS accounts 636 and cannot be automatically validated will have the necessary records output. 637 These records are also available in `fargate certificate info \<domain-name>`. 638 639 AWS Certificate Manager may take up to several hours after the DNS records are 640 created to complete validation and issue the certificate. 641 642 ##### fargate certificate destroy 643 644 ```console 645 fargate certificate destroy <domain-name> 646 ``` 647 648 Destroy certificate 649 650 In order to destroy a certificate, it must not be in use by any load balancers or 651 any other AWS resources. 652 653 [region-table]: https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/ 654 [go-sdk]: https://aws.amazon.com/documentation/sdk-for-go/ 655 [go-env-vars]: http://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#environment-variables 656 [go-shared-credentials-file]: http://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#shared-credentials-file 657 [go-iam-roles-for-ec2-instances]: http://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#iam-roles-for-ec2-instances 658 [go-specifying-credentials]: http://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials 659 [cwl-filter-expression]: http://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html#matching-terms-events 660 [acm-import-cert]: http://docs.aws.amazon.com/acm/latest/APIReference/API_ImportCertificate.html