docs: add task def override

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

@@ -0,0 +1,50 @@
+# Overrides
+If there are fields that are not configurable in the [manifest](../manifest/overview.en.md), users can bypass some of them 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
+<override section>:
+  - path: <CFN field path>
+    value: <value>
+```
+
+## Override Behaviors
+
+- Copilot recursively creates `map` 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`
+
+- Use `-` as index to append a new member to a `list` field. The field will be initiated with this new member if it doesn't exist
+
+- **value** must be scalar value like `bool`, `string`, or `int`, and the new value replaces the old value if exists
+
+## Examples
+
+### Task Definition Override
+!!! Attention
+    Users are not allowed to modify the following fields in the task definition.
+
+    * Family
+    * ContainerDefinitions[<index>].Name (name of any existing container)
+
+Below is an example of adding [`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[-].Name"
+    value: "cpu"
+  - path: "ContainerDefinitions[0].Ulimits[0].SoftLimit"
+    value: 1024
+  - path: "ContainerDefinitions[0].Ulimits[0].HardLimit"
+    value: 2048
+```
+
+Below is exposing an extra UDP port for the main container.
+
+``` yaml
+taskdef_overrides:
+  - path: "ContainerDefinitions[0].PortMappings[-].ContainerPort"
+    value: 2056
+  - path: "ContainerDefinitions[0].PortMappings[1].Protocol"
+    value: "udp"
+```

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