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