From 8ee445a020d1a866839efedf5a9612ddb8c69db8 Mon Sep 17 00:00:00 2001 From: penghaoh Date: Tue, 24 Aug 2021 11:29:50 -0700 Subject: [PATCH] docs: add task def override --- site/content/docs/developing/overrides.en.md | 50 +++++++++++++++++++ .../docs/include/common-svc-fields.en.md | 15 +++++- 2 files changed, 63 insertions(+), 2 deletions(-) create mode 100644 site/content/docs/developing/overrides.en.md diff --git a/site/content/docs/developing/overrides.en.md b/site/content/docs/developing/overrides.en.md new file mode 100644 index 00000000000..41f6a3641ac --- /dev/null +++ b/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 +: + - path: + 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[].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" +``` diff --git a/site/content/docs/include/common-svc-fields.en.md b/site/content/docs/include/common-svc-fields.en.md index 84942170848..abb73cd94f7 100644 --- a/site/content/docs/include/common-svc-fields.en.md +++ b/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`. volume.efs.`uid` Uint32 -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. volume.efs.`gid` Uint32 -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. volume.efs.`auth` Map Specify advanced authorization configuration for EFS. @@ -240,5 +240,16 @@ Optional. The full config file path in your custom Fluent Bit image.
+`taskdef_overrides` Array +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)). + +taskdef_overrides.`path` String +Required. Path to the Task Definition field to override. + +taskdef_overrides.`value` Any +Required. Value of the Task Definition field to override. + +
+ `environments` Map 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.