README.md

ecs-scheduled-task

Allow scheduling tasks utilizing AWS cron expressions.

NOTE: Currently, this module does not support scheduling tasks in response to CloudWatch Events in ECS.

Example Usage

module "scheduled-task" {
  source = "[email protected]:techservicesillinois/terraform-aws-ecs-scheduled-task"

  name = "task-name"
  schedule_expression = "rate(1 hour)"

  network_configuration = {
    vpc      	     = "vpc-name"
    subnet_type      = "campus"
    assign_public_ip = false
  }
}

Argument Reference

• cluster - A name of an ECS cluster. (Default = default)

• desired_count - The number of instances of the task definition to place and keep running. (Default = 1)

• state - State of the rule, valid options are ENABLED, ENABLED_WITH_ALL_CLOUDTRAIL_MANAGEMENT_EVENTS, or DISABLED. (Default = ENABLED)

• launch_type - The launch type on which to run the service. The valid values are EC2 and FARGATE. (Default = FARGATE)

• name - The name of task to be scheduled. (Best practice would involve prefixing your service name to the task to uniquely identify the scheduled task)

• network_configuration - A Network Configuration block. This parameter is required for task definitions that use the awsvpc network mode to receive their own Elastic Network Interface, and it is not supported for other network modes.

• schedule_expression - The scheduling expression. For example, cron(0 20 * * ? *) or rate(5 minutes).

• security_groups - List of security group names (ID does not work!)

• tags - Tags to be applied to resources where supported.

• task_definition - (Optional) A task definition block. Task definition blocks are documented below.

• task_definition_arn - The family and revision (family:revision) or full ARN of the task definition that you want to run in your service. If given, the task definition block is ignored.

• volume - (Optional) A set of volume blocks that containers in your task may use. Volume blocks are documented below.

Debugging

• _debug - (Optional) If set, produce verbose output for debugging.

network_configuration

A network_configuration block supports the following:

• assign_public_ip – (Optional) Default is false.

• encrypted - (Optional) Encrypt data on volume at rest. Default: true.

• subnet_type - (Required) Subnet type (e.g., 'campus', 'private', 'public') for resource placement.

• subnets - (Required) The subnet IDs to associate with the task or service. NOTE: Optional when using subnet_type.

• vpc - (Required) The name of the virtual private cloud to be associated with the task or service. NOTE: Required when using subnet_type.

task_definition

If a task_definition_arn is not given, a container definition will be created for the service. The name of the automatically created container definition is the same as the ECS service name. The created container definition may optionally be further modified by specifying a task_definition block with one of more of the following options:

• container_definition_file - (Optional) An ECS service that does not use an existing task definition requires specifying characteristics for the set of containers that will comprise the service. This configuration is defined in the file specified in the container_definition_file argument, and consists of a list of valid container definitions provided as a valid JSON document. See Example Task Definitions for example container definitions.

Note that only the content of the containerDefinitions key in these example task definitions belongs in the specified container_definition_file. The default filename is either containers.json.tftmpl or containers.json. More details can be found at the end of this section.

• cpu - (Optional) The number of cpu units used by the task. Supported for FARGATE only, defaults to 256 (0.25 vCPU).

• memory - (Optional) The amount (in MiB) of memory used by the task. Supported for FARGATE only, defaults to 512.

• network_mode - (Optional) The Docker networking mode to use for the containers in the task. The valid values are none, bridge, awsvpc, and host.

• task_role_arn - (Optional) The ARN of an IAM role that allows your Amazon ECS container task to make calls to other AWS services.

• template_variables - (Optional) A block of template variables to be expanded while processing the container_definition_file. Used to configure template variables passed to the task definition.

task_definition.template_variables

This block itself is optional. However, if the block is defined by the caller, all of the following arguments must be specified. The arguments supported by this sub-object are as follows:

• docker_tag - (Required) The Docker tag for the image that is to be pulled from the ECR repository at the time the service's ECS tasks are launched.

• region - (Required) The AWS region which hosts the ECR repository from which images are to be pulled.

• registry_id - (Required) The registry ID is the AWS account number which owns the repository to be pulled at the time the service's ECS task is launched.

• splunk_index - (Optional) The Splunk index to which logs should be written. Only used when containers.json.tftpl is configured to use the AWS Splunk log driver.

Notes on the container_definition_file argument

If the task_definition block is defined, and its template_variables block is populated, this module runs the Terraform templatefile() function on the file named in the container_definition_file argument. By default, the file name is containers.json.tftmpl, but it can be overriden by the user. The output from the template's rendering is passed to the task definition.

The use of template variables helps make the Terraform configuration DRY by eliminating the need for manual editing – such as during the promotion of services from test to production accounts.

In order to expand template variables, the following conditions must be met:

• The Terraform configuration must include a template_variables wherein the values of each template variable are defined. Such variables are passed into the task definition at deployment time.
• A containers.json.tftpl file must exist, and should reference each of the template variables referred to in the Terraform configuration. The construct ${variable_name} is used to expand a supported template variable inside the containers.json.tftpl file.

