SetLambdaEnvironmentVariables

A CDK construct to set Lambda environment variables after deployment, helping you break circular dependency chains.

About

Set Lambda environment variables after the Lambda function has been deployed. This allows you to set environment variables based on resources that require this Lambda, which would normally lead to a circular dependency.

Now you can deploy the Lambda and the other resources first, and add environment variables later using this construct.

Caveat: due to the nature of the Lambda control plane API it is not possible to set environment variables individually. This construct works fine for the first deploy. It's the second deploy you have to be careful: if you update something in your function, the behaviour is that first the environment variables (if any) of the function are applied, and the ones set with this construct will be removed. Only then, seconds to minutes after will the environment variables be reapplied.

Installation

npm

npm install cdk-lambda-env-var

yarn

yarn add cdk-lambda-env-var

pnpm

pnpm add cdk-lambda-env-var

Usage

Basic Example

import { Stack, App } from "aws-cdk-lib"
import * as lambda from "aws-cdk-lib/aws-lambda"
import { SetLambdaEnvironmentVariables } from "cdk-lambda-env-var"

const app = new App()
const stack = new Stack(app, "MyStack")

// Create your Lambda function
const myFunction = new lambda.Function(stack, "MyFunction", {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: "index.handler",
  code: lambda.Code.fromAsset("lambda"),
})

// Set environment variables after deployment
new SetLambdaEnvironmentVariables(stack, "SetEnvVars", {
  function: myFunction,
  environment: {
    API_ENDPOINT: "https://api.example.com",
    REGION: "us-east-1",
    DEBUG: "true",
  },
})

Breaking Circular Dependencies

This construct is particularly useful when you have circular dependencies. For example, when a Lambda needs to know about a resource that depends on the Lambda itself:

import { Stack } from "aws-cdk-lib"
import * as lambda from "aws-cdk-lib/aws-lambda"
import * as apigateway from "aws-cdk-lib/aws-apigateway"
import { SetLambdaEnvironmentVariables } from "cdk-lambda-env-var"

// Lambda function that needs to know the API URL
const authFunction = new lambda.Function(this, "AuthFunction", {
  runtime: lambda.Runtime.NODEJS_22_X,
  handler: "index.handler",
  code: lambda.Code.fromAsset("lambda"),
})

// API Gateway that uses the Lambda
const api = new apigateway.LambdaRestApi(this, "MyApi", {
  handler: authFunction,
})

// Set the API URL as an environment variable on the Lambda
// This would normally create a circular dependency!
new SetLambdaEnvironmentVariables(this, "SetApiUrl", {
  function: authFunction,
  environment: {
    API_URL: api.url,
  },
})

How It Works

The construct uses a custom resource with a Lambda-backed handler to:

1. On Create/Update: Fetches the current environment variables from the target Lambda, merges them with the new variables you provide, and updates the Lambda configuration
2. On Delete: Fetches the current environment variables, removes only the variables set by this construct, and updates the Lambda configuration

This ensures that:

• Existing environment variables are preserved (merge behavior)
• Stack updates properly update the environment variables
• Stack deletion only removes the variables added by this construct

Important Behavior Note

When you modify any property of the Lambda function in CDK (environment, code, memory, timeout, etc.) and deploy, CloudFormation updates the Lambda before this construct's custom resource runs. This means:

1. CloudFormation replaces the Lambda's entire environment with what's defined in CDK
2. Any variables set by SetLambdaEnvironmentVariables are temporarily removed
3. The custom resource then runs and re-adds the variables

The variables set by this construct will be temporarily unavailable between steps 1 and 3. If your Lambda is invoked during this window, it will not have access to these environment variables.

This construct automatically detects changes to the target Lambda's configuration and triggers an update to re-apply its environment variables. However, the temporary unavailability window is unavoidable due to how CloudFormation processes updates.

For most deployments this window is very short (seconds), but if you have critical environment variables that must always be present, consider:

• Using a maintenance window for deployments
• Implementing graceful degradation in your Lambda code for missing environment variables

API Reference

SetLambdaEnvironmentVariables

Props

| Property | Type | Description | | ------------- | ------------------------ | -------------------------------------------------------------------------- | | function | lambda.IFunction | The Lambda function to set environment variables on | | environment | Record<string, string> | Environment variables to set. These will be merged with existing variables |

Requirements

• AWS CDK v2.170.0 or later
• Node.js 18 or later

License

This project is licensed under the Apache-2.0 License.