Task Definition Overrides

Attention

Task definition overrides is deprecated.

We recommend using YAML patch overrides instead, as it allows you to edit the entire CloudFormation template and supports the remove operation.

Copilot generates CloudFormation templates using configuration specified in the manifest. However, there are fields that are not configurable in the manifest. For example, You might want to configure the Ulimits for your workload container, but it is not exposed in our manifest.

You can configure additional ECS Task Definition settings by specifying taskdef_overrides rules, which will be applied to the CloudFormation template that Copilot generates out of the manifest.

How to specify override rules?

For each override rule, you need to specify a path of the CloudFormation resource field you want to override, and a value of that field.

The following is an example valid taskdef_overrides field that can be applied to a manifest file:

taskdef_overrides:
- path: ContainerDefinitions[0].Cpu
  value: 512
- path: ContainerDefinitions[0].Memory
  value: 1024

Each rule is applied sequentially to the CloudFormation template. The resulting CloudFormation template becomes the target of the next rule. Evaluation continues until all rules are successfully applied or an error is encountered.

Path Evaluation

The path field is a '.' character separated path to a target Task Definition field under Properties in CloudFormation.
Copilot recursively inserts fields if they don't exist in the CloudFormation template. For example: if a rule has the path A.B[-].C (B and C don't exist), Copilot will insert the field B and C. A concrete example can be found below.
If the target path specifies a member that already exists, that member's value is replaced.
To append a new member to a list field such as Ulimits you can use the special character -: Ulimits[-].

Attention

The following fields in the task definition are not allowed to be modified.

Testing

In order to ensure that your override rules behave as expected, we recommend running copilot svc package or copilot job package to preview the generated CloudFormation template.

Examples

Add `Ulimits` to the main container

taskdef_overrides:
  - path: ContainerDefinitions[0].Ulimits[-]
    value:
      Name: "cpu"
      SoftLimit: 1024
      HardLimit: 2048

Expose an extra UDP port

taskdef_overrides:
  - path: "ContainerDefinitions[0].PortMappings[-].ContainerPort"
    value: 2056
  # PortMappings[1] gets the port mapping added by the previous rule, since by default Copilot creates a port mapping.
  - path: "ContainerDefinitions[0].PortMappings[1].Protocol"
    value: "udp"

Give read-only access to the root file system

taskdef_overrides:
  - path: "ContainerDefinitions[0].ReadonlyRootFilesystem"
    value: true