Skip to content

migration-guide.md

Latest commit

 

History

History
92 lines (62 loc) · 4.54 KB

migration-guide.md

File metadata and controls

92 lines (62 loc) · 4.54 KB

Migration Guide

This guide describes how to migrate an existing Cloudformation stack (and template) to @guardian/cdk.

If you are starting from scratch, see the new project guide.

Overall migration process

  1. Identify the GuCDK pattern which works for your app
  2. Add GuCDK to your repository and CI/CD process
  3. Instantiate a GuCDK pattern alongside your legacy infrastructure (dual-stack), for stateless resources
  4. Switch your production workload (e.g. serving HTTP traffic or processing data) to the GuCDK infrastructure
  5. Remove legacy infrastructure for stateless resources
  6. Where necessary, define stateful resources (e.g. DBs) via cdk components instead of via the original template

Identify the right GuCDK pattern

YAML Infrastructure Application type GuCDK pattern to use
AWS::AutoScaling::AutoScalingGroup with either AWS::ElasticLoadBalancing::LoadBalancer or AWS::ElasticLoadBalancingV2::LoadBalancer Serving HTTP traffic GuEc2App
AWS::AutoScaling::AutoScalingGroup with either AWS::ElasticLoadBalancing::LoadBalancer or AWS::ElasticLoadBalancingV2::LoadBalancer Polling/running tasks on a schedule GuPlayWorkerApp
AWS::Lambda::Function (single) with AWS::ApiGateway::RestApi Serving HTTP traffic GuApiLambda
AWS::Lambda::Function (multiple) with AWS::ApiGateway::RestApi Serving HTTP traffic GuApiGatewayWithLambdaByPath
AWS::Lambda::Function with AWS::Events::Rule Polling/running tasks on a schedule GuScheduledLambda

Add GuCDK to your repository and CI/CD process

  1. Create a new project specifying the --yaml-template-location flag.

    npx @guardian/cdk@latest new --app [app] --stack [stack] --stage [stage] --package-manager [npm|yarn] --yaml-template-location

    For example for the app trigr we do

    npx @guardian/cdk@latest new --app trigr --stack ophan --stage PROD  --package-manager npm --yaml-template-location cloudformation/trigr.cfn.yaml

    See the new project guide for further reading

  2. Check to see what changes will be made to the stack:

    npm run diff -- --profile <AWS PROFILE NAME> <STACK ID FROM bin/cdk.ts>

    Or you could check against local:

    npm run diff -- --template cloudformation/<app>.cfn.yaml <STACK ID FROM bin/cdk.ts>

    Again taking trigr as an example we could do:

    npm run diff -- --template cloudformation/trigr.cfn.yaml Trigr-PROD

    Use Trig-PROD as found in cdk.ts:

    (new Trigr(app, "Trigr-PROD", { stack: "ophan", stage: "PROD" });)

    This should only show differences in how resources are tagged; GuCDK will add various tags to all resources in the stack. If you find this initial diff too noisy, you could temporarily exclude these tags by amending your stack's props, specifically set withoutTags to true.

  3. Configure CI and CD. See Setting up a GuCDK project for more detail.

  4. Raise a PR and merge.

We now have something like this:

CDK(cfn.yaml) -> cfn.json

That is, CDK is merely wrapping an existing template.

The end goal is for CDK to do all the work, and remove the YAML template:

CDK -> cfn.json

In order to achieve this, you should now follow the specific migration guide for the pattern that you're moving to:

If you plan to migrate to the GuPlayWorkerApp pattern then please contact the DevX Reliability & Operations team for support.