AWS CDK Utils

Time to read: 4 minutes

In this blog I am launching a small open source project, aws-cdk-utils.

The aws-cdk-utils is a collection of fringe constructs that I have found useful to re-use.

Vercel Secret Forwarder (Canary )

๐Ÿฆซ NPM: https://www.npmjs.com/package/@cdk-utils/vercel-secret-forwarder

๐Ÿฆ‘ GitHub: https://github.com/simonireilly/aws-cdk-utils

The vercel secret forwarder allows sending environment variables to Vercel, directly from your AWS account.

This means we you can follow security best practices, with a minimal configuration.

Features

  • ๐Ÿ”’ Send secrets to Vercel securely from AWS
  • ๐Ÿงช Support for preview deploys
  • ๐Ÿ› ๏ธ Utilities for binding Vercel URL(s)

Example

Lets say you have a CDK app, that deploys an API Gateway rest API, and a Cognito user pool.

The secrets you need in Vercel, when you build your app are:

  • API_GATEWAY_URL
  • NEXT_PUBLIC_COGNITO_CLIENT_ID

How can we get these into vercel??

Remember, if you are using preview deploys these environment variables will be different, and we want to keep them in sync.

Well, you can just add the forwarder to your aws-cdk or serverless-stack project.

yarn add @cdk-utils/[email protected]

Next, you can import the construct into your own stacks, and forward any configuration or environment variables to your preview deploys.

This enables keeping a preview environment in sync with a Vercel preview deployment, supporting fulls task preview environments with the best experiences from both the CDK and Vercel.

// You will need to get these values
// To get vercel use `vercel link` or starting fresh use `vercel init`
const config = {
  GitBranch: String(process.env.GIT_BRANCH),
  VercelAuthToken: String(process.env.VERCEL_AUTH_TOKEN),
  VercelProjectId: String(process.env.VERCEL_PROJECT_ID),
  VercelProjectName: String(process.env.VERCEL_PROJECT_NAME),
  VercelProjectOrganisation: String(process.env.VERCEL_ORGANISATION_NAME),
}

// Create the construct, and any secrets you need.
const vercel = new VercelSecretSyncConstruct(
  this,
  'SendSecretsToVercel',
  {
    ...config,
    VercelEnvironmentVariables: {
     API_GATEWAY_URL: api.url,
    }
  }
);

// Or add secrets later so you can define secrets across stacks
vercel.addSecret(
  'NEXT_PUBLIC_COGNITO_POOL_ID',
  auth.cognitoUserPool?.userPoolId
);

What does it deploy to my AWS Account

Ok, security is important, the @cdk-utils/vercel-secret-forwarder is aiming to have zero dependencies before moving out of alpha. Additionally it does not need to be granted any IAM access to your AWS account. The lambda runs in AWS's great big VPC play pen, with no access to your own VPC. It takes in messages from cloudformation, and sends secrets out to vercel using HTTPS/TLS over the internet; nothing more.

Architecture of custom resource for vercel secrets

  1. You perform an AWS-CDK deployment which generates cloudformation for your resources.
  2. This provisions a lambda function, which has no access to any other resources in your AWS Account.
  3. Next, each resolved VercelEnvironmentVariable is sent to vercel to create a preview environment variable.

By default all additional environment variables are configured as preview, and when the stack is torn down these secrets are removed.

Wrap Up

This is an exciting experiment for me, and hopefully it can be useful for others using the constructs.

The @cdk-utils are all in alpha, and I am routinely publishing under canary. When I reach v0.0.1 I will be publishing a latest tag release. The main goal is to remove as many dependencies before getting to that point.