docs: add task def override

mkdocs.yml

@@ -47,6 +47,7 @@ nav:
       - Custom Environment Resources: docs/developing/custom-environment-resources.en.md
       - Secrets: docs/developing/secrets.en.md
       - Service Discovery: docs/developing/service-discovery.en.md
+      - Task Definition Overrides: docs/developing/taskdef-overrides.en.md
       - Additional AWS Resources: docs/developing/additional-aws-resources.en.md
       - Sidecars: docs/developing/sidecars.en.md
       - Storage: docs/developing/storage.en.md

site/content/docs/developing/taskdef-overrides.en.md

@@ -0,0 +1,55 @@
+# Task Definition Overrides
+If there are fields that are not configurable in the [manifest](../manifest/overview.en.md), users can bypass some of the [ECS Task Definition setting](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskdefinition.html) by applying override rules to the CloudFormation template Copilot generates out of the manifest.
+
+## How to specify override rules?
+For each override rule, users need to construct the **path** and **value** of the CloudFormation resource field they want to override.
+
+``` yaml
+taskdef_overrides:
+  - path: <ECS Task Definition field path>
+    value: <value>
+```
+
+## Override Behaviors
+
+- Use `-` as index to append a new member to a `list` field
+
+- When applying the override rule, Copilot inserts or updates the fields along the path. More specifically, Copilot recursively inserts fields if they don't exist in the **path**. For example: if `B` and `C` don't exist, `A.B[-].C` will create `B` and `C`
+
+!!! Attention
+    Users are not allowed to modify the following fields in the task definition.
+
+    * [Family](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-resource-ecs-taskdefinition.html#cfn-ecs-taskdefinition-family)
+    * [ContainerDefinitions[<index>].Name](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-containerdefinitions.html#cfn-ecs-taskdefinition-containerdefinition-name)
+
+## Examples
+
+**Add [`Ulimits`](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-ecs-taskdefinition-containerdefinitions-ulimit.html) to the main container**
+
+``` yaml
+taskdef_overrides:
+  - path: ContainerDefinitions[0].Ulimits[-]
+    value:
+      Name: "cpu"
+      SoftLimit: 1024
+      HardLimit: 2048
+```
+
+**Expose an extra UDP port**
+
+``` yaml
+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**
+
+``` yaml
+taskdef_overrides:
+  - path: "ContainerDefinitions[0].ReadonlyRootFilesystem"
+    value: true
+```

site/content/docs/include/common-svc-fields.en.md

@@ -204,10 +204,10 @@ Required. The ID of the filesystem you would like to mount.
 Optional. Defaults to `/`. Specify the location in the EFS filesystem you would like to use as the root of your volume. Must be fewer than 255 characters and must consist only of the characters `a-zA-Z0-9.-_/`. If using an access point, `root_dir` must be either empty or `/` and `auth.iam` must be `true`.
 
 <span class="parent-field">volume.efs.</span><a id="uid" href="#uid" class="field">`uid`</a> <span class="type">Uint32</span>
-Optional. Must be specified with `gid`. Mutually exclusive with `root_dir`, `auth`, and `id`. The POSIX UID to use for the dedicated access point created for the managed EFS filesystem. 
+Optional. Must be specified with `gid`. Mutually exclusive with `root_dir`, `auth`, and `id`. The POSIX UID to use for the dedicated access point created for the managed EFS filesystem.
 
 <span class="parent-field">volume.efs.</span><a id="gid" href="#gid" class="field">`gid`</a> <span class="type">Uint32</span>
-Optional. Must be specified with `uid`. Mutually exclusive with `root_dir`, `auth`, and `id`. The POSIX GID to use for the dedicated access point created for the managed EFS filesystem. 
+Optional. Must be specified with `uid`. Mutually exclusive with `root_dir`, `auth`, and `id`. The POSIX GID to use for the dedicated access point created for the managed EFS filesystem.
 
 <span class="parent-field">volume.efs.</span><a id="auth" href="#auth" class="field">`auth`</a> <span class="type">Map</span>  
 Specify advanced authorization configuration for EFS.
@@ -240,5 +240,16 @@ Optional. The full config file path in your custom Fluent Bit image.
 
 <div class="separator"></div>
 
+<a id="taskdef_overrides" href="#taskdef_overrides" class="field">`taskdef_overrides`</a> <span class="type">Array</span>  
+The `taskdef_overrides` section allows users to apply overriding rules to their ECS Task Definitions (see examples [here](../developing/taskdef-overrides.en.md#examples)).
+
+<span class="parent-field">taskdef_overrides.</span><a id="taskdef_overrides-path" href="#taskdef_overrides-path" class="field">`path`</a> <span class="type">String</span>  
+Required. Path to the Task Definition field to override.
+
+<span class="parent-field">taskdef_overrides.</span><a id="taskdef_overrides-value" href="#taskdef_overrides-value" class="field">`value`</a> <span class="type">Any</span>  
+Required. Value of the Task Definition field to override.
+
+<div class="separator"></div>
+
 <a id="environments" href="#environments" class="field">`environments`</a> <span class="type">Map</span>  
 The environment section lets you override any value in your manifest based on the environment you're in. In the example manifest above, we're overriding the count parameter so that we can run 2 copies of our service in our 'prod' environment, and 2 copies using Fargate Spot capacity in our 'staging' environment.