
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


# 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


# 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