github.com/anth0d/nomad@v0.0.0-20221214183521-ae3a0a2cad06/website/content/plugins/drivers/remote/ecs.mdx (about)

     1  ---
     2  layout: docs
     3  page_title: 'Task Driver Plugins: ECS Task Driver'
     4  description: >-
     5    The AWS ECS Task Driver is an example Remote Task Driver.
     6  ---
     7  
     8  # ECS Task Driver
     9  
    10  Name: `nomad-driver-ecs`
    11  
    12  Homepage: https://github.com/hashicorp/nomad-driver-ecs
    13  
    14  ~> **Note:** The ECS Task Driver is an example Remote Task Driver and **not
    15  intended for production use.**
    16  
    17  The ECS task driver plugin for Nomad allows running [AWS ECS][ecs] tasks via
    18  Nomad. Allocations for these jobs are scheduled onto Nomad clients like
    19  traditional task drivers, however the actual task is executed remotely in
    20  AWS ECS. The Nomad client agent manages the remote ECS task like any other
    21  local Nomad task: restarting it if it fails, stopping it when requested, etc.
    22  
    23  When a Nomad node assigned allocations with ECS tasks is drained, the ECS tasks
    24  are *not stopped.* Instead the replacement allocations reconnect to the
    25  original ECS tasks to avoid unnecessary downtime.
    26  
    27  If a Nomad node assigned allocations with ECS tasks crashes and is considered
    28  `down`, the replacement allocations for the `lost` allocations reconnect to the
    29  original ECS tasks to avoid unnecessary downtime. If the original crashed Nomad
    30  node restarts, it will detect `lost` allocations and stop monitoring them since
    31  a new node has taken over.
    32  
    33  ## Client Requirements
    34  
    35  The AWS ECS Task Driver is not currently built into Nomad and must be
    36  [downloaded][download] onto the client host in the configured [plugin
    37  directory][plugin_dir].
    38  
    39  ### Plugin Options
    40  
    41  Once the plugin binary is installed, the plugin must be configured in your
    42  Nomad client agent's HCL:
    43  
    44  ```hcl
    45  plugin "nomad-driver-ecs" {
    46    config {
    47      enabled = true
    48  
    49      #  AWS ECS Cluster to run tasks in
    50      cluster = "nomad-remote-driver-cluster"
    51  
    52      # AWS ECS Region to run tasks in
    53      region  = "us-east-1"
    54    }
    55  }
    56  ```
    57  
    58  - `cluster` - The [AWS ECS cluster][cluster] to run tasks in.
    59  - `region` - The [AWS region][region] to run tasks in.
    60  
    61  ## Task Configuration
    62  
    63  Nomad ECS tasks must first be defined for the ECS cluster. See the [Nomad ECS
    64  driver demo][demo] task for an example ECS task provisioned by Terraform.
    65  
    66  Once the ECS task is provisioned, Nomad may run it via a job:
    67  
    68  ```hcl
    69  job "nomad-ecs-demo" {
    70    datacenters = ["dc1"]
    71  
    72    group "ecs-remote-task-demo" {
    73      restart {
    74        attempts = 0
    75        mode     = "fail"
    76      }
    77  
    78      reschedule {
    79        delay = "5s"
    80      }
    81  
    82      task "http-server" {
    83        driver       = "ecs"
    84        kill_timeout = "1m" // increased from default to accomodate ECS.
    85  
    86        config {
    87          task {
    88            launch_type     = "FARGATE"
    89            task_definition = "nomad-remote-driver-demo:1"
    90            network_configuration {
    91              aws_vpc_configuration {
    92                assign_public_ip = "ENABLED"
    93                security_groups  = ["sg-0d647d4c7ce15034f"]
    94                subnets          = ["subnet-010b03f1a021887ff"]
    95              }
    96            }
    97          }
    98        }
    99      }
   100    }
   101  }
   102  ```
   103  
   104  - `config.task` stanza defines the configuration of the ECS task:
   105  
   106    - `launch_type` - The launch type on which to run your task.
   107    - `task_definition` - The family and revision (`family:revision`) or full ARN
   108      of the task definition to run.
   109    - `network_configuration` - The network configuration for the task (eg
   110      `awsvpc` for `FARGATE` tasks).
   111  
   112      - `aws_vpc_configuration` - The VPC subnets and security groups associated with a task.
   113  
   114        - `assign_public_ip` - Whether the task's elastic network interface receives a public IP address.
   115        - `security_groups` - The security groups associated with the task or service.
   116        - `subnets` - The subnets associated with the task or service.
   117  
   118  [cluster]: https://docs.aws.amazon.com/AmazonECS/latest/developerguide/clusters.html
   119  [ecs]: https://aws.amazon.com/ecs/
   120  [demo]: https://github.com/hashicorp/nomad-driver-ecs/tree/main/demo
   121  [download]: https://releases.hashicorp.com/nomad-driver-ecs/
   122  [plugin_dir]: /docs/configuration#plugin_dir
   123  [region]: https://docs.aws.amazon.com/general/latest/gr/ecs-service.html