Skip to content

YAML Patch Overrides

Attention

⚠ Overriding CloudFormation templates is an advanced feature which can cause your stacks to not deploy successfully. Please use with caution!

Copilot generates CloudFormation templates using configuration specified in the manifest. However, not all CloudFormation properties are configurable in the manifest. For example, you might want to configure the Ulimits for your workload container, but the property is not exposed in manifests.

Overrides with yamlpatch or cdk allow you to add, delete, or replace any property or resource in a CloudFormation template.

When should I use YAML Patch over CDK overrides?

Both options are a "break the glass" mechanism to access and configure functionality that is not surfaced by Copilot manifests.

We recommend using YAML patch over the AWS Cloud Development Kit (CDK) overrides if 1) you do not want to have a dependency on any other tooling and framework (such as Node.js and the CDK), or 2) you have to write only a handful modifications.

How to get started

You can extend your CloudFormation template with YAML patches by running the copilot [noun] override command. For example, you can run copilot svc override to update the template of a Load Balanced Web Service. The command will generate a sample cfn.patches.yml file under the copilot/[name]/overrides directory.

How does it work?

The syntax of cfn.patches.yml conforms to RFC6902: JSON Patch. Currently, the CLI supports three operations: add, remove, and replace. Here is a sample cfn.patches.yml file:

- op: add
  path: /Mappings
  value:
    ContainerSettings:
      test: { Cpu: 256, Mem: 512 }
      prod: { Cpu: 1024, Mem: 1024}
- op: remove
  path: /Resources/TaskRole
- op: replace
  path: /Resources/TaskDefinition/Properties/ContainerDefinitions/1/Essential
  value: false
- op: add
  path: /Resources/Service/Properties/ServiceConnectConfiguration/Services/0/ClientAliases/-
  value:
    Port: !Ref TargetPort
    DnsName: yamlpatchiscool

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

Path evaluation

The path field of a patch conforms to the RFC6901: JSON Pointer syntax.

  • Each path value is separated by the / character and evaluation stops once the target CloudFormation property is reached.
  • If the target path is an array, the reference token must be either:
    • characters comprised of digits starting at 0.
    • exactly the single character - when the operation is add, to append to the array.

Additional Examples

To add a new property to an existing resource:

- op: add
  path: /Resources/LogGroup/Properties/Tags
  value:
    - Key: keyname
      Value: value1

To add a new property in a specific index of an array:

- op: add
  path: /Resources/TaskDefinition/Properties/ContainerDefinitions/0/EnvironmentFiles/0
  value: arn:aws:s3:::bucket_name/key_name

To add a new element at the end of an array:

- op: add
  path: /Resources/TaskRole/Properties/Policies/-
  value:
    PolicyName: DynamoDBReader
    PolicyDocument:
      Version: "2012-10-17"
      Statement:
        - Effect: Allow
          Action:
            - dynamodb:Get*
          Resource: '*'

To replace an existing property's value:

- op: replace
  path: /Resources/LogGroup/Properties/RetentionInDays
  value: 60

To delete an element from an array, you must reference the exact index:

- op: remove
  path: /Resources/ExecutionRole/Properties/Policies/0/PolicyDocument/Statement/1/Action/0

To delete an entire resource:

- op: remove
  path: /Resources/ExecutionRole