Deploying AWS Infrastructure with cdk-factory: A Configuration-Driven Approach

The AWS Cloud Development Kit (CDK) has revolutionized how we define cloud infrastructure, allowing us to use familiar programming languages to build reliable and scalable applications. However, as projects grow, managing multiple environments, stacks, and deployment pipelines can become complex. Code duplication and inconsistent configurations can creep in, slowing down development.

To address these challenges, I created cdk-factory, an open-source framework that brings a declarative, configuration-driven approach to your AWS CDK projects. Instead of hardcoding values, you define your entire workload—from stacks to pipelines—in a config.json file.

The Philosophy: Configuration Over Code

The core idea behind cdk-factory is to separate the what from the how. Your CDK code defines how to build a piece of infrastructure (like a VPC or a Lambda function), while a config.json file defines what to build for a specific environment.

This approach provides a high-level, easy-to-read blueprint of your infrastructure, making it simple to manage different configurations for development, staging, and production environments without touching the underlying CDK code.

Core Concepts of cdk-factory

The framework is organized around a few key elements in your config.json:

• cdk: Manages global CDK parameters and dynamic values.
• workload: Contains general information about your application.
• stacks: Defines the individual CloudFormation stacks.
• deployments: Groups stacks together for deployment.
• pipelines: Describes AWS CodePipeline configurations for CI/CD.

Let's dive into one of the most powerful features: dynamic parameters.

Dynamic Parameters

The cdk.parameters section in your config.json allows you to inject dynamic values into your CDK application at synth time. This is perfect for handling environment-specific variables like workload names, container image tags, or file paths.

Here’s an example from the cdk-factory documentation:

{
    "cdk": {
        "parameters": [
            {
                "placeholder": "{{WORKLOAD_NAME}}",
                "env_var_name": "CDK_WORKLOAD_NAME",
                "cdk_parameter_name": "WorkloadName"
            },
            {
                "placeholder": "{{CDK_SYNTH_COMMAND_FILE}}",
                "value": "../../samples/website/commands/cdk_synth.sh",
                "cdk_parameter_name": "CdkSynthCommandFile"
            }
        ]
    }
}

Here's what's happening:

1. Placeholder Replacement: The framework finds and replaces placeholders like {{WORKLOAD_NAME}} throughout the config.json file.
2. Value Injection: It retrieves the value from either an environment variable (env_var_name) or a static value.
3. CDK Context: It passes the final value into the CDK application as a context variable (--context WorkloadName=my-app).

This mechanism allows you to create generic, reusable CDK code that is customized entirely through configuration.

Benefits of the cdk-factory Approach

• Reusability: Define a stack once and deploy it to multiple environments just by changing the configuration.
• Clarity: The config.json file serves as a single source of truth for your environment's architecture.
• Consistency: Enforce best practices and a standardized deployment structure across all your projects.
• Scalability: Easily manage dozens of microservices and their deployment pipelines from a central configuration.

Getting Started

cdk-factory is designed to be straightforward to set up. To get started:

1. Clone the repository from GitHub: git clone https://github.com/geekcafe/cdk-factory.git
2. Run the setup script: ./setup.sh
3. Start exploring the sample configurations and building your own.

Conclusion

cdk-factory is an evolving project aimed at making AWS CDK development more structured and scalable. By embracing a configuration-driven approach, you can build more robust, reusable, and manageable infrastructure.

Check out the project on GitHub, try it out, and feel free to contribute. Let's build better infrastructure, together.