In recent years, cloud-native development has become increasingly popular, with Amazon Web Services (AWS) leading the charge with services like AWS Lambda for serverless computing. One of the key tools for managing serverless applications on AWS is the Serverless Application Model (SAM), which simplifies the process of defining and deploying AWS Lambda functions, API Gateway endpoints, and other serverless resources. However, as the cloud landscape evolves, developers look for more powerful and flexible ways to manage their infrastructure-as-code (IaC). This has led to the rise of the AWS Cloud Development Kit (CDK), a framework for defining cloud infrastructure using familiar programming languages.
This guide will explore migrating SAM templates to CDK CloudFormation templates using the CDK CLI’s cdk migrate command, specifically designed to convert existing CloudFormation or SAM templates to CDK code. We’ll explore the benefits of using CDK for infrastructure management, provide a step-by-step tutorial for migration, and highlight best practices along the way.
Section 1: Why Migrate from SAM to CDK?
Before diving into the migration process, let’s understand why developers are considering shifting from SAM to CDK to manage their AWS infrastructure.
- Flexibility and Extensibility: CDK allows developers to define their infrastructure using familiar programming languages like TypeScript, Python, and Java. This enables greater flexibility and extensibility compared to SAM’s YAML-based templates or JSON-based templates.
- Reusable Constructs: While the CDK Migrate CLI tool is a significant step, the true potential of AWS CDK lies in its Layer 2 and Layer 3 capabilities. These advanced constructs are not just upgrades over AWS SAM; they are game changers. They can transform your infrastructure management and development experience, offering unique advantages that are not available in AWS SAM.
Let’s explore these Layer 2 and 3 constructs and understand why they are crucial when transitioning from AWS SAM to AWS CDK.
- Layer 1 (Infrastructure as Code): Layer 1 in AWS CDK represents basic infrastructure constructs such as AWS resources (e.g., Lambda functions, API Gateway endpoints) and configurations. When migrating from AWS SAM to AWS CDK using CDK Migrate, you primarily get Layer 1 constructs, which offer benefits like programmatic infrastructure definition and better abstraction than SAM’s YAML/JSON templates.
- Layer 2 (Higher-Level Patterns and Abstractions): Layer 2 in AWS CDK is where the magic happens. It introduces higher-level patterns and abstractions built on top of Layer 1 constructs. These patterns simplify everyday use cases and encapsulate best practices, making your life as a developer much more accessible. For instance, in CDK, you have constructs like Lambda REST API that combine Lambda functions and API Gateway endpoints, handling all the necessary configurations and integrations for you. Migrating to Layer 2 constructs in CDK can lead to more concise and readable code, reduced boilerplate, and improved adherence to AWS best practices without manual configuration.
- Layer 3 (Custom Abstractions and Extensions): Layer 3 in AWS CDK involves custom abstractions and extensions tailored to your specific use cases or organisational standards. Layer 3 in AWS CDK is where you can genuinely customise your infrastructure. Developers can create reusable constructs, libraries, and modules that encapsulate complex architectures, multi-service deployments, or company-wide standards. This encapsulation means that the internal details of these constructs are hidden, allowing developers to use them without needing to understand or change their internal workings, thereby promoting code reuse and reducing the risk of errors. By migrating to Layer 3 constructs, teams can enforce consistency, promote code reuse, and abstract away low-level implementation details. This leads to faster development cycles as developers can focus on high-level design and logic and easier maintenance as changes can be made at the abstraction level without affecting the underlying infrastructure.
Migrating from AWS SAM to AWS CDK and progressing from Layer 1 to Layer 2 and 3 constructs is a gradual process, but the benefits are worth it. The following are some of the advantages:
- Abstraction and Simplification: Higher layers provide more abstract and simplified ways to define complex architectures, reducing the cognitive load on developers.
- Code Reusability: Custom constructs and patterns in Layer 3 promote code reusability across projects, teams, and environments.
- Custom Abstraction: Layer 3 constructs in AWS CDK offer custom abstractions, allowing flexible and extensible infrastructure definitions. This adaptability and flexibility are not just beneficial; they are essential, as they can provide a sense of security about future-proofing your infrastructure and accommodating diverse use cases and evolving requirements.
- Advanced Features: CDK offers advanced features such as constructs libraries, asset bundling, and integration with IDEs like Visual Studio Code. These features enhance developer productivity and simplify the management of complex infrastructure.
- Ecosystem Support: CDK has a growing ecosystem of community-contributed constructs and libraries, making it easier to integrate with third-party services and AWS resources beyond what SAM offers.
- Abstraction and Integration with Most of the AWS Services: AWS SAM focuses primarily on serverless applications and is more specific to defining AWS Lambda functions, API Gateway endpoints, and related resources. While it’s great for simple serverless applications, it may lack the flexibility needed for more complex infrastructure setups. If the project wants to manage Amazon Redshift Clusters, then there might be a need to use CDK to define infrastructure programmatically. To support consistency across IaC, developers might use CDK constructs to manage AWS infrastructure.
Note: If you have Serverless project that you do not see many modifications to the AWS Architecture, then migrating your SAM project to CDK may not provide a significant benefit.
Section 2: Step-by-Step Migration Guide
Now, let’s walk through migrating a simple CloudFormation stack deployed using SAM template (template.yaml) to a CDK CloudFormation template (/<stack name>/cdk.out/<stack name>.template.json). We’ll use Python as the programming language for CDK.
Prerequisites
- Install Node.js and npm (Node Package Manager) if you haven’t already.
- Make sure you have Python and pip installed on your system.
- Ensure Serverless Framework Python runtime version is configured as per the latest available runtime version.
- Install AWS CDK globally.
- Configure AWS CLI with your credentials
Assumption
- Serverless Framework stack is deployed in the AWS region of choice.
Note: Make a note of the deployed serverless <stack name>. - Run the following command to list the AWS deployed stack outputs:
Note: Replace the <stack name> appropriately.
Section 2a: Migrate SAM Template to CDK Code using cdk migrate command:
- Navigate to your root project directory:
- Run cdk migrate from your terminal:
Note: Replace the <stack name> appropriately.
- CDK constructs should be created in the folder named (stack name).
- Navigate to CDK folder and run cdk ls to ensure that the migrate is successful and we can manage the stack with CDK command going forward.
Sample output:
Section 3: Review and Customise Migrated CDK Code:
Open the generated CDK project in your code editor. The migrated CDK code is in the language-specific file (app.py for Python, app.ts for TypeScript, etc.).
Review the migrated code to ensure all resources and configurations from your SAM template are correctly represented in CDK constructs. You may need to adjust, or additions based on your specific requirements, or any features not directly supported by the migration tool.
Section 4: Deploy Your CDK Stack:
Before deploying your CDK stack, ensure you have configured your AWS credentials using the AWS CLI (aws configure) or environment variables (AWS_ACCESS_KEY_ID, AWS_SECRET_ACCESS_KEY).
Deploy your CDK stack using the following command:
CDK will automatically synthesize your Python code into CloudFormation templates and deploy your AWS resources.
Section 5: Cleanup (Optional)
To remove the resources created by your CDK stack, use the following command:
Section 6: Best Practices and Considerations
- Use CDK Constructs: Leverage CDK constructs for AWS resources (e.g., Function, REST API) instead of explicitly defining CloudFormation resources.
- Modularise Your Code: Break down your CDK stacks into smaller components for better organisation and reuse.
- Review Generated Code: After migration, carefully review the generated CDK code to ensure all resources and configurations are correctly migrated.
- Version Control: Store your CDK code in version control (e.g., Git) for tracking changes and collaboration.
- Testing: Implement automated testing for your CDK code to ensure reliability.
Section 7: Conclusion
Using the cdk migrate CLI tool simplifies migrating SAM templates to CDK CloudFormation templates by automatically generating CDK code based on the existing template. By following best practices and customizing the migrated code as needed, developers can effectively manage their AWS infrastructure using CDK, leveraging its flexibility and capabilities for cloud-native development.
NOTE: cdk migrate tool is still in experimental phase.
Section 8: Additional Resources:
- https://github.com/aws-samples/serverless-test-samples/tree/main
- https://aws.amazon.com/blogs/devops/announcing-cdk-migrate-a-single-command-to-migrate-to-the-aws-cdk/
- https://github.com/aws/aws-cdk/blob/main/packages/aws-cdk/README.md#cdk-migrate
- https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/serverless-cdk-getting-started.html
- https://docs.aws.amazon.com/serverless-application-model/latest/developerguide/what-is-sam.html
- https://aws.amazon.com/blogs/compute/better-together-aws-sam-and-aws-cdk/
