External secrets adapter for Pulumi ESC on AWS Lambda

This example lives in the pulumi/examples repository. Check out just this directory to use it:

$ git clone --filter=blob:none --sparse https://github.com/pulumi/examples pulumi-examples
$ git -C pulumi-examples sparse-checkout set aws-ts-esc-external-adapter-lambda
$ cd pulumi-examples/aws-ts-esc-external-adapter-lambda

A reference implementation showing how to build a secure external secrets adapter for Pulumi ESC. This example validates JWT authentication and request integrity, making it easy to integrate custom or proprietary secret sources with ESC.

For complete documentation on ESC Connect, see the external provider documentation.

Deploying the adapter#

1. Install dependencies:

   npm install

2. Create a new Pulumi stack:

   pulumi stack init dev

3. Configure your AWS region:

   pulumi config set aws:region us-west-2

4. Deploy:

   pulumi up

5. Copy the adapter URL from the output:

   export ADAPTER_URL=$(pulumi stack output adapterUrl)

Using with Pulumi ESC#

Create a Pulumi ESC environment:

values:
  demo:
    fn::open::external:
      url: https://YOUR-API-ID.execute-api.us-west-2.amazonaws.com/stage/
      request:
        message: "Hello from ESC!"

Open the environment:

esc open <your-org>/external-demo

Expected output:

{
  "demo": {
    "response": {
      "message": "External secrets adapter responding successfully!",
      "requestEcho": {
        "message": "Hello from ESC!"
      },
      "timestamp": "2025-11-26T12:00:00.000Z"
    }
  }
}

Building your own adapter#

The ESCRequestValidator class in index.ts handles request integrity validation. To integrate your own secret source:

1. Copy the ESCRequestValidator class into your adapter

2. Replace the TODO comment in the Lambda handler with your secret fetching logic:

   const { claims, requestBody } = await validator.validateRequest(event);
   
   // Use claims to further authorize the request
   if (claims.org !== "YOUR-PULUMI-ORG") {
       return { statusCode: 401 };
   }
   
   // Fetch from your secret source
   const secret = await fetchFromYourSecretStore(requestBody.secretName);
   
   return {
       statusCode: 200,
       body: JSON.stringify(secret),
   };

See the external provider documentation for complete implementation guidance and examples in other languages.

Monitoring#

View Lambda logs:

pulumi logs --follow

Or use the AWS CLI:

aws logs tail /aws/lambda/$(pulumi stack output functionName) --follow

The handler logs JWT claims to CloudWatch for debugging.

Clean up#

pulumi destroy
pulumi stack rm dev

Additional resources#

• Blog: Introducing ESC Connect
• External Provider Documentation
• External Rotator Documentation
• Pulumi ESC Documentation
• Pulumi Community Slack