Extending Copilot with CloudFormation YAML patches

[efekarakus]

This issue is a design proposal that is an alternative to #4208. The goal is the same:

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

However, the user experience in this design document targets clients that need only tiny modifications and don't want to have the AWS Cloud Development Kit (CDK) as a dependency.

Proposal

Instead of using the CDK, we propose allowing clients to write CloudFormation YAML patches. The authoring experience should be familiar to customers that already use task definition overrides but expanded to all resources abstracted by the manifests.

1. Upon running the new copilot [noun] override command, if the client opts into CloudFormation YAML patches then we will generate a single file as output cfn.patches.yml:

   $ copilot svc override
   > Which service's resources would you like to override?
   * frontend
   
   > Which infrastructure as code tool would you like to use to override "frontend"?
   * CloudFormation YAML patches
   
   > Which resources in "frontend" would you like to to override?
   [ ] DiscoveryService          (AWS::ServiceDiscovery::Service)
   [x] Service                   (AWS::ECS::Service)
   [x] PublicNetworkLoadBalancer  (AWS::ElasticLoadBalancingV2::LoadBalancer)
   [ ] TaskDefinition            (AWS::ECS::TaskDefinition)
   ✅ Created a YAML patch file under `copilot/frontend/overrides/` to override the resources:
   .
   ├── cfn.patches.yml
   └── README.md
   
   > Recommended Actions:
   1. Please follow the guide under README.md

2. The authoring experience will conform to RFC6902: JSON Patch with the limitation of only supporting the add, remove, replace operations.

- 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/TaskDefinition/Properties/ContainerDefinitions/-
  value:
    Name: envoy
    Image: aws_account_id.dkr.ecr.us-west-2.amazonaws.com/envoy:latest

The authoring experience with cfn.patches.yml is optimized for tiny CloudFormation tweaks. It's not as flexible and safe as #4208, however it does not depend on any other tools and has a faster learning curve.

Feedback

Please let us know your thoughts on the proposal above 🙇. Would this proposal unblock you?

[efekarakus]

Hi folks!!

I'm really excited to say that AWS Copilot v1.27 is out and YAML patch extensions is now supported! 🚀

• Guide: https://aws.github.io/copilot-cli/docs/developing/overrides/yamlpatch/
• Blog post: https://aws.github.io/copilot-cli/blogs/release-v127/
• Release notes: https://github.com/aws/copilot-cli/releases/tag/v1.27.0

I'll close the issue now! If you have any questions, feedback, or suggestions please feel free to open new GitHub issues 🥳