When I stumble upon an unsolved or undocumented problem and solve it, I like to document it here. subaud is authored by Court Schuett (he/him). While Court is an 8090 Inc employee, opinions and statements on this blog are his own.

About

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


Court Schuett


# AWS CDK Cognito Protected API Demo

This project demonstrates how to create a protected API using AWS CDK with Cognito authentication. It sets up a complete serverless infrastructure including API Gateway, Lambda, and Cognito User Pool. To test the API, we'll configure and use Postman with OAuth 2.0 to sign in and get an access token. This can be an easy way to test your API without setting up a frontend while still using JWTs for authentication.

## Architecture

The infrastructure consists of three main components:

**Cognito User Pool**: Handles user authentication

- Email-based sign-up and sign-in
- Password policies and email verification
- OAuth 2.0 flows support
- Hosted UI for sign-up/sign-in

**API Gateway**: Protected REST API

- Cognito authorizer integration
- Single GET endpoint `/hello`
- JWT token validation

**Lambda Function**: Backend logic

- Returns protected data
- Includes user information from Cognito claims

![Overview](/images/blog/cdk-cognito-api-postman/CogntioAPIPostman.drawio.png)

## Infrastructure Code Overview

### Cognito Setup (CognitoConstruct)

```typescript
this.userPool = new UserPool(this, "UserPool", {
  userPoolName: "postman-demo-user-pool",
  selfSignUpEnabled: true,
  signInAliases: { email: true },
  standardAttributes: {
    email: { required: true, mutable: true },
    givenName: { required: true, mutable: true },
  },
  passwordPolicy: {
    minLength: 8,
    requireLowercase: true,
    requireUppercase: true,
    requireDigits: true,
    requireSymbols: true,
  },
  signInCaseSensitive: false,
  userVerification: {
    emailStyle: VerificationEmailStyle.LINK,
    emailSubject: "Verify your email for our demo app!",
  },
});

this.userPoolClient = new UserPoolClient(this, "UserPoolClient", {
  userPool: this.userPool,
  oAuth: {
    flows: {
      authorizationCodeGrant: true,
      implicitCodeGrant: true,
    },
    scopes: [OAuthScope.EMAIL, OAuthScope.OPENID, OAuthScope.PROFILE],
    callbackUrls: [
      "http://localhost:3000/callback",
      "https://oauth.pstmn.io/v1/callback",
    ],
  },
  preventUserExistenceErrors: true,
  accessTokenValidity: Duration.minutes(60),
  idTokenValidity: Duration.minutes(60),
  refreshTokenValidity: Duration.days(30),
});
```

### API Gateway Setup (ApiGatewayConstruct)

```typescript
const api = new RestApi(this, "ProtectedApi", {
  restApiName: "Protected API Demo",
  description: "API Gateway with Cognito authorization",
});

const authorizer = new CognitoUserPoolsAuthorizer(this, "ApiAuthorizer", {
  cognitoUserPools: [props.userPool],
  authorizerName: "CognitoAuthorizer",
  identitySource: "method.request.header.Authorization",
  resultsCacheTtl: Duration.minutes(5),
});

const resource = api.root.addResource("hello");
resource.addMethod("GET", new LambdaIntegration(props.lambdaFunction), {
  authorizer: authorizer,
  authorizationType: AuthorizationType.COGNITO,
  authorizationScopes: ["email", "openid", "profile"],
});
```

## Understanding Cognito Tokens & API Security

### Token Flow

When a user authenticates through Cognito, three different tokens are issued:

1. **ID Token**: A JWT containing user identity claims (profile info, email, etc.)
2. **Access Token**: A JWT specifically for authorizing API requests
3. **Refresh Token**: Used to obtain new ID and Access tokens when they expire

### How API Gateway Authorization Works

1. Client obtains tokens through Cognito authentication
2. Client includes Access Token in API request (`Authorization: Bearer <token>`)
3. API Gateway:
   - Validates token signature using Cognito's public keys
   - Checks token expiration
   - Verifies audience (client_id) and issuer (Cognito User Pool)
   - Passes user claims to Lambda in `event.requestContext.authorizer`

### JWT Token Structure

Each token is a JSON Web Token (JWT) with three parts:

```bash
header.payload.signature
```

#### ID Token Example

https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-id-token.html

```json
{
  "sub": "user-uuid",
  "email_verified": true,
  "iss": "https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
  "cognito:username": "john.doe",
  "given_name": "John",
  "aud": "{clientId}",
  "token_use": "id",
  "exp": 1234567890,
  "iat": 1234567890
}
```

#### Access Token Example

https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-the-access-token.html

```json
{
  "sub": "user-uuid",
  "device_key": "device-id",
  "scope": "email openid profile",
  "iss": "https://cognito-idp.{region}.amazonaws.com/{userPoolId}",
  "token_use": "access",
  "exp": 1234567890,
  "iat": 1234567890
}
```

### Token Validation Process

https://docs.aws.amazon.com/cognito/latest/developerguide/amazon-cognito-user-pools-using-tokens-verifying-a-jwt.html

1. **Structure Verification**

   - Check if token is well-formed JWT
   - Verify token hasn't expired (`exp` claim)
   - Validate token use (`token_use` claim)

2. **Signature Validation**

   - Download JWKs from Cognito
   - Verify token signature using public key
   - Ensure issuer (`iss`) matches User Pool

3. **Claims Validation**
   - Verify audience (`aud`) matches client ID
   - Check required scopes are present
   - Validate any custom claims

### Security Best Practices

#### Token Configuration

- Access tokens expire in 60 minutes (configured in Cognito client)
- ID tokens expire in 60 minutes (configured in Cognito client)
- Refresh tokens expire in 30 days
- Authorization cache TTL set to 5 minutes in API Gateway
- Tokens must be sent in Authorization header

#### Cognito Security Settings

- Case-insensitive email sign-in enabled
- User existence errors prevented (security feature)
- Password requirements enforced:
  - Minimum length: 8 characters
  - Requires lowercase letters
  - Requires uppercase letters
  - Requires numbers
  - Requires special characters
- Email verification required
- OAuth flows:
  - Authorization Code Grant (for web apps)
  - Implicit Grant (for mobile apps)
- Strict callback URL validation

#### API Gateway Security

- Cognito authorizer validates tokens automatically
- Required scopes: email, openid, profile
- Authorization caching for performance (5-minute TTL)
- Token claims available to Lambda function

### Security Benefits

- **Token-based Authentication**: Stateless, scalable authentication
- **Short-lived Tokens**: Access tokens expire in 1 hour (configurable)
- **Signature Verification**: Prevents token tampering
- **Scope-based Access**: Can restrict API access based on token scopes
- **User Context**: Lambda receives verified user information
- **Standard OAuth2/OIDC**: Industry-standard security protocols

## Testing with Postman

### **Get the Hosted UI URL**

- After deploying, find the `HostedUISignUpUrl` in CloudFormation outputs
- Create an account through the Hosted UI
- Verify your email address

![SignUp](/images/blog/cdk-cognito-api-postman/SignUp.png)
_Sign up page_

![VerificationLink](/images/blog/cdk-cognito-api-postman/VerificationLink.png)
_Verification link_

![VerificationEmail](/images/blog/cdk-cognito-api-postman/VerificationEmail.png)
_Verification email_

###**Configure Postman**

- Create a new request
- Under Authorization tab:
  - Type: OAuth 2.0
  - Grant Type: Authorization Code
  - Callback URL: https://oauth.pstmn.io/v1/callback
  - Auth URL: [CognitoDomainUrl]/oauth2/authorize
  - Access Token URL: [CognitoDomainUrl]/oauth2/token
  - Client ID: [UserPoolClientId]
  - Scope: email openid profile

![UnauthorizedGET](/images/blog/cdk-cognito-api-postman/UnauthorizedGET.png)
_Example of unauthorized GET request_

![AuthorizationSetup1](/images/blog/cdk-cognito-api-postman/AuthorizationSetup1.png)
_Authorization tab with Auth Type set to OAuth 2.0_

![AuthorizationSetup2](/images/blog/cdk-cognito-api-postman/AuthorizationSetup2.png)
_Authorization tab Configuring new token_

### **Get Access Token**

- Click "Get New Access Token"
- Log in with your Cognito credentials
- Use the token for API requests

![AuthorizationSetup3](/images/blog/cdk-cognito-api-postman/AuthorizationSetup3.png)
_Click "Get New Access Token"_

![LoginPopup](/images/blog/cdk-cognito-api-postman/LoginPopup.png)
_Login popup_

![AuthenticationComplete](/images/blog/cdk-cognito-api-postman/AuthenticationComplete.png)
_Authentication complete_

![UseToken](/images/blog/cdk-cognito-api-postman/UseToken.png)
_Click "Use Token"_

### **Make API Requests**

- GET [ApiUrl]/hello

![AuthorizedGET](/images/blog/cdk-cognito-api-postman/AuthorizedGET.png)
_Example of authorized GET request_

## Deployment

```bash
yarn
yarn cdk deploy
```

The deployment will output:

- Cognito Domain URL
- User Pool ID
- Client ID
- API Gateway URL
- Hosted UI URL for sign-up
- Auth URL
- Token URL

## Cleanup

```bash
yarn cdk destroy
```


In this demo we will see how to deploy a Cognito protected API and test it with Postman using OAuth 2.0 for authentication and login

CDK Cognito Protected API Demo with Postman


# Next.js SSR App Runner Deployment with CloudFront

This project demonstrates how to deploy a Next.js SSR application using AWS App Runner and CloudFront. It uses an AWS CDK to define and deploy the infrastructure. The project is managed with projen and includes several custom tasks to support the development process.

Update to: https://subaud.io/blog/next-js-app-runner-with-deployment

GitHub: https://github.com/schuettc/next-js-app-runner-deployment

## Architecture

The architecture consists of the following components:

- Next.js application
- AWS App Runner to host and run the Next.js application
- Amazon CloudFront as a content delivery network (CDN) in front of App Runner
- Lambda@Edge to rewrite headers and support dynamic routing
- Route53 ARecords for DNS
- AWS CDK to define and deploy the infrastructure
- GitHub actions for CI/CD

![Overview](/images/blog/updated-nextjs-app-runner-deployment-with-srr/NextJSAppCloudfront.png)

## Prerequisites

- AWS Account
- Node.js (version 18 or later)
- AWS CDK CLI
- Docker (for local development and testing)

## Getting Started

Clone the repository:

```bash
git clone https://github.com/schuettc/next-js-app-runner-deployment.git
cd next-js-app-runner-deployment
```

Install dependencies:

```bash
yarn
```

Deploy the stack:

```bash
yarn launch
```

## Project Structure

- `src/`: Contains the CDK infrastructure code
  - `appRunner.ts`: Defines the App Runner service
  - `cloudfront.ts`: Sets up the CloudFront distribution
  - `lambda.ts`: Creates the Lambda@Edge function
  - `route53.ts`: Defines the DNS records
  - `next-js-app-runner-deployment.ts`: Main stack definition
- `src/resources/app/`: Contains the Next.js application code

## Custom Origin Request Policy

This project implements a custom origin request policy for CloudFront, which is required when using App Runner as the origin. The policy allows specific headers to be forwarded to the origin:

```typescript:src/cloudfront.ts
    const customOriginRequestPolicy = new OriginRequestPolicy(
      this,
      'UserAgentRefererHeadersPolicy',
      {
        headerBehavior: OriginRequestHeaderBehavior.allowList(
          'User-Agent',
          'Referer',
        ),
      },
    );
```

This custom policy ensures that the `User-Agent` and `Referer` headers are forwarded to the App Runner service, which solves the 404 error that occurs when using AppRunner as the origin for a CloudFront distribution.

https://docs.aws.amazon.com/apprunner/latest/dg/request-route-404-troubleshoot.html

## Lambda@Edge for Header Rewriting

This project uses a Lambda@Edge function to rewrite headers, which is crucial for supporting dynamic routing in Next.js when using App Runner behind CloudFront. The function is associated with both the Origin Request and Viewer Request events in CloudFront.

Here's the Lambda@Edge function code:

```typescript:src/resources/lambdaEdge/index.ts
import { CloudFrontRequestEvent, CloudFrontRequestResult } from 'aws-lambda';

export const handler = async (
  event: CloudFrontRequestEvent,
): Promise<CloudFrontRequestResult> => {
  const request = event.Records[0].cf.request;
  const origin = request.origin?.custom;

  if (origin && origin.domainName) {
    request.headers.host = [{ key: 'Host', value: origin.domainName }];
  }

  return request;
};

```

This function rewrites the `Host` header to match the origin's domain name, ensuring that App Runner receives the correct host information. This is essential for Next.js to properly handle dynamic routes.

The Lambda@Edge function is associated with CloudFront in the following way:

```typescript
        edgeLambdas: [
          {
            functionVersion: lambdaEdgeFunction.function.currentVersion,
            eventType: LambdaEdgeEventType.ORIGIN_REQUEST,
          },
          {
            functionVersion: lambdaEdgeFunction.function.currentVersion,
            eventType: LambdaEdgeEventType.VIEWER_REQUEST,
          },
        ],
      },
```

By attaching this function to both the Origin Request and Viewer Request events, we ensure that the headers are properly rewritten for all incoming requests, allowing Next.js to handle dynamic routing correctly when deployed on App Runner behind CloudFront.

## Deployment

The project includes a GitHub Actions workflow for automated deployments. When you push changes to the `main` branch, it will automatically deploy the updated stack to AWS.

To deploy manually:

1. Configure your AWS credentials
2. Run `yarn deploy`

### projen configuration

```typescript
const deploy = project.github?.addWorkflow("deploy");
deploy?.on({
  push: {
    branches: ["main"],
  },
  workflow_dispatch: {},
});

deploy?.addJobs({
  deploy: {
    runsOn: ["ubuntu-latest"],
    permissions: {
      contents: JobPermission.READ,
      id_token: JobPermission.WRITE,
    },
    steps: [
      { uses: "actions/checkout@v4" },
      {
        uses: "actions/setup-node@v4",
        with: {
          "node-version": "18",
        },
      },
      { run: "yarn install --frozen-lockfile" },
      {
        uses: "aws-actions/configure-aws-credentials@v4",
        with: {
          "aws-access-key-id": "${{ secrets.AWS_ACCESS_KEY_ID }}",
          "aws-secret-access-key": "${{ secrets.AWS_SECRET_ACCESS_KEY }}",
          "aws-region": "${{ secrets.AWS_REGION }}",
        },
      },
      { run: "npx cdk deploy --require-approval never" },
    ],
  },
});
```

## Server Side Rendering

This NextJS includes support for Server Side Rendering (SRR) through dynamic routes and API routes:

```typescript
export default function Post({ params }: { params: { id: string } }) {
  return (
    <div>
      <h1>Post {params.id}</h1>
      <p>This is a dynamic route for post with ID: {params.id}</p>
    </div>
  );
}
```

```typescript
import { NextResponse } from "next/server";

export async function GET() {
  return NextResponse.json({ message: "Hello from the API!" });
}

export async function POST(request: Request) {
  const body = await request.json();
  return NextResponse.json({ message: "Hello from the API!", data: body });
}
```

## Local Development

To run the Next.js application locally:

Navigate to the app directory:

```bash
cd src/resources/app
```

Install dependencies:

```bash
yarn
```

Start the development server:

```bash
yarn dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser

## GitHub Updates with Projen

The project uses projen to manage the project and the Next.js application. We have replaced the default projen upgrade with a custom upgrade. This allows us to upgrade the dependencies for both the main project and the Next.js application in a single step.

```typescript
const upgradeWorkflow = project.github?.addWorkflow("upgrade");
upgradeWorkflow?.on({
  schedule: [{ cron: "0 0 * * 1" }],
  workflow_dispatch: {},
});

upgradeWorkflow?.addJobs({
  upgrade: {
    runsOn: ["ubuntu-latest"],
    permissions: {
      contents: JobPermission.WRITE,
      pullRequests: JobPermission.WRITE,
    },
    steps: [
      { uses: "actions/checkout@v4" },
      { uses: "actions/setup-node@v4", with: { "node-version": "18" } },
      { run: "yarn install" },
      { run: "npx projen upgrade:projen" },
      { run: "npx projen upgrade:nextjs" },
      {
        name: "Create Pull Request",
        uses: "peter-evans/create-pull-request@v6",
        with: {
          token: "${{ secrets.PROJEN_GITHUB_TOKEN }}",
          "commit-message": "chore: upgrade dependencies",
          branch: "projen-upgrade",
          title: "chore: upgrade dependencies",
          body: "This PR upgrades project dependencies, including projen and Next.js. Auto-generated by projen upgrade workflow.",
        },
      },
    ],
  },
});

project.addTask("upgrade:nextjs", {
  exec: ["cd src/resources/app", "yarn upgrade --latest", "cd ../../.."].join(
    " && "
  ),
});

project.addTask("upgrade:projen", {
  description: "Upgrade projen dependencies",
  steps: [
    { exec: "yarn upgrade projen @projen/awscdk-app-ts" },
    { exec: "npx projen" },
  ],
});
```

## Route 53 DNS Configuration

This project uses Amazon Route 53 to manage DNS records for the deployed application. The `Route53Resources` construct in `src/route53.ts` sets up the necessary DNS records to point your domain to the CloudFront distribution.

Two A records are created:

- One for the apex domain (e.g., example.com)
- One for the www subdomain (e.g., www.example.com)

Both A records are set up as alias records pointing to the CloudFront distribution:

```typescript
new ARecord(this, "AliasRecord", {
  zone: hostedZone,
  target: RecordTarget.fromAlias(new CloudFrontTarget(props.distribution)),
  recordName: `${props.domainName}.`,
});

new ARecord(this, "WWWAliasRecord", {
  zone: hostedZone,
  target: RecordTarget.fromAlias(new CloudFrontTarget(props.distribution)),
  recordName: `www.${props.domainName}.`,
});
```

This configuration ensures that both the apex domain and the www subdomain resolve to the CloudFront distribution, which in turn serves the Next.js application running on App Runner.

By using alias records, we benefit from Route 53's ability to automatically update the DNS records if the CloudFront distribution's domain name changes, without any manual intervention.

Make sure to update your domain's name servers to use the ones provided by your Route 53 hosted zone for this configuration to take effect.


Updated NextJS App deployed to App Runner with SSR and GitHub Actions


# Multi-Region Pipeline with AWS CDK

This project implements a multi-region deployment pipeline using AWS CDK. It demonstrates how to create a centralized pipeline that can deploy resources across multiple AWS regions, with a focus on passing parameters between stacks and regions.

## GitHub Repo

https://github.com/schuettc/multi-region-pipeline-with-parameters

## Architecture Overview

![Architecture Diagram](/images/blog/multi-region-deployment-pipeline/MultiRegionPipelineOverview.png)

The solution consists of the following main components:

- **Central Pipeline Stack**: Orchestrates the deployment across multiple regions.
- **Data Stack**: Deployed in the primary region (us-east-1) to manage shared resources.
- **Regional Stacks**: Deployed in each specified region, containing region-specific resources.
- **SNS Topic**: Used for cross-region communication.
- **Lambda Functions**: Deployed in each region to demonstrate the multi-region setup.

## Key Features

- **Multi-Region Deployment**: Automatically deploys resources to multiple AWS regions.
- **Cross-Region Parameter Sharing**: Uses SSM Parameter Store to share information across regions.
- **Centralized SNS Topic**: Facilitates communication between regional resources.
- **Dynamic Region Configuration**: Easily add or remove regions from the deployment.
- **Automated CI/CD**: Uses AWS CodePipeline for continuous integration and deployment.

## Prerequisites

- AWS Account
- AWS CLI configured with appropriate credentials
- Node.js and npm installed

## Project Structure

```bash
.
├── src/
│ ├── config/
│ │ └── regions.ts # Region configuration
│ ├── dataStack/ # Central data stack
│ ├── regionStacks/ # Regional stack definition
│ └── pipeline.ts # Main pipeline definition
├── bootstrapRegions.ts # Script to bootstrap CDK in all regions
├── invokeRegionalLambdas.ts # Script to test regional Lambdas
└── .projenrc.ts # Projen configuration
```

## Deployment

Fork the repository

Clone your forked repository:

```bash
git clone https://github.com/your-username/multi-region-pipeline.git
cd multi-region-pipeline
```

Configure [CodeStar Connection](https://docs.aws.amazon.com/codepipeline/latest/userguide/connections-github.html) with your AWS Account

Update the configuration in `src/multi-region-pipeline.ts` with your information:

```typescript
const pipelineName = "MultiRegionPipeline";
const repoOwner = "schuettc";
const repoName = "multi-region-pipeline-with-parameters";
const repoBranch = "main";
const connectionArn =
  "arn:aws:codeconnections:sa-east-1:104621577074:connection/xxxxxxxxxxxxx";
const accountId = "104621577074";
```

Install dependencies:

```bash
yarn
```

Bootstrap CDK in all required regions:

```bash
yarn bootstrapRegions
```

7. Build the project:

```bash
yarn build
```

Deploy the pipeline:

```bash
yarn launch
```

## How it Works

The regions used in this example are defined in `src/config/regions.ts` file:

```typescript
export const multiRegionConfig: RegionConfig[] = [
  {
    region: "us-east-1",
    services: ["service-a", "service-b", "service-c"],
  },
  {
    region: "us-west-2",
    services: ["service-a", "service-b", "service-c", "service-d"],
  },
];
```

## Pipeline

The pipeline is defined in `src/pipeline.ts` file:

```typescript
const pipeline = new CodePipeline(this, "Pipeline", {
  pipelineName: props.pipelineConfig.pipelineName,
  crossAccountKeys: true,
  synth: new ShellStep("Synth", {
    input: CodePipelineSource.connection(
      `${props.pipelineConfig.repoOwner}/${props.pipelineConfig.repoName}`,
      props.pipelineConfig.repoBranch,
      {
        connectionArn: props.pipelineConfig.connectionArn,
      }
    ),
    env: {
      PIPELINE_NAME: props.pipelineConfig.pipelineName,
      REPO_OWNER: props.pipelineConfig.repoOwner,
      REPO_NAME: props.pipelineConfig.repoName,
      REPO_BRANCH: props.pipelineConfig.repoBranch,
      CONNECTION_ARN: props.pipelineConfig.connectionArn,
      ACCOUNT_ID: this.account,
    },
    commands: ["yarn install --frozen-lockfile", "yarn build", "npx cdk synth"],
  }),
});
```

This provides us the pipeline that we will use to deploy our application.

## Data Stack

The data stack is deployed in the primary region (us-east-1) and contains resources that are shared across all regions. In this example it contains an SNS Topic that is used to receive events from the regional lambdas. We then save the ARN of this topic in the SSM Parameter Store, so that we can reference it in the regional stacks. We will add it to the pipeline so that it is deployed to the `us-east-1` region.

```typescript
const dataStage = new DataStage(this, "DataStage", {
  env: { account: this.account, region: "us-east-1" },
});
pipeline.addStage(dataStage);
```

The stack is defined in `src/dataStack/dataStack.ts` file:

```typescript
export class DataStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps) {
    super(scope, id, props);

    const snsResources = new SNSResources(this, "SNSResources");
    new LambdaResources(this, "LambdaResources", snsResources.topic);

    new CfnOutput(this, "TopicArn", { value: snsResources.topic.topicArn });

    new StringParameter(this, "TopicArnParam", {
      parameterName: "/mulit-region-pipeline/topic-arn",
      stringValue: snsResources.topic.topicArn,
    });
  }
}
```

## Regional Stacks

The regional stacks are deployed in each region that we have defined in the `multiRegionConfig` array. They contain the resources that are specific to that region. In this example they contain a Lambda function that sends a message to the SNS topic that is shared across regions. First, we'll add a wave to our pipeline for the regional deployments.

```typescript
const regionalWave = pipeline.addWave("RegionalDeployments");

getAllRegions().forEach((region) => {
  const regionalStage = new RegionalStage(this, `RegionalStage-${region}`, {
    env: { account: this.account, region },
  });
  regionalWave.addStage(regionalStage);
});
```

The Stack that is deployed in each region is defined in `src/regionStacks/regionStack.ts` file:

```typescript
export class RegionStack extends Stack {
  constructor(scope: Construct, id: string, _props: StackProps) {
    super(scope, id, _props);

    const ssmReaders = new SSMReaders(this, "SSMReaders");

    const topic = Topic.fromTopicArn(
      this,
      "ImportedErrorTopic",
      ssmReaders.topicArn
    );
    const lambdaResources = new LambdaResources(this, "LambdaResources", topic);

    new CfnOutput(this, "LambdaFunctionName", {
      value: lambdaResources.lambdaFunction.functionName,
      exportName: `${this.stackName}-LambdaFunctionName`,
    });
  }
}
```

In order to read the parameter from the SSM Parameter Store, we will use a Custom Resource that will read the parameter and return the value to the regional stack. This is defined in `src/regionStacks/ssmReader.ts` file:

```typescript
const ssmPolicy = new PolicyStatement({
  actions: ["ssm:GetParameter"],
  resources: [
    `arn:aws:ssm:us-east-1:${
      Stack.of(this).account
    }:parameter/mulit-region-pipeline/*`,
  ],
});

const snsTopicArnReader = new AwsCustomResource(this, "SNSTopicArnReader", {
  onCreate: {
    service: "SSM",
    action: "getParameter",
    parameters: {
      Name: "/mulit-region-pipeline/topic-arn",
    },
    region: "us-east-1",
    physicalResourceId: PhysicalResourceId.of("TopicArnParameter"),
  },
  onUpdate: {
    service: "SSM",
    action: "getParameter",
    parameters: {
      Name: "/mulit-region-pipeline/topic-arn",
    },
    region: "us-east-1",
    physicalResourceId: PhysicalResourceId.of("TopicArnParameter"),
  },
  policy: AwsCustomResourcePolicy.fromStatements([ssmPolicy]),
});

this.topicArn = snsTopicArnReader.getResponseField("Parameter.Value");
```

This will allow us to read the parameter from the SSM Parameter Store and use it in the regional stack as an environment variable in the Lambda function.

## Testing

After deployment, you can test the regional Lambda functions using the `invokeRegionalLambdas.ts` script:

```bash
yarn invokeRegionalLambdas
```

This will invoke the Lambda functions in each region and print the response to the console.

This script will invoke the Lambda function in each deployed region and display the results.

## Cross-Region Communication

The project demonstrates cross-region communication using a central SNS topic. Regional Lambdas can publish messages to this topic, which can be consumed by a central Lambda function.

## Cleanup

To remove all deployed resources:

```bash
yarn cdk destroy
```


This demo will explain how to deploy a multi-region pipeline with AWS CDK by passing parameters between stacks.

Deploying a multi-region pipeline with AWS CDK


# Next.js App Runner Deployment with CloudFront

This project demonstrates how to deploy a Next.js application using AWS App Runner and CloudFront. It uses the AWS CDK to define and deploy the infrastructure. The project is managed with projen and includes several custom tasks to support the development process.

Please see update: [https://subaud.io/blog/updated-nextjs-app-runner-deployment-with-ssr](https://subaud.io/blog/updated-nextjs-app-runner-deployment-with-ssr)

## Architecture

The architecture consists of the following components:

1. A Next.js application
2. AWS App Runner to host and run the Next.js application
3. Amazon CloudFront as a content delivery network (CDN) in front of App Runner
4. AWS CDK to define and deploy the infrastructure

## Key Features

- Serverless deployment of a Next.js application using AWS App Runner
- CloudFront distribution with custom origin request policy
- Automated CI/CD pipeline using GitHub Actions
- Infrastructure as Code using AWS CDK

## Prerequisites

- AWS Account
- Node.js (version 18 or later)
- AWS CDK CLI
- Docker (for local development and testing)

## Getting Started

Clone the repository:

```bash
git clone https://github.com/schuettc/next-js-app-runner-deployment.git
cd next-js-app-runner-deployment
```

Install dependencies:

```bash
yarn
```

Deploy the stack:

```bash
yarn launch
```

## Project Structure

- `src/`: Contains the CDK infrastructure code
  - `appRunner.ts`: Defines the App Runner service
  - `cloudfront.ts`: Sets up the CloudFront distribution
  - `next-js-app-runner-deployment.ts`: Main stack definition
- `src/resources/app/`: Contains the Next.js application code

## Custom Origin Request Policy

This project implements a custom origin request policy for CloudFront, which is required when using App Runner as the origin. The policy allows specific headers to be forwarded to the origin:

```typescript:src/cloudfront.ts
    const customOriginRequestPolicy = new OriginRequestPolicy(
      this,
      'UserAgentRefererHeadersPolicy',
      {
        headerBehavior: OriginRequestHeaderBehavior.allowList(
          'User-Agent',
          'Referer',
        ),
      },
    );
```

This custom policy ensures that the `User-Agent` and `Referer` headers are forwarded to the App Runner service, which solves the 404 error that occurs when using AppRunner as the origin for a CloudFront distribution.

https://docs.aws.amazon.com/apprunner/latest/dg/request-route-404-troubleshoot.html

## Deployment

The project includes a GitHub Actions workflow for automated deployments. When you push changes to the `main` branch, it will automatically deploy the updated stack to AWS.

To deploy manually:

1. Configure your AWS credentials
2. Run `yarn deploy`

### projen configuration

```typescript
const deploy = project.github?.addWorkflow('deploy');
deploy?.on({
  push: {
    branches: ['main'],
  },
  workflow_dispatch: {},
});

