How to use Environment Variables in AWS CDK


Borislav Hadzhiev

Fri Apr 23 20213 min read


Photo by Aaron Birch

Updated on Fri Apr 23 2021

In order to use environment variables in AWS CDK we have to first set them using the CDK CLI and then access them in our code on the process.env object.

Environment Variables in CDK #

We use environment variables to pass in key-value pairs to our CDK application, that we can then access in our CDK code.

Environment variables in CDK are accessible at synthesis time, which means that we can use them in our code, i.e. in conditional statements.

This makes the use of environment variables a preferred way to provide configuration to our applications, as opposed to something like Parameters which are only accessible at deployment time, after our CDK code has finished running.

In order to use environment variables in AWS CDK we have to set them using the CDK CLI and access them in our code on the process.env object.

Accessing environment variables in CDK #

We are going to create a small CDK app with an empty stack.

The code for this article is available on GitHub

When instantiating the stack we are going to use 2 environment variables:

  • REGION - the region our stack will be deployed to
  • DEPLOYMENT_ENV - the environment of the stack, i.e. dev, prod, staging, etc
import * as cdk from '@aws-cdk/core';

export class MyCdkStack extends cdk.Stack {
  constructor(scope: cdk.App, id: string, props?: cdk.StackProps) {
    super(scope, id, props);

    // ๐Ÿ‘‡ accessing environment variables
    console.log('REGION ๐Ÿ‘‰', process.env.REGION);
    console.log('DEPLOYMENT_ENV ๐Ÿ‘‰', process.env.DEPLOYMENT_ENV);

const app = new cdk.App();

new MyCdkStack(app, `my-cdk-stack-${process.env.DEPLOYMENT_ENV || ''}`, {
  stackName: `my-cdk-stack-${process.env.DEPLOYMENT_ENV || ''}`,
  env: {
    region: process.env.REGION,
    account: process.env.CDK_DEFAULT_ACCOUNT,

In the code snippet:

  1. We define our cdk stack, named MyCdkStack. The stack tries to access environment variables we haven't yet set, using the process.env object.

  2. We instantiate our CDK stack, using the environment variables, that we'll eventually provide with the CDK CLI.

  3. Note that the value of the environment variables will be undefined if we don't set them. In our case we default them to an empty string, to avoid the type errors.

  4. The environment variable CDK_DEFAULT_ACCOUNT is made available in the CDK environment, so we won't be providing that one.

Setting environment variables in AWS CDK #

We'll use the CDK CLI to set environment variables.

We set the environment variables when issuing the cdk deploy command. We first set the key-value pairs and then issue the command:

REGION=eu-central-1 \
  npx cdk deploy

If we issue the command and check for the output of the console.log calls, we see:

setting env cli

After issuing the command I can open my CloudFormation console and see that the region and deployment environment are taken from the environment variables I provided:

stack with env

Conclusion #

In order to access environment variables in our CDK code we use the process.env object.

The result from accessing process.env is either going to be a string or undefined, depending on if the environment variable has been set.

We can set environment variables in CDK by specifying the key-value pairs in our cdk deploy command, for example:

  npx cdk deploy

The benefit of environment variables is that they are accessible at synthesis time, so we can use the resolved values in our CDK code, as opposed to CDK parameters, which only get resolved at deployment time.

Further Reading #

Join my newsletter

I'll send you 1 email a week with links to all of the articles I've written that week

Buy Me A Coffee