Query

aws::ecs-task-definition

Create an ECS task definition.

Example

aws::ecs-task-definition ecs-task-definition-ec2-example
    family: "ecs-task-definition-ec2-example"
    requires-compatibilities: ["EC2"]
    network-mode: "bridge"
    task-role: $(aws::iam-role ecs-task-role-example)
    execution-role: $(aws::iam-role ecs-task-execution-role-example)
    cpu: 512
    memory: 2048

    container-definition
        name: "ecs-container-definition-example"
        image: "ecs-container-definition-example"
        cpu: 256
        memory: 2048
        memory-reservation: 1024
        links: ["ecs-container-definition-example-2"]

        port-mapping
            container-port: 80
            host-port: 210
            protocol: tcp
        end

        entry-point: ["executable", "param1", "param2"]
        command: ["cparam1","cparam2"]

        environment: {
            VAR: "value"
        }

        mount-point
            source-volume: "ecs-volume-example"
            container-path: "/example-host-volume-path"
            read-only: false
        end

        volume-from
            source-container: "ecs-container-definition-example-2"
            read-only: false
        end

        linux-parameters
            init-process-enabled: true
            shared-memory-size: 128

            capabilities
                add: ["AUDIT_CONTROL", "SYS_ADMIN", "SYS_TTY_CONFIG"]
                drop: ["BLOCK_SUSPEND", "SETPCAP", "WAKE_ALARM"]
            end

            device
                host-path: "/example-device-host-path"
                container-path: "/example-device-container-path"
                permissions: ["read", "write"]
            end

            tmpfs
                container-path: "/example-tmpfs-path"
                size: 64
                mount-options: ["exec", "async", "remount"]
            end

            max-swap: 128
            swappiness: 60
        end

        extra-host
            hostname: "example-extra-hostname"
            ip-address: "40.40.40.40"
        end

        ulimit
            name: "core"
            soft-limit: 256
            hard-limit: 512
        end

        log-configuration
            log-driver: "syslog"
            options: {
                example-option: "example-value"
            }
        end

        health-check
            command: [ "CMD-SHELL", "curl -f http://localhost/ || exit 1" ]
            interval: 30
            timeout: 5
            retries: 3
            start-period: 20
        end

        system-control
            namespace: "net.ipv4.ip_forward"
            value: "1"
        end

        resource-requirement
            type: "GPU"
            value: "4"
        end

        resource-requirement
            type: "InferenceAccelerator"
            value: "ecs-inference-accelerator-example"
        end

        firelens-configuration
            type: "fluentd"
            options: {
                enable-ecs-log-metadata: "true"
            }
        end

        essential: true
        start-timeout: 180
        stop-timeout: 30
        hostname: "example-hostname"
        user: "0:example-group"
        working-directory: "/example-working-directory"
        disable-networking: false
        privileged: true
        readonly-root-filesystem: false
        dns-servers: ["8.8.8.8"]
        interactive: true
        pseudo-terminal: true

        docker-labels: {
            example-label: "example-value"
        }
    end

    container-definition
        name: "ecs-container-definition-example-2"
        image: "ecs-container-definition-example-2"
        cpu: 256
        memory: 2048
        memory-reservation: 1024
        essential: false

        depends-on
            container-name: "ecs-container-definition-example"
            condition: "HEALTHY"
        end

        log-configuration
            log-driver: "awsfirelens"
            options: {
                example-option: "example-value"
            }
        end
    end

    volume
        name: "ecs-volume-example"

        docker-volume-configuration
            scope: "shared"
            autoprovision: true
            driver: "local"
            driver-opts: {
                example-option: "example-value"
            }
            labels: {
                example-label: "example-value"
            }
        end
    end

    inference-accelerator
        device-name: "ecs-inference-accelerator-example"
        device-type: "eia1.medium"
    end

    placement-constraint
        type: "memberOf"
        expression: "runningTasksCount == 1"
    end

    pid-mode: "host"
    ipc-mode: "host"

    tags: {
        Name: "ecs-task-definition-ec2-example"
    }

end

Attributes

