
subaud is authored by Court Schuett (he/him). While Court is an AWS employee, opinions and statements on this blog are his own.


Court Schuett


# CDK Custom Resource Construct Example

[This](https://github.com/schuettc/cdk-custom-resource-construct-example) is an updated example of how to create a Custom Resource Construct for CDK. This example will walk you through the process of creating a [CDK Construct](https://constructs.dev/) that uses Typescript Custom Resources.

## Custom Resources

[Custom Resources](https://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/template-custom-resources.html) allow you to deploy and invoke Lambda functions during the deployment of a CDK. This can be used to supplement CDKs with features that are not natively part of CloudFormation or CDK.

In this example, our Lambda function is simply multiplying an input and returning the result

```typescript
try {
  const multiplyResult = event.ResourceProperties.customResourceNumber * 2;
  response.Status = 'SUCCESS';
  response.Data = { Result: multiplyResult };
  return response;
} catch (error) {
  if (error instanceof Error) {
    response.Reason = error.message;
  }
  response.Status = 'FAILED';
  response.Data = { Result: error };
  return response;
}
```

## Bundling

Because we are using Typescript for our Lambda, we must transpile it before we use it. To do this, we will use [projen](https://github.com/projen/projen) to execute an `esbuild` on our Lambda source code during the build.

To do this, in the `.projenrc.ts` we use `bundler.addBundle`:

```typescript
project.bundler.addBundle('./resources/lambda/', {
  platform: 'node',
  target: 'node18',
});
```

This will create an `index.js` in the `assets/resources/lambda` directory. This is the what we will use in the Custom Resource.

## Custom Resource Provider

To create the Custom Resource we will use [`CustomResourceProvider`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CustomResourceProvider.html). This is different from [`Provider`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources.Provider.html) which is what is normally used within a CDK.

```typescript
const customResourceProvider = CustomResourceProvider.getOrCreateProvider(
  this,
  'Custom::Resource',
  {
    codeDirectory:
      'node_modules/cdk-custom-resource-construct-example/assets/resources/lambda',
    runtime: CustomResourceProviderRuntime.NODEJS_18_X,
    timeout: Duration.seconds(60),
    policyStatements: [
      {
        Effect: 'Allow',
        Action: [
          'logs:CreateLogGroup',
          'logs:CreateLogStream',
          'logs:PutLogEvents',
        ],
        Resource: '*',
      },
    ],
  },
);
```

By using []`getOrCreateProvider`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CustomResourceProvider.html#static-getwbrorwbrcreatewbrproviderscope-uniqueid-props) we can ensure that the Lambda function is created only once even if it used multiple times. The `codeDirectory` used here is the output directory of the bundling. This is what will be used in the CDK that uses this Construct.

## Custom Resource

Finally, we will create the Custom Resource using the previously created Provider.

```typescript
const customResourceResult = new CustomResource(this, 'customResourceResult', {
  serviceToken: customResourceProvider.serviceToken,
  properties: {
    customResourceNumber: props.customResourceNumber,
  },
});

this.customResourceResult = customResourceResult.getAttString('Result');
```

This Custom Resource will take a `prop` when called and return the result.

## Using the Custom Resource

To use this Construct, we will import the `CustomResourceExample`, implement it, and pass it a prop.

```typescript
import { CfnOutput, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { CustomResourceExample } from 'cdk-custom-resource-construct-example';

export class CdkCustomResourceConstructDemoStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const result = new CustomResourceExample(this, 'customResourceResult', {
      customResourceNumber: 5,
    });

    new CfnOutput(this, 'customResourceOutput', {
      value: result.customResourceResult,
    });
  }
}
```

When used this way, the Custom Resource will deploy the Lambda, invoke it, and return the result to the calling CDK.

## Developing

It can be difficult to develop and test a Construct. [`yalc`](https://github.com/wclr/yalc) is a tool that can help with this by allowing us to "publish" locally. To use `yalc`, it should be installed as a `devDep` in the `.projenrc.ts` of the source Construct.

```typescript
  devDeps: ['yalc', 'esbuild'],
```

After building the construct using `yarn projen build`, you can use `yalc publish --push --sig` to push this package to the local store. This should result in an output similar to:

```bash
cdk-custom-resource-construct-example@0.0.0+80079907 published in store.
```

By adding `--sig` we can differentiate versions. In this example `+80079907` is the sig.

Next, you can create a project that uses this package. To do this, you can add the package with yalc: `yalc add cdk-custom-resource-construct-example`. This will add the package to the `package.json` file that can be used like any other package. If needed, you can use `yalc update`. The output should be similar to:

```bash
Package cdk-custom-resource-construct-example@0.0.0+80079907 added
```


CDK Constructs are a great way to create reusable and flexible code for yourself and others.  projen makes it easy to create and publish the project.  CDK Custom Resources are a way to do complex deployments and deploy AWS resources not native to CDK within a CDK.  In this example, an AWS Lambda will be used as a Custom Resource from a published package.

Updated CDK Construct with Custom Resources


> Note: This has been updated [here](/content/blog/updated-cdk-construct-with-custom-resources.md)

Building off of the previous example of [building CDK Custom Resources Constructs](https://subaud.io/blog/building-cdk-custom-resource-constructs-with-projen-and-typescript), in this post, we will look at the steps required to convert this from a JavaScript Lambda to a Typescript Lambda using some of the [magic of projen](https://projen.io/awscdk.html#aws-lambda-functions).

## CDK Construct Code

<pre>
.
├── .eslintrc.json
├── .gitattributes
├── .gitignore
├── .jsii
├── .mergify.yml
├── .npmignore
<mark>├── .projenrc.js</mark>
├── API.md
├── LICENSE
├── README.md
├── package.json
├── src
│   ├── custom-resource-function.ts
<mark>│   ├── custom-resource.lambda.ts
│   └── index.ts</mark>
├── test
│   └── customResource.test.ts
├── tsconfig.dev.json
├── tsconfig.json
└── yarn.lock
</pre>

### Lambda Function

In this example, we will be using projen AWS Lambda Functions to automatically create the Lambda function that will be used by the Custom Resource. In order to create this function, we will create `custom-resource.lambda.ts` in the `src` directory. This will include the Lambda code to be executed during the CDK deployment.

After creating this file, running `npx projen` will create the `custom-resource-function.ts` file in the `src` directory. This is what we will be using in the `index.ts` file as the Lambda function for the Custom Resource.

After importing the function:

```typescript
import { CustomResourceFunction } from './custom-resource-function';
```

We can reference it here:

```typescript
const customResourceLambda = new CustomResourceFunction(
  this,
  'customResourceLambda',
  {
    role: customResourceRole,
    architecture: Architecture.ARM_64,
    timeout: Duration.seconds(60),
  },
);
```

To define the runtime of the Lambda function, in the `.projenrc` file:

```js
  lambdaOptions: {
    runtime: awscdk.LambdaRuntime.NODEJS_18_X,
    bundlingOptions: {
      externals: ['aws-sdk'],
      sourcemap: true,
    },
  },
```

Be sure to check out projen documentation for details on how to use this. [https://projen.io/awscdk.html#aws-lambda-functions](https://projen.io/awscdk.html#aws-lambda-functions)

> **_NOTE:_** NODEJS_18_X is not currently available and this will default to NODEJS_14_X for now.

### Provider

Next, we will include a [`Provider`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources.Provider.html) The [Provider Framework](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources-readme.html#provider-framework) will simplify some of the responses in the Lambda function. This is the recommended approach when using Custom Resources in CDKs.

```typescript
const customResourceProvider = new Provider(this, 'customResourceProvider', {
  onEventHandler: customResourceLambda,
});
```

### Custom Resource

Finally, we will call this Custom Resource

```typescript
const customResourceResult = new CustomResource(this, 'customResourceResult', {
  serviceToken: customResourceProvider.serviceToken,
  properties: {
    customResourceNumber: props.customResourceNumber,
  },
});
```

## Custom Resource Lambda Code

The Typescript Lambda will use the type definitions from [`DefinitelyTyped`](https://github.com/DefinitelyTyped/DefinitelyTyped/tree/master/types/aws-lambda) to make things easier in the Lambda code.

```typescript
import {
  CdkCustomResourceEvent,
  CdkCustomResourceResponse,
  Context,
} from 'aws-lambda';

export const handler = async (
  event: CdkCustomResourceEvent,
  context: Context,
): Promise<CdkCustomResourceResponse> => {
  console.log('Lambda is invoked with:' + JSON.stringify(event));

  const response: CdkCustomResourceResponse = {
    StackId: event.StackId,
    RequestId: event.RequestId,
    LogicalResourceId: event.LogicalResourceId,
    PhysicalResourceId: context.logGroupName,
  };

  if (event.RequestType == 'Delete') {
    response.Status = 'SUCCESS';
    response.Data = { Result: 'None' };
    return response;
  }

  try {
    const multiplyResult = event.ResourceProperties.customResourceNumber * 2;
    response.Status = 'SUCCESS';
    response.Data = { Result: multiplyResult };
    return response;
  } catch (error) {
    if (error instanceof Error) {
      response.Reason = error.message;
    }
    response.Status = 'FAILED';
    response.Data = { Result: error };
    return response;
  }
};
```

Because we used the `Provider` when creating this Custom Resource, the response is significantly easier. We just need to [return](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.custom_resources-readme.html#handling-lifecycle-events-onevent) a `SUCCESS` or `FAILED` to the `onEvent`. We can do this with the `CdkCustomResourceResponse`.

## Using the Construct

No actual changes are needed in the [demo](https://github.com/schuettc/cdk-custom-resource-construct-demo).

### CDK Stack Code

```typescript
import { CfnOutput, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { CustomResourceExample } from 'cdk-custom-resource-construct-example';

export class CdkCustomResourceConstructDemoStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const result = new CustomResourceExample(this, 'customResourceResult', {
      customResourceNumber: 5,
    });

    new CfnOutput(this, 'customResourceOutput', {
      value: result.customResourceResult,
    });
  }
}
```

### Deploy

```bash
git clone https://github.com/schuettc/cdk-custom-resource-construct-demo
cd cdk-custom-resource-construct-demo
yarn
yarn run build
yarn cdk deploy
```

### Result

```
CdkCustomResourceConstructDemoStack: deploying...
 ✅  CdkCustomResourceConstructDemoStack

✨  Deployment time: 81.79s

Outputs:
CdkCustomResourceConstructDemoStack.customResourceOutput = 10
Stack ARN:
arn:aws:cloudformation:us-east-1:112233445566:stack/CdkCustomResourceConstructDemoStack/e47e0d90-742d-11ed-ab03-128d8230a997

✨  Total time: 84.66s
```

## Resources

- [GitHub Repository for Construct](https://github.com/schuettc/cdk-custom-resource-construct-example)
- [GitHub Repository for Demo](https://github.com/schuettc/cdk-custom-resource-construct-demo)
- [NPM Package](https://www.npmjs.com/package/cdk-custom-resource-construct-example)
- [constructs.dev construct](https://constructs.dev/packages/cdk-custom-resource-construct-example)


An update to the previous CDK Construct Custom Resource post.  This time we will be using Typescript instead of JavaScript for the Lambda function.

Using a Typescript Lambda as a CDK Construct Custom Resource


> Note: This has been updated [here](/content/blog/updated-cdk-construct-with-custom-resources.md)

CDK Constructs are a great way to create reusable and flexible code for yourself and others. projen makes it easy to create and publish the project. CDK Custom Resources are a way to do complex deployments and deploy AWS resources not native to CDK within a CDK. In this example, an AWS Lambda will be used as a Custom Resource from a published package.

## Setting Up the Project

To do this yourself: `npx projen new awscdk-construct`

This will create a [projen](https://github.com/projen/projen) project to be used. More information is available here when working with [AWS CDK Constructs](https://github.com/projen/projen/blob/main/docs/awscdk-construct.md). Additionally, this can be set up to publish to the very useful [constructs.dev](https://constructs.dev/contribute) so that others can use your Construct.

## Publishing the Project

Create an Access Token within npm to allow GitHub to publish to npm. Add this Access Token to GitHub in the Secrets section of the repository Settings as `NPM_TOKEN`

```bash
npx projen build
git add .
git commit -m 'commit comment'
git push
```

This will start a GitHub workflow action that will publish to npm.

## Example Construct Code

Standard Imports:

```typescript
import * as path from 'path';
import * as cdk from 'aws-cdk-lib';
import * as iam from 'aws-cdk-lib/aws-iam';
import * as lambda from 'aws-cdk-lib/aws-lambda';
import { Construct } from 'constructs';
```

The Interface that will be used to take input from the deployable CDK. Because this is Typescript, these will be enforced but can be a wide range of types.

```typescript
export interface CdkCustomResourceExampleProps extends cdk.ResourceProps {
  readonly customResourceNumber: number;
}
```

This is the object that will be returned to the deployable CDK as the output from the Custom Resource:

```typescript
export class CustomResourceExample extends Construct {
  public readonly customResourceResult: string;

  constructor(
    scope: Construct,
    id: string,
    props: CdkCustomResourceExampleProps,
  ) {
    super(scope, id);
```

The IAM Role used by the Lambda:

```typescript
const role = new iam.Role(this, 'CustomResourceRole', {
  description: 'Custom Resource Construct Example',
  assumedBy: new iam.ServicePrincipal('lambda.amazonaws.com'),
  managedPolicies: [
    iam.ManagedPolicy.fromAwsManagedPolicyName(
      'service-role/AWSLambdaBasicExecutionRole',
    ),
  ],
});
```

The Lambda that will be created to be used as the Custom Resource:

```typescript
const fn = new lambda.Function(this, 'CustomResourceLambda', {
  runtime: lambda.Runtime.NODEJS_14_X,
  code: lambda.Code.fromAsset(path.join(__dirname, '@/resources')),
  handler: 'index.handler',
  architecture: lambda.Architecture.ARM_64,
  role: role,
  timeout: cdk.Duration.minutes(1),
});
```

The Custom Resource that will be invoked using the above Lambda taking in the properties supplied by the deployable CDK.

```typescript
    const customResourceResult = new cdk.CustomResource(
      this,
      'customResourceResult',
      {
        serviceToken: fn.functionArn,
        properties: {
          customResourceNumber: props.customResourceNumber,
        },
      },
    );

    this.customResourceResult = customResourceResult.getAttString('Result');
  }
}
```

The Lambda code being invoked is a simple multiplication but can be used to create complex deployments that are not native to CDK. In order to simplify deployment, NodeJS has been used for the Lambda instead of Typescript. Typescript must be transpiled to NodeJS to run as a Lambda and using Typescript for the Construct allows us to take advantage of Types within the deployable CDK while still allowing for an easy-to-use package. Python could also be used for the same reasons.

## Demo CDK Code

To add the newly created package to the deployable CDK `yarn add cdk-custom-resource-construct-example`.

This will add it to the `package.json` like other installed dependencies.

```json
  "dependencies": {
    "aws-cdk-lib": "2.3.0",
    "cdk-custom-resource-construct-example": "*",
    "constructs": "^10.0.0",
    "source-map-support": "^0.5.16"
  }
```

In this simple example, the only resource being created is the output from the Custom Resource. `customResourceNumber` is required based on the configuration of the Interface in the Construct.

## Testing the CDK

```bash
git clone https://github.com/schuettc/cdk-custom-resource-construct-demo.git
cd cdk-custom-resource-construct-demo
yarn
yarn run build
yarn cdk deploy
```

This will deploy the CDK and produce the output of the Custom Resource.

```typescript
import { CfnOutput, Stack, StackProps } from 'aws-cdk-lib';
import { Construct } from 'constructs';
import { CustomResourceExample } from 'cdk-custom-resource-construct-example';

export class CdkCustomResourceConstructDemoStack extends Stack {
  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);

    const result = new CustomResourceExample(this, 'customResourceResult', {
      customResourceNumber: 5,
    });

    new CfnOutput(this, 'customResourceOutput', {
      value: result.customResourceResult,
    });
  }
}
```

## Resources

- [GitHub Repository for Construct](https://github.com/schuettc/cdk-custom-resource-construct-example)
- [GitHub Repository for Demo](https://github.com/schuettc/cdk-custom-resource-construct-demo)
- [NPM Package](https://www.npmjs.com/package/cdk-custom-resource-construct-example)
- [constructs.dev construct](https://constructs.dev/packages/cdk-custom-resource-construct-example)


Custom resource

Updated CDK Construct with Custom Resources

Using a Typescript Lambda as a CDK Construct Custom Resource

Building CDK Custom Resource Constructs with projen and Typescript