github.com/illyabusigin/fargate@v0.2.4-0.20180913204215-da49df54049c/README.md (about) 1 # Fargate CLI 2 3 [](https://circleci.com/gh/jpignata/fargate/tree/master) 4 [](https://godoc.org/github.com/jpignata/fargate) 5 6 ## Screencast 7 8 [](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 ``` 493 494 Create a load balancer 495 496 At least one port must be specified for the load balancer listener via the 497 --port flag and a port expression of protocol:port-number. For example, if you 498 wanted an HTTP load balancer to listen on port 80, you would specify HTTP:80. 499 Valid protocols are HTTP, HTTPS, and TCP. You can specify multiple listeners by 500 passing the --port flag with a port expression multiple times. You cannot mix 501 TCP ports with HTTP/HTTPS ports on a single load balancer. 502 503 You can optionally include certificates to secure HTTPS ports by passed the 504 --certificate flag along with a certificate name. This option can be specified 505 multiple times to add additional certificates to a single load balancer which 506 uses Service Name Identification (SNI) to select the appropriate certificate 507 for the request. 508 509 By default, the load balancer will be created in the default VPC and attached 510 to the default VPC subnets for each availability zone. You can override this by 511 specifying explicit subnets by passing the --subnet-id flag with a subnet ID. 512 HTTP/HTTPS load balancers require at least two subnets attached while a TCP 513 load balancer requires only one. You may only specify a single subnet from each 514 availability zone. 515 516 Security groups can optionally be specified for HTTP/HTTPS load balancers by 517 passing the --security-group-id flag with a security group ID. To add multiple 518 security groups, pass --security-group-id with a security group ID multiple 519 times. If --security-group-id is omitted, a permissive security group will be 520 applied to the load balancer. 521 522 ##### fargate lb destroy 523 524 ```console 525 fargate lb destroy <load-balancer-name> 526 ``` 527 528 Destroy load balancer 529 530 ##### fargate lb alias 531 532 ```console 533 fargate lb alias <load-balancer-name> <hostname> 534 ``` 535 536 Create a load balancer alias record 537 538 Create an alias record to the load balancer for domains that are hosted within 539 Amazon Route 53 and within the same AWS account. If you're using another DNS 540 provider or host your domains in a different account, you will need to manually 541 create this record. 542 543 ##### fargate lb info 544 545 ```console 546 fargate lb info <load-balancer-name> 547 ``` 548 549 Inspect load balancer 550 551 Returns extended information about a load balancer including a list of 552 listeners, rules, and certificates in use by the load balancer. 553 554 555 #### Certificates 556 557 Certificates are TLS certificates issued by or imported into AWS Certificate 558 Manager for use in securing traffic between load balancers and end users. ACM 559 provides TLS certificates free of charge for use within AWS resources. 560 561 - [list](#fargate-certificate-list) 562 - [import](#fargate-certificate-import) 563 - [request](#fargate-certificate-request) 564 - [info](#fargate-certificate-info) 565 - [validate](#fargate-certificate-validate) 566 - [destroy](#fargate-certificate-destroy) 567 568 ##### fargate certificate list 569 570 ```console 571 fargate certificate list 572 ``` 573 574 List certificates 575 576 ##### fargate certificate import 577 578 ```console 579 fargate certificate import <domain-name> --certificate <filename> --key <filename> [--chain <filename>] 580 ``` 581 582 Import a certificate 583 584 Upload a certificate from a certificate file, a private key file, and optionally 585 an intermediate certificate chain file. The files must be PEM-encoded and the 586 private key must not be encrypted or protected by a passphrase. See the 587 [AWS Certificate Manager documentation][acm-import-cert] for more details. 588 589 ##### fargate certificate request 590 591 ```console 592 fargate certificate request <domain-name> [--alias <domain-name>] 593 ``` 594 595 Request a certificate 596 597 Certificates can be for a fully qualified domain name (e.g. www.example.com) or 598 a wildcard domain name (e.g. *.example.com). You can add aliases to a 599 certificate by specifying additional domain names via the --alias flag. To add 600 multiple aliases, pass --alias multiple times. By default, AWS Certificate 601 Manager has a limit of 10 domain names per certificate, but this limit can be 602 raised by AWS support. 603 604 ##### fargate certificate info 605 606 ```console 607 fargate certificate info <domain-name> 608 ``` 609 610 Inspect certificate 611 612 Show extended information for a certificate. Includes each validation for the 613 certificate which shows DNS records which must be created to validate domain 614 ownership. 615 616 ##### fargate certificate validate 617 618 ```console 619 fargate certificate validate <domain-name> 620 ``` 621 622 Validate certificate ownership 623 624 fargate will automatically create DNS validation record to verify ownership for 625 any domain names that are hosted within Amazon Route 53. If your certificate 626 has aliases, a validation record will be attempted per alias. Any records whose 627 domains are hosted in other DNS hosting providers or in other DNS accounts 628 and cannot be automatically validated will have the necessary records output. 629 These records are also available in `fargate certificate info \<domain-name>`. 630 631 AWS Certificate Manager may take up to several hours after the DNS records are 632 created to complete validation and issue the certificate. 633 634 ##### fargate certificate destroy 635 636 ```console 637 fargate certificate destroy <domain-name> 638 ``` 639 640 Destroy certificate 641 642 In order to destroy a certificate, it must not be in use by any load balancers or 643 any other AWS resources. 644 645 [region-table]: https://aws.amazon.com/about-aws/global-infrastructure/regional-product-services/ 646 [go-sdk]: https://aws.amazon.com/documentation/sdk-for-go/ 647 [go-env-vars]: http://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#environment-variables 648 [go-shared-credentials-file]: http://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#shared-credentials-file 649 [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 650 [go-specifying-credentials]: http://docs.aws.amazon.com/sdk-for-go/v1/developer-guide/configuring-sdk.html#specifying-credentials 651 [cwl-filter-expression]: http://docs.aws.amazon.com/AmazonCloudWatch/latest/logs/FilterAndPatternSyntax.html#matching-terms-events 652 [acm-import-cert]: http://docs.aws.amazon.com/acm/latest/APIReference/API_ImportCertificate.html