Example containers.json.tftpl file using the AWS log driver

This example shows the pertinent parts of the containers.json.tftpl file when using the default AWS log driver. The three required template variables – docker_tag, region, and registry_id – are expanded and passed to the task definition.

[
  {
    "name": "foobar",
    "image": "${registry_id}.dkr.ecr.${region}.amazonaws.com/foobar:${docker_tag}",
    "logConfiguration": {
       "logDriver": "awslogs",
       "options": {
         "awslogs-stream-prefix": "foobar",
         "awslogs-group": "/service/foobar",
         "awslogs-region": "${region}"
      }
    }
  }
]

Example containers.json.tftpl file using the Splunk log driver

This example shows the pertinent parts of the containers.json.tftpl file when using the Splunk log driver. Note that the three required template variables – docker_tag, region, and registry_id – are required as with the previous example that uses the AWS log driver.

However, this example adds the splunk_index variable for expansion and passing the task definition.

Note that this example uses AWS Systems Manager Parameter Store to securely pass the Splunk token to the task at runtime. The Splunk token is a credential, and should thus not appear in the Terraform configuration.

[
  {
    "name": "foobar",
    "image": "${registry_id}.dkr.ecr.${region}.amazonaws.com/foobar:${docker_tag}",
    "logConfiguration": {
        "logDriver": "splunk",
        "options": {
            "splunk-url": "https://my-splunk-account.splunkcloud.com",
            "splunk-index": "${splunk_index}",
            "splunk-source": "pipeline-general",
            "splunk-format": "json",
            "splunk-gzip": "true"
            },
        "secretOptions": [
            {
            "name": "splunk-token",
            "valueFrom": "/service/foobar/splunk/hec_token"
            }
        ]
  }
]

Example containers.json file (no support for template rendering)

The following example depicts the "legacy" containers.json format which doesn't support template variables. This might be used in cases where a Docker image does not need to be pulled from Amazon ECR. In this type of use case, it may not be necessary to specify the registry_id, region, or docker tag.

Simply omit the template_variables block inside the task_definition block, and using the default file name of containers.json. (The name can be overriden by the user.) In this case, the container definition is simply passed in to the task definition without template expansion.

[
  {
    "name": "apache",
    "image": "httpd",
    "portMappings": [
      {
        "containerPort": 80
      }
    ]
  }
]

volume

A volume block supports the following:

• name - (Required) The name of the volume. This name is referenced in the sourceVolume parameter of container definition in the mountPoints section.

• host_path - (Optional) The path on the host container instance that is presented to the container. If not set, ECS will create a non persistent data volume that starts empty and is deleted after the task has finished.

• docker_volume_configuration - (Optional, but see note) Used to configure a Docker volume. NOTE: Due to limitations in Terraform object typing, either a valid docker_volume_configuration map or the value null must be specified.

• efs_volume_configuration - (Optional, but see note) Used to configure an EFS volume. NOTE: Due to limitations in Terraform object typing, either a valid efs_volume_configuration map or the value null must be specified.

volume = [
    {
      name      = "docker-volume"
      host_path = null

      docker_volume_configuration = null   # Needs to be specified as null, even if not used.
      efs_volume_configuration    = null   # Needs to be specified as null, even if not used.
    }
 ]

docker_volume_configuration

A docker_volume_configuration block appears within a volume block, and supports the following:

• scope - (Optional) The scope for the Docker volume, which determines its lifecycle, either task or shared. Docker volumes that are scoped to a task are automatically provisioned when the task starts and destroyed when the task stops. Docker volumes that are scoped as shared persist after the task stops.

• autoprovision - (Optional) If this value is true, the Docker volume is created if it does not already exist. Note: This field is only used if the scope is shared.

• driver - (Optional) The Docker volume driver to use. The driver value must match the driver name provided by Docker because it is used for task placement.

• driver_opts - (Optional) A map of Docker driver specific options.

• `labels - (Optional) A map of custom metadata to add to your Docker volume.

For more information, see Specifying a Docker volume in your Task Definition Developer Guide

efs_volume_configuration

An efs_volume_configuration block appears within a volume block, and supports the following:

• file_system_id - (Required) The ID of the EFS File System.

• root_directory - (Optional) The path to mount on the host.

volume = [
    {
      name = "efs-volume"
      host_path = null

      docker_volume_configuration = null

      efs_volume_configuration = {
        file_system_id = "fs-012345678"
        root_directory = null
      }
    }
 ]

For more information, see Specifying an Amazon EFS File System in your Task Definition.

Attributes Reference

The following attributes are exported:

• state – Is the task enabled.

• name - The name of the scheduled task.

• schedule_expression - The cron-like expression that determines when the scheduled task is to run.

• task_definition_arn - Full ARN of the task definition created for the scheduled task.