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

@@ -241,7 +241,7 @@ 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/overrides.en.md#task-definition-override)).
+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.