deploy?.addJobs({
  deploy: {
    runsOn: ['ubuntu-latest'],
    permissions: {
      contents: JobPermission.READ,
      id_token: JobPermission.WRITE,
    },
    steps: [
      { uses: 'actions/checkout@v4' },
      {
        uses: 'actions/setup-node@v4',
        with: {
          'node-version': '18',
        },
      },
      { run: 'yarn install --frozen-lockfile' },
      {
        uses: 'aws-actions/configure-aws-credentials@v4',
        with: {
          'aws-access-key-id': '${{ secrets.AWS_ACCESS_KEY_ID }}',
          'aws-secret-access-key': '${{ secrets.AWS_SECRET_ACCESS_KEY }}',
          'aws-region': '${{ secrets.AWS_REGION }}',
        },
      },
      { run: 'npx cdk deploy --require-approval never' },
    ],
  },
});
```

## Local Development

To run the Next.js application locally:

Navigate to the app directory:

```bash
cd src/resources/app
```

Install dependencies:

```bash
yarn
```

Start the development server:

```bash
yarn dev
```

Open [http://localhost:3000](http://localhost:3000) in your browser

## GitHub Updates with Projen

The project uses projen to manage the project and the Next.js application. We have replaced the default projen upgrade with a custom upgrade. This allows us to upgrade the dependencies for both the main project and the Next.js application in a single step.

```typescript
const upgradeWorkflow = project.github?.addWorkflow('upgrade');
upgradeWorkflow?.on({
  schedule: [{ cron: '0 0 * * 1' }],
  workflow_dispatch: {},
});

upgradeWorkflow?.addJobs({
  upgrade: {
    runsOn: ['ubuntu-latest'],
    permissions: {
      contents: JobPermission.WRITE,
      pullRequests: JobPermission.WRITE,
    },
    steps: [
      { uses: 'actions/checkout@v4' },
      { uses: 'actions/setup-node@v4', with: { 'node-version': '18' } },
      { run: 'yarn install' },
      { run: 'npx projen upgrade:projen' },
      { run: 'npx projen upgrade:nextjs' },
      {
        name: 'Create Pull Request',
        uses: 'peter-evans/create-pull-request@v6',
        with: {
          'token': '${{ secrets.PROJEN_GITHUB_TOKEN }}',
          'commit-message': 'chore: upgrade dependencies',
          'branch': 'projen-upgrade',
          'title': 'chore: upgrade dependencies',
          'body':
            'This PR upgrades project dependencies, including projen and Next.js. Auto-generated by projen upgrade workflow.',
        },
      },
    ],
  },
});

project.addTask('upgrade:nextjs', {
  exec: ['cd src/resources/app', 'yarn upgrade --latest', 'cd ../../..'].join(
    ' && ',
  ),
});

project.addTask('upgrade:projen', {
  description: 'Upgrade projen dependencies',
  steps: [
    { exec: 'yarn upgrade projen @projen/awscdk-app-ts' },
    { exec: 'npx projen' },
  ],
});
```


NextJS App deployed to App Runner with GitHub Actions


# Deploying an NVIDIA NIM to EC2

This demo will show you how to deploy an [NVIDIA NIM](https://www.nvidia.com/en-us/ai/) to an Amazon EC2 instance and enable it for inference.

## GitHub Repository

https://github.com/schuettc/ec2-nim-deployment

## Requirements

- NGC API key
- Route 53 Hosted Zone/Domain
- On-Demand vCPU quota

### NGC API Key

In order to use this demo, you will need an NGC API key. This key can be generated here: https://org.ngc.nvidia.com/setup/personal-keys

We will upload this key to [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/) and will be used within the EC2 instance to log in to NGC to download the container.

### Route 53 Hosted Zone/Domain

To enable [TLS security on the Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/create-https-listener.html), we need to generate a certificate using [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/). In order to generate this certificate, we need a domain and Hosted Zone in [Amazon Route 53](https://aws.amazon.com/route53/). We will configure this before launching the stack.

### On-Demand vCPU quota

This demo will launch a G5 EC2 instance. The number of vCPUs used by this instance will depend on the size. For example, a G5.12xlarge instance will use 48 vCPUs. Be sure to [check your utilization and quota value](https://us-west-2.console.aws.amazon.com/servicequotas/home/services/ec2/quotas/L-DB2E81BA) to make sure you can launch this instance. You can request an increase if necessary.

## Setup

### .env Configuration

Before launching, be sure to configure a `.env` file. Many of these fields can be left with their defaults.

```bash
# Stack Configuration
STACK_NAME=nim-stack
AWS_REGION=us-west-2
TEMPLATE_FILE=nims-stack.yaml

# Instance Configuration
INSTANCE_TYPE=g5.12xlarge

# AWS Resources
KEY_NAME=REPLACE_WITH_YOUR_KEY
VPC_ID=
SUBNET_IDS=

# Domain Configuration
DOMAIN_NAME=HOSTNAME.EXAMPLE.COM
HOSTED_ZONE_ID=REPLACE_WITH_YOUR_HOSTED_ZONE_ID

# NVIDIA Configuration
NGC_API_KEY_SECRET_NAME=NGCApiKeySecret
NGC_API_KEY=REPLACE_WITH_YOUR_NGC_API_KEY
REPOSITORY=nim/meta/llama3-8b-instruct
LATEST_TAG=1.0.0
```

You will need to update the following before launching:

```bash
# AWS Resources
KEY_NAME=REPLACE_WITH_YOUR_KEY

# Domain Configuration
DOMAIN_NAME=HOSTNAME.EXAMPLE.COM
HOSTED_ZONE_ID=REPLACE_WITH_YOUR_HOSTED_ZONE_ID

# NVIDIA Configuration
NGC_API_KEY=REPLACE_WITH_YOUR_NGC_API_KEY
```

### Secret Update

To upload the NGC API key to Secrets Manager, run the script:

```bash
./update_ngc_api_key.sh
```

This API Key will be retrieved by the EC2 instance during deployment.

### Launch Cloudformation Stack

You can either create the stack in the AWS Console, or through the included script. The script will populate the parameters required that were configured in the `.env` file. You will need to configure the required parameters in the console.

## Inference

Once the deployment succeeds, you can run inference requests against it using a variety of tools. Included is a script that uses `curl` to make a request to the endpoint using the configured domain name.

```bash
curl -s -X POST "https://$DOMAIN_NAME/v1/chat/completions" \
    -H "Content-Type: application/json" \
    -d '{
        "model": "'"$model_id"'",
        "messages": [
            {"role": "user", "content": "Hello! How are you?"},
            {"role": "assistant", "content": "Hi! I am quite well, how can I help you today?"},
            {"role": "user", "content": "Write a short limerick about the wonders of GPU computing."}
        ],
        "max_tokens": 100
    }' | jq '.choices[0].message.content'
```

To test the endpoint and inference:

```bash
./inference.sh
```

# How it Works

## Components

![Overview](/images/blog/deploying-an-nvidia-nim-to-ec2/Overview.png)

### EC2 Instance

- Uses a G5 instance type (default: g5.12xlarge) for GPU capabilities
- Runs Ubuntu with NVIDIA drivers, Docker, and NVIDIA Container Toolkit
- Automatically pulls and runs the specified NIM container

### Auto Scaling Group (ASG)

- Manages a single EC2 instance
- Ensures high availability and easy updates
- Uses a Launch Template for instance configuration

### Application Load Balancer (ALB)

- Provides HTTPS termination
- Routes traffic to the EC2 instance
- Uses an ACM certificate for HTTPS

### VPC and Networking

- Creates a new VPC with public subnets (or uses existing ones)
- Sets up necessary security groups and routing

### Route 53

- Creates a DNS record pointing to the ALB

## EC2 Configuration

1. The stack creates or uses existing VPC and subnets
2. An EC2 instance is launched with the necessary software and configurations
3. The NIM container is pulled and started on the EC2 instance
4. An ALB is set up to route traffic to the EC2 instance
5. A Route 53 record is created to point the specified domain to the ALB

The stack uses conditions to determine whether to create new VPC resources or use existing ones, making it flexible for different deployment scenarios.

## UserData Script Details

The UserData script in the Launch Template performs several key setup tasks:

1. **System Updates and Dependencies**

   - Updates the package list
   - Installs Python3-pip, AWS CLI, and CloudFormation helper scripts

2. **NVIDIA Driver and CUDA Installation**

   - Installs Linux headers
   - Adds NVIDIA CUDA repository
   - Installs CUDA drivers

3. **Docker Installation**

   - Adds Docker repository
   - Installs Docker CE

4. **NVIDIA Container Toolkit Installation**

   - Adds NVIDIA Docker repository
   - Installs nvidia-docker2
   - Restarts Docker service

5. **NGC API Key Retrieval**

   - Fetches the NGC API Key from AWS Secrets Manager

6. **NIM Container Setup and Run**

   - Sets up environment variables for the container
   - Creates a local cache directory
   - Logs in to the NGC container registry
   - Runs the NIM container with the following configuration:
     - Uses NVIDIA runtime
     - Exposes port 8000
     - Mounts a local cache volume
     - Sets the NGC API Key as an environment variable

7. **Signaling**
   - Signals the success or failure of the setup to CloudFormation

## Docker Container and ALB Interaction

1. **Container Exposure**

   - The NIM container exposes port 8000 inside the EC2 instance

2. **Security Group Configuration**

   - The EC2 security group allows inbound traffic on port 8000 from the ALB security group

3. **ALB Target Group**

   - An ALB Target Group is created with the following properties:
     - Protocol: HTTP
     - Port: 8000
     - Health check path: /health

4. **ALB Listener**

   - The ALB listener is configured for HTTPS (port 443)
   - It forwards traffic to the Target Group

5. **Request Flow**

   - Incoming HTTPS requests hit the ALB
   - The ALB terminates SSL and forwards the request as HTTP to the EC2 instance on port 8000
   - The Docker container receives the request on port 8000 and processes it

6. **Health Checks**
   - The ALB periodically sends health check requests to the `/health` endpoint
   - The NIM container responds to these health checks, allowing the ALB to determine if the instance is healthy

## Instance Types and Costs

This CloudFormation template supports the following instance types for NVIDIA AI Microservices (NIM):

### G5 Instances

- g5.xlarge: 1 GPU, 4 vCPUs, 16 GB RAM
- g5.2xlarge: 1 GPU, 8 vCPUs, 32 GB RAM
- g5.4xlarge: 1 GPU, 16 vCPUs, 64 GB RAM
- g5.8xlarge: 1 GPU, 32 vCPUs, 128 GB RAM
- g5.16xlarge: 1 GPU, 64 vCPUs, 256 GB RAM
- g5.12xlarge: 4 GPUs, 48 vCPUs, 192 GB RAM
- g5.24xlarge: 4 GPUs, 96 vCPUs, 384 GB RAM
- g5.48xlarge: 8 GPUs, 192 vCPUs, 768 GB RAM

⚠️ **Warning**: These instances can be very expensive to run. Please check the current AWS pricing for your region before deploying. For example, as of 2023, the costs for G5 instances in the US East (N. Virginia) region range from $1.006/hour for g5.xlarge to $16.288/hour for g5.48xlarge.

Always remember to stop or terminate your instances when not in use to avoid unnecessary charges.


In this demo we will see how to deploy an NVIDIA NIM to EC2 with Docker to do your own inference

Deploying an NVIDIA NIM to EC2


# GitHub Repository Metrics: A Serverless AWS Implementation

## Overview

This project implements a serverless solution for automatically collecting and analyzing GitHub repository metrics. It uses AWS services including Lambda, S3, Athena, Glue, and EventBridge to gather data from GitHub, store it efficiently, and make it available for analysis.

![Overview](/images/blog/github-insights/GitHubInsights.png)

## GitHub

All code is available here: https://github.com/schuettc/github-insights

## System Architecture

The solution consists of five main components:

1. Lambda Function: Fetches data from GitHub API
2. S3 Bucket: Stores data in Parquet format
3. Glue Database and Table: Defines schema for the data
4. Athena Workgroup and Query: Enables SQL-based analysis
5. EventBridge Rule: Schedules daily data collection

## Implementation Details

### 1. Lambda Function (LambdaResources)

The Lambda function is responsible for querying the GitHub API and writing the results to S3. It's implemented using Node.js and the AWS SDK.

```typescript
export class LambdaResources extends Construct {
  public insightQueryLambda: Function;
  constructor(scope: Construct, id: string, props: LambdaResourcesProps) {
    super(scope, id);

    // ... role creation code omitted for brevity

    this.insightQueryLambda = new NodejsFunction(this, "InsightsQueryLambda", {
      entry: "./src/resources/insightQuery/index.ts",
      runtime: Runtime.NODEJS_LATEST,
      architecture: Architecture.ARM_64,
      memorySize: 1024,
      handler: "handler",
      timeout: Duration.minutes(5),
      role: insightQueryLambdaRole,
      environment: {
        LOG_LEVEL: props.logLevel,
        GITHUB_TOKEN_SECRET_NAME: props.githubTokenSecretName,
        INSIGHTS_BUCKET: props.insightsBucket.bucketName,
      },
    });
    props.insightsBucket.grantReadWrite(this.insightQueryLambda);
  }
}
```

#### Lambda Function Implementation

The core of the data collection is performed by the Lambda function. Here's a simplified version of the main handler:

```typescript
export const handler = async (): Promise<void> => {
  try {
    const githubToken = await getGitHubToken();
    const octokit = new Octokit({ auth: githubToken });

    const repositories = await getRepositoriesFromS3();
    const insights = await fetchRepositoryInsights(octokit, repositories);

    await uploadInsightsToS3(insights);
  } catch (error) {
    console.error("Error in Lambda execution:", error);
    throw error;
  }
};
```

The `fetchRepositoryInsights` function is where the actual GitHub API calls occur:

```typescript
async function fetchRepositoryInsights(
  octokit: Octokit,
  repositories: Repository[]
): Promise<RepoInsights[]> {
  return (
    await Promise.all(
      repositories.map(async ({ owner, repo }) => {
        try {
          const repoData = await octokit.rest.repos.get({ owner, repo });
          const [
            issuesData,
            pullRequestsData,
            contributorsData,
            releasesData,
            commitsData,
          ] = await Promise.all([
            octokit.rest.issues.listForRepo({ owner, repo, state: "all" }),
            octokit.rest.pulls.list({ owner, repo, state: "all" }),
            octokit.rest.repos.listContributors({ owner, repo }),
            octokit.rest.repos
              .getLatestRelease({ owner, repo })
              .catch(() => null),
            octokit.rest.repos.getCommitActivityStats({ owner, repo }),
          ]);

          // Process and aggregate data
          // ...

          return {
            repoName: `${owner}/${repo}`,
            description: repoData.data.description || "",
            stars: repoData.data.stargazers_count,
            forks: repoData.data.forks_count,
            openIssues: repoData.data.open_issues_count,
            // ... other fields
          };
        } catch (error) {
          console.error(`Error fetching data for ${owner}/${repo}:`, error);
          return null;
        }
      })
    )
  ).filter((insight): insight is RepoInsights => insight !== null);
}
```

The collected data is then written to S3 in Parquet format:

```typescript
async function uploadInsightsToS3(insights: RepoInsights[]): Promise<void> {
  const schema = new parquet.ParquetSchema({
    repoName: { type: "UTF8" },
    description: { type: "UTF8" },
    stars: { type: "INT64" },
    // ... other fields
  });

  const writer = await ParquetWriter.openFile(schema, "/tmp/insights.parquet");

  for (const insight of insights) {
    await writer.appendRow({
      ...insight,
      date: `${year}-${month}-${day}`,
    });
  }

  await writer.close();

  const fileContent = await fs.promises.readFile("/tmp/insights.parquet");

  await s3Client.send(
    new PutObjectCommand({
      Bucket: process.env.INSIGHTS_BUCKET,
      Key: `github-insights/year=${year}/month=${month}/day=${day}/insights_${timestamp}.parquet`,
      Body: fileContent,
      ContentType: "application/octet-stream",
    })
  );
}
```

### 2. S3 Bucket (S3Resources)

The S3 bucket is used to store the GitHub repository to query and then to store the GitHub data in Parquet format. The data is partitioned by year, month, and day for efficient querying.

### 3. Glue Database and Table (GlueResources)

AWS Glue is used to define the schema for the GitHub data and set up partition projection.

```typescript
export class GlueResources extends Construct {
  public insightsDatabase: glue.CfnDatabase;
  public insightsTable: CfnTable;
  constructor(scope: Construct, id: string, props: GlueResourcesProps) {
    super(scope, id);

    // ... database creation code omitted for brevity

    this.insightsTable = new glue.CfnTable(this, "GitHubInsightsTable", {
      catalogId: Stack.of(this).account,
      databaseName: this.insightsDatabase.ref,
      tableInput: {
        name: "github_insights",
        tableType: "EXTERNAL_TABLE",
        parameters: {
          EXTERNAL: "TRUE",
          "parquet.compression": "SNAPPY",
          "projection.enabled": "true",
          "projection.year.type": "integer",
          "projection.year.range": "2020,2030",
          "projection.year.digits": "4",
          "projection.month.type": "integer",
          "projection.month.range": "1,12",
          "projection.month.digits": "2",
          "projection.day.type": "integer",
          "projection.day.range": "1,31",
          "projection.day.digits": "2",
          "storage.location.template": `s3://${props.insightsBucket.bucketName}/github-insights/year=$\{year}/month=$\{month}/day=$\{day}`,
        },
        storageDescriptor: {
          // ... storage descriptor details omitted for brevity
        },
        partitionKeys: partitionKeys,
      },
    });
  }
}
```

### 4. Athena Workgroup and Query (AthenaResources)

Amazon Athena is configured with a dedicated workgroup and a sample query for analyzing the GitHub data.

```typescript
export class AthenaResources extends Construct {
  constructor(scope: Construct, id: string, props: AthenaResourceProps) {
    super(scope, id);

    // ... workgroup creation code omitted for brevity

    new athena.CfnNamedQuery(this, "GitHubInsightsSampleQuery", {
      database: props.insightsDatabase.ref,
      queryString: `
        SELECT
          reponame,
          AVG(stars) as avg_stars,
          AVG(forks) as avg_forks,
          AVG(openissues) as avg_open_issues,
          AVG(commitslastmonth) as avg_commits_last_month
        FROM
          github_insights
        WHERE
          year = '${new Date().getUTCFullYear()}'
          AND month = '${(new Date().getUTCMonth() + 1)
            .toString()
            .padStart(2, "0")}'
        GROUP BY
          reponame
        ORDER BY
          avg_stars DESC
      `,
      description:
        "Average stars, forks, open issues, and commits for each repository this month",
      name: "GitHubInsightsMonthlyAverage",
      workGroup: workgroup.ref,
    });
  }
}
```

### 5. EventBridge Rule (EventBridgeResources)

An EventBridge rule is set up to trigger the Lambda function daily.

```typescript
export class EventBridgeResources extends Construct {
  constructor(scope: Construct, id: string, props: EventBridgeResourcesProps) {
    super(scope, id);

    new Rule(this, "DailyLambdaTrigger", {
      schedule: Schedule.cron({ minute: "0", hour: "0" }),
      targets: [new LambdaFunction(props.insightQueryLambda)],
    });
  }
}
```

## Data Flow

1. The EventBridge rule triggers the Lambda function daily.
2. The Lambda function fetches data from GitHub and writes it to S3 in Parquet format.
3. The data is automatically partitioned in S3 based on the Glue table definition.
4. Users can query the data using Athena, with the sample query providing a starting point for analysis.

## Deployment

The entire infrastructure is defined using AWS CDK, allowing for version-controlled, reproducible deployments. The main stack is defined in the `GitHubInsights` class:

```typescript
export class GitHubInsights extends Stack {
  constructor(scope: Construct, id: string, props: GitHubInsightsProps) {
    super(scope, id, props);

    const s3Resources = new S3Resources(this, "S3Resources");
    const glueResources = new GlueResources(this, "GlueResources", {
      insightsBucket: s3Resources.insightsBucket,
    });
    new AthenaResources(this, "AthenaResources", {
      insightsBucket: s3Resources.insightsBucket,
      insightsDatabase: glueResources.insightsDatabase,
    });
    const lambdaResources = new LambdaResources(this, "LambdaResources", {
      logLevel: props.logLevel,
      insightsBucket: s3Resources.insightsBucket,
      githubTokenSecretName: props.githubTokenSecretName,
    });
    new EventBridgeResources(this, "EventBridgeResources", {
      insightQueryLambda: lambdaResources.insightQueryLambda,
    });
  }
}
```

## Querying Data with Athena

Once the data is stored in S3 and the Glue table is set up, users can query the data using Amazon Athena. Here are some example queries:

1. Monthly average metrics for each repository:

```sql
SELECT
  reponame,
  AVG(stars) as avg_stars,
  AVG(forks) as avg_forks,
  AVG(openissues) as avg_open_issues,
  AVG(commitslastmonth) as avg_commits_last_month
FROM
  github_insights
WHERE
  year = '2024'
  AND month = '08'
GROUP BY
  reponame
ORDER BY
  avg_stars DESC
```

2. Repositories with the most growth in stars over the last 30 days:

```sql
WITH current_stats AS (
  SELECT reponame, stars
  FROM github_insights
  WHERE year = '2024' AND month = '08' AND day = '15'
),
previous_stats AS (
  SELECT reponame, stars
  FROM github_insights
  WHERE year = '2024' AND month = '07' AND day = '16'
)
SELECT
  c.reponame,
  c.stars - p.stars AS star_growth,
  ((c.stars - p.stars) / p.stars) * 100 AS growth_percentage
FROM current_stats c
JOIN previous_stats p ON c.reponame = p.reponame
ORDER BY star_growth DESC
LIMIT 10
```

3. Repositories with the highest ratio of closed to open issues:

```sql
SELECT
  reponame,
  AVG(closedissues) as avg_closed_issues,
  AVG(openissues) as avg_open_issues,
  AVG(closedissues) / NULLIF(AVG(openissues), 0) as closed_to_open_ratio
FROM
  github_insights
WHERE
  year = '2024'
  AND month = '08'
GROUP BY
  reponame
HAVING
  AVG(openissues) > 0
ORDER BY
  closed_to_open_ratio DESC
LIMIT 10
```

To run these queries:

1. Open the Athena console in AWS.
2. Select the `github_insights_db` database.
3. Enter the SQL query in the query editor.
4. Click "Run query" to execute and view the results.

The partition projection set up in the Glue table definition allows Athena to efficiently query the data without the need for manual partition management, making it easy to analyze historical trends and current repository states.

![ExampleQuery](/images/blog/github-insights/ExampleQuery.png)

# Deploying

## Configuration Files

### 1. `.env`

This file contains environment variables used by the scripts and the CDK deployment.

**Example content:**

```bash
GITHUB_TOKEN_SECRET=gph_xxxxxxxxxxx
STACK_NAME=GitHubInsights
AWS_REGION=us-east-1
```

**Fields:**

- `GITHUB_TOKEN_SECRET`: Your GitHub personal access token. You will need to create one within GitHub.
- `STACK_NAME`: The name of your CDK stack (used by `upload_repo_list.sh`).
- `AWS_REGION`: The AWS region where your resources are deployed.

**Note:** Never commit the `.env` file to version control. It's included in `.gitignore` by default.

### 2. `repositories.json`

This file contains the list of GitHub repositories you want to monitor.

**Example content:**

```json
[
  {
    "owner": "schuettc",
    "repo": "github-insights"
  }
]
```

**Usage:**

- Add or remove repository objects as needed.
- Each repository object should have an "owner" and "repo" field.
- After modifying this file, run `upload_repo_list.sh` to update the list in your S3 bucket.

## Helper Scripts

### 1. `setup_github_token.sh`

This script is used to securely store your GitHub token in AWS Secrets Manager.

**Purpose:**

- Creates or updates a secret in AWS Secrets Manager to store your GitHub token.
- Allows secure access to the GitHub API without exposing the token in your code.

**Usage:**

1. Ensure you have the AWS CLI configured with appropriate permissions.
2. Create a `.env` file in the project root (see Configuration Files section below).
3. Run the script:

```bash
./setup_github_token.sh
```

**What it does:**

- Reads the `GITHUB_TOKEN_SECRET` from the `.env` file.
- Creates or updates a secret in AWS Secrets Manager with the provided token.
- Uses the `GITHUB_TOKEN_SECRET_NAME` (default: "/github_insights/github_token") as the secret name.
- Sets the AWS region based on the `AWS_REGION` in `.env` or defaults to "us-east-1".

### 2. `upload_repo_list.sh`

This script uploads the list of repositories to be monitored to your S3 bucket.

**Purpose:**

- Uploads the `repositories.json` file to the S3 bucket created by the CDK stack.
- Allows you to easily update the list of repositories to be monitored.

**Usage:**

1. Ensure you have the AWS CLI configured with appropriate permissions.
2. Update the `repositories.json` file with the repositories you want to monitor.
3. Run the script:

```bash
./upload_repo_list.sh
```

**What it does:**

- Retrieves the S3 bucket name from the CloudFormation stack outputs.
- Uploads the `repositories.json` file to the root of the S3 bucket.
- Uses the `STACK_NAME` from the `.env` file to identify the correct CloudFormation stack.
- Sets the AWS region based on the `AWS_REGION` in `.env` or defaults to "us-east-1".

## Workflow

1. Set up your `.env` file with your GitHub token and stack name.
2. Deploy your CDK stack by running `yarn launch`
3. Run `setup_github_token.sh` to securely store your GitHub token.
4. Update `repositories.json` with the list of repositories you want to monitor.
5. Run `upload_repo_list.sh` to upload the repository list to your S3 bucket.

By following this workflow, you ensure that your GitHub token is securely stored and your Lambda function has the latest list of repositories to monitor.

## Conclusion

This serverless architecture provides an efficient method for collecting and analyzing GitHub repository metrics. It leverages AWS services to automate data collection, storage, and query capabilities, enabling data-driven insights into repository activity and health.


In this demo we will see how to deploy an application on AWS that will capture insights from GitHub and store them in S3 to be easily queried with Amazon Athena

GitHub Insights - Capturing Repository Metrics


In this demo we'll see how to deploy a NextJS application to AWS App Runner via CDK using GitHub Actions. This demo will combine and showcase several useful tools to help with deployments. Much of this could also be done using a CDK Pipeline. For smaller and simpler use cases, this can be a lighter weight way of doing it, but is more fragile. This is a simpler and cheaper version the previous [CDK Pipeline for ECS hosted NextJS App](https://subaud.io/blog/cdk-pipeline-ecs-hosted-nextjs) while still supporting the main features in it.

GitHub: https://github.com/schuettc/cdk-nextjs-apprunner

## Overview

![Overview](/images/blog/nextjs-app-deployed-to-app-runner-with-cdk/Overview.png)

The core of this demo is the mechanism to take a local [NextJS](https://nextjs.org/) app, upload it to an S3 bucket, build it using Docker and deploy it to [AWS App Runner](https://aws.amazon.com/apprunner/). By using [AWS CodePipeline](https://aws.amazon.com/codepipeline/) and [AWS CodeBuild](https://aws.amazon.com/codebuild/) to build the [Docker](https://www.docker.com/) image, we eliminate the need to have Docker running locally for our deployment. This allows us to use GitHub actions to use CDK to deploy this application.

## Uploading to S3

```typescript
const dockerAsset = new Asset(this, 'DockerAsset', {
  path: './site',
  exclude: ['**/node_modules/**', '**/lib/**', '/**/.next/**'],
  ignoreMode: IgnoreMode.GIT,
});
```

By using [Asset](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.Asset.html) we are able to Zip and upload all of the relevant files in our NextJS application to an S3 bucket managed by CDK. We will use this S3 bucket as the trigger for our CodePipeline.

## CodePipeline

The actual pipeline for this demo is relatively simple. Using polling on the S3 bucket, it will download the Zip file from S3, extract the files, and execute a build on them.

```typescript
this.pipeline = new Pipeline(this, 'Pipeline', {
  stages: [
    {
      stageName: 'Source',
      actions: [
        new S3SourceAction({
          actionName: 'S3Source',
          bucket: dockerAsset.bucket,
          bucketKey: dockerAsset.s3ObjectKey,
          output: sourceOutput,
        }),
      ],
    },
    {
      stageName: 'Build',
      actions: [
        new CodeBuildAction({
          actionName: 'DockerBuild',
          project: codeBuildProject,
          input: sourceOutput,
          outputs: [buildOutput],
        }),
      ],
    },
  ],
});
```

The buildSpec for this involves three basic steps:

1. Log in to ECR
2. Execute `docker build`
3. Execute `docker push`

```typescript
buildSpec: BuildSpec.fromObject({
  version: '0.2',
  phases: {
    pre_build: {
      commands: [
        'echo Logging in to Amazon ECR...',
        'aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com',
      ],
    },
    build: {
      commands: [
        'echo Build started on `date`',
        'echo Building the Docker image...',
        'docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .',
        'docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG',
      ],
    },
    post_build: {
      commands: [
        'echo Build completed on `date`',
        'echo Pushing the Docker image...',
        'docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG',
      ],
    },
  },
}),
```

With these three steps, we are able to create a Docker image and push to our [Amazon ECR repository](https://docs.aws.amazon.com/ecr/). This is what will be consumed by our App Runner service.

## ImageChecker

In order to make sure the Docker image has been created and is available for the App Runner service, we will create a Lambda backed Custom Resource that will periodically check the pipeline to ensure it has completed successfully. When it has, the Customer Resource will complete and the CDK can continue. We can enforce this by adding a dependency to the Customer Resource to the App Runner service.

```typescript
appRunnerService.service.node.addDependency(imageChecker);
```

Now the CDK will not start deploying the App Runner service until the Customer Resource has completed. This will only run on the initial build. On updates, when a new image is pushed to ECR after the build process completes, App Runner will automatically deploy the updated image.

## App Runner

Finally, we will create the App Runner service and automatically deploy the image.

```typescript
this.service = new apprunnerAlpha.Service(this, 'Service', {
  source: apprunnerAlpha.Source.fromEcr({
    imageConfiguration: { port: 3000 },
    repository: ecrRepository.repository,
    tagOrDigest: 'latest',
  }),
  autoDeploymentsEnabled: true,
  accessRole: appRunnerRole,
});
```

To ensure this works correctly with NextJS we will add a `HOSTNAME` environment variable to the App Runner service.

```typescript
this.service.addEnvironmentVariable('HOSTNAME', '0.0.0.0');
```

## Projen

To help manage this project, we will be using [projen](https://projen.io/).

### Subproject

In addition to the main project, we are also using a subproject to manage the NextJS application with a `parent` of the main project.

```typescript
const site = new web.NextJsTypeScriptProject({
  parent: project,
  defaultReleaseBranch: 'main',
  name: 'cdk-nextjs-apprunner-site',
  outdir: 'site',
  projenrcTs: true,
  tailwind: false,
  tsconfig: {
    compilerOptions: {
      rootDir: '.',
      baseUrl: '.',
    },
    include: [
      'pages/**/*.ts',
      'pages/**/*.tsx',
      'components/**/*.ts',
      'components/**/*.tsx',
      '**/*.ts',
      '**/*.tsx',
      'next-env.d.ts',
    ],
    exclude: ['node_modules'],
  },
  deps: ['@cloudscape-design/components', '@cloudscape-design/global-styles'],
});