Attribute	Description
family	The name shared among all revisions of a task definition. Must be a string 1 to 255 characters long containing letters, numbers, and hyphens. Valid values satisfy the regex: [[-a-zA-Z0-9]{1,255}]. (Required)
task-role	The IAM role that containers in this task can assume. All containers in this task are granted the permissions that are specified in this role.
execution-role	The task execution role that the Amazon ECS container agent and the Docker daemon can assume.
requires-compatibilities set	The launch type required by the task. Valid values are EC2 and FARGATE.
container-definition list subresource	A list of container definitions that describes the different containers that make up the task. (Required) (Required) name The name of the container. Must be a string 1 to 255 characters long containing letters, numbers, and hyphens. Valid values satisfy the regex: [[-a-zA-Z0-9]{1,255}]. (Required) image The image used to start a container. This string is passed directly to the Docker daemon. (Required) cpu The number of cpu units reserved for the container. memory The amount (in MiB) of memory to present to the container. If your container attempts to exceed the memory specified here, the container is killed. The total amount of memory reserved for all containers within a task must be lower than the task memory value, if one is specified. If a task-level memory value is not specified, you must specify a non-zero integer for one or both of memory or memory-reservation in a container definition. If you specify both, memory must be greater than memory-reservation. Minimum allowed value is 4. memory-reservation The soft limit (in MiB) of memory to reserve for the container. When system memory is under heavy contention, Docker attempts to keep the container memory to this soft limit. However, the container can consume more memory when it needs to, up to either the hard limit specified with the memory parameter (if applicable), or all of the available memory on the container instance, whichever comes first. If a task-level memory value is not specified, you must specify a non-zero integer for one or both of memory or memory-reservation in a container definition. If you specify both, memory must be greater than memory-reservation. Minimum allowed value is 4. links list Allows containers to communicate with each other without the need for any port-mapping. This parameter is only supported if the network-mode of a task definition is bridge. port-mapping list subresource The list of port mappings for the container. Port mappings allow containers to access ports on the host container instance to send or receive traffic. container-port The port number on the container that is bound to the user-specified or automatically assigned host-port. (Required) host-port The port number on the container instance to reserve for your container. If you are using containers in a task with the awsvpc or host network-mode, the host-port can either be left blank or set to the same value as the container-port. If you are using containers in a task with the bridge network-mode, you can specify a non-reserved host-port for your container port mapping, or you can omit the host-port (or set it to 0) while specifying a container-port and your container automatically receives a port in the ephemeral port range for your container instance operating system and Docker version. protocol The protocol used for the port mapping. Defaults to tcp. Valid values are tcp or udp. essential If this parameter is set to true, and the container fails or stops for any reason, all other containers that are part of the task are stopped. Defaults to true. entry-point list The entry point that is passed to the container. command list The command that is passed to the container. If there are multiple arguments, each argument should be a separate string in the list. environment map The environment variables to pass to a container. mount-point list subresource The mount points for data volumes in your container. source-volume The name of the volume to mount. Must be the name of a task definition volume. (Required) container-path The path on the container at which to mount the host volume. (Required) read-only If enabled, the container has read-only access to the volume. Otherwise, the container can write to the volume. Defaults to false. volume-from list subresource Data volumes to mount from another container. source-container The name of another container within the same task definition from which to mount volumes. (Required) read-only If true, the container has read-only access to the volume. Otherwise, the container can write to the volume. Defaults to false. linux-parameters subresource Linux-specific modifications that are applied to the container, such as Linux kernel capabilities. capabilities subresource The Linux capabilities for the container that are added to or dropped from the default configuration provided by Docker. add list The Linux capabilities for the container that have been added to the default configuration provided by Docker. Valid values are ALL, AUDIT_CONTROL, AUDIT_WRITE, BLOCK_SUSPEND, CHOWN, DAC_OVERRIDE, DAC_READ_SEARCH, FOWNER, FSETID, IPC_LOCK, IPC_OWNER, KILL, LEASE, LINUX_IMMUTABLE, MAC_ADMIN, MAC_OVERRIDE, MKNOD, NET_ADMIN, NET_BIND_SERVICE, NET_BROADCAST, NET_RAW, SETFCAP, SETGID, SETPCAP, SETUID, SYS_ADMIN, SYS_BOOT, SYS_CHROOT, SYS_MODULE, SYS_NICE, SYS_PACCT, SYS_PTRACE, SYS_RAWIO, SYS_RESOURCE, SYS_TIME, SYS_TTY_CONFIG, SYSLOG and WAKE_ALARM. drop list The Linux capabilities for the container that have been removed from the default configuration provided by Docker. Valid values are ALL, AUDIT_CONTROL, AUDIT_WRITE, BLOCK_SUSPEND, CHOWN, DAC_OVERRIDE, DAC_READ_SEARCH, FOWNER, FSETID, IPC_LOCK, IPC_OWNER, KILL, LEASE, LINUX_IMMUTABLE, MAC_ADMIN, MAC_OVERRIDE, MKNOD, NET_ADMIN, NET_BIND_SERVICE, NET_BROADCAST, NET_RAW, SETFCAP, SETGID, SETPCAP, SETUID, SYS_ADMIN, SYS_BOOT, SYS_CHROOT, SYS_MODULE, SYS_NICE, SYS_PACCT, SYS_PTRACE, SYS_RAWIO, SYS_RESOURCE, SYS_TIME, SYS_TTY_CONFIG, SYSLOG and WAKE_ALARM. device list subresource Any host devices to expose to the container. Not supported under task definitions whose requires-compatibilities parameter contains FARGATE. host-path The path for the device on the host container instance. (Required) container-path The path inside the container at which to expose the host device. permissions list The explicit permissions to provide to the container for the device. By default, the container has permissions for read, write, and mknod for the device. Valid values are read, write and mknod. init-process-enabled Enable to run an init process inside the container that forwards signals and reaps processes. shared-memory-size The value for the size (in MiB) of the /dev/shm volume. Not supported under task definitions whose requires-compatibilities parameter contains FARGATE. tmpfs list subresource The container path, mount options, and size (in MiB) of the tmpfs mount. Not supported under task definitions whose requires-compatibilities parameter contains FARGATE. container-path The absolute file path where the tmpfs volume is to be mounted. (Required) size The size (in MiB) of the tmpfs volume. Minimum allowed value is 1. (Required) mount-options list The list of tmpfs volume mount options. Valid values are defaults, ro, rw, suid, nosuid, dev, nodev, exec, noexec, sync, async, dirsync, remount, mand, nomand, atime, noatime, diratime, nodiratime, bind, rbind, unbindable, runbindable, private, rprivate, shared, rshared, slave, rslave, relatime, norelatime, strictatime, nostrictatime, mode, uid, gid, nr_inodes, nr_blocks and mpol. max-swap The total amount of swap memory (in MiB) a container can use. If a value of 0 is specified, the container will not use swap. Not supported under task definitions whose requires-compatibilities parameter contains FARGATE. Minimum allowed value is 0. swappiness This allows you to tune a container’s memory swappiness behavior. A swappiness value of 0 will cause swapping to not happen unless absolutely necessary. A swappiness value of 100 will cause pages to be swapped very aggressively. Defaults to 60. Can only be set if max-swap is set. Valid values are between 0 to 100. depends-on list subresource The dependencies defined for container startup and shutdown. A container can contain multiple dependencies. When a dependency is defined for container startup, for container shutdown it is reversed. container-name The name of a container. (Required) condition The dependency condition of the container. Valid values are START, COMPLETE, SUCCESS or HEALTHY. (Required) start-timeout Time duration (in seconds) to wait before giving up on resolving dependencies for a container. stop-timeout Time duration (in seconds) to wait before the container is forcefully killed if it doesn’t exit normally on its own. Defaults to 30. Maximum allowed value is 120. hostname The hostname to use for your container. This parameter is not supported if the task definition’s network-mode is awsvpc. user The user name to use inside the container. You can use the following formats. If specifying a UID or GID, you must specify it as a positive integer. user user:group uid uid:gid user:gid uid:group working-directory The working directory in which to run commands inside the container. disable-networking If true, networking is disabled within the container. privileged If true, the container is given elevated privileges on the host container instance (similar to the root user). This parameter is not supported when the task definition’s ‘requires-compatibilities’ parameter contains ‘FARGATE’. readonly-root-filesystem If true, the container is given read-only access to its root file system. dns-servers list A list of DNS servers that are presented to the container. dns-search-domains list A list of DNS search domains that are presented to the container. extra-host list subresource A list of hostnames and IP address mappings to append to the /etc/hosts file on the container. This parameter is not supported if the task definition’s network-mode is awsvpc. hostname The hostname to use in the /etc/hosts entry. (Required) ip-address The IP address to use in the /etc/hosts entry. (Required) docker-security-options list A list of strings to provide custom labels for SELinux and AppArmor multi-level security systems. This parameter is not supported when the task definition’s ‘requires-compatibilities’ parameter contains ‘FARGATE’ interactive If true, this allows you to deploy containerized applications that require stdin or a tty to be allocated. pseudo-terminal If true, a TTY is allocated. docker-labels map A key/value map of labels to add to the container. ulimit list subresource A list of ulimits to set in the container. name The type of the ulimit. Valid values are core, cpu, data, fsize, locks, memlock, msgqueue, nice, nofile, nproc, rss, rtprio, rttime, sigpending or stack. (Required) soft-limit The soft limit for the ulimit type. (Required) hard-limit The hard limit for the ulimit type. (Required) log-configuration subresource The log configuration specification for the container. log-driver The log driver to use for the container. When the task definition’s requires-compatibilities parameter contains FARGATE, the only supported log drivers are awslogs, splunk, and awsfirelens. Valid values are json-file, syslog, journald, gelf, fluentd, awslogs, splunk, awsfirelens, logentries or sumologic. (Required) options map The configuration options to send to the log driver. health-check subresource The container health check command and associated configuration parameters for the container. command list A list of strings representing the command that the container runs to determine if it is healthy. The list must start with CMD to execute the command arguments directly, or CMD-SHELL to run the command with the container’s default shell. (Required) interval The time period in seconds between each health check execution. Defaults to 30. Valid values are between 5 to 300. timeout The time period in seconds to wait for a health check to succeed before it is considered a failure. Defaults to 5. Valid values are between 2 to 60. retries The number of times to retry a failed health check before the container is considered unhealthy. Defaults to 3. Valid values are between 1 to 10. start-period The optional grace period within which to provide containers time to bootstrap before failed health checks count towards the maximum number of retries. If a health check succeeds within the start-period, then the container is considered healthy and any subsequent failures count toward the maximum number of retries. This parameter is disabled by default. Valid values are between 0 to 300. system-control list subresource A list of namespaced kernel parameters to set in the container. This parameter is not supported when the task definition’s ‘requires-compatibilities’ parameter contains ‘FARGATE’. namespace The namespaced kernel parameter for which to set a value. (Required) value The value for the namespaced kernel parameter specified in namespace. resource-requirement list subresource The type and amount of a resource to assign to a container. This parameter is not supported when the task definition’s ‘requires-compatibilities’ parameter contains ‘FARGATE’. type The type of resource to assign to a container. Valid values are GPU or InferenceAccelerator. (Required) value The value for the specified resource type. If the GPU type is used, the value is the number of physical GPUs the Amazon ECS container agent will reserve for the container. The total of all GPU resource requirements’ values across a task definition may not exceed 16. If the InferenceAccelerator type is used, the value should match the device-name for an inference-accelerator specified in a task definition. (Required) firelens-configuration subresource The FireLens configuration for the container. This is used to specify and configure a log router for container logs. type The log router to use. Valid values are fluentd or fluentbit. (Required) options map The options to use when configuring the log router. This field can be used to specify a custom configuration file or to add additional metadata, such as the task, task definition, cluster, and container instance details to the log event.
volume list subresource	A list of volume definitions that containers in the task may use. name The name of the volume. Must be a string 1 to 255 characters long containing letters, numbers, and hyphens. Valid values satisfy the regex: [[-a-zA-Z0-9]{1,255}]. (Required) host-source-path The path on the host container instance that is presented to the container. When the task definition’s ‘requires-compatibilities’ parameter contains ‘FARGATE’, this parameter is not supported. docker-volume-configuration subresource This parameter is specified when using Docker volumes. scope The scope for the Docker volume that determines its lifecycle. 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. Valid values are task or scope. (Required) autoprovision If this value is true, the Docker volume is created if it does not already exist. This field is only used if the scope is shared. driver The Docker volume driver to use. The driver value must match the driver name provided by Docker. (Required) driver-opts map A map of Docker driver-specific options. labels map Custom metadata to add to your Docker volume.
placement-constraint list subresource	An array of placement constraint objects to use for the task. A maximum of 10 constraints are allowed per task (this limit includes constraints in the task definition and those specified at runtime). type The type of constraint. The only valid value is memberOf. This constraint restricts selection to be from a group of valid candidates. (Required) expression A cluster query language expression to apply to the constraint. (Required)
network-mode	The Docker networking mode to use for the containers in the task. The host and awsvpc modes offer the highest networking performance for containers because they use the EC2 network stack instead of the virtualized network stack provided by the bridge mode. If requires-compatibilities contains FARGATE, the awsvpc mode is required. Valid values are none, bridge, awsvpc or host.
cpu	The number of CPU units used by the task. Valid values range from 128 (0.125 vCPUs) to 10240 (10 vCPUs). If requires-compatibilities contains FARGATE, this field is required and the valid values are 256, 512, 1024, 2048, and 4096.
memory	The amount of memory (in MiB) used by the task. If requires-compatibilities contains FARGATE, this field is required and the valid values are determined by the cpu parameter as follows: - if cpu = 256: 512, 1024, 2048 - if cpu = 512: 1024, 2048, 3072, 4096 - if cpu = 1024: 2048, 3072, 4096, 5120, 6144, 7168, 8192 - if cpu = 2048: Between 4096 and 16384 in increments of 1024 - if cpu = 4096: Between 8192 and 30720 in increments of 1024
pid-mode	The process namespace to use for the containers in the task. If host is specified, then all containers within the tasks that specified the host pid-mode on the same container instance share the same process namespace with the host Amazon EC2 instance. If task is specified, all containers within the specified task share the same process namespace. If requires-compatibilities contains FARGATE, this parameter is not supported. If no value is specified, the default is a private namespace. Valid values are host or task.
ipc-mode	The IPC resource namespace to use for the containers in the task. If host is specified, then all containers within the tasks that specified the host ipc-mode on the same container instance share the same IPC resources with the host Amazon EC2 instance. If task is specified, all containers within the specified task share the same IPC resources. If none is specified, then IPC resources within the containers of a task are private and not shared with other containers in a task or on the container instance. If requires-compatibilities contains FARGATE, this parameter is not supported. If no value is specified, then the IPC resource namespace sharing depends on the Docker daemon setting on the container instance. Valid values are host, task or none.
proxy-configuration subresource	The proxy configuration for the task definition. type The proxy type. Currently the only supported value is APPMESH. (Required) container-name The name of the container that will serve as the App Mesh proxy. (Required) properties map The set of network configuration parameters to provide the Container Network Interface (CNI) plugin, specified as key-value pairs. Valid keys include: IgnoredUID - (Required) The user ID (UID) of the proxy container as defined by the user parameter in a container-definition. This is used to ensure the proxy ignores its own traffic. If IgnoredGID is specified, this parameter may be excluded. IgnoredGID - (Required) The group ID (GID) of the proxy container as defined by the user parameter in a container-definition. This is used to ensure the proxy ignores its own traffic. If IgnoredUID is specified, this parameter may be excluded. AppPorts - (Required) The list of ports that the application uses. Network traffic to these ports is forwarded to the ProxyIngressPort and ProxyEgressPort. ProxyIngressPort - (Required) Specifies the port that incoming traffic to the AppPorts is directed to. ProxyEgressPort - (Required) Specifies the port that outgoing traffic from the AppPorts is directed to. EgressIgnoredPorts - The egress traffic going to the specified ports is ignored and not redirected to the ProxyEgressPort. EgressIgnoredIPs - The egress traffic going to the specified IP addresses is ignored and not redirected to the ProxyEgressPort. Custom properties may be specified as well. (Required)
inference-accelerator list subresource	The Elastic Inference accelerators to use for the containers in the task. Maximum allowed items are 1. device-name The Elastic Inference accelerator device name. The device name must also be referenced in a container definition as a resource requirement. (Required) device-type The Elastic Inference accelerator type to use. (Required)
tags map	The metadata applied to the task definition. Each tag consists of a key and an optional value. Up to 50 tags per resource are allowed. The maximum character length is 128 for keys and 256 for values. Tags may not be prefixed with aws:, regardless of character case.

Outputs

Attribute	Description
revision	A version number of a task definition in a family. When you register a task definition for the first time, the revision is 1. Each time that you register a new revision of a task definition in the same family, the revision value always increases by one, even if you have deregistered previous revisions in this family.
arn	The full Amazon Resource Name (ARN) of the task definition.