site.synth();
```

### CDK Deploy GitHub Action

Because we are using CodeBuild to build the Docker image, we can use GitHub actions to start the deploy process. To do this with projen, we will create a new workflow. This will be added to the existing actions and trigger on a merge or push to `main`.

```typescript
const cdkDeploy = project.github.addWorkflow('cdk-deploy');
cdkDeploy.on({
  push: { branches: ['main'] },
  pullRequest: { branches: ['main'], types: ['closed'] },
});

cdkDeploy.addJobs({
  deploy: {
    runsOn: ['ubuntu-latest'],
    name: 'Deploy CDK Stack',
    permissions: {
      actions: JobPermission.WRITE,
      contents: JobPermission.READ,
      idToken: JobPermission.WRITE,
    },
    if: "github.event.pull_request.merged == true || github.event_name == 'push'",
    steps: [
      { uses: 'actions/checkout@v3' },
      {
        name: 'Setup Node.js',
        uses: 'actions/setup-node@v3',
        with: {
          'node-version': '18',
        },
      },
      { run: 'yarn install --frozen-lockfile' },
      {
        name: 'Configure AWS Credentials',
        uses: 'aws-actions/configure-aws-credentials@v4',
        with: {
          'aws-access-key-id': '${{ secrets.AWS_ACCESS_KEY_ID }}',
          'aws-secret-access-key': '${{ secrets.AWS_SECRET_ACCESS_KEY }}',
          'aws-region': 'us-east-1',
          'role-session-name': 'GitHubActionsCDKDeploy',
        },
      },
      {
        name: 'CDK Diff',
        run: 'npx cdk diff',
      },
      {
        name: 'CDK Deploy',
        run: 'npx cdk deploy --all --require-approval never',
      },
    ],
  },
});
```

### AWS Credentials

In order to use this feature, you will need to create a user in your AWS account that has sufficient permissions to deploy the CDK. Using the ACCESS_KEY_ID and SECRET_ACCESS_KEY generated for this user, GitHub can deploy the CDK. To create a user with permissions you can run:

```bash
./setup_aws_cdk_deploy
```

The output will contain an ACCESS_KEY_ID and SECRET_ACCESS_KEY that can be added to your GitHub repo as secrets.

![GitHubSecrets](/images/blog/nextjs-app-deployed-to-app-runner-with-cdk/GitHubSecrets.png)

The policy attached to this user has extensive permissions so care must be taken with this ACCESS_KEY_ID.


Deploy a NextJS Application to AWS App Runner using CDK

NextJS App deployed to App Runner with CDK


[cdk-nag](https://github.com/cdklabs/cdk-nag) is a useful tool for enforcing best practices within a CDK stack. This can be combined with [jest](https://jestjs.io/) testing used in [projen](https://projen.io/) to ensure a compliant deployment.

## GitHub Repo

https://github.com/schuettc/cdk-nag-with-projen

## CDK Setup

After creating a basic projen project with something like `npx projen new awscdk-app-ts`, the `.projenrc.ts` file should be updated with `devDeps: ['cdk-nag']`. This will install `cdk-nag` as a [devDependency](https://docs.npmjs.com/specifying-dependencies-and-devdependencies-in-a-package-json-file).

Next, we will create a very basic CDK Stack:

```typescript
new Bucket(this, 'Bucket', {
  removalPolicy: RemovalPolicy.DESTROY,
  autoDeleteObjects: true,
  encryption: BucketEncryption.S3_MANAGED,
});
```

## Test Setup

By default, projen will run tests using the files in the `test` folder. In this case, we have created a `cdk-nag.test.ts` file that will be run during deployment.

Let's set up that file. First, we'll set up the basics by importing the Stack that we will be deploying. In this case, we will import the `CDKNagWithProjen` Stack from `../src/cdk-nag-with-projen` and test against that.

```typescript
import { AwsSolutionsChecks } from 'cdk-nag';
import { CDKNagWithProjen } from '../src/cdk-nag-with-projen';

describe('cdk-nag AwsSolutions Pack', () => {
  let stack: Stack;
  let app: App;

  beforeEach(() => {
    app = new App();
    stack = new CDKNagWithProjen(app, 'CDKNagWithProjen', {});

    outputStream = fs.createWriteStream('cdk-nag-output.txt');
  });

  afterEach(() => {
    outputStream.end();
  });
  ...
});
```

## Test without Suppressions

First, we'll run tests against the Stack without suppressions and write the output to a file.

```typescript
import { App, Aspects, Stack } from 'aws-cdk-lib';
import { Annotations, Match } from 'aws-cdk-lib/assertions';
import { AwsSolutionsChecks } from 'cdk-nag';

describe('cdk-nag AwsSolutions Pack', () => {
  ...
  test('Output all Warnings and Errors', () => {
    Aspects.of(stack).add(
      new AwsSolutionsChecks({
        verbose: true,
        logIgnores: false,
      }),
    );

    const warnings = Annotations.fromStack(stack).findWarning(
      '*',
      Match.stringLikeRegexp('AwsSolutions-.*'),
    );

    outputStream.write('All Warnings:\n');
    warnings.forEach((warning) => {
      outputStream.write(warning.entry.data);
    });

    const errors = Annotations.fromStack(stack).findError(
      '*',
      Match.stringLikeRegexp('AwsSolutions-.*'),
    );

    outputStream.write('All Errors:\n');
    errors.forEach((error) => {
      outputStream.write(error.entry.data);
    });
  });
}
```

Each of these warnings and errors will be written to the `cdk-nag-output.txt` file. This will record the results of `cdk-nag` without any suppressions. In this example, the results will look like this:

```text
All Warnings:
All Errors:
AwsSolutions-S1: The S3 Bucket has server access logs disabled. The bucket should have server access logging enabled to provide detailed records for the requests that are made to the bucket.
AwsSolutions-S10: The S3 Bucket or bucket policy does not require requests to use SSL. You can use HTTPS (TLS) to help prevent potential attackers from eavesdropping on or manipulating network traffic using person-in-the-middle or similar attacks. You should allow only encrypted connections over HTTPS (TLS) using the aws:SecureTransport condition on Amazon S3 bucket policies.
AwsSolutions-S10: The S3 Bucket or bucket policy does not require requests to use SSL. You can use HTTPS (TLS) to help prevent potential attackers from eavesdropping on or manipulating network traffic using person-in-the-middle or similar attacks. You should allow only encrypted connections over HTTPS (TLS) using the aws:SecureTransport condition on Amazon S3 bucket policies.
```

This test has no expectations so will throw no errors when running `yarn projen test` or during deployment. The results of these tests are only written to the `cdk-nag-output.txt` file.

## Add suppressions

If these errors are acceptable, we can add a suppression to `cdk-nag`. To do this, we'll create `nagSuppressions.ts`.

```typescript
import { Stack } from 'aws-cdk-lib';
import { NagSuppressions } from 'cdk-nag';

export function applySuppressions(stack: Stack): void {
  NagSuppressions.addStackSuppressions(stack, [
    {
      id: 'AwsSolutions-S1',
      reason: 'Suppressing S3 server access logging warning for demo purposes',
    },
    {
      id: 'AwsSolutions-S10',
      reason: 'Suppressing S3 bucket SSL requirement warning for demo purposes',
    },
  ]);
}
```

## Test with suppressions

Next, we'll run these tests again with suppressions.

```typescript
import { App, Aspects, Stack } from 'aws-cdk-lib';
import { Annotations, Match } from 'aws-cdk-lib/assertions';
import { AwsSolutionsChecks } from 'cdk-nag';
import { applySuppressions } from '../src/nagSuppressions';


describe('cdk-nag AwsSolutions Pack', () => {
  ...

  test('No unsuppressed Warnings or Errors after applying suppressions', () => {
    applySuppressions(stack);

    Aspects.of(stack).add(
      new AwsSolutionsChecks({
        verbose: true,
        logIgnores: false,
      }),
    );

    const unsuppressedWarnings = Annotations.fromStack(stack).findWarning(
      '*',
      Match.stringLikeRegexp('AwsSolutions-.*'),
    );

    expect(unsuppressedWarnings).toHaveLength(0);

    const unsuppressedErrors = Annotations.fromStack(stack).findError(
      '*',
      Match.stringLikeRegexp('AwsSolutions-.*'),
    );

    expect(unsuppressedErrors).toHaveLength(0);
  });
});
```

In this test, we are expecting `unsuppressedWarnings` and `unsuppressedErrors` to have a length of 0. If that is not the case, the tests will fail. If there are no warnings or errors, the result should look like this:

```text
$ npx projen test
👾 test | jest --passWithNoTests --updateSnapshot
 PASS  test/cdk-nag.test.ts
  cdk-nag AwsSolutions Pack
    ✓ Output all Warnings and Errors (220 ms)
    ✓ No unsuppressed Warnings or Errors after applying suppressions (51 ms)

------------------------|---------|----------|---------|---------|-------------------
File                    | % Stmts | % Branch | % Funcs | % Lines | Uncovered Line #s
------------------------|---------|----------|---------|---------|-------------------
All files               |     100 |      100 |     100 |     100 |
 cdk-nag-with-projen.ts |     100 |      100 |     100 |     100 |
 nagSuppressions.ts     |     100 |      100 |     100 |     100 |
------------------------|---------|----------|---------|---------|-------------------
Test Suites: 1 passed, 1 total
Tests:       2 passed, 2 total
Snapshots:   0 total
Time:        2.756 s, estimated 3 s
Ran all test suites.
```

## Result

With a projen project configured CDK stack with this setup, we can perform `cdk-nag` tests on the Stack, capture the results, suppress acceptable warnings and errors, and then deploy confidently.


In this demo we will see how to deploy and test a projen based project with cdk-nag

cdk-nag with projen


In this demo, we will see how to build an application that will accept streaming audio sent via gRPC and have the audio transcribed using [OpenAI Whisper](https://openai.com/research/whisper). This demo builds off of the previous [gRPC Streaming Audio with Node](https://subaud.io/blog/node-grpc-server) blog post. However, in this demo, the ECS uses an [EC2 based deployment that supports GPUs](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-gpu.html). This requires several changes to the deployment that will be highlighted.

## Overview

![Overview](/images/blog/streaming-whisper-ecs-hosted/StreamingWhisper.png)

The basic concepts of the previous [gRPC Streaming Audio with Node](https://subaud.io/blog/node-grpc-server) remain largely the same. An audio stream will be generated from a local gRPC client and sent to a gRPC server hosted in [Amazon Elastic Container Service (ECS)](https://aws.amazon.com/ecs/). The server will transcribe the audio and return the results to the gRPC client. While the previous model used a Fargate hosted container, this demo uses an EC2 deployed container in order to use a GPU. Additionally, while the previous model used [Amazon Transcribe](https://aws.amazon.com/transcribe/) to provide the Speech To Text processing, this uses Whisper as the ASR and is included in the container that is built and deployed. Because Whisper does not normally support streaming audio, we will have to introduce a chunking mechanism that Whisper can use.

## GitHub Repo

https://github.com/schuettc/hosted-whisper-streaming

## ECS Deployment

```typescript
const cluster = new Cluster(this, 'cluster', {
  vpc: props.vpc,
});

const launchTemplate = new LaunchTemplate(this, 'LaunchTemplate', {
  machineImage: EcsOptimizedImage.amazonLinux2(AmiHardwareType.GPU),
  instanceType: new InstanceType('g4dn.2xlarge'),
  requireImdsv2: true,
  userData: UserData.forLinux(),
  securityGroup: ecsServiceSecurityGroup,
  role: ec2Role,
  blockDevices: [
    {
      deviceName: '/dev/xvda',
      volume: BlockDeviceVolume.ebs(300),
    },
  ],
});

const autoScalingGroup = new AutoScalingGroup(this, 'AutoScalingGroup', {
  vpc: props.vpc,
  launchTemplate: launchTemplate,
  desiredCapacity: 1,
  minCapacity: 1,
  maxCapacity: 2,
  vpcSubnets: { subnetType: SubnetType.PUBLIC },
});

const capacityProvider = new AsgCapacityProvider(this, 'AsgCapacityProvider', {
  autoScalingGroup,
});

cluster.addAsgCapacityProvider(capacityProvider);
```

Some changes are required in the CDK to use an EC2 based deployment of ECS. Here we see the [Launch Template](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/ec2-launch-templates.html) that defines the EC2 instance parameters. An autoscaling group is also configured to allow this demo to scale up if needed.

```typescript
const taskDefinition = new Ec2TaskDefinition(this, 'taskDefinition', {
  taskRole: hostedWhisperStreamingRole,
  networkMode: NetworkMode.BRIDGE,
});

taskDefinition.addContainer('HostedWhisperStreaming', {
  image: ContainerImage.fromAsset('src/resources/whisperServer'),
  environment: {
    ECS_LOGLEVEL: props.logLevel,
  },
  gpuCount: 1,
  memoryLimitMiB: 31690,
  cpu: 8192,
  portMappings: [{ containerPort: 50051, hostPort: 50051 }],
  logging: new AwsLogDriver({ streamPrefix: 'HostedWhisperStreaming' }),
});

this.ecsService = new Ec2Service(this, 'ECSService', {
  cluster: cluster,
  taskDefinition: taskDefinition,
  capacityProviderStrategies: [
    { capacityProvider: capacityProvider.capacityProviderName, weight: 1 },
  ],
});
```

Next we configure the [Task Definition](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/task_definitions.html) that will use the included Docker container image.

## Docker Image

```Dockerfile
FROM --platform=linux/amd64 nvidia/cuda:12.2.2-cudnn8-runtime-ubuntu22.04 AS base

RUN apt-get update && apt-get install -y --no-install-recommends \
    python3 python3.10-dev python3-pip python3.10-venv libsndfile1 build-essential curl git  && \
    rm -rf /var/lib/apt/lists/*

FROM base AS builder

COPY src/requirements.txt ./

RUN pip3 install --upgrade pip setuptools wheel && \
    pip3 install --user -r requirements.txt && \
    pip3 install --user git+https://github.com/openai/whisper.git

FROM base
ENV MODEL=${MODEL}
ENV LOG_LEVEL=${LOG_LEVEL}

COPY --from=builder /root/.local /root/.local
COPY src/* ./
RUN chmod +x /entrypoint.sh

EXPOSE 50051

ENTRYPOINT ["/entrypoint.sh"]


```

The Dockerfile included creates a Docker image that uses the [nvidia/cuda Docker image](https://hub.docker.com/r/nvidia/cuda/) as the base. This image will allow us to use the GPUs on the EC2 instance.

The `pip3 install` commands are particularly important when using this image. These will update and install the necessary tools to install and configure Whisper. In order to ensure the model is downloaded and installed, `python3 -c "import whisper; whisper.load_model('base')"` is run as part of the build.

As part of the `entrypoint.sh` script, we will be sure to set the correct path for the cuDNN libraries.

```bash
export LD_LIBRARY_PATH=`python3 -c 'import os; import nvidia.cublas.lib; import nvidia.cudnn.lib; print(os.path.dirname(nvidia.cublas.lib.__file__) + ":" + os.path.dirname(nvidia.cudnn.lib.__file__))'`
```

This solves the `Could not load library libcudnn_ops_infer.so.8. Error: libcudnn_ops_infer.so.8: cannot open shared object file: No such file or directory` issue that is caused by the `LD_LIBRARY_PATH` not containing the correct locations for the libraries.

Finally, we will start the server.

```bash
python3 server.py
```

## Whisper Server

The server starts with two Servicers - AudioTranscriberServicer and HealthCheckServicer. The HealthCheckServicer is used to validate to the Application Load Balancer

```python
def serve():
    server = grpc.server(futures.ThreadPoolExecutor(max_workers=10))
    audio_transcriber_pb2_grpc.add_AudioTranscriberServiceServicer_to_server(
        AudioTranscriberServicer(), server
    )
    audio_transcriber_pb2_grpc.add_HealthCheckServiceServicer_to_server(
        HealthCheckServicer(), server
    )
    server.add_insecure_port("[::]:50051")
    server.start()
    logger.info("Server started. Listening on port 50051.")
    server.wait_for_termination()
```

The AudioTranscriberServicer will be used to process the audio stream and return the transcriptions to the gRPC client. Whisper does not natively support streaming audio, so we must break the streamed audio into chunks that Whisper can use. To do this, audio processor will process the audio frames and use VAD to detect speech segments. These frames are buffered until a non-speech frame is encountered. When this happens, the frames are joined into a chunk. If the chunk is long enough, it is processed by [faster-whisper](https://github.com/SYSTRAN/faster-whisper) using the `large-v2` model. This allows for rapid transcription of streaming audio while allowing Whisper to provide the best results.

## Notes and Warnings

Because this deployment uses GPU based instance(s), be sure to check the [prices of the instances](https://aws.amazon.com/ec2/pricing/on-demand/) that will be used.

![Pricing](/images/blog/streaming-whisper-ecs-hosted/Pricing.png)

## Testing

This demo requires a [domain hosted in Route 53](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/registrar.html) so that a certificate can be associated with the [Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-target-groups.html#target-group-protocol-version) listener. To configure the domain within the deployment, create a `.env` file with a `DOMAIN_NAME=` associated with a [Hosted Zone Name](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) in the account.

Once the `.env` has been configured, you can deploy the CDK from the cloned repo:

```bash
yarn deploy
```

After deploying the CDK, you can test the functionality by running the included client. This client will capture audio from your microphone and stream it to the server using gRPC. Output from the CDK will be used to configure the client in the `/client/.env` file. To run the client:

```bash
cd client
yarn build
yarn start
```

![ClientStreaming](/images/blog/streaming-whisper-ecs-hosted/CLIExample.gif)

## Cleanup

In order to delete this CDK, you should remove the Auto Scaling Group first. Once that is done, you can delete the Stack from Cloudformation.


A CDK stack that will deploy a will create an ECS hosted application for streaming audio with gRPC to Whisper and getting the transcription output

Using Whisper with Streaming Audio


This simple bash script can be used to get the public and private IP addresses of the Tasks within a Fargate Cluster. With the `CLUSTER_NAME` defined as an environment variable, this script will iterate through all of the Tasks in a Cluster and create a `.env` file with both the public and private addresses of the Tasks.

```bash
#!/bin/bash

> taskIps.env

TASK_LIST=$(aws ecs list-tasks --cluster $CLUSTER_NAME)
TASK_ARNS=$(echo "$TASK_LIST" | jq -r '.taskArns[]')

while IFS= read -r TASK_ARN; do
    NETWORK_INTERFACE_ID=$(aws ecs describe-tasks --cluster $CLUSTER_NAME --tasks "$TASK_ARN" --query 'tasks[0].attachments[0].details[?name==`networkInterfaceId`].value' --output text)
    PRIVATE_IP=$(aws ecs describe-tasks --cluster $CLUSTER_NAME --tasks "$TASK_ARN" --query 'tasks[0].attachments[0].details[?name==`privateIPv4Address`].value' --output text)
    PUBLIC_IP=$(aws ec2 describe-network-interfaces --network-interface-ids "$NETWORK_INTERFACE_ID" --query 'NetworkInterfaces[*].Association.PublicIp' --output text)
    TASK_NAME=$(aws ecs describe-tasks --cluster $CLUSTER_NAME --tasks "$TASK_ARN" --query 'tasks[0].containers[0].name' --output text | tr '[:lower:]' '[:upper:]')
    echo "${TASK_NAME}_PUBLIC_IP=$PUBLIC_IP" >> taskIps.env
    echo "${TASK_NAME}_PRIVATE_IP=$PRIVATE_IP" >> taskIps.env
done <<< "$TASK_ARNS"


```

The basic steps involved:

- Get the Tasks in the Cluster
- Get the ARNs of the Tasks
- Loop through the Task ARNs
  - Get the Network Interface ID of the Task using the Task ARN and Cluster Name
  - Get the Private IP using the Task ARN and Cluster Name
  - Get the Public IP using the Network Interface ID
  - Get the Task Name from the Task ARN and Cluster Name
  - Write everything to the the `.env` file

### GitHub Gist

https://gist.github.com/schuettc/5e805ec2ca6c21f9b3af3f9cfa75fade


This simple bash script can be used to get the public and private IP addresses of a Fargate Cluster

Bash script to get ECS Fargate Cluster IP Addresses


In this demo, we'll see how to deploy a [Knowledge Base for Amazon Bedrock](https://aws.amazon.com/bedrock/knowledge-bases/) with [Amazon OpenSearch](https://aws.amazon.com/opensearch-service/) as the vector store using CDK. Deploying a Knowledge Base requires severals steps that will be accomplished using a [Custom Resource](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.CustomResource.html). This Custom Resource will build resources following this basic guide: https://docs.aws.amazon.com/bedrock/latest/userguide/knowledge-base-create.html

- Create Bucket
- Create Vector Index
  - Create Access Policy
  - Create Network Security Policy
  - Create Encryption Policy
  - Create Collection
  - Create Index
- Create Knowledge Base
- Create Data Source

This demo also includes a Lambda function that will [`StartIngestionJob`](https://docs.aws.amazon.com/bedrock/latest/APIReference/API_agent_StartIngestionJob.html) when a new object is created in the Bucket to automatically sync the Data Source with the Knowledge Base.

## Custom Resource Configuration

Due to the complex nature of Knowledge Bases, many fields are statically defined in this demo that can and should be customized.

### Names

This CDK deployment uses two names for configuring the resources used - a `namePrefix` and `nameSuffix`. The `namePrefix` can be defined in a `.env` file:

```bash
NAME_PREFIX='sample-name'
```

The `nameSuffix` will be generated during deployment and used throughout. The result is that most resources will be named: `namePrefix-nameSuffix`.

### Access Policy

```typescript
const parsedArns: string[] = JSON.parse(accessPolicyArns);
const principalArray = [
  ...parsedArns,
  knowledgeBaseRoleArn,
  knowledgeBaseCustomResourceRole,
];

const policy = [
  {
    Rules: [
      {
        Resource: [`collection/${namePrefix}-${nameSuffix}`],
        Permission: [
          'aoss:DescribeCollectionItems',
          'aoss:CreateCollectionItems',
          'aoss:UpdateCollectionItems',
        ],
        ResourceType: 'collection',
      },
      {
        Resource: [`index/${namePrefix}-${nameSuffix}/*`],
        Permission: [
          'aoss:UpdateIndex',
          'aoss:DescribeIndex',
          'aoss:ReadDocument',
          'aoss:WriteDocument',
          'aoss:CreateIndex',
        ],
        ResourceType: 'index',
      },
    ],
    Principal: principalArray,
    Description: '',
  },
];
```

For example, this Access Policy will be applied to the OpenSearch Collection that is created. This will include the necessary Roles for the deployment, as well as any users or roles you would like to add. In order to access the Collection and Index within the Console, you will need to add the appropriate role or user.

```typescript
const bedrockKnowledgeBase = new CustomResource(
  this,
  'KnowledgeBaseCustomResource',
  {
    serviceToken: knowledgeBaseProvider.serviceToken,
    properties: {
      knowledgeBaseBucketArn: props.knowledgeBaseBucket.bucketArn,
      knowledgeBaseRoleArn: this.knowledgeBaseRole.roleArn,
      knowledgeBaseCustomResourceRole: knowledgeBaseCustomResourceRole.roleArn,
      accessPolicyArns: JSON.stringify([]),
      nameSuffix: Names.uniqueId(this).slice(-6).toLowerCase(),
      namePrefix: props.namePrefix,
      knowledgeBaseEmbeddingModelArn:
        'arn:aws:bedrock:us-east-1::foundation-model/amazon.titan-embed-text-v1',
    },
  },
);
```

### Collection

```typescript
const createCollectionResponse = await openSearchServerlessClient.send(
  new CreateCollectionCommand({
    clientToken: randomUUID(),
    type: 'VECTORSEARCH',
    name: `${namePrefix}-${nameSuffix}`,
  }),
);
```

A `VECTORSEARCH` type Collection will be created that will use the previously created policies.

### Index

Once the Collection is created, a [`k-NN`](https://opensearch.org/docs/latest/search-plugins/knn/index/) index will be created. See: https://opensearch.org/docs/latest/search-plugins/knn/knn-index/ for more details on configuring your Index.

```typescript
var createIndexResponse = await client.indices.create({
  index: `${namePrefix}-${nameSuffix}`,
  body: {
    settings: {
      'index.knn': true,
    },
    mappings: {
      properties: {
        [`${namePrefix}-vector`]: {
          type: 'knn_vector',
          dimension: 1536,
          method: {
            name: 'hnsw',
            engine: 'faiss',
            parameters: {
              ef_construction: 512,
              m: 16,
            },
          },
        },
      },
    },
  },
});
```

### Knowledge Base

Once the Collection and Index have been created, the `VECTOR` Knowledge Base using `OPENSEARCH_SERVERLESS` will be created.

```typescript
const data = await bedrockAgentClient.send(
  new CreateKnowledgeBaseCommand({
    clientToken: randomUUID(),
    name: `${namePrefix}-${nameSuffix}`,
    roleArn: knowledgeBaseRoleArn,
    knowledgeBaseConfiguration: {
      type: 'VECTOR',
      vectorKnowledgeBaseConfiguration: {
        embeddingModelArn: knowledgeBaseEmbeddingModelArn,
      },
    },
    storageConfiguration: {
      type: 'OPENSEARCH_SERVERLESS',
      opensearchServerlessConfiguration: {
        collectionArn: collectionArn,
        vectorIndexName: `${namePrefix}-${nameSuffix}`,
        fieldMapping: {
          vectorField: `${namePrefix}-vector`,
          textField: 'text',
          metadataField: 'metadata',
        },
      },
    },
  }),
);
```

### Data Source

Finally, a Data Source will be added using the previously created S3 Bucket.

```typescript
const dataSourceCreateResponse = await bedrockAgentClient.send(
  new CreateDataSourceCommand({
    knowledgeBaseId: knowledgeBaseId,
    clientToken: randomUUID(),
    name: `${namePrefix}-${nameSuffix}`,
    dataSourceConfiguration: {
      type: 'S3',
      s3Configuration: {
        bucketArn: knowledgeBaseBucketArn,
        inclusionPrefixes: ['knowledgeBase'],
      },
    },
  }),
);
```

## Result

We can see the the Knowledge Base has been created, but we still need to select a Model and Sync our data.

![BedrockConsole](/images/blog/cdk-bedrock-knowledge-base/BedrockConsole.png)

Let's select `Claude 3 Sonnet` for our Model.

![Model](/images/blog/cdk-bedrock-knowledge-base/Model.png)

And now, let's upload a file to the `knowledgeBase` folder in our S3 Bucket. This will automatically trigger a `StartIngestionJob` that will sync our Data Source with our Knowledge Base.

![S3Upload](/images/blog/cdk-bedrock-knowledge-base/BucketUpload.png)

Now we can test our Knowledge Base with the uploaded file and get the results back from the uploaded document.

![RAGResults](/images/blog/cdk-bedrock-knowledge-base/RAGResult.png)

## GitHub

This demo can be found on GitHub here: https://github.com/schuettc/cdk-bedrock-knowledge-base

## Deploy

To deploy this demo:

```bash
yarn launch
```

To destroy this demo:

```bash
yarn cdk destroy
```


In this demo we will see how to deploy an Amazon Bedrock Knowledge Base with an OpenSearch Vector Index using CDK

CDK Deployment of Amazon Bedrock Knowledge Base with OpenSearch Serverless


# Amazon Chime SDK Call Analytics Consumer

This code will deploy a small application that can be used with [Amazon Chime SDK call analytics](https://docs.aws.amazon.com/chime-sdk/latest/dg/call-analytics.html) to view the results in real-time.

![AmazonChimeSDKCallAnalyticsConsumer](/images/blog/amazon-chime-sdk-call-analytics-reader/AmazonChimeSDKCallAnalyticsConsumer.png)

## Process

1. A SIP or SIPREC INVITE is sent to the Amazon Chime SDK Voice Connector
2. This triggers EventBridge
3. An EventBridge [event](https://docs.aws.amazon.com/chime/latest/ag/automating-chime-with-cloudwatch-events.html) is sent to the associated Lambda function
4. The Lambda starts the [Amazon Chime SDK media insights pipeline](https://docs.aws.amazon.com/chime-sdk/latest/dg/create-config-console.html)
5. RTP is delivered from the Amazon Chime SDK Voice Connector to the Amazon Chime SDK call analytics processor
6. Amazon Chime SDK events from EventBridge are sent to a Kinesis Data Stream
7. RTP from the Amazon Chime SDK Voice Connector is processed with Transcribe
8. Results from Transcribe are sent from the Amazon Chime SDK call analytics processor to the Kinesis Data Stream
9. Kinesis Data Stream records are consumed on a Lambda function
10. These records are delivered to a WebSocket API
11. And viewable on an S3/CloudFront hosted React App

## Deployed Components

- Amazon Chime SDK call analytics configuration
- S3 bucket for recordings
- EventBridge rule
- EventBridge Lambda function
- Kinesis Data Stream
- Kinesis Data Stream consuming Lambda function
- WebSocket API
- DynamoDB to track connections
- S3 bucket for React app
- CloudFront Distribution associated with S3 bucket

## Messages

All of the messages related to Amazon Chime SDK call analytics will be delivered to the client through the WebSocket API from the Kinesis Data Stream. These messages can be filtered within the app to more easily see the various message types.

![AmazonChimeSDKCallAnalyticsMessages](/images/blog/amazon-chime-sdk-call-analytics-reader/AmazonChimeSDKCallAnalyticsMessages.png)

## Using

To use this app, you will need to deploy this app and configure an Amazon Chime SDK Voice Connector. This app will start Amazon Chime SDK call analytics for any Amazon Chime Voice Connector in the Region. Any time a call uses an Amazon Chime SDK Voice Connector, the EventBridge Lambda will start an Amazon Chime SDK call analytics media insights pipeline associated with the deployed Amazon Chime SDK call analytics configuration.

## Deploying

To deploy this demo, use:

```bash
yarn launch
```

To remove this demo, use:

```bash
yarn cdk destroy
```

## GitHub Repo

All code available here: https://github.com/schuettc/amazon-chime-sdk-call-analytics-reader


A simple React application and related infrastructure that will consume Amazon Chime SDK call analytics events

Amazon Chime SDK Call Analytics Consumer


This demo will guide you through the process of deploying a [gRPC](https://grpc.io/) server that is capable of receiving streaming audio from a gRPC client and processing that audio with [Amazon Transcribe](https://aws.amazon.com/transcribe/) and returning the result to the client.

[GitHub Repo](https://github.com/schuettc/node-grpc-demo)

## Server Infrastructure

![gRPCServerOverview](/images/blog/node-grpc-server/gRPCServerOverview.png)

This demo will deploy a [Fargate](https://aws.amazon.com/fargate/) container that runs the gRPC server. This gRPC server will be available through an [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/) that is enabled with HTTPS through a [Certificate](https://docs.aws.amazon.com/acm/latest/userguide/gs-acm-request-public.html) generated through [AWS Certificate Manager](https://aws.amazon.com/certificate-manager/).

### Certificate Manager

```typescript
this.hostedZone = HostedZone.fromLookup(this, 'HostedZone', {
  domainName: props.domainName,
});

this.certificate = new Certificate(this, 'Certificate', {
  domainName: `grpc.${props.domainName}`,
  validation: CertificateValidation.fromDns(this.hostedZone),
});
```

Using a provided domain name, the CDK will lookup the associated [HostedZone](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/hosted-zones-working-with.html) and create a Certificate that will be associated with the Application Load Balancer.

### Application Load Balancer

```typescript
const grpcServerTargetGroup = new ApplicationTargetGroup(
  this,
  'gRPCServerTargetGroup',
  {
    vpc: props.vpc,
    port: 50051,
    protocol: ApplicationProtocol.HTTP,
    protocolVersion: ApplicationProtocolVersion.GRPC,
    targets: [this.fargateService],
    healthCheck: {
      healthyGrpcCodes: '12',
    },
  },
);

this.applicationLoadBalancer.addListener('fargateListener', {
  port: 50051,
  protocol: ApplicationProtocol.HTTPS,
  certificates: [ListenerCertificate.fromCertificateManager(props.certificate)],
  open: true,
  defaultTargetGroups: [grpcServerTargetGroup],
});

props.applicationLoadBalancerSecurityGroup.addIngressRule(
  Peer.anyIpv4(),
  Port.tcp(50051),
);
```

This will create an Application Load Balancer [Target Group](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-target-groups.html) that uses `ApplicationProtocolVersion.GRPC` as the protocol version. Additionally, the `healthCheck` will look for gRPC codes in the response from the gRPC server. The [Listener](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/load-balancer-listeners.html) associated with the Application Load Balancer uses HTTPS and the previously created Certificate. The Listener will use port `50051` and forward to port `50051` on the Fargate task. This port is also opened on the Application Load Balancer Security Group.

### Route 53

```typescript
new ARecord(this, 'grpcARecord', {
  zone: props.hostedZone,
  recordName: 'grpc',
  target: RecordTarget.fromAlias(
    new LoadBalancerTarget(this.applicationLoadBalancer),
  ),
});
```

Finally, an [A Record](https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/ResourceRecordTypes.html#AFormat) will be created that points to the Application Load Balancer alias use the record name `grpc`. This will create a record `grpc.example.com` that can be used with the Application Load Balancer.

## gRPC Server

### Server initialization

```typescript
function main() {
  const server = new grpc.Server();
  server.addService(audio_proto.AudioStreamer.service, { streamAudio });
  server.bindAsync(
    '0.0.0.0:50051',
    grpc.ServerCredentials.createInsecure(),
    () => {
      server.start();
      console.log('gRPC server started on port 50051');
    },
  );
}

main();
```

The main function of the server code, is used to create the server that is listening on port `50051` with HTTP. The Application Load Balancer will provide the TLS security so HTTP can be used here.

### streamAudio Function

```typescript
function streamAudio(call: grpc.ServerWritableStream<any, any>) {
  console.log('Streaming audio data received from client.');

  const audioStream = new PassThrough();

  startTranscription(audioStream, call).catch((error) => {
    console.error('Transcription error:', error);
    call.write({ message: error });
  });

  call.on('data', (data: any) => {
    audioStream.write(data.audioData);
  });

  call.on('end', async () => {
    console.log('Streaming completed.');
    audioStream.end();
  });

  audioStream.on('end', () => {
    console.log('Transcribing ended.');
  });
}
```

Now, when a stream arrives, the `streamAudio` function will begin processing the stream. In this example, it involves three major steps:

1. Create `audioStream` PassThrough Stream
2. Start `startTranscription` function with the `audioStream`
3. Write data to the `audioStream` from the gRPC stream as it arrives

### Transcribe the stream

```typescript
const audioStream = async function* () {
  for await (const chunk of stream) {
    const buffer = Buffer.from(chunk);
    yield { AudioEvent: { AudioChunk: buffer } };
  }
};

const command = new StartStreamTranscriptionCommand({
  LanguageCode: LanguageCode.EN_US,
  MediaEncoding: MediaEncoding.PCM,
  MediaSampleRateHertz: 16000,
  AudioStream: audioStream(),
});

const response = await client.send(command);
```

This will send the stream to Transcribe for processing. Once we get a response back from Transcribe, we will write this back to the gRPC client via the stream.

```typescript
call.write({
  message: JSON.stringify(
    event.TranscriptEvent.Transcript.Results[0].Alternatives[0].Transcript,
  ),
});
```

## gRPC Client

```typescript
async function main() {
  let target: string = 'localhost:50051';
  let credentials = grpc.credentials.createInsecure();

  if (TARGET) {
    target = `${TARGET}:50051`;
    credentials = grpc.credentials.createSsl();
  }

  console.log(`Using target: ${target}`);

  if (!WAV_FILE) {
    throw new Error('WAV_FILE required');
  }

  console.log(`Using source: ${WAV_FILE}`);

  const { audioStream } = await processFfmpeg(WAV_FILE);
}
```

The main client function will determine the `TARGET` and `WAV_FILE` to be used. This client can be used both locally or with the deployed gRPC server. A `WAV_FILE` is required and can be stored in the `client\src` directory and will be copied over during the Docker build. If the `WAV_FILE` is a stereo file with each channel a separate user, they will be muxed together when sent to the gRPC server. The result will be that the transcription is the combined result of both channels. If you want to get a single channel, you can modify the `ffmpeg` to only pass one channel, or separate the `WAV_FILE` before sending.

### ffmpeg Processing

```typescript
async function processFfmpeg(fileName: string): Promise<{
  audioStream: PassThrough;
}> {
  console.log('Processing with ffmpeg');
  const audioStream = new PassThrough();

  ffmpeg(fileName)
    .native()
    .output(audioStream)
    .format('wav')
    .audioCodec('pcm_s16le')
    .audioBitrate(8000)
    .on('error', (error: { message: string }) => {
      console.log('Cannot process: ' + error.message);
    })
    .run();

  return { audioStream };
}
```

This demo uses `ffmpeg` to ensure the audio being streamed is sent at the correct rate and with the correct formatting.

### Streaming

```typescript
const client = new audio_proto.AudioStreamer(target, credentials);
const chunkSize = 1024;
const call = client.streamAudio();

audioStream.on('data', (chunk) => {
  let offset = 0;
  while (offset < chunk.length) {
    const end = Math.min(offset + chunkSize, chunk.length);
    const chunkToSend = chunk.slice(offset, end);
    call.write({ audioData: chunkToSend });
    offset = end;
  }
});

audioStream.on('end', () => {
  console.log('Audio stream ended.');
  call.end();
});

call.on('data', (response: any) => {
  console.log(`${Date.now()}: ${response.message}`);
});

call.on('end', () => {
  console.log('gRPC call ended.');
  process.exit(0);
});

call.on('error', (err: any) => {
  console.error('Error:', err);
});
```

Once the `audioStream` has been created through `processFfmpeg`, when data arrives, it will be written to the gRPC stream in chunks through the client. Responses that are generated on the server (the transcriptions) will be surfaced through the `call.on('data', () => {})` function.

## In Action

![InActionOverview](/images/blog/node-grpc-server/InActionOverview.png)

In order to test this demo, you can either use it locally or through the deployed Fargate container.

### Deploying

```bash
yarn launch
```

This will deploy the CDK stack to your account. You will need a HostedZone domain in order to use this. The A Record created will be written to the `client\src\.env` file so that you can use the client with this gRPC server.

### Testing

In order to test locally, you will need to start the gRPC server. In the `src\resources\gRPCServer` directory, you can start the gRPC Server Docker container:

```bash
docker-compose run --build grpc-server
```

You will need to have AWS credentials exposed in this container in order to use Transcribe.

In the `client\src` directory, you can start the gRPC Client Docker container:

```bash
docker-compose run --build -e TARGET= grpc-client
```

You can add the the `WAV_FILE` environment variable in the command line as well

```bash
docker-compose run --build -e TARGET= -e WAV_FILE=EXAMPLE.wav grpc-client
```

This will use the localhost as the `TARGET`. If you want to test with the hosted gRPC server and have already deployed it, you can use:

```bash
docker-compose run --build grpc-client
```

### Client Results

![ClientResults](/images/blog/node-grpc-server//ClientResults.png)

### Server Results

![ServerResults](/images/blog/node-grpc-server/ServerResults.png)


This demo will show you how to deploy and use a gRPC server and client to stream audio and use Amazon Transcribe to analyze the audio

gRPC Streaming Audio with Node


# CDK Pipeline for ECS hosted NextJS App

In this demo we will explore and see how to use two different, but complementary techniques:

- Using CDK Pipelines to deploy a Stack
- Deploying a NextJS application to an ECS Fargate container

In each of these examples, we will look at several different mechanisms to provide security and scaling. This blog has been converted to using this method of hosting.

## GitHub Repo

https://github.com/schuettc/cdk-pipeline-ecs-hosted-nextjs

## CDK Pipeline

![CDKPipelineOverview](/images/blog/cdk-pipeline-ecs-hosted-nextjs/CDKPipelineOverview.png)

This demo uses [AWS CodeStar Connections](https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html) to create a link to a GitHub repo. This will allow us to use GitHub commits to push changes to our NextJS App through the CDK Pipeline.

The [cdk-pipeline-ecs-hosted-nextjs.ts](https://github.com/schuettc/cdk-pipeline-ecs-hosted-nextjs/blob/main/src/cdk-pipeline-ecs-hosted-nextjs.ts) file will create a Stack with a self-mutating CodePipeline. This is the Pipeline contains a Stage that will deploy the the NextJSApp Stack. This Pipeline is triggered by the GitHub repo and branch associated.

```typescript
const pipeline = new CodePipeline(this, 'Pipeline', {
  synth: new CodeBuildStep('Synth', {
    input: CodePipelineSource.connection(props.githubRepo, props.githubBranch, {
      connectionArn: props.connectionArn,
    }),
    commands: ['yarn install --frozen-lockfile', 'yarn build', 'npx cdk synth'],
    rolePolicyStatements: [
      new PolicyStatement({
        actions: ['sts:AssumeRole'],
        resources: ['*'],
        conditions: {
          StringEquals: {
            'iam:ResourceTag/aws-cdk:bootstrap-role': 'lookup',
          },
        },
      }),
    ],
  }),
  selfMutation: true,
  dockerEnabledForSynth: true,
});

pipeline.addStage(
  new NextJSAppStage(this, 'NextJSApp', props as NextJSAppProps),
);
```

## NextJS App

![NextJSAppOverview](/images/blog/cdk-pipeline-ecs-hosted-nextjs/ECSFargateNextJSApp.png)

The demo optionally uses a pre-configured Route 53 Hosted Zone domain. Otherwise the traffic will route through the following services:

- Route 53 (Optional)
- Cloudfront
- Application Load Balancer
- Fargate with Auto Scaling Group

### Securing Traffic

In order to ensure that traffic uses this path, we will establish the follow security mechanisms.

#### Fargate

```typescript
const fargateTargetGroup = new ApplicationTargetGroup(
  this,
  'nextJsAppTargetGroup',
  {
    vpc: props.vpc,
    port: 3000,
    protocol: ApplicationProtocol.HTTP,
    targets: [this.fargateService],
    healthCheck: {
      path: '/',
      protocol: Protocol.HTTP,
      port: '3000',
    },
  },
);
```

When configuring the `ApplicationTargetGroup` that points to the Fargate application, a Security Group will be created that allows traffic from the Application Load Balancer to access the Fargate task.

![FargateSecurityGroup](/images/blog/cdk-pipeline-ecs-hosted-nextjs/FargateSecurityGroup.png)

This Security Group will use the Security Group of the Application Load Balancer.

### Application Load Balancer

```typescript
this.applicationLoadBalancerSecurityGroup.addIngressRule(
  Peer.anyIpv4(),
  Port.tcp(80),
);
```

This Security Group will allow traffic in from any IPv4 address on TCP Port 80. In order to ensure that traffic from sources besides Cloudfront are rejected, we will use a configuration of the Listener.

```typescript
const fargateListener = this.applicationLoadBalancer.addListener(
  'fargateListener',
  {
    port: 80,
    protocol: ApplicationProtocol.HTTP,
    open: true,
    defaultAction: ListenerAction.fixedResponse(403),
  },
);

fargateListener.addAction('ForwardFromCloudFront', {
  action: ListenerAction.forward([fargateTargetGroup]),
  conditions: [
    ListenerCondition.httpHeader(props.customHeader, [props.randomString]),
  ],
  priority: 1,
});
```

This Listener will by default reject all traffic that is sent to it. An additional action will be used to allow traffic with a specific header and value to forward to the Fargate application. This information is created separately and configured during deployment. For more information on this mechanism, see [building-a-websocket-server-with-fargate-and-cdk](https://subaud.io/blog/building-a-websocket-server-with-fargate-and-cdk).

The result:

![Listener](/images/blog/cdk-pipeline-ecs-hosted-nextjs/Listener.png)

### Cloudfront

```typescript
this.distribution = new Distribution(this, 'CloudfrontDistribution', {
  minimumProtocolVersion: SecurityPolicyProtocol.TLS_V1_2_2021,
  defaultBehavior: {
    origin: new LoadBalancerV2Origin(props.applicationLoadBalancer, {
      httpPort: 80,
      protocolPolicy: OriginProtocolPolicy.HTTP_ONLY,
      originId: 'default-origin',
    }),
    viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    cachePolicy: CachePolicy.CACHING_DISABLED,
    allowedMethods: AllowedMethods.ALLOW_GET_HEAD_OPTIONS,
    originRequestPolicy: OriginRequestPolicy.ALL_VIEWER,
  },
  domainNames: props.domainName ? [props.domainName] : undefined,
  certificate: certificate,
  priceClass: PriceClass.PRICE_CLASS_100,
});
```

The Distribution created includes a domain and SSL certificate to provide HTTPS access to the Fargate task. Requests to HTTP will redirect to HTTPS.

#### Domain (optional)

```typescript
if (props.domainName) {
  hostedZone = HostedZone.fromLookup(this, 'HostedZone', {
    domainName: props.domainName,
  });

  certificate = new Certificate(this, 'Certificate', {
    domainName: props.domainName,
    validation: CertificateValidation.fromDns(hostedZone),
  });
}

if (hostedZone && props.domainName) {
  new AaaaRecord(this, 'mainAaaaRecord', {
    zone: hostedZone,
    target: RecordTarget.fromAlias(new CloudFrontTarget(this.distribution)),
  });

  new ARecord(this, 'mainARecord', {
    zone: hostedZone,
    target: RecordTarget.fromAlias(new CloudFrontTarget(this.distribution)),
  });
}
```

If a domain is included in the deployment, a certificate will be created and used in addition to the default Cloudfront certificate. DNS records will be created associated with this domain.

#### Custom Header

To create the header used to ensure traffic is sourced from Cloudfront, the Cloudfront Distribution Origin will be configured to send it using a Custom Resource.

```typescript
new CustomResource(this, 'customHeaderCustomResource', {
  serviceToken: customHeaderCustomResourceProvider.serviceToken,
  properties: {
    DistributionId: this.distribution.distributionId,
    Origins: [
      {
        OriginId: 'default-origin',
        CustomHeaders: [
          {
            HeaderName: props.customHeader,
            HeaderValue: props.randomString,
          },
        ],
      },
    ],
  },
});
```

The result will look something like this:

![Origin](/images/blog/cdk-pipeline-ecs-hosted-nextjs/Origin.png)

### Fargate Task

```typescript
const ecsTask = new FargateTaskDefinition(this, 'ecsTask', {
  memoryLimitMiB: 2048,
  cpu: 1024,
  runtimePlatform: {
    operatingSystemFamily: OperatingSystemFamily.LINUX,
    cpuArchitecture: CpuArchitecture.X86_64,
  },
});

ecsTask.addContainer('NextJsContainer', {
  image: ContainerImage.fromAsset('nextjs-docker'),
  containerName: 'nextJsApp',
  portMappings: [{ containerPort: 3000, hostPort: 3000 }],
  logging: LogDrivers.awsLogs({
    streamPrefix: 'nextJsApp',
  }),
  environment: {},
});

const taskSecurityGroup = new SecurityGroup(this, 'taskSecurityGroups', {
  vpc: props.vpc,
});

this.fargateService = new FargateService(this, 'nextJsAppFargateService', {
  cluster: cluster,
  taskDefinition: ecsTask,
  assignPublicIp: true,
  desiredCount: 1,
  vpcSubnets: { subnetType: SubnetType.PUBLIC },
  securityGroups: [taskSecurityGroup],
});
```

The Fargate Service will be configured with a port mapping for port 3000. This corresponds to the Application Load Balancer that forwards traffic to port 3000. The Fargate task will be deployed in the VPC created during the deployment and assigned a public IP address.

The Docker image used is the example shown here: https://github.com/vercel/next.js/tree/canary/examples/with-docker

### Result

The result is an Application Load Balancer that will only accept traffic with a specific header and value. This header and value are known only by the deployed Cloudfront Distribution. Traffic with this header will be forwarded to a Fargate task that only allows traffic from the Security Group associated with the Application Load Balancer. This deployment allows us to restrict access to the the Fargate task that uses the Cloudfront Distribution.

## Configuration and Deployment

To deploy this repo, you will need to complete the following steps:

1. Fork this repo
2. Configure Codestar connections with your GitHub repo
3. Configure a Hosted Zone in Route 53 with your domain (optional)
4. Configure your `.env` file
5. Deploy

### Configure Codestar

To configure your AWS account to support a connection to GitHub, follow the instructions here: https://docs.aws.amazon.com/dtconsole/latest/userguide/connections-create-github.html

The result will look something like this:

![Connections](/images/blog/cdk-pipeline-ecs-hosted-nextjs/Connections.png)

### Configure Hosted Zone (optional)

To create a Hosted Zone, follow the instructions here: https://docs.aws.amazon.com/Route53/latest/DeveloperGuide/CreatingHostedZone.html

The result will look something like this:

![HostedZone](/images/blog/cdk-pipeline-ecs-hosted-nextjs/HostedZone.png)

### Configure `.env` file

Before deploying, you will need to configure a `.env` file with the following fields:

```bash
CONNECTION_ARN=arn:aws:codestar-connections:us-east-1:112233445566:connection/XXXXXXXXXXXXXXXXXXXXXXXX
GITHUB_REPO=XXXXXXXXXXX/cdk-pipeline-ecs-hosted-nextjs
GITHUB_BRANCH=main
DOMAIN_NAME=example.com
```

`DOMAIN_NAME` is optional

### Deploy

To deploy the Pipeline:

```bash
yarn launch
```

Deploying the Pipeline will begin the process of deploying the NextJSApp stack.


A CDK Pipeline example that will deploy a NextJS App on ECS

CDK Pipeline for ECS hosted NextJS App


# ffmpeg streaming to KVS

[GitHub Repo](https://github.com/schuettc/ffmpeg-kvs-streaming)

[Amazon Kinesis Video Streams](https://aws.amazon.com/kinesis/video-streams) can be used to get access to other AWS services with streaming video. In this demo, we will see how to use [Node.js](https://nodejs.org/en) and [ffmpeg](https://ffmpeg.org/) to convert a file into a stream that can be sent to KVS.

![Overview](/images/blog/streaming-to-kvs-with-ffmpeg/ffmpegStreaming.png)

1. An object is created in the Amazon Simple Storage Service (Amazon S3) bucket. When this happens, a notification is sent to the associated AWS Lambda function.
2. This Lambda makes a request to the [Application Load Balancer](https://docs.aws.amazon.com/elasticloadbalancing/latest/application/introduction.html) associated with the [AWS Fargate](https://aws.amazon.com/fargate/) task with the object information.
3. The Fargate application downloads the object from S3 and begins processing (processing details below).
4. The Fargate application streams the contents of the object to [Amazon Kinesis Video Streams](https://aws.amazon.com/kinesis/video-streams/).

## Processing with ffmpeg

Once the file has been downloaded from S3, the application will begin processing the file with ffmpeg.

```typescript
async function processFfmpeg(fileName: string): Promise<{
  videoStream: PassThrough;
}> {
  console.log('Processing with ffmpeg');
  const videoStream = new PassThrough();
  let videStreamCount: number = 0;

  ffmpeg(fileName)
    .native()
    .output(videoStream)
    .outputOptions(['-profile:v baseline'])
    .videoCodec('libx264')
    .size('640x480')
    .audioCodec('aac')
    .format('matroska')
    .on('error', (error) => {
      console.log('Cannot process: ' + error.message);
    })
    .on('stderr', (data) => {
      if (videStreamCount % COUNT_FREQUENCY === 0) {
        console.info(`videoStream: ${data}`);
      }
      videStreamCount++;
    })
    .run();

  return { videoStream };
}
```

To do this, we will create a `PassThrough` stream that will be used as the output of the ffmpeg pipe. By using `.native()` as an input option, the ffmpeg pipe will read the contents of the file at the native frame rate. The output options used will format the output stream so that it can be used by KVS.

## Streaming Media

Because Kinesis Video Streams [PutMedia](https://docs.aws.amazon.com/kinesisvideostreams/latest/dg/API_dataplane_PutMedia.html) does not have a corresponding AWS SDK command, we must use a direct HTTP request. This involves several extra steps:

1. GetDataEndpoint
2. GetCredentials
3. SignRequest
4. PutMedia

### GetDataEndpoint

```typescript
async function getEndpoint(
  streamArn: string,
): Promise<GetDataEndpointCommandOutput['DataEndpoint']> {
  const response = await kvsClient.send(
    new GetDataEndpointCommand({
      APIName: APIName.PUT_MEDIA,
      StreamARN: streamArn,
    }),
  );
  return response.DataEndpoint;
}
```

The first step to sending a stream to KVS is to get an endpoint for the stream we are going to use. We have already created the stream during the deployment of the CDK, so we will use that stream as the target.

### GetCredentials

```typescript
const ECS_ROLE = process.env.ECS_ROLE || '';

async function getCredentials(): Promise<
  AssumeRoleCommandOutput['Credentials']
> {
  console.log('Getting credentials');
  const response = await stsClient.send(
    new AssumeRoleCommand({
      RoleArn: ECS_ROLE,
      RoleSessionName: 'kvs-stream',
    }),
  );
  return response.Credentials;
}
```

In order to stream to the KVS, we will need to assume an IAM role that has permission to do this. More details about doing this using a local Docker are outlined below.

#### IAM Role

```typescript
this.kinesisRole = new Role(this, 'kinesisRole', {
  assumedBy: new CompositePrincipal(
    new ArnPrincipal(kvsProducerRole.roleArn),
    new AccountPrincipal(Stack.of(this).account),
  ),
  inlinePolicies: {
    ['KinesisVideoPolicy']: new PolicyDocument({
      statements: [
        new PolicyStatement({
          resources: ['*'],
          actions: ['kinesisvideo:PutMedia'],
        }),
      ],
    }),
  },
});
```

During the deployment of the CDK, an [IAM Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html) is created. This is the role that we will assume and use to `PutMedia`. This Role is passed to the application through environment variables.

### SignRequest

```typescript
async function signRequest(
  streamArn: string,
  endpoint: string,
): Promise<{ signedUrl: aws4.Request; reqUrl: string }> {
  const credentials = await getCredentials();
  if (!credentials) {
    throw new Error('Failed to get credentials');
  }
  const signedUrl = aws4.sign(
    {
      host: endpoint,
      path: '/putMedia',
      service: 'kinesisvideo',
      method: 'POST',
      headers: {
        'Content-Type': 'application/json',
        'x-amzn-stream-arn': streamArn,
        'x-amzn-fragment-timecode-type': 'ABSOLUTE',
        'x-amz-content-sha256': 'UNSIGNED-PAYLOAD',
      },
    },
    {
      accessKeyId: credentials.AccessKeyId,
      secretAccessKey: credentials.SecretAccessKey,
      sessionToken: credentials.SessionToken,
    },
  );
  if (!signedUrl || !signedUrl.host || !signedUrl.path) {
    throw new Error('Failed to sign request');
  }
  const reqUrl = signedUrl.host + signedUrl.path;
  return { signedUrl: signedUrl, reqUrl: reqUrl };
}
```

Using the credentials from the assumed role, the Stream ARN, and the DataEndpoint, we will use [aws4](https://github.com/mhart/aws4) to sign the request we will be making and get a URL to use in the `PutMedia`.

### PutMedia

```typescript
const agent = new Agent({
  rejectUnauthorized: false,
});
const axiosParams = {
  method: 'POST',
  timeout: 40 * 1000,
  url: reqUrl,
  headers: signedUrl.headers as AxiosHeaders,
  data: stream,
  responseType: 'stream' as ResponseType,
  maxContentLength: Infinity,
  httpsAgent: agent,
};
```

Next, we will combine all of the pieces together as we prepare to `PutMedia`. Using the stream generated by `ffmpeg` and the url generated by `aws4`, we will create a `POST` request using [axios](https://axios-http.com/docs/intro).

```typescript
let streamCount: number = 0;

try {
  const response = (await axios(axiosParams)) as AxiosResponse;
  const startFragmentNumber = await getStartFragmentNumber(response);

  response.data.on('data', (chunk: Buffer) => {
    if (streamCount % COUNT_FREQUENCY === 0) {
      console.info(`Stream: ${streamArn} - Chunk: ${chunk.toString()}`);
    }
    streamCount++;
  });
  response.data.on('end', async () => {
    console.log(`Stream: ${streamArn} ended`);
  });

  response.data.on('error', (error: Error) => {
    console.error(`Error in ${streamArn} stream: ${error}`);
  });
  if (startFragmentNumber) {
    return { streamArn, startFragmentNumber };
  } else {
    throw new Error('StartFragment not found');
  }
} catch (error) {
  console.error('Error in putMedia:', error);
  throw error;
}
```

Finally, we will make the `POST` request to the `PutMedia` API and process the responses. For every fragment sent, KVS will acknowledge with a response:

```json
{
       Acknowledgement : {
          "EventType": enum
          "FragmentTimecode": Long,
          "FragmentNumber": Long,
          "ErrorId" : String
      }
}
```

## Testing

In order to test this demo, you can upload a movie file to the S3 bucket that is created during the CDK deployment. This will start processing on the Fargate container and streaming to KVS. This stream can be seen in the [KVS Console](https://us-east-1.console.aws.amazon.com/kinesisvideo/home?region=us-east-1#/streams) and finding the stream named `ffmpeg-streaming`.

![KVSConsole](/images/blog/streaming-to-kvs-with-ffmpeg/KVS.png)

This stream can be viewed with `Media playback`.

![MediaPlayback](/images/blog/streaming-to-kvs-with-ffmpeg/MediaPlayback.png)

## Developing Locally with Docker

Because development like this can require extensive trial and error testing, it is useful to test locally with a Docker image before deploying to Fargate. This will involve several steps:

1. Build a local Docker container
2. Pass credentials and environment variables to this container
3. Run the local Docker container
4. Trigger this container

### Build the Docker container

To do this, we will use [Docker Compose](https://docs.docker.com/compose/) and a `.env` file.

```docker-compose
version: '3'
services:
  ffmpeg:
    build:
      context: .
      dockerfile: Dockerfile
    environment:
      - AWS_PROFILE
      - AWS_ACCESS_KEY_ID
      - AWS_SECRET_ACCESS_KEY
      - AWS_SESSION_TOKEN
      - COUNT_FREQUENCY=60
      - ECS_ROLE
      - KVS_STREAM_ARN
    volumes:
      - ~/.aws/:/root/.aws:ro
    ports:
      - '80:80'
    command: ['npm', 'start']
```

### Pass credentials and environment variables

This will use the `Dockerfile` used in the deployment with environment variables and a mounted volume that references `~./aws`. This will allow us to pass credentials from the [`~.aws/credentials`](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-files.html) file and use the associated `AWS_PROFILE`.

Alternatively, you can export `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` as environment variables.

`ECS_ROLE` and `KVS_STREAM_ARN` are created during the deployment of the CDK and passed to the `.env` file through the outputs of the CDK.

### Run the Docker container

To run the Docker container:

```bash
docker-compose up --build
```

This will re-build and run the Docker container

### Trigger the Docker container

[Postman](https://www.postman.com/) is a useful tool for making API request. This is similar to what we will be doing with the Lambda function and serves as a convenient way to test locally. The Docker container will be running on port 80, so we will make a `POST` request to `localhost:80/processObject` passing the `bucketName` and `keyName` of the object to be processed.

![Postman](/images/blog/streaming-to-kvs-with-ffmpeg/Postman.png)

## Using this demo

### Requirements

- yarn installed
- ARM processor
- Docker desktop running

### Deploy

```bash
yarn launch
```

### Cleanup

```bash
yarn cdk destroy
```


This demo will go through the steps to process a file with ffmpeg and stream the contents to KVS using Node.js

Streaming to KVS with ffmpeg and Node.js


[Feature flags](https://docs.aws.amazon.com/cdk/v2/guide/featureflags.html) are a way to modify the deployment behavior of an AWS SDK deployment. These are potentially breaking, so use with caution. These feature flags are stored in the [context](https://docs.aws.amazon.com/cdk/v2/guide/context.html) of the CDK as key-value pairs.

For example:

```json
  "context": {
    "@aws-cdk/aws-ec2:uniqueImdsv2TemplateName": true
  },
```

Here we are setting a feature flag to tell the CDK to always use a unique launch template name. This is useful when [requiring imdsv2](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2-readme.html#configuring-instance-metadata-service-imds) for an EC2 instance.

```typescript
    const ec2Instance = new Instance(this, 'Instance', {
      vpc: props.vpc,
      instanceType: InstanceType.of(InstanceClass.C7G, InstanceSize.MEDIUM),
      machineImage: ubuntuAmi,
      requireImdsv2: true,
      userData: userData,
      ...
    })
```

Without this feature flag enabled, you are likely to get an error similar to this:

```bash
Launch template name already in use. (Service: AmazonEC2; Status Code: 400; Error Code: InvalidLaunchTemplateName.AlreadyExistsException;
```

To add this feature flag to the `cdk.json` file when using [projen](https://projen.io/) we must modify the `.projenrc.ts` file.

```typescript
project.cdkConfig.json.addOverride('context', {
  '@aws-cdk/aws-ec2:uniqueImdsv2TemplateName': true,
});
```

This will add the necessary context to the `cdk.json` file and enable the [`uniqueImdsv2TemplateName`](https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cx-api/FEATURE_FLAGS.md#aws-cdkaws-ec2uniqueimdsv2templatename) feature flag.

For a complete list of available feature flags available: https://github.com/aws/aws-cdk/blob/main/packages/%40aws-cdk/cx-api/FEATURE_FLAGS.md


Feature flags can be used to modify the deployment characteristics of a CDK deployment.  These feature flags can be enabled in projen by modifying the cdk.json file.

Adding feature flags to AWS CDK through runtime context with projen


# CDK Deployment of Docker Image with CodeBuild

In many CDK deployments, a local Docker build can be done to create assets. For example, when deploying a [Python Lambda with Requirements](https://subaud.io/blog/deploying-python-lambda-with-requirements-using-cdk) you can use a [bundling](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.AssetOptions.html#bundling) to install dependencies before the Function is zipped and uploaded. This can cause issues if the CPU of the machine doing the deploy is different from the [Architecture](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Architecture.html) of the [Function](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda.Function.html). If the CPU of the machine doing the deploy is an Intel based machine, but the Function is `ARM_64` the Function will not work. The same applies to [Fargate](https://docs.aws.amazon.com/AmazonECS/latest/userguide/what-is-fargate.html) containers. In this demo, you will see how to deploy a Fargate container without having to worry about the CPU of the deploying machine using [AWS CodeBuild](https://aws.amazon.com/codebuild/).

## Goal

In this demo, we are trying to build a CDK deployed Fargate container that is accessed through a Cloudfront Distribution and Application LoadBalancer using a custom Docker build.

![GoalOverview](/images/blog/CodeBuildOverviewGoal.png)

In order to do this, we must build a [Docker image](https://docs.aws.amazon.com/AmazonECS/latest/userguide/create-container-image.html). We want to use an `ARM_64` cpuArchitecture for this image, but do not want to require the CDK to be deployed from a machine with an `ARM_64` CPU. Therefore, we will use CodeBuild to build the image.

## ECS Setup

The first step to deploying this image is to create the ECS infrastructure. Much of this is covered [here](https://www.subaud.io/blog/building-a-websocket-server-with-fargate-and-cdk) in more detail.

The biggest difference is that we will initialize this ECS cluster with a container that we will not be using for long.

```typescript
taskDefinition.addContainer('cdk-codebuild', {
  image: ContainerImage.fromRegistry(
    'public.ecr.aws/nginx/nginx:latest-arm64v8',
  ),
  portMappings: [{ containerPort: 80, hostPort: 80 }],
  logging: new AwsLogDriver({ streamPrefix: 'cdk-codebuild' }),
  healthCheck: {
    command: ['CMD-SHELL', 'curl -f http://localhost/'],
  },
});
```

The container that we are adding here is only a placeholder until we can build and deploy our actual image. To do this, we will use an `ARM_64` [nginx](https://gallery.ecr.aws/nginx/nginx) image. When the ECS service is created, this image will be used for the Task created.

## Building the Image

![BuildOverview](/images/blog/CodeBuildOverviewBuild.png)

Uploading and building the image is a multi-step process that will take local code and deploy it to our Fargate Service.

### Uploading Assets

The first step to deploying this image is to upload the local `Dockerfile` and associated code.

```typescript
const bundle = new Asset(this, 'bundle', {
  path: 'src/resources/dockerExample',
});
```

This will zip the contents of the `dockerExample` directory and upload to the CDK assets bucket.

### Pipeline

In order to build the image, we will use an [AWS CodePipeline](https://aws.amazon.com/codepipeline/) with this bucket and key as the source.

```typescript
const sourceAction = new S3SourceAction({
  actionName: 'S3Source',
  bucket: bundle.bucket,
  bucketKey: bundle.s3ObjectKey,
  output: sourceOutput,
  trigger: S3Trigger.EVENTS,
});
```

Now, whenever this key is updated, the AWS CodePipeline will trigger. This pipeline is only three steps - source, build, and deploy:

```typescript
new Pipeline(this, 'docker-codebuild-pipeline', {
  stages: [
    {
      stageName: 'source',
      actions: [sourceAction],
    },
    {
      stageName: 'build',
      actions: [buildAction],
    },
    {
      stageName: 'deploy',
      actions: [deployAction],
    },
  ],
});
```

### CodeBuild

The build portion of this pipeline is the most complex but can be broken down to a few key steps:

1. Using the source key (the uploaded Zip file)
2. A `docker build` command is executed
3. This image is pushed to an ECR repository
4. An `imagedefinitions.json` file is created with this information

```typescript
const project = new Project(this, 'codeBuildProject', {
  role: codeBuildRole,
  buildSpec: BuildSpec.fromObject({
    version: '0.2',
    phases: {
      pre_build: {
        commands: [
          'echo Logging in to Amazon ECR...',
          'aws ecr get-login-password --region $AWS_DEFAULT_REGION | docker login --username AWS --password-stdin $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com',
        ],
      },
      build: {
        commands: [
          'echo Build started on `date`',
          'echo Building the Docker image...',
          'docker build -t $IMAGE_REPO_NAME:$IMAGE_TAG .',
          'docker tag $IMAGE_REPO_NAME:$IMAGE_TAG $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG',
        ],
      },
      post_build: {
        commands: [
          'echo Build completed on `date`',
          'echo Pushing the Docker image...',
          'docker push $AWS_ACCOUNT_ID.dkr.ecr.$AWS_DEFAULT_REGION.amazonaws.com/$IMAGE_REPO_NAME:$IMAGE_TAG',
          'echo Writing image definitions file...',
          'printf \'[{"name":"cdk-codebuild","imageUri":"%s"}]\' $IMAGE_REPO_URI:$IMAGE_TAG > imagedefinitions.json',
        ],
      },
    },
    artifacts: {
      files: ['imagedefinitions.json'],
    },
  }),
  source: Source.s3({
    bucket: bundle.bucket,
    path: bundle.s3ObjectKey,
  }),
  environment: {
    buildImage: LinuxArmBuildImage.AMAZON_LINUX_2_STANDARD_3_0,
    environmentVariables: {
      AWS_DEFAULT_REGION: { value: Stack.of(this).region },
      AWS_ACCOUNT_ID: { value: Stack.of(this).account },
      IMAGE_REPO_NAME: { value: this.ecrRepository.repositoryName },
      IMAGE_REPO_URI: { value: this.ecrRepository.repositoryUri },
      IMAGE_TAG: { value: 'latest' },
    },
  },
});
```

This will use a `LinuxArmBuildImage` to create the Docker image, ensuring us that an `ARM_64` CPU will be used when the image is created regardless of the CPU of the machine doing the CDK deployment.

### Deployment

Finally, we will use this image to deploy to the Fargate service previously created.

```typescript
const deployAction = new EcsDeployAction({
  actionName: 'Deploy',
  service: props.fargateService,
  input: buildOutput,
});
```

The `public.ecr.aws/nginx/nginx:latest-arm64v8` image that was originally used will be replaced with the newly built image that has been uploaded to an ECR repository.

## Caveats

In a deployment like this, the CodePipeline will only be triggered when the source code for the Docker image is changed. If you need to rebuild the image for any reason, you will need to manually run the CodePipeline.

## GitHub Repo

This demo is available here: https://github.com/schuettc/cdk-docker-codebuild

## Testing

To test this for yourself, simply clone this repo and deploy the CDK:

```bash
git clone git@github.com:schuettc/cdk-docker-codebuild.git
cd cdk-docker-codebuild
yarn launch
```

## Cleanup

To remove these resources:

```bash
yarn cdk destroy
```


In this demo we will see how to deploy a custom built Fargate container using CodeBuild

CDK Deployment of Docker Image with CodeBuild

# Building a Private Fargate Task and Lambda

In order to build an AWS Fargate task in a [private subnet](https://docs.aws.amazon.com/vpc/latest/userguide/configure-subnets.html) that can still be invoked by a Lambda function, the Lambda function must also be built in the same VPC with access to the private subnet.

![Overview](/images/blog/PrivateLambdaFargate.png)

## GitHub Repo

Full code is available here: https://github.com/schuettc/cdk-private-fargate-with-lambda

## Building the VPC and ALB

```typescript
this.vpc = new Vpc(this, 'VPC', {
  subnetConfiguration: [
    {
      cidrMask: 24,
      name: 'PrivateSubnet',
      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    },
    {
      cidrMask: 24,
      name: 'PublicSubnet',
      subnetType: SubnetType.PUBLIC,
    },
  ],
  maxAzs: 2,
});
```

Here we are creating a VPC with two types of Subnets - `PRIVATE_WITH_EGRESS` and `PUBLIC`.

```typescript
this.applicationLoadBalancer = new ApplicationLoadBalancer(this, 'alb', {
  vpc: this.vpc,
  vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  internetFacing: false,
  securityGroup: this.fargateSecurityGroup,
});
```

Next we will create an Application Load Balancer in the `PRIVATE_WITH_EGRESS` subnet.

## Fargate

```typescript
this.fargateService = new ApplicationLoadBalancedFargateService(
  this,
  'fargateService',
  {
    taskImageOptions: {
      image: ContainerImage.fromRegistry('amazon/amazon-ecs-sample'),
      taskRole: fargateTaskRole,
    },
    publicLoadBalancer: false,
    vpc: props.vpc,
    assignPublicIp: false,
    openListener: false,
    loadBalancer: props.applicationLoadBalancer,
    listenerPort: 80,
    taskSubnets: {
      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    },
    securityGroups: [props.fargateSecurityGroup],
    runtimePlatform: {
      operatingSystemFamily: OperatingSystemFamily.LINUX,
      cpuArchitecture: CpuArchitecture.X86_64,
    },
  },
);
```

Next we will create the Fargate Service and Task, once again assigning it to the `PRIVATE_WITH_EGRESS` subnet using the previously created Application Load Balancer.

## Lambda

```typescript
const fargateLambdaInPrivateVPCwithSG = new NodejsFunction(
  this,
  'fargateLambdaInPrivateVPCwithSG',
  {
    entry: 'src/resources/fargateLambda/index.ts',
    runtime: Runtime.NODEJS_LATEST,
    architecture: Architecture.ARM_64,
    role: lambdaRole,
    timeout: Duration.seconds(60),
    vpc: props.vpc,
    vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
    securityGroups: [lambdaSecurityGroup],
    environment: {
      FARGATE_ALB_URL: props.fargateService.loadBalancer.loadBalancerDnsName,
    },
  },
);
```

Finally, we will create the Lambda function and assign to the `PRIVATE_WITH_EGRESS` subnet.

## Security Groups

In addition to containing the Lambda, Application Load Balancer, and Fargate within the same VPC and private subnet, Security Groups can also be used to restrict access.

```typescript
this.fargateSecurityGroup = new SecurityGroup(this, 'fargateSecurityGroup', {
  vpc: this.vpc,
  description: 'Security Group for Fargate ALB',
});
```

First we will create a Security Group for the Application Load Balancer.

```typescript
const lambdaSecurityGroup = new SecurityGroup(this, 'LambdaSecurityGroup', {
  vpc: props.vpc,
});
```

Next we will create a Security Group for the Lambda function.

```typescript
props.fargateSecurityGroup.connections.allowFrom(
  new Connections({
    securityGroups: [lambdaSecurityGroup],
  }),
  Port.tcp(80),
  'allow traffic on port 80 from the Lambda security group',
);
```

Finally, we will allow a connection from the Lambda Security Group to the Application Load Balancer Security Group. This will allow the Lambda function to make requests to the Fargate Task through the Application Load Balancer. The other two Lambda functions show how this is required as they do not work. The first does not include the correct Security Group and the second does not include the correct VPC subnet.

## Result

Once deployed, the Lambda function in the correct VPC with the correct Security Group will be able to make a request to the Fargate task and get a response:

```html
<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="utf-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1" />
    <title>Simple PHP App</title>
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <link href="assets/css/bootstrap.min.css" rel="stylesheet" />
    <style>
      body {
        margin-top: 40px;
        background-color: #333;
      }
    </style>
    <link href="assets/css/bootstrap-responsive.min.css" rel="stylesheet" />
    
  </head>

  <body>
    <div class="container">
      <div class="hero-unit">
        <h1>Simple PHP App</h1>
        <h2>Congratulations</h2>
        <p>Your PHP application is now running on a container in Amazon ECS.</p>
        <p>The container is running PHP version 5.4.16.</p>
      </div>
    </div>
  </body>
</html>
```

The other Lambda functions will timeout and fail

```text
Task timed out after 60.07 seconds
```

Additionally, the Application Load Balancer URL will only return an RFC 1918 private address:

```bash
$ nslookup internal-Privat-vpcRe-8uesdCpJs6j6-1716194524.us-east-1.elb.amazonaws.com

Non-authoritative answer:
Name:	internal-privat-vpcre-8uesdcpjs6j6-1716194524.us-east-1.elb.amazonaws.com
Address: 10.0.1.253
Name:	internal-privat-vpcre-8uesdcpjs6j6-1716194524.us-east-1.elb.amazonaws.com
Address: 10.0.0.230
```

How to build a private Fargate task and connect to it with an AWS Lambda function using AWS CDK.  

Using CDK to build a Fargate task with AWS Lambda integration


```typescript
import { RemovalPolicy, IgnoreMode } from 'aws-cdk-lib';
import { Bucket, ObjectOwnership } from 'aws-cdk-lib/aws-s3';
import { Source, BucketDeployment } from 'aws-cdk-lib/aws-s3-deployment';
import { Construct } from 'constructs';

export class BucketDeploymentExample extends Construct {
  constructor(scope: Construct, id: string) {
    super(scope, id);

    const assetBucket = new Bucket(this, 'assetBucket', {
      publicReadAccess: false,
      removalPolicy: RemovalPolicy.DESTROY,
      objectOwnership: ObjectOwnership.BUCKET_OWNER_PREFERRED,
      autoDeleteObjects: true,
    });

    new BucketDeployment(this, 'assetBucketDeployment', {
      sources: [
        Source.asset('src/resources/server/assets', {
          exclude: ['**/node_modules/**', '**/dist/**'],
          ignoreMode: IgnoreMode.GIT,
        }),
      ],
      destinationBucket: assetBucket,
      retainOnDelete: false,
      memoryLimit: 512,
    });
  }
}
```

Here we can see an example of how to prevent some files and directories from being uploaded as part of the bucket deployment. In this case, we want to prevent `**/node_modules/**` and `**/dist/**` from being uploaded as they are part of the local development and not needed in the bucket. We are going to use [`IgnoreMode`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.IgnoreMode.html) to use the [`.gitignore specification`](https://git-scm.com/docs/gitignore).

Now, when using [`BucketDeployment`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.BucketDeployment.html) with a [`Source`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.Source.html), we can use [`AssetOptions`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_assets.AssetOptions.html) to prevent those entire directories from being included in the upload.


When uploading files and directories during a CDK bucket deployment, `exclude` can be used.  This samples shows how to use that feature.

Excluding files and directories from a CDK Bucket Deployment


# Simple Dev EC2 Instance

This simple Cloudformation template will deploy a new EC2 instance in a new VPC that can be used for dev work. This instance uses [Ubuntu](https://ubuntu.com/) with either an [ARM64](https://aws.amazon.com/ec2/instance-types/m7g/) or [X86_64](https://aws.amazon.com/ec2/instance-types/m5/) CPU and can be deployed as a `LARGE`, `XLARGE`, or `2XLARGE` instance size. It comes pre-installed with several commonly used packages:

- NodeJS 18
- Python 3.10
- pip
- jq
- Docker

## Adding Keys (optional)

If you'd like to copy private or public keys to the instance during deployment, you can add them to SSM before deploying.

```bash
aws ssm put-parameter --name /devServer/publicKey --overwrite --type SecureString --value $(cat ~/.ssh/key.pub | base64)
aws ssm put-parameter --name /devServer/githubKey --overwrite --type SecureString --value $(cat ~/.ssh/private.pem | base64)
```

These commands will base64 encode the contents of these files and store in them in [SSM Parameter Store](https://docs.aws.amazon.com/systems-manager/latest/userguide/systems-manager-parameter-store.html).

During deployment, these parameters will be read and used to configure the instance.

```bash
GITHUB_KEY=$(aws ssm get-parameter --with-decryption --name /devServer/githubKey --query Parameter.Value --output text 2> /dev/null)
EXIT_CODE=$?
if [[ "$EXIT_CODE" -ne 0 ]]; then echo 'No GitHub Key found'; else echo 'Found GitHub Key' && echo $GITHUB_KEY | base64 -d > /home/ec2-user/.ssh/github.pem; fi
PUBLIC_KEY=$(aws ssm get-parameter --with-decryption --name /devServer/publicKey --query Parameter.Value --output text 2> /dev/null)
EXIT_CODE=$?
if [[ "$EXIT_CODE" -ne 0 ]]; then echo 'No Public Key found'; else echo 'Found Public Key' && echo $PUBLIC_KEY | base64 -d >> /home/ec2-user/.ssh/authorized_keys; fi
chmod 600 /home/ec2-user/.ssh/github.pem
chown ec2-user:ec2-user /home/ec2-user/.ssh/*
```

## Security Group

Several TCP ports will be opened in the Security Group.

```yaml
SecurityGroupIngress:
  - IpProtocol: tcp
    FromPort: '22'
    ToPort: '22'
    CidrIp: 0.0.0.0/0
  - IpProtocol: tcp
    FromPort: '80'
    ToPort: '80'
    CidrIp: 0.0.0.0/0
  - IpProtocol: tcp
    FromPort: '443'
    ToPort: '443'
    CidrIp: 0.0.0.0/0
  - IpProtocol: tcp
    FromPort: '3000'
    ToPort: '3000'
    CidrIp: 0.0.0.0/0
  - IpProtocol: tcp
    FromPort: '8080'
    ToPort: '8080'
    CidrIp: 0.0.0.0/0
```

This will open the following ports:

- 22
- 80
- 443
- 3000
- 8080

## Deployment Options

![DeploymentOptions](/images/blog/DeploymentOptions.png)

During deployment, you can choose the CPU Type, the Instance Size, and if you wish to add Administrator Access.

> Adding Administrator Access will allow you to use all AWS resources, but **must** be used with caution

[![Launch](https://s3.amazonaws.com/cloudformation-examples/cloudformation-launch-stack.png)](https://us-east-1.console.aws.amazon.com/cloudformation/home?region=us-east-1#/stacks/create/review?templateURL=https://subaud-resources.s3.amazonaws.com/ec2-cloudformation/template.yaml&stackName=DevServer)


This Cloudformation template will deploy a simple EC2 instance to be used as a development server.  Several common packages are included in the deployment and keys can be installed during deployment.

Deploy a simple EC2 Instance via Cloudformation


# 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


I use [projen](https://github.com/projen/projen) for almost all of my projects because it allows me to not worry about all of the very necessary but tedious parts of a project - `.gitignore`, `.eslintrc.json`, GitHub Actions workflows, etc. However, I often find myself having both a front end and back end in the same repository. While projen and [GitHub Actions](https://github.com/features/actions) will automatically take care of upgrading dependencies in my main folder, I also want it to take care of dependencies in other parts of my project.

## Schedule

For the main folder dependencies, once a day upgrades is very aggressive. We can adjust that in our `.projenrc.js` file to weekly:

```javascript
const { UpgradeDependenciesSchedule } = require('projen/lib/javascript');

const project = new awscdk.AwsCdkTypeScriptApp({
  ...projectConfig,
  depsUpgradeOptions: {
    ignoreProjen: false,
    workflowOptions: {
      labels: ['auto-approve', 'auto-merge'],
      schedule: UpgradeDependenciesSchedule.WEEKLY,
    },
  },
});
```

This pushes our `upgrade` workflow out to [once a week](https://crontab.guru/#0_0_*_*_1):

```yaml
name: upgrade
on:
  workflow_dispatch: {}
  schedule:
    - cron: 0 0 * * 1
```

## Additional Actions

To add an action, we will once again edit our `.projenrc.js` file. This time we will add a workflow.

```javascript
const { JobPermission } = require('projen/lib/github/workflows-model');

const upgradeSite = project.github.addWorkflow('upgrade-site');
upgradeSite.on({ schedule: [{ cron: '0 0 * * 1' }], workflowDispatch: {} });
```

This will create a new workflow on the same schedule as the existing `upgrade` workflow.

Next, we will add a job that will:

- Install dependencies via `yarn`
- Upgrade dependencies
- Create a Pull Request

```javascript
upgradeSite.addJobs({
  upgradeSite: {
    runsOn: ['ubuntu-latest'],
    name: 'upgrade-site',
    permissions: {
      actions: JobPermission.WRITE,
      contents: JobPermission.READ,
      idToken: JobPermission.WRITE,
    },
    steps: [
      { uses: 'actions/checkout@v3' },
      {
        name: 'Setup Node.js',
        uses: 'actions/setup-node@v3',
        with: {
          'node-version': '16',
        },
      },
      {
        run: 'yarn install --check-files --frozen-lockfile',
        workingDirectory: 'site',
      },
      { run: 'yarn upgrade', workingDirectory: 'site' },
      {
        name: 'Create Pull Request',
        uses: 'peter-evans/create-pull-request@v4',
        with: {
          'token': '${{ secrets.' + AUTOMATION_TOKEN + ' }}',
          'commit-message': 'chore: upgrade site',
          'branch': 'auto/projen-upgrade',
          'title': 'chore: upgrade site',
          'body': 'This PR upgrades site',
          'labels': 'auto-merge, auto-approve',
          'author': 'github-actions <github-actions@github.com>',
          'committer': 'github-actions <github-actions@github.com>',
          'signoff': true,
        },
      },
    ],
  },
});
```

Adjust the `workingDirectory` as needed for any directory that has dependencies that can be upgraded.

## Result

Now, we will have a weekly GitHub Actions workflow that will upgrade dependencies for both our main folder, as well as a subfolder of our choosing. This can be used to help keep [Dependabot](https://github.com/dependabot/dependabot-core) alerts to a minimum by keeping up with security updates.

```yaml
name: upgrade-site
on:
  schedule:
    - cron: 0 5 * * 1
  workflow_dispatch: {}
jobs:
  upgradeSite:
    name: upgrade-site
    runs-on: ubuntu-latest
    permissions:
      actions: write
      contents: read
      id-token: write
    steps:
      - uses: actions/checkout@v3
      - name: Setup Node.js
        uses: actions/setup-node@v3
        with:
          node-version: '16'
      - run: yarn install --check-files --frozen-lockfile
        working-directory: site
      - run: yarn upgrade
        working-directory: site
      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v4
        with:
          token: ${{ secrets.PROJEN_GITHUB_TOKEN }}
          commit-message: 'chore: upgrade site'
          branch: auto/projen-upgrade
          title: 'chore: upgrade site'
          body: This PR upgrades site
          labels: auto-merge, auto-approve
          author: github-actions <github-actions@github.com>
          committer: github-actions <github-actions@github.com>
          signoff: true
```


This article will show you how to add custom GitHub Actions workflows with Projen

Custom GitHub Action workflows with projen


# CDK Websocket Server

In this demo, we see how to build a simple WebSocket server using Amazon Elastic Container Service with Fargate. This demo also includes an [Amazon CloudFront Distribution](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/distribution-working-with.html), [Application Load Balancer](https://aws.amazon.com/elasticloadbalancing/application-load-balancer/), and [Auto Scaling group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html). This will allow the server to scale up as needed while using TLS to secure the communication.

![Overview](/images/blog/WebSocketOverview.png)

## ECS Fargate

## Docker Build

```Dockerfile
FROM --platform=linux/arm64 node:20
WORKDIR /usr/src/app
COPY . .
RUN yarn && yarn build
EXPOSE 8080
CMD [ "node", "dist/server.js" ]
```

The Docker build is a simple Typescript based server that runs on NodeJS. This Dockerfile will copy the contents of the source directory and use `tsc` to transpile the Typescript file into Javascript before running.

### Cluster and Auto Scaling Group

First we will create the cluster that our container will run in.

```typescript
this.cluster = new Cluster(this, "Cluster", {
  vpc: props.vpc,
  clusterName: "websocket-service",
});

const autoScalingGroup = new AutoScalingGroup(this, "AutoScalingGroup", {
  vpc: props.vpc,
  instanceType: new InstanceType("m6i.large"),
  machineImage: EcsOptimizedImage.amazonLinux2(),
  desiredCapacity: 1,
});

autoScalingGroup.role.addManagedPolicy(
  ManagedPolicy.fromAwsManagedPolicyName("AmazonSSMManagedInstanceCore")
);

const capacityProvider = new AsgCapacityProvider(this, "capacityProvider", {
  autoScalingGroup: autoScalingGroup,
});

this.cluster.addAsgCapacityProvider(capacityProvider);
```

This cluster is running in a newly created VPC and includes an Auto Scaling Group.

### Fargate Task Definition

Next, we will create a Fargate container that will run our WebSocket Server. This will consist of several configurations that need to work together.

```typescript
const webSocketTask = new FargateTaskDefinition(
  this,
  "WebSocketTaskDefinition",
  {
    memoryLimitMiB: 2048,
    cpu: 1024,
    runtimePlatform: {
      operatingSystemFamily: OperatingSystemFamily.LINUX,
      cpuArchitecture: CpuArchitecture.ARM64,
    },
    taskRole: websocketServiceRole,
  }
);
```

Here we are setting up the basics of our compute. This Task will use `ARM64` compute. All components must be configured to use the same type of compute.

### Fargate Container

Next we will set up our container.

```typescript
webSocketTask.addContainer("WebSocketContainer", {
  image: ContainerImage.fromAsset("src/resources/containerImage"),
  containerName: "websocket-service",
  portMappings: [{ containerPort: 8080, hostPort: 8080 }],
  logging: LogDrivers.awsLogs({
    streamPrefix: "websocket-service",
  }),
  healthCheck: {
    command: ["CMD-SHELL", "curl -f http://localhost:8080/health"],
    interval: Duration.seconds(30),
    timeout: Duration.seconds(30),
  },
  environment: {},
});
```

There are several key components here.

#### Port Mappings

In this example, we are using port `8080` on the container and host. Later we will see how to map the public facing port to this port.

#### Health Check

This container is also configured to perform periodic health checks to verify the container is running correctly. In this example, we are running a `curl` on the server.

### Fargate Service

Finally, we will create the Service using the previously created Task.

```typescript
const websocketService = new FargateService(this, "WebSocketService", {
  cluster: this.cluster,
  taskDefinition: webSocketTask,
  assignPublicIp: true,
  desiredCount: 1,
  vpcSubnets: { subnetType: SubnetType.PUBLIC },
  securityGroups: [webSocketServiceSecurityGroup],
  enableExecuteCommand: true,
});
```

With the Fargate created, we can tie this to an Application Load Balancer.

#### Security Group

To ensure that only the Application Load Balancer can make requests to the Fargate container, we will attach a Security Group to the Fargate Service and allow the Application Load Balancer Security Group access to it.

```typescript
const albSecurityGroup = new SecurityGroup(this, "ALBSecurityGroup", {
  vpc: props.vpc,
  description: "Security Group for ALB",
  allowAllOutbound: true,
});

webSocketServiceSecurityGroup.connections.allowFrom(
  new Connections({
    securityGroups: [albSecurityGroup],
  }),
  Port.tcp(8080),
  "allow traffic on port 8080 from the ALB security group"
);
```

## Application Load Balancer

```typescript
this.applicationLoadBalancer = new ApplicationLoadBalancer(
  this,
  "ApplicationLoadBalancer",
  {
    vpc: this.vpc,
    internetFacing: true,
  }
);
```

The Application Load Balancer is created and associated with the VPC.

### Target Group

```typescript
const webSocketTargetGroup = new ApplicationTargetGroup(
  this,
  "webSocketTargetGroup",
  {
    vpc: props.vpc,
    port: 8080,
    protocol: ApplicationProtocol.HTTP,
    targets: [websocketService],
    healthCheck: {
      path: "/",
      protocol: Protocol.HTTP,
      port: "8080",
    },
  }
);
```

First, we will create a Target Group. This is where traffic will be sent. Here we can see port `8080` as the port to send traffic to on the container. This corresponds to the port exposed on the Fargate container. This Target Group will forward requests to the Fargate Service. This Application Load Balancer also includes a health check. This health check is different from the previously created health check as the Application Load Balancer is initiating this check rather than the container itself.

### Listener

```typescript
const webSocketListener = props.applicationLoadBalancer.addListener(
  "webSocketListener",
  {
    port: 80,
    protocol: ApplicationProtocol.HTTP,
    open: true,
    defaultAction: ListenerAction.fixedResponse(403),
  }
);

webSocketListener.addAction("ForwardFromCloudFront", {
  conditions: [
    ListenerCondition.httpHeader(props.customHeader, [props.randomString]),
  ],
  action: ListenerAction.forward([webSocketTargetGroup]),
  priority: 1,
});
```

Next we will create a Listener. Here we can see the listener is listening on port `80`. This is where we made the conversion from port `80` to port `8080`. We are using Protocol `HTTP`. The server will upgrade this HTTP request to WebSocket when it is received.

### Actions

To [restrict access to the Application Load Balancer](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/restrict-access-to-load-balancer.html) we will be adding a unique header to the CloudFront Distribution and a corresponding condition on the Application Load Balancer.

We do that here by creating a default action that responds with a `403`. This means that the Application Load Balancer will reject any request unless it includes a specific Header and Value. In this case, the Application Load Balancer will forward the request to the `webSocketTargetGroup`. We will be adding this Header and Value on the Origin of the CloudFront Distribution in the next step.

Note that the Application Load Balancer is using `HTTP` and not `HTTPS`. We will be enforcing `HTTPS` at the Cloudfront Distribution layer. Be only allowing traffic to our Application Load Balancer from our CloudFront Distribution, we can enforce `HTTPS` be used from the Client. This allows us to create a secure connection without a owning a domain that can be used to generate the certificate.

## Cloudfront Distribution

Finally, we will create our CloudFront Distribution. This will be used to provide TLS to our Application Load Balancer.

```typescript
const defaultOrigin = new LoadBalancerV2Origin(props.applicationLoadBalancer, {
  httpPort: 80,
  protocolPolicy: OriginProtocolPolicy.HTTP_ONLY,
  originId: "defaultOrigin",
});

this.distribution = new Distribution(this, "Distribution", {
  defaultBehavior: {
    origin: defaultOrigin,
    viewerProtocolPolicy: ViewerProtocolPolicy.HTTPS_ONLY,
    cachePolicy: CachePolicy.CACHING_DISABLED,
    allowedMethods: AllowedMethods.ALLOW_ALL,
    originRequestPolicy: OriginRequestPolicy.ALL_VIEWER,
  },
  defaultRootObject: "index.html",
  priceClass: PriceClass.PRICE_CLASS_100,
  logBucket: distributionLoggingBucket,
  enableLogging: true,
});
```

Here we are creating a CloudFront Distribution that only accepts HTTPS. This will create a certificate that is used by the Distribution. This Distribution will send that traffic to our Application Load Balancer on port `80`.

### Custom Header

In order to provide the security outlined above using Custom Headers and Values, we must add those Headers and Values to the Origination. Unfortunately, that feature does not existing natively in CDK. Therefore, we will use a Custom Resource to add the Headers and Values.

```typescript
new CustomResource(this, "customHeaderCustomResource", {
  serviceToken: customHeaderCustomResourceProvider.serviceToken,
  properties: {
    DistributionId: this.distribution.distributionId,
    Origins: [
      {
        OriginId: "defaultOrigin",
        CustomHeaders: [
          {
            HeaderName: props.customHeader,
            HeaderValue: props.randomString,
          },
        ],
      },
    ],
  },
});
```

Using the previously created Distribution, we will pass the information to our Custom Resource that will be added to the Distribution.

### Custom Resource

```typescript
const updatedOrigins = Distribution.DistributionConfig!.Origins!.Items!.map(
  (origin: any) => {
    const matchedOrigin = Origins.find((o: any) => o.OriginId === origin.Id);
    if (matchedOrigin) {
      return {
        ...origin,
        CustomHeaders: {
          Quantity: matchedOrigin.CustomHeaders.length,
          Items: matchedOrigin.CustomHeaders.map((header: any) => ({
            HeaderName: header.HeaderName,
            HeaderValue: header.HeaderValue,
          })),
        },
      };
    }
    return origin;
  }
);
```

Within the Custom Resource, we will `GetDistributionConfiguration` and match up the origin with the desired Header and Value. Using this updated configuration, we will `UpdateDistributionConfiguration`. Now, when a request is made to our CloudFront Distribution, it will add this Header and Value to the request to the Application Load Balancer. This, in turn, will forward the request to our Fargate Service.

## Results

We have now created an auto-scaling, load-balanced application that is secured with `HTTPS` using a CloudFront Distribution. This will allow you to build a secure WebSocket server that will automatically adapt to your traffic needs.

## Deployment

To deploy this demo, simply run:

```bash
yarn launch
```

## Removal

This demo does include services that can accumulate costs, so be sure to remove when not needed. To delete:

```bash
yarn cdk destroy
```

You may have to manually delete the Auto Scaling Group if it is not able to automatically delete.

## Repo

https://github.com/schuettc/cdk-websocket-server


This demo will show how to build and deploy a Fargate WebSocket server.  This application will automatically scale and use TLS to secure the connection.

Building and Deploying a WebSocket server with Fargate and CDK


![Overview](/images/blog/KDSReader.png)

In this demo, we see how to build a React based Websocket reader to get information from a Kinesis Data Stream to a client in real-time. This can be useful for viewing the contents of a Kinesis Data Stream.

## Components

### Websocket API

This demo uses an [Amazon API Gateway using WebSockets](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-websocket-api.html). Three routes are configured in this API Gateway: $connect, $disconnect, and $default. Connect and Disconnect are used to control connections to the API Gateway. These requests are passed to the Lambda function and stored in the DynamoDB.

```typescript
this.webSocketApi = new WebSocketApi(this, "webSocketApi", {});

this.webSocketApi.addRoute("$connect", {
  integration: new WebSocketLambdaIntegration(
    "ConnectIntegration",
    this.lambdaHandler
  ),
});
this.webSocketApi.addRoute("$disconnect", {
  integration: new WebSocketLambdaIntegration(
    "DisconnectIntegration",
    this.lambdaHandler
  ),
});
this.webSocketApi.addRoute("$default", {
  integration: new WebSocketLambdaIntegration(
    "DefaultIntegration",
    this.lambdaHandler
  ),
});
```

### Lambda Handler

When the request is made to the Lambda function, the request is processed and information about the connection stored in the DynamoDB.

```typescript
export const handler: Handler = async (event) => {
  if (isAPIGatewayProxyEvent(event)) {
    // WebSocket connection and disconnection handling
    const connectionId = event.requestContext.connectionId;
    console.log('endpoint:  ' + process.env.API_GATEWAY_ENDPOINT);

    if (event.requestContext.eventType === 'CONNECT') {
      await ddbDocClient.send(
        new PutCommand({
          TableName: process.env.CONNECTION_TABLE,
          Item: { connectionId },
        }),
      );
      return { statusCode: 200 };
    } else if (event.requestContext.eventType === 'DISCONNECT') {
      await ddbDocClient.send(
        new DeleteCommand({
          TableName: process.env.CONNECTION_TABLE,
          Key: { connectionId },
        }),
      );
      return { statusCode: 200 };
    }
```

This information will be used when a Kinesis Data Stream record is used to [invoke the Lambda function](https://docs.aws.amazon.com/lambda/latest/dg/with-kinesis.html).

```typescript
this.lambdaHandler = new NodejsFunction(this, "lambdaHandler", {
  entry: "src/resources/handler/index.ts",
  runtime: Runtime.NODEJS_18_X,
  architecture: Architecture.ARM_64,
  timeout: Duration.seconds(60),
  role: lambdaHandlerRole,
  environment: {
    STREAM_NAME: props.kinesisDataStream.streamName,
    CONNECTION_TABLE: props.connectionTable.tableName,
    API_GATEWAY_ENDPOINT: `https://${this.webSocketApi.apiId}.execute-api.${this.webSocketApi.stack.region}.amazonaws.com/${this.webSocketStage.stageName}`,
  },
});

new EventSourceMapping(this, "eventSourceMapping", {
  target: this.lambdaHandler,
  eventSourceArn: props.kinesisDataStream.streamArn,
  startingPosition: StartingPosition.LATEST,
});
```

Here we see the Lambda function being created and `EventSourceMapping` used to trigger the Lambda when a record is added to the Kinesis Data Stream.

```typescript
  } else if (isKinesisStreamEvent(event)) {
    // Kinesis Data Stream processing
    for (const record of event.Records) {
      const kinesisData = Buffer.from(record.kinesis.data, 'base64').toString(
        'utf8',
      );
      console.log('Kinesis Record:', kinesisData);

      const connections = await ddbDocClient.send(
        new ScanCommand({ TableName: process.env.CONNECTION_TABLE }),
      );
      const postData = JSON.parse(kinesisData);

      if (connections.Items) {
        console.log('Connections: ' + JSON.stringify(connections.Items));
        for (const connection of connections.Items) {
          try {
            await apiGatewayManagementApi.send(
              new PostToConnectionCommand({
                ConnectionId: connection.connectionId,
                Data: new TextEncoder().encode(JSON.stringify(postData)),
              }),
            );
          } catch (error) {
            if (
              error instanceof Error &&
              'statusCode' in error &&
              error.statusCode === 410
            ) {
              // Remove stale connections
              await ddbDocClient.send(
                new DeleteCommand({
                  TableName: process.env.CONNECTION_TABLE,
                  Key: { connectionId: connection.connectionId },
                }),
              );
            }
          }
        }
      }
    }
  }
```

Now, when the Lambda is triggered by a KDS event, the Lambda will check if there are any active connections in the DynamoDB. If there are, the record will be written to the API Gateway.

### Client

In the client we will create a connection to the API Gateway so we can receive messages as they arrive.

```typescript
useEffect(() => {
  const ws = new WebSocket(WEB_SOCKET_URL + "/" + WEB_SOCKET_STAGE);

  ws.onopen = () => {
    console.log("Connected to WebSocket");
    setSocket(ws);
    setConnected(true);
  };

  ws.onmessage = (event) => {
    console.log("Received message:", event.data);
    const data: Message = JSON.parse(event.data);
    setMessages((prevMessages) => [...prevMessages, data]);
  };

  ws.onerror = (error: Event) => {
    console.error("WebSocket error:", error);
  };

  ws.onclose = () => {
    console.log("WebSocket connection closed");
    setSocket(null);
    setConnected(false);
  };

  return () => {
    if (ws) {
      ws.close();
    }
  };
}, []);
```

Once the client establishes a connection to the API Gateway, when a message is received, the data will be saved to State and displayed.

```typescript
return (
  <div className="header">
    {connected ? (
      <div style={{ color: "green" }}>WebSocket connected</div>
    ) : (
      <div style={{ color: "red" }}>WebSocket disconnected</div>
    )}
    <button onClick={clearMessages}>Clear</button>
    <div className="messages">
      <h2>Messages</h2>
      <ul className="message-list">
        {messages.map((message, index) => (
          <li key={index} className="message">
            <MessageItem message={message} />
          </li>
        ))}
      </ul>
      <AlwaysScrollToBottom />
    </div>
  </div>
);
```

## GitHub

This demo can be found here: https://github.com/schuettc/react-websocket-reader-for-kds

## Deploy

To deploy this demo:

```bash
yarn launch
```

## Cleanup

To destroy these components:

```bash
yarn cdk destroy
```


In this demo, we will be building a React based WebSocket reader that uses Amazon API Gateway to read data from a Kinesis Data Stream

Creating a React based WebSocket reader for KDS


# Multiple CPU Architecture CDK Deployment of an Asterisk to ECS Fargate

This demo contains a CDK deployment of an Asterisk server to Amazon ECS using Fargate. This will allow us to deploy an Asterisk server to a Docker container.

[https://github.com/schuettc/cdk-fargate-asterisk](https://github.com/schuettc/cdk-fargate-asterisk)

## Docker Image

For this demo, we will be using the [andrius/asterisk](https://github.com/andrius/asterisk) Docker image.

## Asterisk Configuration

To allow for customized configuration, we will copy files from the local directory to the Asterisk server in the `Dockerfile`.

```docker
COPY config/* /etc/asterisk
COPY docker-entrypoint.sh /
RUN chmod +x /docker-entrypoint.sh
```

In this example, we are copying in several files for our configuration including a `pjsip.conf` and `extensions.conf` files.

```asterisk
[udp]
type=transport
protocol=udp
bind=0.0.0.0
external_media_address=PUBLIC_IP
external_signaling_address=PUBLIC_IP
allow_reload=yes
```

In the [`pjsip.conf`](https://github.com/schuettc/cdk-fargate-asterisk/blob/main/src/resources/asterisk/config/pjsip.conf) file, we are simply loading a basic `udp` transport. We will configure this during deployment later.

## Multiple Build Platforms

In order to accommodate deployments from multiple platforms, we will ensure that the deployed version matches the built version.

In the [`Dockerfile`](https://github.com/schuettc/cdk-fargate-asterisk/blob/main/src/resources/asterisk/Dockerfile) we will use `${BUILDPLATFORM}` to make sure we're building using the local architecture. We need to do this because we are copying files to the image and then building it before deploying it.

```docker
FROM --platform=${BUILDPLATFORM} andrius/asterisk
```

In the [`ecs.ts`](https://github.com/schuettc/cdk-fargate-asterisk/blob/main/src/ecs.ts) file, we will determine the local architecture and use that.

```typescript
let deployArch: CpuArchitecture;
const cpuArch = os.arch();
if (cpuArch === 'arm64') {
  deployArch = CpuArchitecture.ARM64;
} else {
  deployArch = CpuArchitecture.X86_64;
}
```

Then, when we create the Task, we will use that `deployArch` as part of the build for the `cpuArchitecture`.

```typescript
this.task = new FargateTaskDefinition(this, 'TaskDefinition', {
  memoryLimitMiB: 2048,
  cpu: 1024,
  runtimePlatform: {
    operatingSystemFamily: OperatingSystemFamily.LINUX,
    cpuArchitecture: deployArch,
  },
  taskRole: asteriskTaskRole,
  volumes: [
    {
      name: 'asteriskLogs',
      efsVolumeConfiguration: {
        fileSystemId: fileSystem.fileSystemId,
        transitEncryption: 'ENABLED',
        authorizationConfig: {
          accessPointId: asteriskAccessPoint.accessPointId,
          iam: 'ENABLED',
        },
      },
    },
  ],
});
```

Now the deployed version will match the locally built version.

For example, when the Docker image is built on an M1 Mac, the Architecture type will be `ARM64`.

![ARM64](/images/blog/ARM64.png)

However, if the Docker image is built on an X86 based CPU, the Architecture type will be `X86_64`.

![X86_64](/images/blog/X86_64.png)

## Access the Asterisk Server

Once deployed, the Asterisk server can be accessed using [`ecs-execute`](https://docs.aws.amazon.com/AmazonECS/latest/developerguide/ecs-exec.html)

Included in the output of the CDK will be several commands that can be copied to the terminal for ssh access.

To access the running Asterisk:

- Copy/paste the `CLUSTER=` command
- Copy/paste the `TASK=` command
- Copy/paste either `aws ecs execute-command` command

## Asterisk Configuration

During deployment of the Fargate container, the Dockerfile will use [`docker-entrypoint.sh`](https://github.com/schuettc/cdk-fargate-asterisk/blob/main/src/resources/asterisk/docker-entrypoint.sh) as it's `ENTRYPOINT`. Everything in that file will be executed. We can use this to configure the Asterisk during deployment.

```bash
echo "METADATA: " ${ECS_CONTAINER_METADATA_URI_V4}
curl -o metadata.json ${ECS_CONTAINER_METADATA_URI_V4}/task
cat metadata.json
TASK_ARN=$( curl ${ECS_CONTAINER_METADATA_URI_V4}/task | jq -r '.TaskARN' )
echo "TASK_ARN: " $TASK_ARN
CLUSTER=$( curl ${ECS_CONTAINER_METADATA_URI_V4}/task | jq -r '.Cluster' )
echo "CLUSTER: " $CLUSTER
ENI=$(aws ecs describe-tasks --tasks $TASK_ARN --cluster $CLUSTER | jq -r '.tasks[0].attachments[0].details[1].value' )
echo "ENI: " $ENI
PUBLIC_IP=$( aws ec2 describe-network-interfaces --network-interface-ids $ENI | jq -r '.NetworkInterfaces[0].Association.PublicIp' )
echo "PUBLIC_IP: ${PUBLIC_IP}"

sed -i "s/PUBLIC_IP/$PUBLIC_IP/g" /etc/asterisk/pjsip.conf
```

With this shell script, we will determine the `PUBLIC_IP` of the container that is running and use that to configure the `pjsip.conf` file. This can be expanded to configure other parts of the Asterisk server as needed.

## Deploy/Destroy

To deploy this demo:

```bash
yarn launch
```

To destroy this demo:

```bash
yarn cdk destroy
```


This CDK will deploy a an Asterisk server to AWS Fargate from multiple CPU architectures

Multiple CPU Architecture CDK Deployment of an Asterisk to ECS Fargate


# Deploying Cross-Region Certificates with AWS Cloudfront via CDK

[AWS Certificate Manager](https://aws.amazon.com/certificate-manager/) (ACM) can be used to deploy TLS certificates for use with things like [Amazon Cloudfront](https://docs.aws.amazon.com/AmazonCloudFront/latest/DeveloperGuide/Introduction.html). However, ACM certificates must be deployed in `us-east-1`. In order to deploy an ACM certificate and associate with a resource outside of `us-east-1`, a multiple stack deployment must be used. The repo here: [https://github.com/schuettc/cdk-cross-region-cloudfront](https://github.com/schuettc/cdk-cross-region-cloudfront) will show an example of this.

## Certificate Stack

The first stack to be deployed will be the `CertificateStack`. This stack will create a `Certificate` in the `us-east-1` region that can be used by a Cloudfront Distribution in another region.

```typescript
interface CertificateStackProps extends StackProps {
  siteSubdomain: string;
  domain: string;
  hostedZoneId: string;
}

export class CertificateStack extends Stack {
  siteCertificate: Certificate;
  constructor(scope: Construct, id: string, props: CertificateStackProps) {
    super(scope, id, props);

    const certificateResources = new CertificateResources(this, 'certificate', {
      siteSubdomain: props.siteSubdomain,
      domain: props.domain,
      hostedZoneId: props.hostedZoneId,
    });

    this.siteCertificate = certificateResources.siteCertificate;
  }
}

const app = new App();

const certEnv = {
  account: process.env.CDK_DEFAULT_ACCOUNT,
  region: 'us-east-1',
};

const certProps = {
  siteSubdomain: process.env.SITE_SUBDOMAIN || '',
  domain: process.env.DOMAIN || '',
  hostedZoneId: process.env.HOSTED_ZONE_ID || '',
};

const certStack = new CertificateStack(app, 'CertificateStack', {
  ...certProps,
  env: certEnv,
  crossRegionReferences: true,
});

app.synth();
```

Here we are explicitly declaring `us-east-1` as the region to deploy this `Stack` to because ACM certificates used with CloudFront _must_ use `us-east-1`. We are passing in to the `Stack` props from a `.env` file that will be used to create the `Certificate`. This `Certificate` will be used as input to the next `Stack`. Note that the `Stack` must take the input `crossRegionReferences: true` to let the next `Stack` use this `Certificate`.

## Site Stack

```typescript
interface SiteStackProps extends StackProps {
  siteCertificate: Certificate;
  siteSubdomain: string;
  domain: string;
  hostedZoneId: string;
}

export class SiteStack extends Stack {
  constructor(scope: Construct, id: string, props: SiteStackProps) {
    super(scope, id, props);

    const site = new SiteResources(this, 'site', {
      siteCertificate: props.siteCertificate,
      siteSubdomain: props.siteSubdomain,
      domain: props.domain,
      hostedZoneId: props.hostedZoneId,
    });

    new CfnOutput(this, 'distributionURL', {
      value: site.distribution.domainName,
    });

    new CfnOutput(this, 'siteUrl', {
      value: `https://${props.siteSubdomain}.${props.domain}`,
    });
  }
}

const app = new App();

const siteEnv = {
  account: process.env.CDK_DEFAULT_ACCOUNT,
  region: 'eu-central-1',
};

const siteProps = {
  siteCertificate: certStack.siteCertificate,
  siteSubdomain: process.env.SITE_SUBDOMAIN || '',
  domain: process.env.DOMAIN || '',
  hostedZoneId: process.env.HOSTED_ZONE_ID || '',
};

new SiteStack(app, 'SiteStack', {
  ...siteProps,
  env: siteEnv,
  crossRegionReferences: true,
});

app.synth();
```

Here we are creating a second `Stack` as part of this deployment. This `Stack` will deploy the actual website using the `Certificate` from the previous `Stack`. The props used for this `Stack` are the same as the previous `Stack` with the addition of the `Certificate` created in the first `Stack`. This `Stack` uses a typical Single-Page Application (SPA) deployment of S3 + CloudFront with a specific `Certificate` and `ARecord` assigned.

```typescript
this.siteBucket = new Bucket(this, 'websiteBucket', {
  publicReadAccess: false,
  removalPolicy: RemovalPolicy.DESTROY,
  autoDeleteObjects: true,
});

const hostedZone = HostedZone.fromHostedZoneAttributes(this, 'hostedZone', {
  zoneName: props.domain,
  hostedZoneId: props.hostedZoneId,
});

this.distribution = new Distribution(this, 'CloudfrontDistribution', {
  enableLogging: true,
  domainNames: [props.siteSubdomain + '.' + props.domain],
  certificate: props.siteCertificate,
  minimumProtocolVersion: SecurityPolicyProtocol.TLS_V1_2_2021,
  defaultBehavior: {
    origin: new S3Origin(this.siteBucket),
    viewerProtocolPolicy: ViewerProtocolPolicy.REDIRECT_TO_HTTPS,
    cachePolicy: CachePolicy.CACHING_DISABLED,
  },
  defaultRootObject: 'index.html',
});

new ARecord(this, 'clientSiteARecord', {
  zone: hostedZone,
  target: RecordTarget.fromAlias(new CloudFrontTarget(this.distribution)),
  recordName: props.siteSubdomain + '.' + props.domain,
});
```

The result will be an SPA deployed to S3 with a CloudFront Distribution that uses a specific URL from Route53 and a Certificate provided by ACM. This site can be deployed in any Region while the Certificate will be deployed in `us-east-1` as required by CloudFront.

![Distribution](/images/blog/Distribution.png)

## .env File

To deploy this demo, a `.env` file must be used. This `.env` file will contain the following:

```bash
SITE_SUBDOMAIN = 'cross-region-site'
DOMAIN = 'example.com'
HOSTED_ZONE_ID = 'Z00000000000000000000'
```

## Result

![Result](/images/blog/Cross-Region-Deploy-Result.png)

The result is an [SPA deployed](https://cross-region-site.subaud.io/) to a non `us-east-1` Region while still using an ACM Certificate used by CloudFront all deployed by CDK. Information on [cross-region certificates](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_certificatemanager-readme.html#cross-region-certificates) is available on the AWS CDK Reference Documentation.

## Resources

- Github Repo: [https://github.com/schuettc/cdk-cross-region-cloudfront](https://github.com/schuettc/cdk-cross-region-cloudfront)


In order to deploy a Certificate with a CloudFront Distribution, a multi-stack CDK must be used to deploy the Certificate in us-east-1 and the SPA in a different Region.  This CDK deployment will show how to do that.

Deploy a Cross-Region SPA with Cloudfront using CDK


# Minecraft CDK Deployment using AWS Fargate

This [repo](https://github.com/schuettc/cdk-minecraft) will deploy an AWS Fargate based Minecraft server that uses Route 53 to update the service and activate the Minecraft server.

Much of the work here is based on the work by [doctorrat117](https://github.com/doctorray117) from [minecraft-ondemand](https://github.com/doctorray117/minecraft-ondemand).

## Overview

![Overview](/images/blog/Minecraft.png)

## .env File

The .env file used by this deployment includes several variables that will be referenced later. A sample .env file is included: [.env.sample](/.env.sample) and should be updated and renamed to `.env`.

```bash
MINECRAFT_EDITION = 'java'
SERVER_SUBDOMAIN = 'minecraft'
DOMAIN = 'example.com'
HOSTED_ZONE_ID = 'Z00000000000000000000'
MEMORY_SIZE = '8192'
CPU_SIZE = '4096'
SNS_EMAIL = 'admin@example.com'
STARTUP_MIN = '10'
SHUTDOWN_MIN = '20'
DEBUG = 'true'
```

A Route 53 domain and Hosted Zone ID is required for this deployment. These will be used to start the service.

### AWS Fargate Service

This deployment uses an AWS Fargate service to deploy two containers - the Minecraft server and a watchdog server. The Minecraft server is the reason for deploying this and will be used to play the game. The watchdog container is used to ensure that the Minecraft server is still being used.

#### Starting the Service

To start the service and allow someone to use the Minecraft server, a query to `SERVER_SUBDOMAIN`.`DOMAIN` will result in Route 53 updating Cloudwatch logs. This Cloudwatch log will trigger an AWS Lambda Function to set the `desired-count` of the Fargate service to 1.

```python
    if desired == 0:
        ecs.update_service(
            cluster=CLUSTER,
            service=SERVICE,
            desiredCount=1,
        )
        print("Updated desiredCount to 1")
    else:
        print("desiredCount already at 1")
```

By setting the `desired-count` to 1, the containers in the ECS service will be activated and available. The AWS ECS Service includes the Minecraft server container and a watchdog container. Both of these will be started when the `desired-count` is set to 1.

```typescript
this.service = new FargateService(this, "FargateService", {
  serviceName: "MineCraftService",
  cluster: this.cluster,
  capacityProviderStrategies: [
    {
      capacityProvider: "FARGATE",
      weight: 1,
      base: 1,
    },
  ],
  taskDefinition: this.task,
  assignPublicIp: true,
  desiredCount: 0,
  vpcSubnets: { subnetType: SubnetType.PUBLIC },
  securityGroups: [props.securityGroup],
  enableExecuteCommand: true,
});

const minecraftServerContainer = this.task.addContainer(
  "MinecraftServerContainer",
  {
    image: ContainerImage.fromRegistry(props.serverConfig.image),
    environment: {
      EULA: "TRUE",
      MEMORY: "8G",
    },
    portMappings: [
      {
        containerPort: props.serverConfig.port,
        hostPort: props.serverConfig.port,
        protocol: props.serverConfig.protocol,
      },
    ],
    essential: false,
    logging: props.serverConfig.debug
      ? new AwsLogDriver({
          logRetention: RetentionDays.THREE_DAYS,
          streamPrefix: "minecraft",
        })
      : undefined,
  }
);

this.task.addContainer("WatchdogContainer", {
  image: ContainerImage.fromAsset(
    path.resolve(__dirname, "./resources/watchdogContainer")
  ),
  essential: true,
  environment: {
    CLUSTER: this.cluster.clusterName,
    SERVICE: "MineCraftService",
    DNSZONE: props.subDomainHostedZoneId,
    SERVERNAME: `${props.serverSubDomain}.${props.domain}`,
    SNSTOPIC: props.snsTopic?.topicArn || "",
    STARTUPMIN: props.startupMin,
    SHUTDOWNMIN: props.shutdownMin,
  },
  logging: props.serverConfig.debug
    ? new AwsLogDriver({
        logRetention: RetentionDays.THREE_DAYS,
        streamPrefix: "minecraft",
      })
    : undefined,
});
```

#### Stopping the Service

During normal operations, both the Minecraft container and Watchdog container will be active. The Minecraft server is used to play the game while the Watchdog server will monitor the activity of the Minecraft server. When the watchdog server determines that the Minecraft server has not been used for `SHUTDOWN_MIN`, the watchdog server will set the `desired-count` of the Fargate Service to 0. By setting the `desired-count` to 0, the containers will be stopped to reduce costs.

### Notification

When the AWS Fargate service starts or stops, a notification is sent to SNS.

```bash
function send_notification ()
{
  [ "$1" = "startup" ] && MESSAGETEXT="${SERVICE} is online at ${SERVERNAME}"
  [ "$1" = "shutdown" ] && MESSAGETEXT="Shutting down ${SERVICE} at ${SERVERNAME}"

  ## SNS Option
  [ -n "$SNSTOPIC" ] && \
  echo "SNS topic set, sending $1 message" && \
  aws sns publish --topic-arn "$SNSTOPIC" --message "$MESSAGETEXT"
}
```


This demo will use CDK to deploy a Minecraft server on AWS Fargate using Route 53 as the trigger

Deploy a Minecraft server with AWS Fargate and AWS CDK


In this demo, we will show how to conditionally deploy resources using environment variables.

## Passing Environment Variables

This CDK uses a Stack with several inputs. Besides the standard `env` input, we are also defining `StackProps` that will be used to pass the `bucketName` from the environment to the Stack.

```typescript
const devEnv = {
  account: process.env.CDK_DEFAULT_ACCOUNT,
  region: process.env.CDK_DEFAULT_REGION,
};

const stackProps = {
  bucketName: process.env.BUCKET_NAME || "",
};

new ConditionalDeployment(app, "ConditionalDeployment", {
  ...stackProps,
  env: devEnv,
});
```

Here we see the standard `projen` created `devEnv` and the App that is being deployed. We are additionally adding `stackProps` to the Stack that is being created and passing the environment variable `BUCKET_NAME` to it if it is present.

## Stack and StackProps

```typescript
interface ConditionalDeploymentProps extends StackProps {
  bucketName?: string;
}

let deploymentBucket: IBucket;

export class ConditionalDeployment extends Stack {
  constructor(scope: Construct, id: string, props: ConditionalDeploymentProps) {
    super(scope, id, props);
```

Here we have defined `ConditionalDeploymentProps` as a `StackProps` to be passed to the Stack as well as `deploymentBucket`. This will be used later with either a new bucket or the existing bucket.

## Condition

```typescript
if (props.bucketName) {
  deploymentBucket = Bucket.fromBucketName(this, "Bucket", props.bucketName);
} else {
  deploymentBucket = new Bucket(this, "Bucket", {
    encryption: BucketEncryption.S3_MANAGED,
    blockPublicAccess: BlockPublicAccess.BLOCK_ALL,
    removalPolicy: RemovalPolicy.DESTROY,
    autoDeleteObjects: true,
  });
}
```

This is where we will check to see if a string has been passed as a prop named `bucketName` to the Stack. It is not required to be passed, but if it is, we want to use that bucket as the deployment destination. To do that, we need to get the [`IBucket`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.IBucket.html) using [`Bucket.fromBucketName`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3.Bucket.html#static-fromwbrbucketwbrnamescope-id-bucketname).

If no prop named `bucketName` was passed to the Stack, we will create a bucket. In either case, the bucket that we will be deploying to is referenced by `deploymentBucket`.

## Deploying to the Bucket

```typescript
const data = {
  bucketName: deploymentBucket.bucketName,
  text: "Hello World",
};

new BucketDeployment(this, "Deployment", {
  sources: [Source.jsonData("config.json", data)],
  destinationBucket: deploymentBucket,
});
```

Now, we will create a simple JSON file using `Source.jsonData` and upload this file to the bucket. This will either be an existing bucket referenced in the environment variables, or a newly created bucket. In either case, we can use `deplyomentBucket` as the `destinationBucket` because we are always creating an `IBucket`. If the bucket already exists, we use `fromBucketName` and if the bucket does not exist, `new Bucket` will return an `IBucket`.

## Deploying with Environment Variables

> Note: You must replace `conditional-cdk-deploy-demo` with a unique name

```bash
export BUCKET_NAME=conditional-cdk-deploy-demo
yarn launch
```

or

```bash
BUCKET_NAME=conditional-cdk-deploy-demo yarn launch
```

Once completed, we can see that an existing S3 bucket has the `config.json` file in it.

```bash
aws s3 ls s3://conditional-cdk-deploy-demo
aws s3 cp s3://conditional-cdk-deploy-demo/config.json ./
cat config.json
```

## Deploying without Environment Variables

```bash
unset BUCKET_NAME
yarn launch
```

When the CDK is deployed, a new bucket will be created. This bucket name will be in the output of the CDK and can be used to verify the creation of the bucket and the deployment of the `config.json` file.

## Testing the CDK

In order to verify that our CDK is correct, we should test it. This is done as part of a projen build. In this demo, we are using Snapshots to test.

```typescript
test("Snapshot", () => {
  const app = new App();
  const stack = new ConditionalDeployment(app, "test", {});

  const template = Template.fromStack(stack);
  expect(template.toJSON()).toMatchSnapshot();
});

test("SnapshotWithBucketName", () => {
  const app = new App();
  const stack = new ConditionalDeployment(app, "test", {
    bucketName: "test-bucket",
  });

  const template = Template.fromStack(stack);
  expect(template.toJSON()).toMatchSnapshot();
});
```

This will now create snapshots for both scenarios. Without the second snapshot, we would have uncovered lines in the test.


This demo will describe how to create a CDK with conditional resource deployment and how to use Environment Variables with that conditional deployment

Conditional Resource Deployment and Environment Variables with CDK


> 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

```bash
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


In order to deploy a Python Lambda function with additional dependencies, we must use something that will [install those dependencies](https://packaging.python.org/en/latest/tutorials/managing-dependencies/). With NodeJS, we can use something like [`esbuild`](https://esbuild.github.io/) to do this. In a Typescript CDK, we can use npm or yarn to install this as a [development dependency](https://classic.yarnpkg.com/en/docs/dependency-types#toc-devdependencies). However, we do not have this option with a Python Lambda. To have this built during deployment, we can use the [bundlingOptions interface](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.BundlingOptions.html).

```typescript
this.queryLambda = new Function(this, "QueryLambda", {
  code: Code.fromAsset(path.join(__dirname, "resources/query_lambda"), {
    bundling: {
      image: Runtime.PYTHON_3_9.bundlingImage,
      command: [
        "bash",
        "-c",
        "pip install -r requirements.txt -t /asset-output && cp -au . /asset-output",
      ],
    },
  }),
  runtime: Runtime.PYTHON_3_9,
  vpc: props.vpc,
  vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  architecture: Architecture.ARM_64,
  handler: "index.handler",
  timeout: Duration.minutes(5),
  role: props.role,
  layers: [props.powerToolsLayer],
  environment: {
    RDS_SECRET_NAME: props.dataBase.secret?.secretName!,
  },
});
```

In [this](https://github.com/schuettc/cdk-private-rds-with-lambda/blob/main/src/lambda.ts) example from the [cdk-private-rds-with-lambda](https://github.com/schuettc/cdk-private-rds-with-lambda) repository, we can see the `QueryLambda` function is being created using `Code` from the `/resources/query_lambda` directory and bundled using a Docker image. This does require Docker desktop to be run locally or from the pipeline that is deploying this function.

When this Lambda function is deployed, `pip install` will be used with the `requirements.txt` file in the `/query_lambda` directory to create the zip file that will be uploaded as the Lambda function.

```bash
resources/
├── initialize_lambda/
│   ├── index.py
│   └── requirements.txt
└── query_lambda/
    ├── index.py
    └── requirements.txt
```


This article will show you how to deploy a Python Lambda function with additional dependencies using CDK

Deploying a Python Lambda with Requirements using CDK


In this blog, we will walk through building an [Amazon RDS](https://aws.amazon.com/rds/) database using CDK. This database will be built in an isolated subnet. An AWS Lambda function will be built to initialize this database during the deployment of the CDK. Another AWS Lambda function will be built to write data to this database once a day. An EC2 instance will be built to connect to this database.

## GitHub Repo

Full code is available here: https://github.com/schuettc/cdk-private-rds-with-lambda

## VPC - Virtual Private Cloud

The first Construct built in this CDK is the Amazon Virtual Private Cloud (VPC). This will lay the foundation for future networking and placement of infrastructure.

```typescript
this.vpc = new Vpc(this, "VPC", {
  natGateways: 1,
  subnetConfiguration: [
    {
      cidrMask: 24,
      name: "Private",
      subnetType: SubnetType.PRIVATE_ISOLATED,
    },
    {
      cidrMask: 24,
      name: "PrivateWithEgress",
      subnetType: SubnetType.PRIVATE_WITH_EGRESS,
    },
    {
      cidrMask: 24,
      name: "Public",
      subnetType: SubnetType.PUBLIC,
    },
  ],
});
```

We will be building a VPC with three SubnetTypes. This Construct will build a complete VPC infrastructure, including:

- Multi-AZ Subnets
- Route Tables
- Security Groups
- Internet Gateway
- NAT Gateway

We will be using this infrastructure for our EC2 instance, RDS database, and Lambda functions.

## PostgreSQL RDS Database

Once the VPC is created, we will be creating an RDS Database within it. In this example, we will be creating a PostgreSQL database.

```typescript
this.database = new DatabaseInstance(this, "database", {
  engine: DatabaseInstanceEngine.POSTGRES,
  vpc: props.vpc,
  vpcSubnets: { subnetType: SubnetType.PRIVATE_ISOLATED },
  instanceType: InstanceType.of(
    InstanceClass.BURSTABLE4_GRAVITON,
    InstanceSize.LARGE
  ),
  multiAz: false,
  allowMajorVersionUpgrade: true,
  autoMinorVersionUpgrade: true,
  backupRetention: Duration.days(21),
  securityGroups: [props.securityGroup],
});
```

Because we use `vpcSubnets: { subnetType: SubnetType.PRIVATE_ISOLATED }` this RDS instance will be created in a [subnet](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.SubnetType.html#private_isolated) that does not route traffic to the Internet. To connect to this RDS database, we will have to create resources within the VPC that can connect to it.

## Database Initializer Custom Resource

Once the PostgreSQL database has been created, we need to initialize it. This will be done using a Custom Resource during the deployment of the CDK. This Custom Resource will be an AWS Lambda function that creates a table. This AWS Lambda Function must be created in the same VPC as the RDS database.

```typescript
const initializeLambda = new Function(this, "InitializeTableLambda", {
  code: Code.fromAsset(path.join(__dirname, "resources/initialize_lambda"), {
    bundling: {
      image: Runtime.PYTHON_3_9.bundlingImage,
      command: [
        "bash",
        "-c",
        "pip install -r requirements.txt -t /asset-output && cp -au . /asset-output",
      ],
    },
  }),
  runtime: Runtime.PYTHON_3_9,
  vpc: props.vpc,
  vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  architecture: Architecture.ARM_64,
  layers: [props.powerToolsLayer],
  role: props.role,
  handler: "index.handler",
  timeout: Duration.minutes(5),
  environment: {
    RDS_SECRET_NAME: props.dataBase.secret?.secretName!,
  },
});
```

This AWS Lambda Function will be used by the Custom Resource to initialize the PostgreSQL database during the creation of the CDK.

### Database Initializer Function

```python
def create_table():
    create_table = """CREATE TABLE queries(
            id SERIAL PRIMARY KEY,
            query_date DATE
            )
            """
    try:
        cursor.execute(create_table)
        cursor.close()
        connection.commit()
    except (Exception, psycopg2.DatabaseError) as error:
        print(error)
    finally:
        if connection is not None:
            connection.close()
```

When this AWS Lambda Function is called during the deployment of the CDK, we will create a table with two columns: `id` and `query_date`. These columns will be used by the recurring Query function to populate the RDS database.

## EC2 Instance

In order to interact with the PostgreSQL database, we will be creating an EC2 instance that is able to connect to the database.

```typescript
const ec2Instance = new Instance(this, "Instance", {
  vpc: props.vpc,
  vpcSubnets: { subnetType: SubnetType.PRIVATE_WITH_EGRESS },
  instanceType: InstanceType.of(InstanceClass.C6G, InstanceSize.MEDIUM),
  machineImage: ami,
  init: CloudFormationInit.fromConfigSets({
    configSets: {
      default: ["install"],
    },
    configs: {
      install: new InitConfig([
        InitCommand.shellCommand("yum update -y"),
        InitCommand.shellCommand("yum upgrade -y"),
        InitCommand.shellCommand("amazon-linux-extras install postgresql15"),
      ]),
    },
  }),
  initOptions: {
    timeout: Duration.minutes(20),
    includeUrl: true,
    includeRole: true,
    printLog: true,
  },
  role: ec2Role,
});
```

This instance will be created in the same `PRIVATE_WITH_EGRESS` SubnetType that the AWS Lambda Functions are created in. This will allow us to install the [`psql` client](https://docs.aws.amazon.com/AmazonRDS/latest/UserGuide/USER_ConnectToPostgreSQLInstance.html#USER_ConnectToPostgreSQLInstance.psql) and connect to the database. This instance can be used only as needed and stopped when not needed to reduce EC2 costs.

From the EC2 Console, you can Connect to the instance.

![EC2Instance](/images/blog/RDS-EC2Instance.png)

### Secret Manager

In order to connect to the PostgreSQL database, you will need the `hostname`, `username`, and `password`. These have been automatically generated for you and stored in [AWS Secrets Manager](https://aws.amazon.com/secrets-manager/).

![SecretManger](/images/blog/RDS-SecretManager.png)

Once connected to the the EC2 Instance, using [AWS Session Manger](https://docs.aws.amazon.com/systems-manager/latest/userguide/session-manager.html) you can connect to the RDS database using `psql`.

```bash
psql -h host -p 5432 -U postgres postgres
```

In this example, replace `host` with the value from the Secrets.

![Secrets](/images/blog/RDS-Secrets.png)

At the prompt, enter the `password` from the Secrets.

### PostgreSQL Verification

From the prompt, verify that the table has been created:

```sql
\dt+
```

Output:

```bash
                      List of relations
 Schema |  Name   | Type  |  Owner   |  Size   | Description
--------+---------+-------+----------+---------+-------------
 public | queries | table | postgres | 0 bytes |
```

However, nothing has been created in the table yet:

```sql
SELECT * FROM queries;
```

Output:

```bash
 id | query_date
----+------------
(0 rows)
```

### Writing Data

To write data to the PostgreSQL database, you can wait for the EventBridge scheduled rule to trigger the AWS Lambda Function, or you can test the function manually. Once run, the AWS Lambda function should write a single record to the file that can be seen by using:

```SQL
SELECT * FROM queries;
```

With expected output similar to:

```bash
 id | query_date
----+------------
  1 | 2022-11-07
(1 row)
```

## Conclusion

Instructions for deploying this demo are available at the GitHub repo. Once deployed, you should now have an Amazon RDS database deployed to an isolated subnet that is able to be used by both an EC2 Instance and AWS Lambda function. This will allow you to update and interact with the PostgreSQL database while ensuring that it is in an isolated subnet. In future posts, we will explore how this database can be used with Amazon Quicksight to create customized reports and dashboards.


How to build a private RDS database and connect to it with an AWS Lambda function using AWS CDK.  

Using CDK to build an RDS database with AWS Lambda integration


Because GitHub will only provide stats for the previous 14 days, if we want to maintain long-term stats, we need to pull stats and store them. [PyGitHub](https://pypi.org/project/PyGithub/) is a useful Python library for doing that using the [GitHub API v3](https://docs.github.com/en/rest). This Python script will pull stats from queried repositories and store them in a CSV.

```python
import os
import csv
from github import Github

GITHUB_KEY = os.environ.get("POETRY_GITHUB_KEY")
g = Github(GITHUB_KEY)

with open("repos.csv", "w", newline="", encoding="utf-8") as csvfile:
    repo_writer = csv.writer(csvfile, delimiter=",")
    repo_writer.writerow([
      "Repo Name",
      "Repo Link",
      "Repo Pushed At",
      "Forks", "StarGazers",
      "Open Issues",
      "Security Alerts",
      "Open Pull Requests"])
    for repo in g.search_repositories(query="user:schuettc cdk"):
        repo_writer.writerow(
            [
                repo.name,
                repo.html_url,
                repo.pushed_at,
                repo.forks_count,
                repo.stargazers_count,
                repo.open_issues_count,
                repo.get_vulnerability_alert(),
                repo.get_pulls().totalCount,
            ]
        )
```

This script will query [GitHub](https://github.com) for [`user:schuettc cdk`](https://github.com/search?q=user%3Aschuettc+cdk&type=repositories). This query will return all GitHub repositories created by user [`schuettc`](https://github.com/schuettc) (me) with `cdk` in the repository name. The result will be used to create a CSV file that contains these repositories and various GitHub stats.

Be sure to create a [GitHub personal access token](https://docs.github.com/en/authentication/keeping-your-account-and-data-secure/creating-a-personal-access-token) with an appropriate scope and save as `POETRY_GITHUB_KEY` in a local `.env` file to use.

The result will be something like this:

![CSV](/images/blog/PyGithubRepos.png)

- GitHub repository: [pygithub-query-csv](https://github.com/schuettc/pygithub-query-csv)


If you need to modify the keys of a Python dictionary, a recursive function can be a useful way to work through the entire dictionary.  This [gist](https://gist.github.com/schuettc/3875da7458e3573646599e70b7b17a61) is an example of how to do that.

Using PyGitHub to Manage and Track GitHub Repositories


A twist on the previous [Recursively Modify Python Dictionary](recursively-modify-python-dictionary), this function will modify a Python dictionary to convert snake_case keys to PascalCase keys.

```python
def snake_to_PascalCase(d):
    for k, v in d.copy().items():
        if isinstance(v, dict):
            d.pop(k)
            d[k.title().replace("_", "")] = v
            snake_to_PascalCase(v)
        elif isinstance(v, list):
            d.pop(k)
            d[k.title().replace("_", "")] = v
            for i in v:
                v.remove(i)
                v.append(snake_to_PascalCase(i))
        else:
            d.pop(k)
            d[k.title().replace("_", "")] = v
    return d
```

- Gist: [snake_to_PascalCase.py](https://gist.github.com/schuettc/7f59c5faaf0609ca04a5dc04751960eb)


A twist on the previous [Recursively Modify Python Dictionary](/content/blog/recursively-modify-python-dictionary.md), this function will modify a Python dictionary to convert snake_case keys to PascalCase keys.

snake_to_PascalCase


[NextJS](https://nextjs.org/learn/foundations/about-nextjs/what-is-nextjs) is a powerful React framework that we can use to deploy directly from GitHub to [AWS Amplify](https://aws.amazon.com/amplify/). We will also be using [CodeSandbox](https://codesandbox.io/docs/overview) to work with the code before deploying.

[![amplifybutton](https://oneclick.amplifyapp.com/button.svg)](https://console.aws.amazon.com/amplify/home#/deploy?repo=https://github.com/schuettc/nextjs-ssr-with-amplify-deploy)

## Working with CodeSandbox

After creating the GitHub repo, we will [import the code](https://codesandbox.io/docs/importing#import-from-github) into a [CodeSandbox project](https://codesandbox.io/p/github/schuettc/nextjs-ssr-with-amplify-deploy/main?file=%2FREADME.md). This will allow us to work with and explore the code before deploying to our Amplify App.

### Creating AWS Credentials

Because this demo will use an [AWS SDK](https://aws.amazon.com/sdk-for-javascript/) request ([DescribeInstances](https://docs.aws.amazon.com/AWSEC2/latest/APIReference/API_DescribeInstances.html)), we will need to configure credentials that include permission to make this request. In order to do this, we will be creating a [User](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_users_create.html) and assigning it a [Role](https://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles.html). This Role should be limited in scope to only the Action that is required.

```json
{
  "Version": "2012-10-17",
  "Statement": [
    {
      "Sid": "DescribeInstances",
      "Effect": "Allow",
      "Action": "ec2:DescribeInstances",
      "Resource": "*"
    }
  ]
}
```

When this User is created, you will get an AWS_ACCESS_KEY_ID and AWS_SECRET_ACCESS_KEY. We will be using these to configure our application so that it has permissions to `DescribeInstances`.

### Adding AWS Credentials

After the AWS Credentials have been created, they must be added to the application. To do this with Code Sandbox, we will use [Environment Variables](https://codesandbox.io/docs/secrets) in our container. If you want to make changes, you will need to fork this project. When you do this, these environment variables will not be copied so you must use your own AWS Credentials.

![ConfigEnvVar](/images/blog/ConfigEnvVariables.png)

![EnvVariables](/images/blog/EnvVariables.png)

### Using the AWS SDK with Credentials

After configuring the Environment Variables in Code Sandbox, we can use the AWS SDK in the [pages/api/instances.js](https://github.com/schuettc/nextjs-ssr-with-amplify-deploy/blob/main/pages/api/instances.js) file.

```javascript
import { EC2Client, DescribeInstancesCommand } from '@aws-sdk/client-ec2';
const config = {
  region: 'us-east-1',
  credentials: {
    accessKeyId: process.env.ACCESS_KEY_ID,
    secretAccessKey: process.env.SECRET_ACCESS_KEY,
  },
};

const client = new EC2Client(config);
```

### next.config.js

To pass [Environment Variables to Amplify](https://docs.aws.amazon.com/amplify/latest/userguide/server-side-rendering-amplify.html#ssr-environment-variable-support), we need to modify the next.config.js file. We'll be adding these same Environment Variables to Amplify a little later.

```javascript
const withTranspileModules = require('next-transpile-modules');
const withPlugins = require('next-compose-plugins');

module.exports = withPlugins(
  [withTranspileModules(['@cloudscape-design/components'])],
  {
    env: {
      ACCESS_KEY_ID: process.env.ACCESS_KEY_ID,
      SECRET_ACCESS_KEY: process.env.SECRET_ACCESS_KEY,
    },
  },
);
```

### amplify.yml

To configure the build of the Amplify application, we include `amplify.yml` and instruct it to use Node version 16 as part of the build.

```yaml
version: 1
frontend:
  phases:
    preBuild:
      commands:
        - nvm use $VERSION_NODE_16
        - npm ci
    build:
      commands:
        - nvm use $VERSION_NODE_16
        - npm run build
  artifacts:
    baseDirectory: .next
    files:
      - '**/*'
  cache:
    paths:
      - node_modules/**/*
```

### Result

Now that we have our API configured with credentials, when the front end application uses this API, we will query the associated account for active instances in `us-east-1` and display them on a simple page. We can see these results live in our Code Sandbox now before we deploy to Amplify to ensure everything looks the way we want it.

![Result](/images/blog/Result.png)

## Deploying in AWS Amplify

In order to deploy to AWS Amplify, we will need to use the GitHub Apps feature to [authorize Amplify](https://docs.aws.amazon.com/amplify/latest/userguide/setting-up-GitHub-access.html) to read your GitHub repository.

### Begin Deploy

After clicking the above `Deploy to Amplify Console` link, you will begin the process of deploying to Amplify.

![Deploy](/images/blog/Deploy.png)

### Add Environment Variables

At the next screen, you will be able to add Environment Variables. Please note the additional Environment Variable needed in addition to your Access Key ID and Secret Access Key:

`AMPLIFY_NEXTJS_EXPERIMENTAL_TRACE` = `true`

![AddEnvVariables](/images/blog/AddEnvVariablesToAmplify.png)

### Deploying

Once added, the App will being deploying. This will fork the repository into your GitHub account and begin installing to Amplify.

![Deploying](/images/blog/Deploying.png)

### Deploy Failure

This first deploy should result in a failure to deploy that we will be fixing next.

![FailureToDeploy](/images/blog/DeployFailure.png)

## Finalizing Amplify Configuration

In order to [deploy an SSR Application on AWS Amplify](https://docs.aws.amazon.com/amplify/latest/userguide/server-side-rendering-amplify.html), we must add appropriate Service Role permissions to correct this error:

> Cannot find any generated SSR resources to deploy. If you intend for your app to be SSR, please check your app Service Role permissions. Otherwise, please check out our docs on how to setup your app to be detected as SSG (https://docs.aws.amazon.com/amplify/latest/userguide/server-side-rendering-amplify.html#deploy-nextjs-app)

### Add Service Role

In the App settings, select General and Edit. If there is no available Service role, you will need to create a new service role.

![ServiceRole](/images/blog/ServiceRole.png)

Follow the prompts to create a new Service Role, assign that role in the Amplify App settings, and then Save.

### Update Build Settings

Additionally, you should configure the Build image settings. In the App settings, select Build settings and Edit. Set the Next.js version to `latest` and the Node.js version to `14`. This will ensure the AWS Lambdas that are created as part of this application use Node version 14.

![UpdateBuildSettings](/images/blog/BuildSettings.png)

### Redeploy

Return to your App and select `Redeploy this version`

![Redeploy](/images/blog/Redeploy.png)

### Success!

Your app should now successfully deploy and can be accessed at the Domain shown in the console.

![Success](/images/blog/Success.png)

## Resources

- [GitHub Repository](https://github.com/schuettc/nextjs-ssr-with-amplify-deploy)
- [Code Sandbox Project](https://codesandbox.io/p/github/schuettc/nextjs-ssr-with-amplify-deploy/main)
- [Amplify One-Click Deploy](https://console.aws.amazon.com/amplify/home#/deploy?repo=https://github.com/schuettc/nextjs-ssr-with-amplify-deploy)


[NextJS](https://nextjs.org/learn/foundations/about-nextjs/what-is-nextjs) is a powerful React framework that we can use to deploy directly from GitHub to [AWS Amplify](https://aws.amazon.com/amplify/). We will also be using [CodeSandbox](https://codesandbox.io/docs/overview) to work with the code before deploying.

Deploying a NextJS SSR Application to Amplify


Creating an [AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) (Amazon Machine Image) can be done via the AWS Console. It can also be created via AWS CLI or SDKs. This CDK Construct will assist with the creation of an AMI as part of a [CDK](https://aws.amazon.com/cdk/) deployment.

This AMI can then be used in a complex deployment that requires a lengthy initial build but would need to be deployed quickly as part of a an [Auto-Scaling Group](https://docs.aws.amazon.com/autoscaling/ec2/userguide/auto-scaling-groups.html).

The included example will show how you can create an AMI after deploying an EC2 Instance and then create a new EC2 Instance using the created AMI to deploy more quickly. Keep and eye out here for future deployments that will include more complex examples of this CDK Construct.

## Background

From [Creating an AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html#creating-an-ami):

> You can launch an instance from an existing AMI, customize the instance (for example, [install software](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/install-software.html) on the instance), and then save this updated configuration as a custom AMI. Instances launched from this new custom AMI include the customizations that you made when you created the AMI.

This CDK Construct will assist in you creating that AMI for later use.

## Installing

To add to your AWS CDK package.json file:

```bash
yarn add cdk-create-ami
```

## How It Works

To create an image:

```ts
import * as ami from 'cdk-create-ami';
```

```ts
const amiImage = new ami.CreateAMI(this, 'amiImage', {
  instanceId: baseInstance.instanceId,
  deleteAmi: true,
  deleteInstance: true,
  blockDeviceMappings: [
    {
      deviceName: '/dev/sdh',
      ebs: {
        volumeSize: 20,
        volumeType: ami.VolumeType.GP3,
        deleteOnTermination: true,
      },
    },
  ],
  tagSpecifications: [
    {
      resourceType: ami.ResourceType.IMAGE,
      tags: [{ key: 'TagKey', value: 'TagValue' }],
    },
  ],
});
```

This will take an already created [Instance](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Instances.html) and convert it to an AMI. This process involves stopping the Instance and then creating the AMI. Besides typical AMI creation options regarding [block device mappings](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/block-device-mapping-concepts.html) and [tags](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/Using_Tags.html), the AMI can be created with two options:

```ts
      deleteAmi: true,
      deleteInstance: true,
```

- deleteAmi: When the CDK is destroyed, if this is set to `True`, the AMI will be deleted. Otherwise, the AMI will be retained.
- deleteInstance: When the CDK is deployed, if this is set to `True`, the base image will be deleted. Otherwise, the instance will be retained in a `Stopped` state.

## Example

The associated example includes two Stacks that can be created.

- AMIExample - Deploys Instance and creates AMI from Instance
- InstanceExample - Deploys Instance from previously created AMI

### AMI Example

```bash
cd example
yarn ami
```

This will deploy an Instance and create an AMI from the created Instance.

#### Creating the Instance

```ts
const vpc = new VPC(this, 'VPC');
const baseInstance = new BaseInstance(this, 'Instance', {
  vpc: vpc.vpc,
  securityGroup: vpc.securityGroup,
  ec2Role: vpc.ec2Role,
});
```

The example will create a VPC and Instance to be used to create the AMI. This instance contains a [cloud-init script](example/resources/base_install.sh):

```bash
HOMEDIR=/home/ec2-user
yum update -y
yum install net-tools -y
yum install wget -y

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`
LOCAL_HOSTNAME=$( curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/public-hostname )
INSTANCE_ID=$( curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/instance-id )

echo "AMI Hostname: $LOCAL_HOSTNAME" >> /home/ec2-user/config.txt
echo "AMI InstanceId: $INSTANCE_ID" >> /home/ec2-user/config.txt
```

This will result in a file: `/home/ec2-user/config.txt` that contains the base instance information. This fille will be retained in the AMI.

```bash
AMI Hostname: ec2-54-152-127-245.compute-1.amazonaws.com
AMI InstanceId: i-002aeb6cdde92c9b5
```

#### SSM

The AMI information will be stored in AWS Systems Manager - Parameter Store

![CDK-Create-AMI-SSM](/images/blog/SSM.png)

### Instance Example

Once the AMI has been created, that AMI can be used to create a new Instance that has been pre-configured.

```bash
yarn instance imageId=IMAGEID
```

The IMAGEID to be used is provided as output from the AMI Example Stack.

This AMI Image ID is retrieved by the CDK:

```ts
const customAmi = new ec2.GenericSSMParameterImage(
  '/createAMI/' + props.imageId,
  ec2.OperatingSystemType.LINUX,
);
```

This AMI Image ID is used to create the new Instance:

```ts
const ec2Instance = new ec2.Instance(this, 'Instance', {
  vpc: props.vpc,
  instanceType: ec2.InstanceType.of(
    ec2.InstanceClass.T4G,
    ec2.InstanceSize.MEDIUM,
  ),
  machineImage: customAmi,
  // More Instance configuration here
});
```

This instance contains a [cloud-init script](example/resources/new_install.sh):

```bash
HOMEDIR=/home/ec2-user

TOKEN=`curl -X PUT "http://169.254.169.254/latest/api/token" -H "X-aws-ec2-metadata-token-ttl-seconds: 21600"`
LOCAL_HOSTNAME=$( curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/public-hostname )
INSTANCE_ID=$( curl -H "X-aws-ec2-metadata-token: $TOKEN" -v http://169.254.169.254/latest/meta-data/instance-id )

echo "New Instance Hostname: $LOCAL_HOSTNAME" >> /home/ec2-user/config.txt
echo "New Instance InstanceId: $INSTANCE_ID" >> /home/ec2-user/config.txt
```

Because the Instance used to create the AMI has already updated and installed packages, these do not need to be run again. Instead, the new Instance Hostname and InstanceId will be copied to the existing `/home/ec2-user/config.txt` file.

```bash
AMI Hostname: ec2-54-152-127-245.compute-1.amazonaws.com
AMI InstanceId: i-002aeb6cdde92c9b5
New Instance Hostname: ec2-54-242-5-47.compute-1.amazonaws.com
New Instance InstanceId: i-0e67014a77d5d1995
```


Creating an [AMI](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html) (Amazon Machine Image) can be done via the AWS Console.  It can also be created via AWS CLI or SDKs.  This CDK Construct will assist with the creation of an AMI as part of a [CDK](https://aws.amazon.com/cdk/) deployment.

Create AMI CDK Construct


If you need to modify the keys of a Python dictionary, a recursive function can be a useful way to work through the entire dictionary. This [gist](https://gist.github.com/schuettc/3875da7458e3573646599e70b7b17a61) is an example of how to do that.

```python
def capitalize_keys(d):
    for k, v in d.copy().items():
        if isinstance(v, dict):
            d.pop(k)
            d[f"{k[0].upper() +k[1:]}"] = v
            capitalize_keys(v)
        else:
            d.pop(k)
            d[f"{k[0].upper() +k[1:]}"] = v
    return d
```

Each iteration through the function will look at the Value (v) and determine if it is a dict. If it is, the Key (k) will be removed and replaced with a capitalized version of the Key. Then, because we know the Value is a dict, the function will be called again with the Value as the input. If the Value is not a dict, we have reached the end of the dict and don't need to recurse again.

Other data manipulations can be made on the JSON object through these recursions as well.

For instance:

```python
def capitalize_keys(d):
    for k, v in d.copy().items():
        if isinstance(v, dict):
            d.pop(k)
            d[f"{k[0].upper() +k[1:]}"] = v
            capitalize_keys(v)
        else:
            if k == "keyToChange":
                v = int(v)
            d.pop(k)
            d[f"{k[0].upper() +k[1:]}"] = v
    return d
```

In this example, the Value (v) of the Key (k) 'keyToChange' will be changed from a `string` to an `int`.

An example dictionary that has been processed:

```json
[
  {
    appName: 'Capitalize',
    resources: {
      url: 'example.com',
      file: 'file.txt',
    },
  },
];
```

Result:

```json
[
  {
    AppName: 'Capitalize',
    Resources: {
      Url: 'example.com',
      File: 'file.txt',
    },
  },
];
```


Recursively Modify Python Dictionary


To add on to the previous [article](https://subaud.io/importing-an-amazon-lex-bot-with-cdk/) that described how to import an Amazon Lex Bot with CDK, I have created a [CDK Construct](https://constructs.dev/packages/cdk-lex-zip-import/v/0.0.4?lang=typescript) that you can import and use in your own CDK projects.

To add this to your CDK project, simply import the Construct:

```bash
yarn add cdk-lex-zip-import
```

Within your CDK:

```typescript
const bot = new lexupload.ImportBot(this, 'lexBot', {
  sourceDirectory: './resources/LexBot',
  lexRoleArn: lexRole.roleArn,
});
```

The `sourceDirectory` must include a file named `LexBot.zip`. This file will be uploaded to an S3 Bucket and then imported using a Lambda backed Custom Resource.

Additionally, a Resource Policy can be applied to the Alias once it is imported.

```typescript
bot.addResourcePolicy(resourceArn, policy);
```

A complete example might look like this:

```typescript
import { Stack, StackProps } from 'aws-cdk-lib';
import * as iam from 'aws-cdk-lib/aws-iam';
import * as lexupload from 'cdk-lex-zip-import';
import { Construct } from 'constructs';

export class MyStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps = {}) {
    super(scope, id, props);

    const lexRole = new iam.Role(this, 'lexRole', {
      assumedBy: new iam.ServicePrincipal('lex.amazonaws.com'),
      inlinePolicies: {
        ['lexPolicy']: new iam.PolicyDocument({
          statements: [
            new iam.PolicyStatement({
              resources: ['*'],
              actions: ['polly:SynthesizeSpeech', 'comprehend:DetectSentiment'],
            }),
          ],
        }),
      },
    });

    const bot = new lexupload.ImportBot(this, 'lexBot', {
      sourceDirectory: './resources/LexBot',
      lexRoleArn: lexRole.roleArn,
    });

    const resourceArn = `arn:aws:lex:${this.region}:${this.account}:bot-alias/${bot.botId}/${bot.botAliasId}`;
    const policy = {
      Version: '2012-10-17',
      Statement: [
        {
          Sid: 'AllowChimePstnAudioUseBot',
          Effect: 'Allow',
          Principal: { Service: 'voiceconnector.chime.amazonaws.com' },
          Action: 'lex:StartConversation',
          Resource: resourceArn,
          Condition: {
            StringEquals: { 'AWS:SourceAccount': `${this.account}` },
            ArnEquals: {
              'AWS:SourceArn': `arn:aws:voiceconnector:us-east-1:${this.account}:*`,
            },
          },
        },
      ],
    };
    bot.addResourcePolicy(resourceArn, policy);
  }
}
```

For more information or to contribute, please see the [GitHub repo](https://github.com/schuettc/cdk-lex-zip-import).


To add on to the previous [article](https://subaud.io/importing-an-amazon-lex-bot-with-cdk/) that described how to import an Amazon Lex Bot with CDK, I have created a [CDK Construct](https://constructs.dev/packages/cdk-lex-zip-import/v/0.0.4?lang=typescript) that you can import and use in your own CDK projects.

A CDK Construct for Importing Amazon Lex Bots


Amazon Lex Bots are a way to use natural language conversational interfaces that can be used through a variety of integrations such as Facebook and Slack. A Lex Bot can be built and deployed through the AWS console. However, it can also be deployed by CDK, Cloudformation, or SDK. In this post, I will explain how to import an existing Lex Bot using CDK and SDK.

![LexBot](/images/blog/Directory.png)

After cloning [this repo](https://github.com/schuettc/cdk-lex-import), you will see a zipped LexBot in the `resources` directory. As part of the CDK, this file will be copied up with the Lex import Lambda. You can replace this Zip file with a Lex Bot of your choosing.

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

const uid: string = Names.uniqueId(this);

const LexResourceProvider = new cr.Provider(this, 'LexResourceProvider', {
  onEventHandler: lexDeployLambda,
});

const lexBot = new CustomResource(this, 'LexCustomResource', {
  serviceToken: LexResourceProvider.serviceToken,
  properties: { uid: uid, lex_role_arn: lexRole.roleArn },
});
```

While the CDK is being deployed, the Custom Resource Lambda will be triggered with a `Create` RequestType. This will cause the Lambda to begin the process of importing the bot.

```python
def create_bot(bot_name, lex_role_arn, account_id):
    response_data = {}
    upload_info = lex.create_upload_url()
    upload_bot(upload_info)
    import_bot(bot_name, upload_info["importId"], lex_role_arn)
    bot_id = get_bot_id(bot_name)
    bot_alias_id = get_bot_alias_id(bot_id)
    put_resource_policy(bot_id, bot_alias_id, account_id)
    build_bot(bot_id)
    response_data["bot_id"] = bot_id
    response_data["bot_alias_id"] = bot_alias_id
    return response_data
```

There are multiple steps required to import and build a Lex bot. This function will work through each of those.

The first step is to create a URL that will be used as part of the import. This is done with a single lexv2-models API call:

```python
upload_info = lex.create_upload_url()
```

Once this URL is created, it is passed to the upload_bot function and the `LexBot.zip` file is uploaded to the specified URL.

```python
def upload_bot(upload_info):
    http = urllib3.PoolManager()
    try:
        with open("LexBot.zip", mode="rb") as bot:
            file_data = bot.read()

    except Exception as e:
        error = {"error": f"Exception thrown: {e}"}
        print(error)
        raise Exception(error)
    try:
        upload = http.request(
            "PUT", upload_info["uploadUrl"], body=file_data, headers={"Content-Type": "application/zip"}
        )

    except Exception as e:
        error = {"error": f"Exception thrown: {e}"}
        print(error)
        raise Exception(error)
    logger.info(upload.data.decode("utf-8"))
    return upload
```

Once uploaded to S3, the bot must be imported.

```python
def import_bot(bot_name, import_id, lex_role_arn):
    bot_import_result = lex.start_import(
        importId=import_id,
        resourceSpecification={
            "botImportSpecification": {
                "botName": bot_name,
                "roleArn": lex_role_arn,
                "dataPrivacy": {"childDirected": False},
                "idleSessionTTLInSeconds": 600,
            },
        },
        mergeStrategy="Overwrite",
    )
    logger.info(bot_import_result)
    return bot_import_result
```

If a Resource Policy is required for your Bot, it can be added with the `put_resource_policy` function also included. The Bot will then be built and is now ready for use.

Once the Lambda has completed importing the Bot to Lex, it will return the bot_id and bot_alias_id to the CDK.

Once the Lex bot has been imported, it can be tested in the Lex console.

![LexTest](/images/blog/LexTest.png)

### Resources

- [GitHub Repo](https://github.com/schuettc/cdk-lex-import)
- [Amazon Lex](https://aws.amazon.com/lex/)
- [Boto3 - Lexv2-Models](https://boto3.amazonaws.com/v1/documentation/api/latest/reference/services/lexv2-models.html)


Amazon Lex Bots are a way to use natural language conversational interfaces that can be used through a variety of integrations such as Facebook and Slack.  A Lex Bot can be built and deployed through the AWS console.  However, it can also be deployed by CDK, Cloudformation, or SDK.  In this post, I will explain how to import an existing Lex Bot using CDK and SDK.

Importing an Amazon Lex Bot with CDK


## Full Stack CDK Example

This example will build a CDK Pipeline that will build a backend and frontend and then pass API Gateway URL information from the backend to the frontend. This information can be used to make calls to the backend without having to manually pass the URL information. When connected to a Github repo, the CDK pipeline will automatically trigger and rebuild so changes to any portion of the app through GitHub.

**Please note: this deployment will create a file that will be accessible to the public so sensitive information should not be included. **

![Full Stack App Overview](/images/Pipeline.png)

### CDK Pipeline

The pipeline created is a self-mutating pipeline associated with a GitHub repo using a CodeStar connection. This can be adjusted to other Pipeline [sources](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.pipelines-readme.html#synth-and-sources).

This pipeline contains a single Stage with three Stacks.

```typescript
    const pipeline = new pipelines.CodePipeline(this, 'Pipeline', {
      ...
    });

    const stages = new Stages(this, 'Stages', {});
    pipeline.addStage(stages);
```

### Backend Stack

```typescript
export class Backend extends Stack {
  public readonly config: Object;

  constructor(scope: Construct, id: string, props?: StackProps) {
    super(scope, id, props);
    ...
    this.config = {
      API_URL: api.url,
    };
  }
}
```

The Backend stack creates a sample Lambda function and associates it with an API Gateway. The URL from this API Gateway is used as the output in a JSON Object that will be used in the Config Stack.

### Frontend Stack

The Frontend Stack is a simple S3 + Cloudfront Distribution that will be used to host a React SPA. Before uploading to the S3 bucket with `s3deploy.BucketDeployment` it must be bundled. The output of this `yarn build` will be copied to the outputDir and deployed to the S3 bucket.

```typescript
const bundle = s3deploy.Source.asset('./site', {
  bundling: {
    command: [
      'sh',
      '-c',
      'echo "Docker build not supported. Please install esbuild."',
    ],
    image: DockerImage.fromRegistry('alpine'),
    local: {
      tryBundle(outputDir: string) {
        try {
          execSync('esbuild --version', execOptions);
        } catch {
          /* istanbul ignore next */
          return false;
        }
        execSync(
          'cd site && yarn install --frozen-lockfile && yarn build',
          execOptions,
        );
        copySync('./site/build', outputDir, {
          ...execOptions,
          recursive: true,
        });
        return true;
      },
    },
  },
});
```

### Config Stack

The Config stack creates a `config.json` file in the S3 bucket that was created in the Frontend Stack with the API URL information from the Backend Stack using a CustomResource.

```typescript
new customresource.AwsCustomResource(this, 'ConfigFrontEnd', {
  onUpdate: {
    service: 'S3',
    action: 'putObject',
    parameters: {
      Body: JSON.stringify(props.config),
      Bucket: props.siteBucket.bucketName,
      Key: 'config.json',
    },
    physicalResourceId: customresource.PhysicalResourceId.of(
      Date.now().toString(),
    ),
  },
  policy: customresource.AwsCustomResourcePolicy.fromSdkCalls({
    resources: customresource.AwsCustomResourcePolicy.ANY_RESOURCE,
  }),
});
```

### React App

With the Backend and Frontend created, the React App deployed to the S3 bucket must read the `config.json` file that was created in the Config Stack. It is very important to note that this file is publicly visible so you should not put any sensitive information in it. Another [method](https://docs.aws.amazon.com/apigateway/latest/developerguide/apigateway-control-access-to-api.html) should be used to secure your API Gateway.

```javascript
export async function config() {
  const data = await fetch('./config.json').then((response) => response.json());

  const AmplifyConfig = {
    API: {
      endpoints: [
        {
          name: 'demoApi',
          endpoint: data.API_URL,
        },
      ],
    },
  };

  return AmplifyConfig;
```

The `Config.js` file is used to fetch the information in the `config.json` file that was written to the S3 bucket by the Config Stack. To use this locally, this file must be copied to the `src/site/public` directory.

```javascript
const apiConfig = await config();
API.configure(apiConfig);
const randomNumberResult = await API.post('demoApi', 'demo', {
  body: {},
});
setRandomNumber(randomNumberResult);
```

The React App uses Amplify to make API calls using the API information from the `Config.js` file. This could be enhanced with Cognito to provide API Gateway security.

Complete demo [here](https://github.com/schuettc/full-stack-cdk-example).


This example will build a CDK Pipeline that will build a backend and frontend and then pass API Gateway URL information from the backend to the frontend. This information can be used to make calls to the backend without having to manually pass the URL information.  When connected to a Github repo, the CDK pipeline will automatically trigger and rebuild so changes to any portion of the app through GitHub.

Creating a Full Stack App with CDK Pipelines


### Overview

![EC2](/images/blog/Example-EC2.png)

Cloud-init is a powerful way of configuring an EC2 instance. CDK can create an EC2 instance and use cloud-init to pass dynamically created variables to this EC2 instance which can be used to configure the instance. When combined, these tools can be used to create fully configured and deployed dynamic EC2 instances.

[This GitHub repo](https://github.com/schuettc/cdk-ec2-example) will deploy an EC2 instance using CDK. This EC2 instance will download and install [Asterisk 18](https://wiki.asterisk.org/wiki/display/AST/Asterisk+18+Documentation) on the EC2 instance. Additionally, it will create a `pjsip.conf` file and configure that using the Elastic IP address created by the CDK.

Once the Elastic IP is created, by the CDK, it is passed to the EC2 Instance using cloud-init:

```ts
      init: ec2.CloudFormationInit.fromConfigSets({
        configSets: {
          default: ['install', 'config'],
        },
        configs: {
          install: new ec2.InitConfig([
            ec2.InitFile.fromObject('/etc/config.json', {
              IP: ec2Eip.ref,
            }),
```

This file will be stored on the newly created instance based on resources created by the CDK. In this example, the Elastic IP address is passed to the JSON object. This information can also be [queried with metadata](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/instancedata-data-retrieval.html), but is used in this example as information that can be dynamically created by the CDK and passed to the EC2 Instance.

Files can be loaded to the EC2 instance from [multiple sources](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_ec2.InitSource.html). In this example, we are loading a bash script from the local deployment of the CDK and executing it on the EC2 instance. This cloud-init configuration in the CDK will load the [`install.sh`](https://github.com/schuettc/cdk-ec2-example/blob/main/src/asteriskConfig/install.sh) file from the `./src/asteriskConfig/` directory into the `/etc/` directory of the Instance and then execute it.

```ts
            ec2.InitFile.fromFileInline(
              '/etc/install.sh',
              './src/asteriskConfig/install.sh',
            ),
            ec2.InitCommand.shellCommand('chmod +x /etc/install.sh'),
            ec2.InitCommand.shellCommand('cd /tmp'),
            ec2.InitCommand.shellCommand('/etc/install.sh'),
          ]),
```

The example script will download and install an Asterisk PBX on to the EC2 instance. Additional files are included in the GitHub repo that are used to more fully configure the Asterisk server using `jq` and `sed` with the information passed to the Instance from the CDK:

```bash
IP=$( jq -r '.IP' /etc/config.json )

sed -i "s/IP_ADDRESS/$IP/g" /etc/asterisk/pjsip.conf
```

[initOptions](https://docs.aws.amazon.com/cdk/api/v2//docs/aws-cdk-lib.aws_ec2.ApplyCloudFormationInitOptions.html) can also be used to ensure that the configuration of the EC2 instance succeeds.

```json
      initOptions: {
        timeout: Duration.minutes(15),
      },
```

If the timeout fails or the Instance returns a failure, the CDK will roll back to the previous state. When the cloud-init configuration of the Instance succeeds, it will pass this information back to the CDK. Until then, the CDK will remain in a Creating state and will not progress. This is useful when you want to ensure that the build and configuration of the EC2 instance succeeds before deploying additional resources with the CDK.

More details are provided in the [GitHub repo](https://github.com/schuettc/cdk-ec2-example).


Cloud-init is a powerful way of configuring an EC2 instance. CDK can create an EC2 instance and use cloud-init to pass dynamically created variables to this EC2 instance which can be used to configure the instance.  When combined, these tools can be used to create fully configured and deployed dynamic EC2 instances.

Building an EC2 Instance with CDKv2 and Cloud-Init


> 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)


Building CDK Custom Resource Constructs with projen and Typescript


Managing multiple AWS accounts with AWS CLI can be a challenge. Here is how I set up my macOS terminal. This configuration will set up a terminal shell that will show your AWS account and git information in the prompt. The example provided includes access key and SSO with MFA logins.

- Install [iTerm2](https://iterm2.com/)
- Install [Oh My Zsh](https://ohmyz.sh/#install)
- Install [Powerline Fonts](https://github.com/powerline/fonts)
- Install [AWS CLI v2](https://docs.aws.amazon.com/cli/latest/userguide/getting-started-install.html)
- Configure [Command Completion for AWS CLI](https://docs.aws.amazon.com/cli/latest/userguide/cli-configure-completion.html#cli-command-completion-linux)
- Install [git](https://github.com/git-guides/install-git#install-git-on-mac)
- Install [fig](https://fig.io/)

### Configure Oh My Zsh - ~/.zshrc

```bash
ZSH_THEME="agnoster"
plugins=(git aws)
```

### Configure agnoster - ~/.oh-my-zsh/themes/agnoster.zsh-theme

This will remove the context from the prompt to shrink it down a little and add a right prompt with the current date/time. These are optional and can be customized to your preference.

```bash
#  prompt_context
RPROMPT="[%D{%y/%m/%f}|%@]"
```

### Configure iTerm Profile

```bash
Preferences -> Profile -> Text -> Font: Any of the Powerline Fonts
Preferences -> Profile -> Colors -> Color Presets: Solarized Dark
```

### Configure AWS Config - ~/.aws/config

This is a sample config file that shows how to use an account with and without SSO.

```text
[profile account1]
region=us-east-1
output=json

[profile account2]
region = us-east-1
output = json
sso_start_url = https://xxxxxxxxxxxxx.awsapps.com/start
sso_region = us-east-1
sso_account_id = 123456789012
sso_role_name = ROLE
```

### Configure AWS Credentials - ~/.aws/credentials

Because the SSO account will acquire credentials during the login process, it is not needed here.

```text
[account1]
aws_access_key_id=XXXXXXXXXXXXX
aws_secret_access_key=XXXXXXXXXXXXXXXXXXXXXXXXX
```

### Using aws plugin

The Oh My Zsh aws plugin will allow you to easily switch between accounts.

- Switch to account without SSO: `asp account1`
- Switch to account with SSO and MFA: `asp account2 login`
- Clear account: `asp`

### Empty profile

It can be useful to have an empty profile that is used with exported `AWS_ACCESS_KEY_ID`, `AWS_SECRET_ACCESS_KEY`, and `AWS_SESSION_TOKEN` information. To create a profile using AWS CLI:

```bash
aws configure set profile.PROFILE_NAME.region us-east-1
aws configure set profile.PROFILE_NAME.output json
aws configure set profile.PROFILE_NAME.aws_access_key_id ''
aws configure set profile.PROFILE_NAME.aws_secret_access_key ''
aws configure set profile.PROFILE_NAME.aws_session_token ''
```

## Configured Result

![Configured Shell](/images/blog/shell.png)


Managing multiple AWS accounts with AWS CLI can be a challenge.  Here is how I set up my macOS terminal.  This configuration will set up a terminal shell that will show your AWS account and git information in the prompt.  The example provided includes access key and SSO with MFA logins.

Setting up a shell for multiple AWS accounts


When building ARM64 resources with CDK Pipelines, it is necessary to have them built using an ARM64 Image with CodeBuild. Otherwise, you will get an error like this during the Synth action:

`[Warning] The requested image's platform (linux/arm64/v8) does not match the detected host platform (linux/amd64) and no specific platform was requested`

To ensure that the image used is an arm64/v8 image, the Typescript code should look like this:

```typescript
const cdkPipeline = new pipelines.CodePipeline(this, 'Pipeline', {
  selfMutation: true,
  dockerEnabledForSelfMutation: true,
  dockerEnabledForSynth: true,
  synth: new pipelines.ShellStep('Synth', {
    input: pipelines.CodePipelineSource.connection(
      'repo/cdk-pipeline-deployment',
      'main',
      {
        connectionArn:
          'arn:aws:codestar-connections:us-east-2:xxxxxxxxxxx:connection/xxxxxxx-7d1c-453c-xxxx-1c73586de313',
      },
    ),
    commands: ['npm ci', 'npm run build', 'npx cdk synth'],
  }),
  synthCodeBuildDefaults: {
    buildEnvironment: {
      computeType: codebuild.ComputeType.LARGE,
      buildImage: codebuild.LinuxBuildImage.AMAZON_LINUX_2_ARM,
    },
  },
  assetPublishingCodeBuildDefaults: {},
  selfMutationCodeBuildDefaults: {},
  codeBuildDefaults: {},
});
```

At this point, Stages can be added with :

`cdkPipeline.addStage(...)`

This is a self-mutating build. However, if you add the Stage with ARM64 resources before adding the synthCodeBuildDefaults, it will fail. To mutate the pipeline to allow the Stage to be built, remove the Stage, add the buildEnvironment parameters, rebuild the pipeline, add the Stage back, and rebuild the pipeline again. Now this pipeline should use the correct image when building the ARM64 resources.


When building ARM64 resources with CDK Pipelines, it is necessary to have them built using an ARM64 Image with CodeBuild.  

Building ARM64 Infrastructure with CDK Pipelines


'Simple bash script to download and compile [SIPp](https://github.com/SIPp/sipp.git) on an Amazon Linux 2 instance. This can take a while to build because of the cmake dependency.'

```bash
yum groupinstall "Development Tools" -y
yum install ncurses-compat-libs ncurses-devel sudo wget openssl-devel pcap libpcap-devel libnet gsl -y
pushd /tmp
wget https://cmake.org/files/v3.18/cmake-3.18.0.tar.gz
tar -xvzf cmake-3.18.0.tar.gz
cd cmake-3.18.0
./bootstrap
make
sudo make install
popd
git clone https://github.com/SIPp/sipp.git
cd sipp
/usr/local/bin/cmake . -DUSE_PCAP=1 -DUSE_GSL=1
make
```


Simple bash script to download and compile [SIPp](https://github.com/SIPp/sipp.git) on an Amazon Linux 2 instance.  This can take a while to build because of the cmake dependency.

Installing SIPp on Amazon Linux 2 Instance


This simple script will look through a bucket to find all objects that match a `LastModified` date and delete. This can be adjusted to delete objects before, after, or matching the date specified. Use at your own risk.

```python
import boto3
from datetime import datetime, timezone

s3 = boto3.client("s3")
bucket = "INSERT_BUCKET_NAME"
paginator = s3.get_paginator("list_objects_v2")
pages = paginator.paginate(Bucket=bucket)
date_check = datetime(2021, 11, 1)

keys_to_delete = []
for page in pages:
    for object in page["Contents"]:
        if object["LastModified"] > date_check.replace(tzinfo=timezone.utc):
            keys_to_delete.append({"Key": object["Key"]})

s3.delete_objects(Bucket=bucket, Delete={"Objects": keys_to_delete})
```

Gist [here](https://gist.github.com/schuettc/83c2ef71b5604eff69d1248553a8ef2c).


This simple script will look through a bucket to find all objects that match a `LastModified` date and delete.  This can be adjusted to delete objects before, after, or matching the date specified.  Use at your own risk.

Bulk Delete S3 Objects by LastModified Date


Previously, we looked at how to use CDK Pipelines to create a [full stack deployment](https://subaud.io/creating-a-full-stack-app-with-cdk-pipeline/). This deployment used multiple Cloudformation stacks to create a front-end and back-end. This example will show a similar process, but uses a new technique that will allow us to use a single stack to deploy both front-end and back-end while still maintaining the ability to work on the front-end locally.

```typescript
export class SingleStackFullStack extends Stack {
  constructor(scope: Construct, id: string, props: StackProps = {}) {
    super(scope, id, props);
    const infrastructure = new Infrastructure(this, 'infrastructure');

    const site = new Site(this, 'Site', { apiUrl: infrastructure.apiUrl });
  }
}
```

The entry point to the CDK simply calls two separate Constructs. In this case, we are creating the back-end with the `infrastructure` Construct and the front-end with the `site` Construct. The `infrastructure` Construct contains an API Gateway that we will be using to invoke a Lambda function. The URL of this API Gateway will be passed to `site` Construct as a prop to be used there.

```typescript
const exampleLambda = new NodejsFunction(this, 'meetingLambda', {
  entry: 'resources/index.ts',
  bundling: {
    nodeModules: ['aws-lambda'],
  },
  handler: 'lambdaHandler',
  runtime: Runtime.NODEJS_16_X,
  architecture: Architecture.ARM_64,
  role: infrastructureRole,
  timeout: Duration.seconds(60),
  environment: {
    MEETINGS_TABLE: exampleTable.tableName,
  },
});
```

The Lambda function used in the back-end uses Typescript code and is built using the [NodejsFunction Construct](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_lambda_nodejs.NodejsFunction.html). This will use `esbuild` to transpile the Typescript code into Javascript to be run in the NodeJS Lambda function.

---

The front-end Construct will use a typical S3 Bucket + Cloudfront distribution to create a static website built from a React application.

The deployment to the S3 bucket will consist of two components: a production built version of the React application and JSON file with the URL from the API Gateway.

```typescript
const config = {
  apiUrl: props.apiUrl,
};

new BucketDeployment(this, 'DeployBucket', {
  sources: [bundle, Source.jsonData('config.json', config)],
  destinationBucket: this.siteBucket,
  distribution: this.distribution,
  distributionPaths: ['/*'],
});
```

The deployment uses [`Source.jsonData`](https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.aws_s3_deployment.Source.html#static-jsonwbrdataobjectkey-obj) to capture deploy-time values before it creates the key containing the JSON data in the S3 bucket. This allows us to create the API Gateway and pass the URL of this API Gateway to the S3 bucket as a JSON file in a single stack.

---

This JSON file will be read by the front-end React application in the [`Config.js`](https://github.com/schuettc/single-stack-full-stack-example/blob/main/site/src/Config.js) file:

```javascript
const config = await fetch('./config.json').then((response) => response.json());

export const AmplifyConfig = {
  API: {
    endpoints: [
      {
        name: 'exampleApi',
        endpoint: config.apiUrl,
      },
    ],
  },
};
```

To allow for a top level await, be sure to enable it in the [`webpack.config.js`](https://github.com/schuettc/single-stack-full-stack-example/blob/bf6fd9b7ac310a19a5f6ae5382316da37e708b6f/site/webpack.config.js#L61-L63) file:

```javascript
    experiments: {
        topLevelAwait: true,
    },
```

Within [`App.js`](https://github.com/schuettc/single-stack-full-stack-example/blob/main/site/src/App.js) this will be used to configure Amplify:

```javascript
import { AmplifyConfig as config } from './Config';
import { Amplify, API } from 'aws-amplify';
Amplify.configure(config);
```

This will be used to POST to the API Gateway to invoke the Lambda function and get the response.

```javascript
useEffect(() => {
  const fetchData = async () => {
    const exampleResponse = await API.post('exampleApi', 'example', {});
    console.log(exampleResponse);
    setHelloWorld(exampleResponse.message);
  };

  fetchData().catch(console.error);
}, []);
```

---

Additionally, working on the the React application locally is possible by copying the `config.json` from the S3 bucket to the local directory for use with `yarn run start`.

Creating additional `package.json` scripts with Projen can be done using `project.addTask`. This example uses a script to make deployments easy:

```javascript
project.addTask('launch', {
  exec: 'yarn && yarn projen && yarn build && yarn cdk bootstrap && yarn cdk deploy --hotswap && yarn configLocal',
});
```

This script will build and deploy the included CDK as well as download the `config.json` file for use locally using the `configLocal` script.

The `configlocal` script will download the `config.json` from the S3 bucket and copy to the appropriate local directory.

```javascript
project.addTask('getBucket', {
  exec: "aws cloudformation describe-stacks --stack-name single-stack-full-stack-example-dev --query 'Stacks[0].Outputs[?OutputKey==`siteBucket`].OutputValue' --output text",
});

project.addTask('configLocal', {
  exec: 'aws s3 cp s3://$(yarn run --silent getBucket)/config.json site/public/',
});
```

---

The result of this CDK is a fully built and deployed front-end and back-end React application that is hosted but can also be worked on locally.

The full code is available here: [https://github.com/schuettc/single-stack-full-stack-example](https://github.com/schuettc/single-stack-full-stack-example)


Previously, we looked at how to use CDK Pipelines to create a [full stack deployment](https://subaud.io/creating-a-full-stack-app-with-cdk-pipeline/).  This deployment used multiple Cloudformation stacks to create a front-end and back-end.  This example will show a similar process, but uses a new technique that will allow us to use a single stack to deploy both front-end and back-end while still maintaining the ability to work on the front-end locally.