Forem: Matt Martz

Supercharging a Serverless Slackbot with Amazon Bedrock

Matt Martz — Tue, 07 Nov 2023 13:30:50 +0000

In the dynamic world of software development, staying abreast of changes and deployments is crucial for team collaboration and efficiency. In my previous post, From Code to Conversation: Bridging GitHub Actions and Slack with CDK, I introduced a solution that used AWS Cloud Development Kit (CDK) to deploy a Lambda and DynamoDB-powered Slack App that gave teams push-button deployments between environments from Slack. Building on that foundation, this follow-up article delves into a significant enhancement the integration of Amazon Bedrock, AWS's generative AI service, to revolutionize how we handle commit logs and release summaries.

The updated Deployer Bot is not just smarter; it's designed to be more responsive and informative by utilizing an event-driven architecture that streamlines notifications and summaries. By tapping into the power of generative AI, the bot now offers concise, human-readable summaries of commits and release notes, making it easier for teams to grasp the impact of their work at a glance.

As an example... When I added this to my team's internal Slack Bot (based on the previous post's work). Bedrock provided this commit summary: "The commit enables the bot to summarize code changes and releases using AI via AWS Bedrock, including analyzing commits for risks and generating release prep recommendations between environments.". My commit message was only "bedrock... not handling brext w/ios though". 🤯

Commits trigger webhooks that flow through a series of AWS Lambda functions, orchestrating the process from commit tracking to AI-powered summarization, culminating in neatly packaged per-environment releases communicated via Slack. As part of the commit analysis and summarization, we get results like this on a completed deployment:

In this article, we'll explore the rationale behind each architectural decision, the process of incorporating Amazon Bedrock into our bot, and the benefits that an event-driven model brings to our CI/CD pipelines. For the DevOps enthusiasts and the code-curious alike, the complete codebase is accessible on GitHub at https://github.com/martzcodes/blog-cicd-bedrock-releases.

A quick note on costs: Amazon Bedrock and the models they run are NOT free. In my case, I've restricted the analysis to a limit of 10000 "tokens" so the max cost of processing a large commit or release for my case is about $0.10 - $0.20. Claude's upper token limit is 100k tokens which would have a max cost of $1-2 per model invocation.

Revamping the Architecture: Embracing Event-Driven Design

The transformation of the Deployer Bots architecture to an event-driven model marks a significant enhancement from its original design. This section will explore the rationale behind adopting an event-driven approach, the benefits it offers, and how it is implemented within the context of the Deployer Bot integrated with Amazon Bedrock for AI-powered commit summarization and release management.

Understanding Event-Driven Architecture (EDA)

Event-Driven Architecture (EDA) is a design paradigm centered around the production, detection, consumption, and reaction to events. An event is any significant state change that is of interest to a system or component. EDA allows for highly reactive systems that are more flexible, scalable, and capable of handling complex workflows. It is particularly well-suited for asynchronous data flow and microservices patterns, often found in cloud-native environments.

Why Event-Driven?

The original Deployer Bot followed a more traditional request/response model, where actions were triggered by direct requests. While functional, this approach had limitations in terms of scalability and real-time responsiveness. The integration of Amazon Bedrock and the necessity to process and summarize commit data presented an opportunity to redesign the architecture to be more reactive and efficient.

Benefits of Event-Driven Architecture

Scalability : EDA allows each component to operate independently, scaling up or down as needed without impacting the entire system.
Resilience : The decoupled nature of services in EDA results in a system that is less prone to failures. If one service goes down, the rest can continue to operate.
Real-Time Processing : Events can be processed as soon as they occur, providing immediate feedback and actions, which is crucial for CI/CD workflows.
Flexibility : New event consumers can be added to the architecture without impacting existing workflows, allowing for easier updates and enhancements.

Implementing EDA in Deployer Bot

The integration of EDA into the Deployer Bot involves several key components working in tandem:

Event Sources : These are the triggers for the workflow, such as GitHub webhooks for commits and deployments that initiate the process.
Event Bus : AWS services like Amazon EventBridge can serve as the backbone of EDA, routing events to the appropriate services.
Lambda Functions : Serverless functions respond to events, such as fetching, processing, and summarizing commit data, and orchestrating the workflow.
DynamoDB : Acts as the storage mechanism, logging events, and maintaining state where necessary.
Amazon Bedrock : Provides AI-powered summarization of commits and releases.

In the original architecture (above) we did everything synchronously driven by webhooks. A GitHub Action CI/CD deployment would occur that would lead to a message posted in Slack with a button. If the approve button was clicked it would create the next environment's deployment in GitHub. There was no tracking of commits (or even what was in a release) and as a user of this system for several months, it was often hard to link the Slack messages back to the actual code that was being deployed (despite the commit SHA's being there). There was a lot of mental overhead. 🥵

In the new architecture (below) we expand on this by isolating responsibilities between lambdas, making them simpler (do less) and tracking new information asynchronously.

Two parallel/asynchronous paths happen as part of the deployments in GitHub. The first path relates to the commit and the second relates to the deployment.

Some notes on the architecture diagram:

The red lines are for visibility only (to help highlight the paths when lines cross each other).
We're only using the Default Event Bus
Lambdas F, B and 2 are API Driven and in the Nested API Stack
The rest of the Lambdas are Event Driven and in the Nested Event Stack

For the first path with the GitHub Commit Webhook...

GitHub's commit webhook sends the push event to the /github/commit endpoint
The lambda makes sure that it was a commit to the main branch for a project we care about. It forwards an event to the event bus to process the commit message with the minimum information we need. It quickly responds back to GitHub with an OK status. (If we waited for the commit fetching/analysis via bedrock sometimes the lambda wouldn't respond quick enough and GitHub would think it failed).
Asynchronously the process-commit lambda fetches the actual FULL commit from GitHub which includes the patches made in this commit.
The commit w/patches are sent to Bedrock where we use Anthropic's Claude v2 LLM to summarize the commit into 1-2 sentences for a target audience of developers or product managers.
The commit (without the patches) and summary are then stored in DynamoDB for later release-querying.

The Commit path takes on the order of 30 seconds (frequently less) to complete. Meanwhile, since a commit occurred on the main branch and triggered GitHub Actions... the pipeline should be testing/deploying in the background. Once the GitHub Actions pipeline is complete it will send a deployment webhook:

A. The GitHub Actions pipeline completes sending a deployment webhook to the API

B. The Lambda that receives this webhook stores the deployment information in DynamoDB and emits two EventBridge events. One to send a message to the deployment channel in Slack and another to summarize the release.

C. The track-release lambda fetches all of the commits that occurred in the environment since the last release. Here a release is considered a group of commits that were newly deployed in an environment. The dev environment releases are (usually) single-commits. Ideally test and prod would follow this pattern but frequently there's some lag and the test/prod releases end up being larger. Note: this lambda also fetches the NEXT higher environment's commits (a sort of "draft" release) and those also get summarized. I should have spun this out into a separate lambda, but I'll leave that for future-me.

D. With the release commits fetched, they're all sent together to Bedrock to be summarized. For a larger release, it ends up summarizing multiple commit summaries.

E. With the release summary and next-env summary the track-release lambda stores the release notes in DynamoDB and sends an event to update the deployment's message with this new information.

F. (Arguably this could be a third path... 😅) Once the user clicks the approve button, the /slack/interactive endpoint emits an event to deploy the next environment.

G. A lambda receives that event and triggers the GitHub Actions pipeline for the next environment.

Code Structure

I'm not going to do a complete walkthrough of the code... because there is a lot of it. Instead I will highlight particular files of interest at a high level. Feel free to reach out on socials or in the comments if you'd like something explained more in-depth.

blog-cicd-bedrock-releases-stack.ts - This stack creates the DynamoDB table and two Nested Stacks
nested-api-stack.ts - Creates a RestAPI backed by Lambdas for the Webhook Endpoints
routes/webhooks.ts - Defines the Endpoint structure for the lambdas and what permissions they should have via a common interface (nested-api-stack uses this to build the lambdas)
constructs/api.ts - Creates the actual API and Lambdas w/their permissions and paths based on the routes/webhooks.ts file
nested-event-stack.ts - Creates Event-Driven Lambdas and their Rules
routes/events.ts - Similar to routes/webhooks.ts this defines the Lambdas with their corresponding Rules and Permissions.
lambda/ - This folder contains all of the lambda runtime eligible code. Files from inside of here should not be making imports outside of this file structure (other than external npm libraries). This is to help isolate the code and ensure we aren't accidentally bundling things into our lambdas we don't need. I've seen this a lot in teams that make heavy use of index.ts files for imports 🤢
lambda/common/bedrock.ts - The Bedrock Helper file which has the functions to do the various summaries.

😍 I've been using a similar pattern at work using Nested API and Nested EventBridge Stacks and am loving it. If you'd be interested in a dedicated post on that let me know in the comments!

Prompt-Engineering for Commit and Release Summaries

The integration of generative AI into the Deployer Bot's operations involved precise prompt engineering to ensure that commit and release summaries are informative and accessible. The focus was on creating concise yet comprehensive summaries tailored to the needs of both developers and product managers. The following discussion dives into how the code facilitates this process.

The below prompts are in the lambda helper methods at https://github.com/martzcodes/blog-cicd-bedrock-releases/blob/main/lib/lambda/common/bedrock.ts

Commit Summaries

For commit summaries, I designed a prompt to guide the AI to provide succinct summaries that highlight the purpose and potential impact of the changes, particularly emphasizing backward compatibility and flagging possible breaking changes. The following TypeScript excerpt outlines this process:

// Function to generate a summary for a single commit
export const summarizeCommit = async (commit: string): Promise<string> => {
  ...
  const prompt = `...Provide a 1-2 sentence summary of the commit that would be useful for developers and product managers...`;
  ...
};

In the function summarizeCommit, the prompt specifically instructs the AI to focus on a summary that is relevant to both technical stakeholders and decision-makers. This helps ensure that any non-backwards compatible changes are prominently reported, which is crucial for maintaining the integrity of the API.

Release Summaries

The task of summarizing releases brings together multiple commits into a narrative that outlines the key developments and their implications. The summarizeRelease function employs a carefully designed prompt to distill this information:

// Function to create a summary for a release
export const summarizeRelease = async (release: string): Promise<string> => {
  ...
  const prompt = `...You will create a 1-4 sentence summary of the release below...`;
  ...
};

Here, the prompt emphasizes not only the inclusion of changes but also highlights the importance of metrics, contributions, and cadenceall of which are critical for assessing the release's impact.

Environment Comparison Summaries

When preparing to promote changes from one environment to another, it's vital to understand the differences. The prepRelease function encapsulates this through its prompt, which is structured to provide a recommendation based on the commits analyzed:

// Function to summarize differences between environments and provide a release recommendation
export const prepRelease = async ({
  ...
}): Promise<string> => {
  ...
  const prompt = `...Make a recommendation for whether to promote or not...`;
  ...
};

In this function, the AI is tasked not just with summarizing the technical changes but also with evaluating the suitability of promoting the release, incorporating a strategic aspect into the summary.

Utilizing Amazon Bedrock Runtime

All these prompts are then passed to the Amazon Bedrock Runtime, invoking the model through InvokeModelCommand with an input that defines the parameters of the AI's generation process, including token limits and stop sequences. These configurations are essential for controlling costs and ensuring the responses are concise:

const command = new InvokeModelCommand(input);
const response = await client.send(command);
...

This snippet is a crucial part of the process, as it executes the command and handles the response from the Bedrock AI, translating it into a usable summary.

ONE IMPORTANT NOTE: At the time of this writing (11/6/2023) the AWS Lambda Runtime for NodeJS (18) does NOT include the @aws-sdk/client-bedrock bundled into that. As an added "bonus" the CDK's NodejsFunction construct (which uses esbuild) by default makes @aws-sdk/* as external modules. This means that @aws-sdk/client-bedrock ends up NOT being bundled into the lambda. In order to get around this I needed to update our NodejsFunction props to bypass this. I also have to give the lambdas IAM access to invoke bedrock models. This can be done via by adding an initial policy to the lambda:

const fn = new NodejsFunction(this, `${endpoint.lambda}Fn`, {
  // ...
  bundling: {
    // Nodejs function excludes aws-sdk v3 by default because it is included in the lambda runtime
    // but bedrock is not built into the lambda runtime so we need to override the @aws-sdk/* exclusions
    externalModules: [
      "@aws-sdk/client-dynamodb",
      "@aws-sdk/client-eventbridge",
      "@aws-sdk/client-secrets-manager",
      "@aws-sdk/lib-dynamodb",
    ],
  },
  ...(endpoint.bedrock && {
    initialPolicy: [
      new PolicyStatement({
        effect: Effect.ALLOW,
        actions: ["bedrock:InvokeModel"],
        resources: ["*"],
      }),
    ],
  }),
});

Continual Evolution of Prompts

It's important to note that these prompts are not static. They are subject to continuous evaluation and iteration, ensuring that the summaries remain pertinent and value-adding as the project and AI capabilities evolve.

By embedding such targeted prompts into the Deployer Bot's workflow, the DevOps team ensures that the summaries generated are not only informative but also actionable, fostering a deeper understanding and facilitating informed decision-making throughout the development process.

Now let's try it!

In order to test this and iterate on my prompt templates, I created a CICD-example project: https://github.com/martzcodes/cicd-example

This project uses OIDC and GitHub Actions to deploy the stack. In this case, I'm just deploying the same stack with an "environment"-specific name to the same account. To reset I would stash my changes and force-push to an earlier state and re-apply the stashes.

Backwards compatibility is really important in software engineering, so one of the first things I wanted to focus on was that. I created a simple RestApi with a single endpoint pointed at /dummy. On my first attempt at prompt engineering, I included a statement like APIs must be backwards compatible, if they are not make a note of it.

I then did a deployment where I renamed the /dummy endpoint to /something (creative, I know). The response from bedrock specifically said this was backwards compatible / not a breaking change:

The release for cicd-example in prod environment contains 5 commits:

Adds an API Gateway API with Lambda endpoint

Defines the Lambda handler function

Updates API path from /dummy to /example (committed twice)

Updates API Gateway path resource from dummy to example No breaking changes or bugs were noted. The API update is backwards compatible.

A renamed endpoint could absolutely be breaking. After a few iterations, I settled on a prompt line like: APIs must be backwards compatible which includes path changes, if they are not it should be highlighted in the summary. After that, I got much more reliable callouts for path changes*.

I also made an attempt for bedrock/Claude to detect misspellings in code. For example, I defined an endpoint called /soemthing ... I could not find a prompt combination that would identify that misspelling... and in fact, in the summaries, it actually corrected it (which is VERY BAD) 😬

The release adds a new API and Lambda function. A new /something endpoint was added to the API without breaking backwards compatibility.

After installing it at work and running it for a day I asked my colleagues for feedback on the accuracy... and the feedback was very positive but it wasn't perfect.

For example...

The XXXXXX repo in the dev environment released changes on 2023-11-06T22:26:41.517Z. It includes 1 commit which adds a new '/cognito/revoke' endpoint that could break backwards compatibility if clients are not updated. No other major changes or risks noted.

New endpoints can rarely be a breaking change. Back to the drawing board, I guess 😅

Future Directions and Conclusion

As we continue to explore the intersection of generative AI and DevOps, I can see a lot of potential for a GenerativeAI+Serverless Deployer Bot. The integration of AI-driven summaries for commits and releases is just the beginning. The future is poised for a host of innovative features that could transform CI/CD pipelines and development workflows, making them more efficient and intelligent.

Expanding AI Capabilities in DevOps

Automated Code Review Assistance : By refining our prompts, we could extend the Deployer Bot's functionality to include automated code reviews, where the bot could provide preliminary feedback on pull requests, analyzing code for style, complexity, and even security vulnerabilities.
Dynamic Troubleshooting Guides : Generative AI could be harnessed to create real-time troubleshooting guides based on the errors and logs encountered during builds or deployments, providing developers with immediate, context-specific solutions.
Predictive Analytics for CI/CD : Leveraging historical data, the bot could predict potential bottlenecks and suggest optimizations in the CI/CD pipeline, leading to preemptive resource management and smoother release cycles.
Personalized Developer Assistance : AI could be programmed to learn individual developer preferences and work patterns, offering customized tips, reminders, and resources to enhance productivity.
Enhanced Onboarding : For new team members, the Deployer Bot could become an on-demand mentor, explaining CI/CD processes, and codebase navigation, and providing answers to common questions through an interactive AI-driven chat.
AI-Powered Testing and Quality Assurance : Integrating AI to analyze test results could lead to quicker identification of flaky tests and provide insights on test coverage and quality, potentially predicting which parts of the code are most likely to fail.

Conclusion

The integration of generative AI into the Deployer Bot represents a significant leap forward for DevOps teams. It is a testament to the transformative potential of AI when applied with precision and creativity. The Deployer Bot, once a mere facilitator of notifications, has evolved into a sophisticated assistant that enhances decision-making and streamlines workflows. Looking ahead, I am excited about the prospect of a more proactive, AI-powered assistant that not only informs but also predicts and strategizes, becoming an indispensable ally in the fast-paced world of software development.

The current capabilities of the Deployment Deployer Bot lay the foundation for these advancements. I'm sure this will not be my last post on the matter. My recent trip to EDA Day in Nashville gave me a lot of inspiration.

From Code to Conversation: Bridging GitHub Actions and Slack with CDK

Matt Martz — Mon, 21 Aug 2023 14:13:31 +0000

In this post, we're diving into the powerful world of automation using the AWS Cloud Development Kit (CDK) to create a serverless-backed Slack App. The goal? Seamlessly managing application deployments through GitHub Deployments. Here's a glimpse into how it all ties together:

GitHub Deployments notifies our serverless app, which consists of an AWS API Gateway Rest API backed by multiple lambda functions. One of these lambdas gets invoked by the GitHub Deployments webhook to handle deployment status updates.
Once informed, our bot relays these updates to a Slack channel.
Upon a successful deployment, the bot prompts users with, "Do you want to deploy this to the next environment?"
Users have the option to greenlight this deployment or reject it.
And when it comes to the all-important production environment, only selected approvers can make the final decision. Others can voice their views through a "vote".

The best part? Although our demonstration employs CDK, this framework isn't limited to CDK deployments. You can adapt it for any project deployable via GitHub Actions, making it a flexible tool for various deployment needs.

Here's a structured flow of our approach:

Setting up a placeholder for secret tokens.
Constructing the CDK App with key components: RestApi, DynamoDB, and several lambdas.
Safeguarding the GitHub access token and Slack Bot token inside our placeholder.
Integrating the GitHub Deployment Webhook.
Ensuring seamless Slack interactions.
Incorporating GitHub Deployments within our GitHub Actions workflows.

Eager to dive into the code? Check out the project on GitHub: https://github.com/martzcodes/blog-cicd-slackbot.

Note : This project has multiple layers, and we won't be delving into each line of code. If you find any part lacking, don't be shy. Drop your questions in the comments or catch me on Mastodon at https://awscommunity.social/@martzcodes.

Create a Placeholder Secret

Why a Placeholder? : Before diving in, you might wonder why we're setting placeholders. When working with AWS CDK, there's a tendency to automate the creation of secrets. However, I've found this method can sometimes reset these secrets unintentionally. And although CloudFormation is an option, it would expose our Secret values in its YAML file. This is where manually set placeholders come in handy they ensure our secrets remain secret.

Let's get started:

Head over to the AWS Console and create a new Secret.
Choose the "Other type of secret" option.
Toggle over to the Plaintext option under the Key/value pairs tab.
For the value, enter: {"SLACK_TOKEN":"xoxb-placeholder","GITHUB_TOKEN":"github_pat_placeholder"}.
Click on "Next".
Name your secret slackbot-deployer.
Proceed by clicking "Next".
Opt for "No rotation" and click "Next".
Finally, click on "Store" to save the secret.

Once saved, refreshing the secrets list will show you the secret's details. Look out for the secret ARN, which will appear something like this: arn:aws:secretsmanager:us-east-1:123456789012:secret:slackbot-deployer-XYZ123. Keep this ARN handy, as we'll integrate it into our CDK App in the subsequent steps.

Deploying the CDK App

Time to create our CDK App! If you're looking to speed things up, grab the example code from my GitHub. Alternatively, for the DIY enthusiasts, start a CDK project from the ground up. Navigate to your desired project folder and initiate the project with:

npx cdk init --language typescript

This command spins up a CDK version 2 project. If you've been working with a globally installed version 1 CDK, it's time to uninstall it and stick with npx.

Once our app is initialized, we're going to make changes to the bin/blog-cicd-slackbot.ts file to introduce necessary configurations.

const oidcs: Record<string, string> = {
  test: "arn:aws:iam::922113822777:role/GitHubOidcRole",
  prod: "arn:aws:iam::349520124959:role/GitHubOidcRole",
};
const nextEnvs: Record<string, string> = {
  dev: "test",
  test: "prod",
};

const app = new cdk.App();
new BlogCicdSlackbotStack(app, "BlogCicdSlackbotStack", {
  nextEnvs,
  oidcs,
  secretArn: "YOUR SECRET ARN HERE",
});

This configuration sets the stage for our environment flow and the OIDC Roles, enabling GitHub Actions to deploy CDK applications without saving secrets in GitHub. For a hands-on demonstration on crafting these OIDC roles with CDK, check out the Construct in lib/github-oidc.ts. While my roles are provisioned externally and are commented out, this should offer you a practical reference.

Create a RestAPI

Got the starter code? Jump ahead to "Deploy the App". If not, keep reading.

Let's tweak the lib/blog-cicd-slackbot-stack.ts file, first defining the Stack's Prop interface to resonate with the bin file. Here, we'll amplify the default StackProps interface by integrating three additional attributes:

export interface BlogCicdSlackbotStackProps extends cdk.StackProps {
  nextEnvs: Record<string, string>;
  oidcs: Record<string, string>;
  secretArn: string;
}

Then, modify the constructor like so:

constructor(scope: Construct, id: string, props: BlogCicdSlackbotStackProps) {

Our next move is forging the RestApi and carving out a slack/ resource:

const api = new RestApi(this, "BlogCicdSlackbotApi", {
  deployOptions: {
    dataTraceEnabled: true,
    tracingEnabled: true,
    metricsEnabled: true,
  },
  description: `API for BlogCicdSlackbotApi`,
  endpointConfiguration: {
    types: [EndpointType.REGIONAL],
  },
});
const slackResource = api.root.addResource("slack");

Let's establish our default lambda environment and properties:

const environment = {
  OIDCS: JSON.stringify(oidcs),
  SECRET_ARN: secret.secretArn,
  NEXT_ENVS: JSON.stringify(nextEnvs),
  TABLE_NAME: table.tableName,
};

const lambdaProps = {
  runtime: Runtime.NODEJS_18_X,
  memorySize: 1024,
  timeout: cdk.Duration.seconds(30),
  environment,
};

Remember : Not all our lambda functions will harness the secret/table and related functionalities. We're only granting access to lambdas if they genuinely require it. Yet, knowledge of the SECRET_ARN is harmless.

Wrap it up by creating the lambda and its endpoint:

const slackAction = new NodejsFunction(this, "SlackActionFn", {
  entry: "lib/lambda/api/slack-action.ts",
  ...lambdaProps,
});
slackResource.addResource("action").addMethod(
  "POST",
  new LambdaIntegration(slackAction)
);

Peek into my lambda's handler code present in lib/lambda/api/slack-action.ts:

import { APIGatewayEvent } from "aws-lambda";

export const handler = async (event: APIGatewayEvent) => {
  const body = JSON.parse(event.body || "{}");
  console.log(JSON.stringify({body}, null, 2));

  return {
    statusCode: 200,
    body: body.challenge,
  };
};

Heads Up! : It's essential to have esbuild and aws-lambda types added to your project. Here's how:

npm i --save-dev esbuild @types/aws-lambda

This ensures CDK avoids invoking a Docker container for lambda bundling.

Deploy the App

Everything's set? Deploy the app! Once done, you'll receive the API Url as an Output resembling:

Outputs:
BlogCicdSlackbotStack.BlogCicdSlackbotApiEndpointCDDA7E36 = https://xicnr82c7a.execute-api.us-east-1.amazonaws.com/prod/

Jot down this URL (inclusive of /prod/) we'll integrate it into the Slack App's manifest soon.

Gathering the Secrets

Before diving deep, let's ensure we have all the secrets we need for this project safely tucked away in our placeholder Secret.

We'll retrieve two primary secrets:

GitHub Personal Access Token : Enables our application to interact with GitHub Actions.
Slack App Bot Token : Helps us create and edit Slack messages.

GitHub Personal Access Token

For this, we'll employ GitHub's fine-grained tokens, which offer precise control over permissions.

Head over to the GitHub tokens page.
Remember, these tokens come with an expiration which you can set for up to a year.
If you're working within an organization like me, set the "Resource owner" to your organization.
Grant access to All repositories (both public and private).
Then, ensure you grant the following repository-level access:

Once you've completed these steps, you can copy your access token. It'll look something like this: github_pat_BLAH. Keep this safe we'll need it shortly.

Creating a Slack App

Time to nab the Slack App's Bot token:

Start by visiting the Slack API page.
Click on "Create New App".
Opt to create an app using a manifest:

{
    "display_information": {
        "name": "deploy-bot"
    },
    "features": {
        "bot_user": {
            "display_name": "deployer",
            "always_online": true
        },
        "slash_commands": [
            {
                "command": "/deployer_add_auth",
                "url": "REPLACE THIS WITH YOUR APIGW URL/slack/add-approver",
                "description": "Add an approver for Deployments",
                "usage_hint": "@user",
                "should_escape": true
            },
            {
                "command": "/deployer_list_auth",
                "url": "REPLACE THIS WITH YOUR APIGW URL/slack/list-approvers",
                "description": "Show who can approve deployments",
                "should_escape": false
            },
            {
                "command": "/deployer_remove_auth",
                "url": "REPLACE THIS WITH YOUR APIGW URL/slack/remove-approver",
                "description": "Remove someone as an approver",
                "usage_hint": "@user",
                "should_escape": true
            }
        ]
    },
    "oauth_config": {
        "scopes": {
            "user": [
                "users.profile:read"
            ],
            "bot": [
                "app_mentions:read",
                "channels:history",
                "chat:write",
                "chat:write.customize",
                "chat:write.public",
                "emoji:read",
                "groups:history",
                "groups:read",
                "groups:write",
                "im:history",
                "im:read",
                "im:write",
                "incoming-webhook",
                "pins:read",
                "pins:write",
                "reactions:read",
                "reactions:write",
                "users:read",
                "users.profile:read",
                "commands"
            ]
        }
    },
    "settings": {
        "event_subscriptions": {
            "request_url": "REPLACE THIS WITH YOUR APIGW URL/slack/action",
            "bot_events": [
                "app_mention"
            ]
        },
        "interactivity": {
            "is_enabled": true,
            "request_url": "REPLACE THIS WITH YOUR APIGW URL/slack/interaction"
        },
        "org_deploy_enabled": false,
        "socket_mode_enabled": false,
        "token_rotation_enabled": false
    }
}

Once the app's up and running, install it in your workspace.
Navigate to the OAuth & Permissions page to fetch the Bot User OAuth Token.

Update the Placeholder Secret

Armed with both tokens, revisit your placeholder Secret on the AWS Console. Here's what you do:

Click on Retrieve secret value.
Choose Edit.
Enter the tokens in their respective key-value fields.
Don't forget to hit "Save" after inputting both tokens.

Get ready, the exciting part is about to start!

Setting Up the GitHub Deployment Webhook Integration

Integrating GitHub Deployment Status webhook can be a game-changer. Not only will it ensure timely Slack notifications but also helps in maintaining a reliable history in DynamoDB.

1. Provisioning a DynamoDB Table

Firstly, we need to create a table where deployments will be recorded:

const table = new Table(this, "Table", {
  partitionKey: { name: "pk", type: AttributeType.STRING },
  sortKey: { name: "sk", type: AttributeType.STRING },
  billingMode: BillingMode.PAY_PER_REQUEST,
  removalPolicy: cdk.RemovalPolicy.DESTROY,
  timeToLiveAttribute: "ttl",
});

This table is straightforward. Given that our traffic isn't predictable, opting for the Pay Per Request model ensures cost-effectiveness.

2. Incorporating the Secret

Before we proceed, it's essential to incorporate the secret saved from the earlier stages:

const secret = Secret.fromSecretCompleteArn(this, `BlogCicdSlackbotSecret`, secretArn);

3. Lambda & API Gateway Endpoint

As theres only one GitHub endpoint, bundling the creation of both the Lambda function and its associated resource streamlines the process. Make sure the Lambda function can access both DynamoDB and Secrets Manager:

const githubWebhookFn = new NodejsFunction(this, "GithubWebhookFn", {
  entry: "lib/lambda/api/github-webhook.ts",
  ...lambdaProps,
});
table.grantReadWriteData(githubWebhookFn);
secret.grantRead(githubWebhookFn);
api.root
  .addResource("github")
  .addMethod("POST", new LambdaIntegration(githubWebhookFn));

Dive into lib/lambda/api/github-webhook.ts to examine the logic. While the file may seem hefty, the bulk of it centers around Slack message formatting.

- Storing Deployment Details:

We extract vital details from the event to be logged in DynamoDB:

const {
  state: status,
  environment: env,
  created_at: createdAt,
  updated_at: updatedAt,
  target_url: url,
} = body.deployment_status;
const { id: deploymentId, ref: branch, sha } = body.deployment;
const repo = body.repository.name;
const author = body.deployment_status.creator.login;
const owner = body.repository.owner.login;

- Retrieving Slack Token:

Fetch the Slack token securely from Secrets Manager:

const secret = await sm.send(
  new GetSecretValueCommand({
    SecretId: process.env.SECRET_ARN,
  })
);
const slackToken = JSON.parse(secret.SecretString || "").SLACK_TOKEN;

- Managing Deployment Statuses:

When a new deployment status hits, it's crucial to determine its relative standing. We do this by fetching the most recent deployment status and comparing the deploymentId:

const pk = `REPO#${repo}#ENV#${env}`.toUpperCase();
const sk = "LATEST";

// get deployment status from dynamodb
const ddbRes = await ddbDocClient.send(
  new GetCommand({
    TableName: process.env.TABLE_NAME,
    Key: {
      pk,
      sk,
    },
  })
);

If the deploymentId from the incoming webhook doesn't match the last "LATEST" item, it implies a newer deployment has superseded it. As a result, we should:

Update the previous Slack message by removing its action buttons.
Append a note indicating Automatic rejection by subsequent deployment.
Archive the last item under a unique Sort Key, ensuring its retrievable but not in the immediate queue.

const slackRes = await fetch("https://slack.com/api/chat.update", {
  method: "POST",
  body: JSON.stringify({
    channel: "C04KW81UAAV",
    ts: existingItem.slackTs,
    blocks: oldBlocks,
  }),
  headers: {
    "Content-Type": "application/json",
    Authorization: `Bearer ${slackToken}`,
  },
});
await slackRes.json();
await ddbDocClient.send(
  new PutCommand({
    TableName: process.env.TABLE_NAME,
    Item: {
      ...existingItem,
      sk: `DEPLOYMENT#${existingItem.deploymentId}`.toUpperCase(),
      blocks: JSON.stringify(oldBlocks),
    },
  })
);

New deployments, on the other hand, engage the chat.postMessage Slack API, furnishing essential deployment details.

For deployments matching the "LATEST" deploymentId, its crucial to ensure the incoming status isnt redundant. Successful deployments headed for another environment get approve/reject action buttons. This updated deployment, now the newest, gets stored under the "LATEST" sort key, paired with the Slack message timestamp for subsequent edits.

Lastly, successful deployments are logged in a meta item, an inventory of all triumphant deployments segregated by environment:

const envLatest = await ddbDocClient.send(
    new GetCommand({
      TableName: process.env.TABLE_NAME,
      Key: {
        pk: `LATEST`,
        sk: `${nextEnvs[env]}`,
      },
    })
  );
  const updatedRepo = {
    url: item.url,
    sha: item.sha,
    deploymentId: item.deploymentId,
    deployedAt: Date.now(),
    branch: item.branch,
    owner: item.owner,
  };
  if (!envLatest.Item) {
    await ddbDocClient.send(
      new PutCommand({
        TableName: process.env.TABLE_NAME,
        Item: {
          pk: `LATEST`,
          sk: `${nextEnvs[env]}`,
          repos: {
            [repo]: updatedRepo,
          },
        },
      })
    );
  } else {
    // Update existingItem by replacing the repo
    await ddbDocClient.send(
      new UpdateCommand({
        TableName: process.env.TABLE_NAME,
        Key: {
          pk: `LATEST`,
          sk: `${nextEnvs[env]}`,
        },
        // update the repos attribute
        UpdateExpression: "SET repos.#repo = :repo",
        ExpressionAttributeNames: {
          "#repo": repo,
        },
        ExpressionAttributeValues: {
          ":repo": updatedRepo,
        },
      })
    );
  }

The structuring of this meta item is worth noting. The deployment details nestle within a repos map in DynamoDB. Leveraging UpdateCommand helps pinpoint updates to specific repositories, ensuring that new build data doesn't accidentally overwrite unrelated data due to race conditions.

4. Integrating the GitHub Webhook

Navigate to your GitHub Organization's settings. Create a fresh webhook with the following attributes:

Payload URL : your-apigateway-url/github
Content type : application/json
SSL Verification : Enabled
Events : Specifically opt for Deployment statuses
Status : Active

Finalize your configurations. Now, every GitHub Deployment activates the Lambda, meticulously processing deployment data in line with your design.

Integrating Slack Interactions

Let's enhance the workflow and user experience by setting up Slack interactions for our deployment notifications.

1. Establishing the Interaction Endpoint

To catch Slack interactions like button presses, we need a dedicated endpoint. Update the lib/blog-cicd-slackbot-stack.ts to introduce this Lambda function and endpoint:

const slackInteractiveFn = new NodejsFunction(this, "SlackInteractiveFn", {
  entry: "lib/lambda/api/slack-interactive.ts",
  ...lambdaProps,
});
table.grantReadWriteData(slackInteractiveFn);
secret.grantRead(slackInteractiveFn);
slackResource
  .addResource("interaction")
  .addMethod("POST", new LambdaIntegration(slackInteractiveFn));

Though the handler for this function (lib/lambda/api/slack-interactive.ts) is extensive, it's primarily devoted to processing Slack messages and extracting information from the event.

- Decoding the Slack Payload:

Given Slack's use of the x-www-form-urlencoded content type, manual decoding becomes imperative:

const decodedString = decodeURIComponent(event.body!);
const jsonString = decodedString.replace("payload=", "");
const jsonObject = JSON.parse(jsonString);
const message = jsonObject.message;
const approved = jsonObject.actions[0].value === "approved";
const repo = jsonObject.message.text.split("Repo:*\n")[1].split("+")[0];
const env = jsonObject.message.text
  .split("+deployment+to+")[1]
  .split("+by+")[0];
const authority = jsonObject.user.name; // user who did the interaction
const branch = jsonObject.message.text.split("Branch:*\n")[1].split("+")[0];

- Fetching Tokens:

This Lambda could require tokens for both GitHub and Slack. Thus, lets retrieve them:

const secret = await sm.send(
  new GetSecretValueCommand({
    SecretId: process.env.SECRET_ARN,
  })
);
const slackToken = JSON.parse(secret.SecretString || "").SLACK_TOKEN;
const githubToken = JSON.parse(secret.SecretString || "").GITHUB_TOKEN;

- Retrieving User's Image:

To enrich our Slack messages with user details, fetch the user's profile picture via the Slack API:

const slackAuthorityRes = await fetch(
  `https://slack.com/api/users.profile.get?user=${jsonObject.user.id}`,
  {
    method: "GET",
    headers: {
      "Content-Type": "application/json",
      Authorization: `Bearer ${slackToken}`,
    },
  }
);
const slackAuthority = await slackAuthorityRes.json();
const userImg = slackAuthority.profile.image_24;

- Processing Slack Messages:

A series of operations then follows:

Embed the user's profile picture, corresponding to their action (approve/reject).
Handle vote changes to ensure clarity in responses.
For deployments to "prod", cross-verify the user's authority against a list of approved users.

On gaining approval:

Update the LATEST deployment item status
Retrieve the workflow list for the repository, enabling us to identify the correct workflowId
Initiate the deployment for the succeeding environment

await ddbDocClient.send(
  new PutCommand({ TableName: process.env.TABLE_NAME, Item: existingItem })
);
const githubListWorkflowsRes = await fetch(
  `https://api.github.com/repos/${existingItem.owner}/${repo}/actions/workflows`,
  {
    method: "GET",
    headers: {
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      Authorization: `Bearer ${githubToken}`,
    },
  }
);
const { workflows } = await githubListWorkflowsRes.json();
const workflow = workflows.find(
  (workflow: any) => workflow.name === "deploy-to-env"
);
await fetch(
  `https://api.github.com/repos/${existingItem.owner}/${repo}/actions/workflows/${workflow.id}/dispatches`,
  {
    method: "POST",
    body: JSON.stringify({
      ref: branch,
      inputs: {
        deploy_env: nextEnvs[env],
        oidc_role: oidcs[nextEnvs[env]],
      },
    }),
    headers: {
      Accept: "application/vnd.github+json",
      "X-GitHub-Api-Version": "2022-11-28",
      Authorization: `Bearer ${githubToken}`,
    },
  }
);

Concluding this segment, the Slack message is refreshed, and the updated information is stored in DynamoDB.

2. Managing Approvers

The next phase involves facilitating the management of deployment approvers via Slack slash commands. Three distinct Lambdas will handle these functionalities addition, removal, and listing of approvers.

An initial approver sets the tone, and subsequent approvals or removals of approvers happen under their discretion. To glean details about an approver, like their name, email, or profile picture, the add-approver endpoint uses the Slack Token.

For those eager to dive into the implementation, the code is hosted in the following:

lib/lambda/api/slack-add-approver.ts
lib/lambda/api/slack-list-approvers.ts
lib/lambda/api/slack-remove-approver.ts

Though we're summarizing this section, remember that having a robust system of approval is paramount, especially for production deployments.

Setting Up GitHub Deployments with GitHub Actions

To harness the power of GitHub Deployments, let's configure some environments for your project.

1. Configuring Environments:

First, head to your repository's settings page and open the Environments tab. For instance, the URL might resemble: https://github.com/martzcodes/blog-cicd-slackbot/settings/environments. Here, introduce a fresh environment for each stage you aim to monitor. Ensure their names correspond with your nextEnvs configuration object. For example, my setup included dev, test, and prod.

2. Configuring GitHub Actions:

Now, ensure your deployment-focused GitHub Actions are set to employ GitHub Deployments. Some sample workflows are available at: GitHub Sample Workflows.

The pipeline.yml file, which springs into action upon commits to the main branch, facilitates continuous deployment to the dev environment. This action sets the stage for our Slack integration. Notably, this pipeline is named Deploy - a detail the GitHub webhook Lambda verifies.

Subsequently, the deploy-to-env.yml workflow is tailored to possess matching inputs. Triggered by the pipeline.yml workflow, both workflow_call and workflow_dispatch triggers accept these inputs:

inputs:
  deploy_env:
    description: 'Environment to deploy to'
    required: true
    type: string
  oidc_role:
    description: 'OIDC Role to assume for deployment'
    required: true
    type: string

Although your deployment steps could differ, it's crucial to encapsulate your deployment within status update stages:

  - name: start deployment
    uses: bobheadxi/deployments@v1.2.0
    id: deployment
    with:
      step: start
      env: ${{ inputs.deploy_env }}
  - name: ${{ inputs.deploy_env }} deploy
    env:
      DEPLOY_ENV: ${{ inputs.deploy_env }}
    run: npx cdk deploy --ci --require-approval never --concurrency 5 -v
  - name: update deployment status
    uses: bobheadxi/deployments@v1.2.0
    with:
      step: finish
      status: ${{ job.status }}
      env: ${{ inputs.deploy_env }}
      deployment_id: ${{ steps.deployment.outputs.deployment_id }}

The central idea here is that the bobheadxi/deployments action communicates with GitHub's API to register a deployment for the relevant environment. For a clearer perspective, a live example resides here: Live GitHub Example.

Live Demonstration

Let's observe this integration in its full glory.

1 - Initialization: Using the Slack slash command /deployer_list_auth, I'll confirm our approver list starts empty:

2 - Commencing a Deployment: I'll initiate a deployment in my dev environment and after a brief wait an in_progress message surfaces:

3 - Deployment Completion: On the successful completion of the deployment, our message updates, introducing action buttons. Given our next environment, "test", no approvers are mandated:

4 - Deployment Approval: Tapping the "Approve" button results in another message transformation, indicating approval along with the removal of the action buttons:

5 - Test Environment Deployment: Shortly, the in_progress message for the test environment arrives:

6 - Rejection Attempt: After the test environment has a successful deployment and the buttons appear... As an outsider to the approver list, my "Reject" action prompts an updated message, retaining the buttons:

7 - Adding to the Approver List: I'll employ the /deployer_add_auth command to add myself to the approver list:

8 - Final Rejection: After clicking the "Reject' button again the deployment is successfully rejected, with our message updated accordingly:

Conclusion

The intertwining of continuous integration and deployment with communication tools, as we've explored in this journey, opens a myriad of possibilities. Not only does it seamlessly merge developer actions with team-wide notifications, but it also introduces an additional layer of transparency and control over our deployment processes. The adaptability of the systems we've integrated, namely GitHub and Slack, offer a rich tapestry of features to build upon, as demonstrated by our use of GitHub Deployment and its potential with GitHub Actions.

It's worth noting the original plan was to leverage GitHub Deployment Protection rules. These rules present a solid framework for controlling deployments in a more granular way. However, a significant limitation arose: their availability is restricted to either public repositories or those operating under GitHub Enterprise. This limitation led to a more creative approach, embedding the essence of what these rules offer, but in a broader context suitable for various repository types.

To conclude, technology continues to provide tools and platforms, ripe with features and functionalities, waiting to be moulded and interconnected in ways that best suit our needs. This exploration was just a glimpse into the vast world of CI/CD and team communication integrations. As you embark on your own integrative ventures, remember that while off-the-shelf solutions are great, sometimes thinking outside the box or outside the repository, in this case can lead to even more robust and tailor-made solutions for your team.

Amplifying AWS Tutorials: Building a Social Notes App with "Sign in with Apple" and AWS Pinpoint Analytics

Matt Martz — Tue, 01 Aug 2023 00:24:33 +0000

For the 2023 AWS Amplify + Hashnode Hackathon, I wanted to take a closer look into iOS development and take the introductory iOS notes app from AWS Amplify's tutorial to the next level by incorporating powerful features like federated login via Apple's "Sign in with Apple" Then we'll add some easy Analytics to our app with AWS Pinpoint.

While AWS's initial tutorial covered basic username/password authentication... users appreciate convenience and security. To support this, we'll add "Sign in with Apple" support, which offers users a seamless and privacy-focused login option. With "Sign in with Apple," users can authenticate with their Apple ID and stay in control of their personal information (including giving them the ability to hide their email).

A successful app requires understanding user behavior and optimizing user experiences. That's where AWS Pinpoint Analytics comes into play. I'll demonstrate how to integrate AWS Pinpoint into the notes app, enabling us to collect critical user engagement data. With this newfound insight, we can analyze user interactions, monitor feature adoption, and make data-driven decisions to enhance the app's performance.

AWS Amplify is a comprehensive development platform offered by Amazon Web Services (AWS) that simplifies the process of building web and mobile applications. It provides developers with a set of tools, services, and libraries to accelerate the development of cloud-powered applications.

This tutorial assumes you are familiar with the basics of AWS Amplify, including authentication setup and working with the Amplify Storage component. If you're new to these concepts, I recommend checking out the original AWS Amplify tutorial to get up to speed.

The code for this project is located here: https://github.com/martzcodes/blog-amplifyhackathon-ios-2023

Updating the App to use "Sign in with Apple"

Amplify and Apple make it really easy to incorporate "Sign in with Apple" (SIWA) into your applications. SIWA allows you to federate users into an Amazon Cognito identity pool using the AWS Amplify Libraries for Swift. By federating a user into a Cognito identity pool, it allows us to use temporary AWS IAM credentials for the users based on the identity token that Apple provides us. In doing so, we can use those AWS IAM credentials to access other services like Amazon S3, AppSync and Pinpoint.

This article will show you how to use Sign in with Apple (SIWA) to retrieve an identity token and federate the user in an Amazon Cognito identity pool using the AWS Amplify Libraries for Swift. Federating a user in an identity pool provides them with credentials that allow them to access other services like Amazon S3 and Amazon DynamoDB.

First, we'll update amplify's auth to use Apple's provider. Below is the full list of answers when running amplify update auth:

$ amplify update auth
 What do you want to do? Walkthrough all the auth configurations
 Select the authentication/authorization services that you want to use: User Sign-Up, Sign-In, connected with AWS IAM controls (Enables per-user Storage features for images or other content, Analytics, and more)
 Allow unauthenticated logins? (Provides scoped down permissions that you can control via AWS IAM) Yes
 Do you want to enable 3rd party authentication providers in your identity pool? Yes
 Select the third party identity providers you want to configure for your identity pool: Apple

 You've opted to allow users to authenticate via Sign in with Apple. If you haven't already, you'll need to go to https://developer.apple.com/account/#/welcome and configure Sign in with Apple.

 Enter your Bundle Identifier for your identity pool: <your app bundle id from apple>
 Do you want to add User Pool Groups? No
 Do you want to add an admin queries API? No
 Multifactor authentication (MFA) user login options: OFF
 Email based user registration/forgot password: Enabled (Requires per-user email entry at registration)
 Specify an email verification subject: Your verification code
 Specify an email verification message: Your verification code is {####}
 Do you want to override the default password policy for this User Pool? No
 Specify the app's refresh token expiration period (in days): 30
 Do you want to specify the user attributes this app can read and write? No
 Do you want to enable any of the following capabilities?
 Do you want to use an OAuth flow? No
? Do you want to configure Lambda Triggers for Cognito? Yes
? Which triggers do you want to enable for Cognito

Identity pools do NOT use Cognito User Groups... they use AWS IAM-based access. In order to make use of these for our app, we need to switch AWS AppSync to use IAM auth instead of Cognito User Groups. Let's run amplify update api. Below are the full answers for this section:

amplify update api
? Select from one of the below mentioned services: GraphQL
...
? Select a setting to edit Authorization modes
? Choose the default authorization type for the API IAM
? Configure additional auth types? No

Before we can push these changes, we need to update our schema.graphql. It was using auth based on Cognito Pools, but we need to switch it to IAM-based auth. For demo sake, we also want to enable guests (unauthenticated users) to also read notes. We'll update the schema.graphql file to:

type NoteData
@model
@auth(
    rules: [
      { allow: public, provider: iam, operations: [read] }
      { allow: private, provider: iam, operations: [read, create, update, delete] }
    ]
  ) {
    id: ID!
    name: String!
    description: String
    image: String
}

{ allow: public, provider: iam, operations: [read] } gives guests read access
{ allow: private, provider: iam, operations: [read, create, update, delete] } gives logged in users full CRUD access

With the schema.graphql updated, we can run amplify codegen models to regenerate the APIs.

With these changes, we can run amplify push and our backend will update to reflect these new changes. Next, we'll need to modify some of the swift code.

Instead of using Amplify.Auth.signInWithWebUI we need to use the SignInWithApple button and then make a call to federateToIdentityPool. SignInWithApple is a capability provided by Apple. Once signed in, it provides an identity token that is used by federateToIdentityPool

In ContentView.swift:

// add this to the top of the file
import AuthenticationServices

// In the ContentView view:
func configureRequest(_ request: ASAuthorizationAppleIDRequest) {
    request.requestedScopes = [.email]
}
func handleResult(_ result: Result<ASAuthorization, Error>) {
    switch result {
    case .success(let authorization):
        guard let credential = authorization.credential as? ASAuthorizationAppleIDCredential,
                let identityToken = credential.identityToken else {
                    return
                }
        guard let tokenString = String(data: identityToken, encoding: .utf8) else {
            return
        }
        Backend.shared.federateToIdentityPools(with: tokenString)
        self.userData.isSignedIn = true;
    case .failure(let error):
        print(error)
    }
}

// replace the original sign in button with:
SignInWithAppleButton(
    onRequest: configureRequest,
    onCompletion: handleResult
)
.frame(maxWidth: 300, maxHeight: 45)

SignInWithAppleButton triggers the SIWA capability by Apple. configureRequest ensures that the email is returned as part of the scope of the identityToken. On completion then parses the identityToken and sends it to our Backend.swift service.

In Backend.swift the Amplify.Auth plugin calls federateToIdentityPool:

func federateToIdentityPools(with tokenString: String) {
    guard
        let plugin = try? Amplify.Auth.getPlugin(for: "awsCognitoAuthPlugin") as? AWSCognitoAuthPlugin
    else { return }

    Task {
        do {
            let result = try await plugin.federateToIdentityPool(
                withProviderToken: tokenString,
                for: .apple
            )
            print("Successfully federated user to identity pool with result:", result)
        } catch {
            print("Failed to federate to identity pool with error:", error)
        }
    }
}

In this version of our code, we also have an auth listener that triggers UI updates based on session events. The auth listener in our Backend.swift file looks like this now:

public func listenAuthUpdate() async -> AsyncStream<AuthStatus> { 
    return AsyncStream { continuation in
        continuation.onTermination = { @Sendable status in
                   print("[BACKEND] streaming auth status terminated with status : \(status)")
        }

        // listen to auth events.
        // see https://github.com/aws-amplify/amplify-ios/blob/master/Amplify/Categories/Auth/Models/AuthEventName.swift
        let _ = Amplify.Hub.listen(to: .auth) { payload in            
            print(payload.eventName)
            switch payload.eventName {
            case "Auth.federatedToIdentityPool":
                print("User federated, update UI")
                continuation.yield(AuthStatus.signedIn)
                Task {
                    await self.updateUserData(withSignInStatus: true)
                }
            case "Auth.federationToIdentityPoolCleared":
                print("User unfederated, update UI")
                continuation.yield(AuthStatus.signedOut)
                Task {
                    await self.updateUserData(withSignInStatus: false)
                }
            case HubPayload.EventName.Auth.sessionExpired:
                print("Session expired, show sign in aui")
                continuation.yield(AuthStatus.sessionExpired)
                Task {
                    await self.updateUserData(withSignInStatus: false)
                }
            default:
                print("\(payload)")
                break
            }
        }
    }
}

For federation events, the events end up being Auth.federatedToIdentityPool and Auth.federationToIdentityPoolCleared.

Adding AWS Pinpoint for App Analytics

Next, we want to see what our users are doing in our Notes app and see if they're really making use of the "new" image upload feature.

First, we'll need to update amplify by running amplify add analytics:

amplify add analytics
? Select an Analytics provider Amazon Pinpoint
 Provide your pinpoint resource name: amplifypushup

Then we'll run amplify push.

We'll need to add the Amplify Analytics libraries to our app by making sure the AWSPinpointAnalyticsPlugin is installed. And then we'll add the initialization in our Backend.swift file:

private init() {
  // initialize amplify
  do {
      try Amplify.add(plugin: AWSCognitoAuthPlugin())
      try Amplify.add(plugin: AWSAPIPlugin(modelRegistration: AmplifyModels()))
      try Amplify.add(plugin: AWSS3StoragePlugin())
      try Amplify.add(plugin: AWSPinpointAnalyticsPlugin()) // <-- add this
      try Amplify.configure()
      print("Initialized Amplify");
  } catch {
    print("Could not initialize Amplify: \(error)")
  }

If we want to track how popular our image upload feature is, we can add an event:

let properties: AnalyticsProperties = [
    "eventPropertyStringKey": "eventPropertyStringValue",
    "eventPropertyIntKey": 123,
    "eventPropertyDoubleKey": 12.34,
    "eventPropertyBoolKey": true
]

let event = BasicAnalyticsEvent(
    name: "imageUploaded",
    properties: properties
)

try Amplify.Analytics.record(event: event)

You can also emit events related to authentication that Pinpoint will automatically track:

_userauth.sign_in
_userauth.sign_up
_userauth.auth_fail

Conclusion

In my quest to elevate the capabilities of AWS Amplify tutorials, I ventured into iOS development for the 2023 AWS Amplify + Hashnode Hackathon. Building upon the introductory iOS notes app tutorial provided by AWS Amplify, I took the app to the next level by incorporating sought-after features like "Sign in with Apple" and AWS Pinpoint Analytics.

The inclusion of "Sign in with Apple" as a federated login option significantly enhances the app's authentication experience. Users can now seamlessly log in with their Apple ID, ensuring both convenience and privacy. This advanced authentication option empowers users to stay in control of their personal information, including the ability to hide their email.

In addition to empowering users with a better way to sign-in, I integrated AWS Pinpoint Analytics into the notes app. By leveraging AWS Pinpoint's analytical capabilities, we gained valuable insights into user engagement and behavior. This data-driven approach allows us to analyze user interactions, monitor feature adoption, and make informed decisions to optimize the app's performance and user experience.

As you explore the code and implement these advanced features, I encourage you to further experiment and customize the app to suit your specific use case and preferences. Remember to refer to the code repository for detailed implementations.

Thank you for joining me on this amplified journey to enhance AWS tutorials. With "Sign in with Apple" and AWS Pinpoint Analytics at your fingertips, you're equipped to build robust and engaging mobile apps that connect users with seamless authentication and actionable insights.

Leveraging CDK and Serverless for Bluesky Feed Generation

Matt Martz — Wed, 05 Jul 2023 19:04:11 +0000

In the dynamic world of social media, Bluesky is carving out a niche with its innovative approach to content curation. With its unique "My Feeds" feature, Bluesky empowers users to customize their social media experience by choosing from a variety of feeds, each powered by a different algorithm.

Creating these diverse feeds, however, requires a Bluesky feed generator, a tool that necessitates some technical know-how. This is where AWS services come into the picture, simplifying the deployment and operation of a Bluesky feed generator.

Our proposed architecture leverages AWS Fargate, AWS Lambda, and Aurora Serverless. AWS Fargate runs a container designed to parse the Bluesky event stream, capturing only the relevant data. This data is then stored in an Aurora Serverless database. AWS Lambda is employed to deliver the stream, working in tandem with AWS Fargate to reduce operational overhead and allow us to focus on core functionality. This combination also serves as our "feed algorithm".

Deploying the Bluesky feed generator as an AWS CDK project not only streamlines the process of feed creation but also democratizes it, making it accessible to a wider audience. It facilitates easy scaling of resources, and efficient cost management, and enables us to focus more on developing unique, user-centric feeds rather than managing the underlying infrastructure.

In the upcoming sections of this blog post, we'll delve deeper into the technical aspects of deploying a Bluesky feed generator using AWS services. We'll provide a step-by-step guide to help you get started, including creating a feed of "skeets" from AWS Employees, AWS Heroes, and AWS Community Builders.

PSST... feel free to follow me on Bluesky too

The Bluesky-provided Feed Generator

Bluesky provides a basic feed generator on their GitHub, but it's a bit like having a camera without the right settings - it lacks the necessary architecture to capture the perfect shot.

At its heart, the service provided by Bluesky's repo performs three key functions:

It latches onto the Bluesky Websocket stream and filters events into a database. It's like adjusting the focus on your camera, ensuring only the relevant subjects are in clear view 1.
It features a feed endpoint that cherry-picks relevant rows from the database. Think of it as the photographer, selecting the best shots for the final album 2.
It includes a static endpoint that "registers" the feed. This is like the metadata of a photo, providing all the necessary information about the shot 3.

To register the feed service, a script is run that's a bit like the final editing process before the photos are published. It connects to Bluesky and registers the feed name and service URL, making sure everything is picture-perfect 4.

Now, here's where we bring in the big guns - AWS CDK. We're going to give this feed generator a major upgrade.

Firstly, we'll move the WebSocket stream connection to a Fargate service. This is akin to upgrading from a manual focus to an automatic one - it's faster, more efficient, and doesn't require as much manual effort.

Next, we'll transform the feed endpoint into an AWS Lambda function. This is like having an automated photo editor - it's more efficient, scalable, and doesn't require constant supervision.

The static endpoint will be relocated to a simple MockIntegration in the APIGateway. This is like moving your photo metadata management to a digital platform - it's more efficient, reliable, and easily accessible.

Lastly, we'll shift the feed registration script to be run by a CustomResource-invoked Lambda. This is like automating your final photo editing process - it's more reliable, efficient, and doesn't require constant attention.

In essence, we're taking the basic structure provided by Bluesky and supercharging it with the power of AWS CDK.

Crafting The Bluesky Database

First up on our agenda is the creation of the database that will serve as the meeting point for our parser and feed. This setup bears a resemblance to my recent post about Creating an Aurora MySQL Database and Setting Up a Kinesis CDC Stream with AWS CDK. However, there's a twist - we won't be needing the stream this time, and we'll be employing Aurora Serverless instead.

Our game plan involves crafting a CDK Construct that houses the database and a CustomResource-invoked Lambda that will lay the groundwork for the database schema. Let's dive into the creation of the database:

this.db = new ServerlessCluster(this, 'cluster', {
  clusterIdentifier: `bluesky`,
  credentials: Credentials.fromGeneratedSecret('admin'),
  defaultDatabaseName: dbName,
  engine: DatabaseClusterEngine.AURORA_MYSQL,
  removalPolicy: RemovalPolicy.DESTROY,
  enableDataApi: true,
  vpc,
});

Next, we'll whip up the lambda function and the custom resource:

const dbInitFn = new NodejsFunction(this, "dbInitFn", {
  functionName: "bluesky-db-init",
  entry: join(__dirname, "lambda/db-init.ts"),
  runtime: Runtime.NODEJS_18_X,
  timeout: Duration.minutes(15),
  tracing: Tracing.ACTIVE,
  environment: {
    DB_NAME: dbName,
    CLUSTER_ARN: this.db.clusterArn,
    SECRET_ARN: this.db.secret?.secretArn || '',
  },
});
this.db.grantDataApiAccess(dbInitFn);

const initProvider = new Provider(this, `init-db-provider`, {
  onEventHandler: dbInitFn,
});

new CustomResource(this, `init-db-resource`, {
  serviceToken: initProvider.serviceToken,
});

Our lambda's handler will be interacting with the database using the RDS Data API, taking advantage of the secrets that CloudFormation has created for the database:

if (event.RequestType === "Create") {
    await client.send(cmd(`select 1`));
    console.log("db-init: create tables");
    await client.send(
      cmd(
        `CREATE TABLE IF NOT EXISTS post (uri VARCHAR(255) NOT NULL, cid VARCHAR(255) NOT NULL, author VARCHAR(255) NOT NULL, replyParent VARCHAR(255), replyRoot VARCHAR(255), indexedAt DATETIME NOT NULL, PRIMARY KEY (uri));`
      )
    );
    console.log("created post table");
    await client.send(cmd(`CREATE TABLE IF NOT EXISTS sub_state (service VARCHAR(255) NOT NULL, cursor_value INT NOT NULL, PRIMARY KEY (service));`))
    console.log("created sub_state table");
}

Since we want the tables to be created only when the stack is first deployed, we filter on event.RequestType === "Create". However, to err on the side of caution, we've also included IF NOT EXISTS in the SQL commands. Better safe than sorry!

Constructing the Parser: Connecting to the Bluesky Event Stream

In the next phase of our process, we're going to construct the parser that connects to the Bluesky event stream. This component is the linchpin that connects us to the publicly available Bluesky web socket event stream. It's like the lens of our camera, capturing the events that we're interested in and focusing them into a coherent image.

Let's dive into the code and understand the key parts:

const cluster = new Cluster(this, "bluesky-feed-generator-cluster", {
  vpc,
  enableFargateCapacityProviders: true,
});

Here, we're setting up our Fargate cluster. This is akin to positioning our camera on a tripod, providing a stable platform for our operations.

const taskDefinition = new FargateTaskDefinition(
  this,
  "bluesky-feed-generator-task",
  {
    runtimePlatform: {
      cpuArchitecture: CpuArchitecture.ARM64,
    },
    memoryLimitMiB: 1024,
    cpu: 512,
  }
);
db.grantDataApiAccess(taskDefinition.taskRole);

Next, we're defining a Fargate task. This is like adjusting the camera's settings, such as aperture and shutter speed, to ensure we capture the best possible shot. We're also granting this task access to our database, much like giving our camera the ability to store the photos it captures.

const logging = new AwsLogDriver({
  logRetention: RetentionDays.ONE_DAY,
  streamPrefix: "bluesky-feed-generator",
});

We're setting up a log driver here, which is akin to the camera's viewfinder, allowing us to monitor and review our operations.

taskDefinition.addContainer("bluesky-feed-parser", {
  logging,
  image: ContainerImage.fromDockerImageAsset(
    new DockerImageAsset(this, "bluesky-feed-parser-img", {
      directory: join(__dirname, ".."),
      platform: Platform.LINUX_ARM64,
    })
  ),
  environment: {
    DB_NAME: dbName,
    CLUSTER_ARN: db.clusterArn,
    SECRET_ARN: db.secret?.secretArn || '',
  }
});

Here, we're adding a container to our task definition. This is like attaching a lens to our camera, defining what it will capture. We're also specifying the environment variables, which are akin to the camera's internal settings.

new FargateService(this, "bluesky-feed-generator", {
  cluster,
  taskDefinition,
  enableExecuteCommand: true,
  // fargate service needs to select subnets with the NAT in order to access AWS services
  vpcSubnets: {
    subnetType: SubnetType.PRIVATE_WITH_EGRESS,
  },
  securityGroups: [securityGroup]
});

Finally, we're creating a new Fargate service, which is like pressing the camera's shutter button, setting everything into motion. We're specifying that the service should be able to execute commands and that it should select subnets with NAT to access AWS services, ensuring our camera can communicate with the outside world.

The Service Code

The code for our Fargate Service is heavily inspired by the feed generator provided by Bluesky. However, we've stripped out all the unnecessary parts (like express, etc). All we need to do is connect to the WebSocket stream and save relevant events to the already-created database.

When we created the DockerImageAsset above, we pointed it to our root directory which contains a Dockerfile. This Dockerfile installs the dependencies and runs the app which creates a FirehoseSubscription.

for (const post of ops.posts.creates) {
  if (awsCommunityDids.includes(post.author)) {
    const user = awsCommunityDidsToKeys[post.author];
    console.log(`${user} posted ${post.record.text}`);
    postsToCreate.push({
      uri: post.uri,
      cid: post.cid,
      author: user,
      replyParent: post.record?.reply?.parent.uri ?? null,
      replyRoot: post.record?.reply?.root.uri ?? null,
      indexedAt: new Date().toISOString().slice(0, 19).replace("T", " "),
    });
  }
}

if (postsToCreate.length > 0) {
  console.log(JSON.stringify({ postsToCreate }));
  const insertSql = `INSERT INTO post (uri, cid, author, replyParent, replyRoot, indexedAt) VALUES ${postsToCreate
    .map(
      () => "(:uri, :cid, :author, :replyParent, :replyRoot, :indexedAt)"
    )
    .join(", ")} ON DUPLICATE KEY UPDATE uri = uri`;

  const insertParams = postsToCreate.flatMap((post) => [
    { name: "uri", value: { stringValue: post.uri } },
    { name: "cid", value: { stringValue: post.cid } },
    { name: "author", value: { stringValue: post.author } },
    {
      name: "replyParent",
      value: post.replyParent
        ? { stringValue: post.replyParent }
        : { isNull: true },
    },
    {
      name: "replyRoot",
      value: post.replyRoot
        ? { stringValue: post.replyRoot }
        : { isNull: true },
    },
    { name: "indexedAt", value: { stringValue: post.indexedAt } },
  ]);

  const insertCmd = cmd(insertSql, insertParams);
  await client.send(insertCmd);
  console.log(`Created ${postsToCreate.length} posts`);
}

This is akin to the post-processing phase in photography. We're selecting the best shots (or in this case, posts) based on our predefined criteria, and storing them in our database. We're also ensuring that we handle deletions appropriately, keeping our collection of shots up-to-date.

The Bluesky Feed

The final CDK Construct creates an API Gateway with two endpoints, and the CustomResource that registers the feed.

Creating the Feed

This section of the code is primarily concerned with setting up the API Gateway and the DNS records for the service. Here are the key parts:

const hostedzone = HostedZone.fromLookup(this, "hostedzone", {
  domainName: zoneDomain,
});
const certificate = new Certificate(this, "certificate", {
  domainName,
  validation: CertificateValidation.fromDns(hostedzone),
});

Here, we're looking up the hosted zone for our domain and creating a certificate for it. This is like setting up the address and credentials for our online photo gallery.

const api = new RestApi(this, "RestApi", {
  defaultMethodOptions: {
    methodResponses: [{ statusCode: "200" }],
  },
  deployOptions: {
    tracingEnabled: true,
    metricsEnabled: true,
    dataTraceEnabled: true,
  },
  endpointConfiguration: {
    types: [EndpointType.REGIONAL],
  },
});

Next, we're setting up the REST API. This is like setting up the interface for our online gallery, defining how users will interact with it.

Of course, let's not forget the MockIntegration:

const didIntegration = new MockIntegration(didOptions);
const didResource = api.root
  .addResource(".well-known")
  .addResource("did.json");
didResource.addMethod("GET", didIntegration, {
  methodResponses: [
    {
    statusCode: "200",
    },
  ],
});

Here, we're setting up a MockIntegration. In the context of AWS API Gateway, a MockIntegration is a type of integration that allows you to simulate API behavior without implementing any backend logic. It's like a placeholder or a dummy that returns pre-configured responses to requests.

In this case, we're using it to serve a static JSON response for the did.json endpoint under the .well-known path. This endpoint is typically used to provide a standard way to discover information about the domain, and in this case, it's providing information about the Bluesky feed generator service.

This is akin to having a static information page in our photo gallery that provides details about the gallery itself. It doesn't change or interact with the visitor but provides essential information for anyone who asks.

const feedFn = new NodejsFunction(this, "feed", {
  functionName: "bluesky-feed",
  entry: join(__dirname, "lambda/feed.ts"),
  runtime: Runtime.NODEJS_18_X,
  timeout: Duration.seconds(30),
  tracing: Tracing.ACTIVE,
  environment: {
    DB_NAME: dbName,
    CLUSTER_ARN: db.clusterArn,
    SECRET_ARN: db.secret?.secretArn || "",
  },
});
db.grantDataApiAccess(feedFn);

Here, we're defining a new Node.js function that will serve as the feed for our service. This is like setting up the mechanism that will display the photos in our gallery.

api.root
  .addResource("xrpc")
  .addResource("app.bsky.feed.getFeedSkeleton")
  .addMethod("GET", feedIntegration);

This is where we're defining the endpoint for our feed. This is like setting up the URL where users can view our photo gallery.

api.addDomainName(`Domain`, {
  domainName,
  certificate,
  securityPolicy: SecurityPolicy.TLS_1_2,
});
new ARecord(scope, `ARecord`, {
  zone: hostedzone,
  recordName: domainName,
  target: RecordTarget.fromAlias(new ApiGateway(api)),
});

Finally, we're associating our domain name with our API and creating an A record for it. This is like linking our online gallery to our chosen web address, making it accessible to the public.

Registering the feed

We create another lambda and custom resource with:

const publishSecret = Secret.fromSecretCompleteArn(this, "publish-secret", props.publishFeed.blueskySecretArn);
const publishFeedFn = new NodejsFunction(this, "publish-feed", {
  functionName: "bluesky-publish-feed",
  entry: join(__dirname, "lambda/publish-feed.ts"),
  runtime: Runtime.NODEJS_18_X,
  timeout: Duration.seconds(30),
  tracing: Tracing.ACTIVE,
  environment: {
    HANDLE: props.publishFeed.handle,
    SECRET_ARN: props.publishFeed.blueskySecretArn,
    FEEDGEN_HOSTNAME: domainName,
    FEEDS: JSON.stringify(props.publishFeed.feeds),
  },
});
publishSecret.grantRead(publishFeedFn);

const publishProvider = new Provider(this, `publish-feed-provider`, {
  onEventHandler: publishFeedFn,
});

new CustomResource(this, `publish-feed-resource`, {
  serviceToken: publishProvider.serviceToken,
  properties: {
    Version: `${Date.now()}`,
  },
});

Here we make sure that it has access to our Bluesky App password (created on our Bluesky account's settings page).

The handler code follows the same process as Bluesky's own publishFeedGen.ts script, except we get the password from the secrets manager first. This code runs with every deployment and supports registering multiple feeds pointing at the same lambda.

Tying It All Together: Deploying the Stack

Having created the individual constructs, we now need to assemble them into a cohesive stack. This is akin to putting together our camera, lens, and tripod into a complete photography setup.

const vpc = new Vpc(this, "vpc");
const securityGroup = new SecurityGroup(this, "security-group", {
  vpc,
  allowAllOutbound: true,
});

const dbName = 'bluesky';
const { db } = new BlueskyDb(this, 'bluesky-db', {
  dbName,
  vpc,
});

const domainName = 'martz.codes';

new BlueskyParser(this, 'bluesky-parser', {
  db,
  dbName,
  securityGroup,
  vpc,
});

new BlueskyFeed(this, 'bluesky-feed', {
  db,
  dbName,
  domainName,
  publishFeed,
});

In the code above, we're first setting up a Virtual Private Cloud (VPC) and a security group. This is like choosing a location for our photo shoot and setting up the necessary security measures.

Next, we're creating our Bluesky database within this VPC. This is akin to setting up our storage system for the photos we'll capture.

We then instantiate our Bluesky parser and feed constructs, passing in the necessary parameters such as the database, domain name, and security group. This is like setting up our camera and lens, ready to start capturing photos.

In the bin file, we include the required publishFeed properties:

publishFeed: {
    handle: 'martz.codes',
    blueskySecretArn: "arn:aws:secretsmanager:us-east-1:359317520455:secret:bluesky-rQXJxQ",
    feeds: {
      "aws-community": {
        displayName: "AWS Community",
        description: "This is a test feed served from an AWS Lambda. It is a list of AWS Employees, AWS Heroes and AWS Community Builders",
      }
    },
  },

This is like setting up the details of our photo gallery, including the name, description, and access credentials.

It's worth noting that this stack was built iteratively. While it should work as expected, there may be a missing dependency that could affect the deployment order for the CustomResources.

Once deployed, we can visit the feed's page on Bluesky: https://bsky.app/profile/did:plc:a62mzn6xxxxwktpdprw2lvnc/feed/aws-community

The URL structure is as follows: https://bsky.app/profile/<owner's DID>/feed/<short-name>. When this URL is loaded in Bluesky, the Bluesky service makes a call to the feed URL. The feed then replies with several DIDs of posts, which the Bluesky service hydrates. This is like visiting our online photo gallery, where the service fetches and displays the photos based on the visitor's request.

Conclusion

And there you have it! We've walked through the process of deploying a Bluesky feed generator using AWS services, specifically AWS CDK, Fargate, Lambda, and Aurora Serverless. This setup allows us to parse the Bluesky event stream, store relevant events in a database, and serve the feed using a serverless architecture. It's like setting up a fully automated photography studio that captures, stores, and displays photos based on specific criteria.

But this is just the beginning. There are countless ways you could expand on this setup to suit your specific needs or explore new possibilities. Here are a few ideas to get you started:

Customize Your Feed Algorithm: The feed algorithm we used in this example is relatively simple, focusing on posts from specific authors. You could expand on this by incorporating more complex criteria, such as keywords, hashtags, or even sentiment analysis. This would be like using advanced filters or editing techniques to select and enhance your photos.
Integrate with Other Services: You could integrate your feed generator with other AWS services or third-party APIs to add more functionality. For example, you could use AWS Comprehend to analyze the sentiment of posts, AWS Translate to support multiple languages, or AWS SNS to send notifications when new posts are added to the feed.
Create a User Interface: While Bluesky provides a platform to view the feeds, you could also create your own user interface to display the feeds in a unique way. This could be a web app, a mobile app, or even an Alexa skill. This would be like creating your own online gallery or photo app to showcase your photos.
Scale Up: Our setup is designed to be scalable, but you could take this further by implementing more advanced scaling strategies. For example, you could use AWS Auto Scaling to automatically adjust the capacity of your Fargate service based on demand, or AWS ElastiCache to improve the performance of your database.
Secure Your Setup: While we've implemented basic security measures, there's always more you can do to protect your data and your users. You could use AWS Shield for DDoS protection, AWS WAF for web application firewall, or AWS Macie to discover, classify, and protect sensitive data.

Remember, the sky's the limit when it comes to what you can achieve with AWS services and Bluesky. So don't be afraid to experiment, innovate, and create something truly unique.

Destroy THEIR Stacks - Ephemeral CDK Stacks as a Service

Matt Martz — Thu, 29 Jun 2023 15:53:02 +0000

In this post, we will enhance our ephemeral stack architecture by consolidating the destruction process to a central service. We will utilize a stack lifetime tag in conjunction with the MakeDestroyable aspect from the @aws-community/ephemeral npm library.

Ephemeral stacks are temporary stacks in AWS that are designed to exist for a short period of time. This is particularly useful in development environments where you want to test something but dont need the stack to be up indefinitely.

This article is a follow-up to two previous posts on the topic of ephemeral stacks:

The Value of Ephemeral Stacks

But why would you want to use ephemeral stacks?

Cost Savings 💰 : By using resources only for the time needed, you can significantly reduce costs. You no longer have to worry about unused resources accumulating costs because the stacks self-terminate after the stipulated period.
Efficient Resource Allocation 🔄 : In fast-paced development environments, resources are constantly being allocated and deallocated. Ephemeral stacks make this process more efficient, ensuring that resources are available when needed and are released when no longer in use.
Reduced Complexity 🧠 : Keeping track of which resources are actively being used can be a complex task. By using ephemeral stacks, you know that any active resource is being used for a good reason. This reduces the complexity of managing your infrastructure.
Enhanced Security 🔒 : Minimizing the lifespan of your stacks reduces the exposure window for potential security vulnerabilities. By limiting the duration a resource is up, you inherently limit the time it can be exploited.
Realistic Testing Environments 🧪: Ephemeral stacks are great for simulating production environments without the permanence. They allow you to conduct realistic tests and experiments, enabling you to glean insights and identify issues that might not be evident in traditional development environments.
Simplified Clean-Up 🧹: Forget the days of manually cleaning up resources post-testing. With the self-destruction aspect of ephemeral stacks, the clean-up is automatic. This not only saves time but also ensures that no remnants are left behind that can cause clutter or additional costs.
Easy Scalability for Temporary Needs : Sometimes you need to scale resources quickly to meet a temporary need (e.g., a one-time data processing job). Ephemeral stacks allow for such scalability without the long-term commitment.

Armed with these benefits, its clear that ephemeral stacks are an incredibly powerful tool for optimizing AWS resource management, especially in development environments. Let's dive into how we can further improve the architecture by consolidating the destruction process.

Understanding the Key Components

We will go through the changes to the @aws-community/ephemeral npm library and demonstrate how it can be used.

The code for the @aws-community/ephemeral npm library is here: https://github.com/aws-community-projects/ephemeral

The example project that uses it is here: https://github.com/martzcodes/blog-ephemeral

The DestroyMe Stack and Construct

The DestroyMeConstruct uses the SelfDestructAspect from previous posts to ensure that all of the AWS Resources in the stack are set to a DESTROY retention policy. Additionally, it sets a STACK_LIFE tag on the stack, which indicates how long the stack should remain if there are no updates to it. This tag will be used by an external service to pick up and process the stack for destruction. Heres the code snippet for this part:

Tags.of(Stack.of(this)).add('STACK_LIFE', duration.toSeconds().toString());
Aspects.of(Stack.of(this)).add(new SelfDestructAspect());

DestroyMeStack is a higher-level construct that simply includes DestroyMeConstruct, making it convenient to extend.

The Destroyer Stack

The DestroyerStack is the core of this enhancement. Instead of having each stack deploy a step function that will self-destroy, which could lead to conflicts or complications, we centralize the destruction process.

DestroyerStack uses AWS Service Events from CloudFormation to detect stacks that have the STACK_LIFE tag. Every time a CDK Stack deploys, it generates a CloudFormation Stack Status event. Using this event, we can fetch the stack details, including the tags, and determine if we should track the stack for deletion.

If the stack has the STACK_LIFE tag, we add an entry into a DynamoDB table with a TimeToLive (TTL) property. This TTL is the sum of the current time and the stack life duration. When DynamoDB removes the item due to TTL expiration, we trigger a Lambda function to delete the stack.

Here's how the table is created:

const tableName = 'destroyer';
const table = new Table(this, tableName, {
  tableName,
  partitionKey: {
    name: 'pk',
    type: AttributeType.STRING,
  },
  billingMode: BillingMode.PAY_PER_REQUEST,
  removalPolicy: RemovalPolicy.DESTROY,
  timeToLiveAttribute: 'ttl',
  stream: StreamViewType.NEW_AND_OLD_IMAGES,
});

In case the stack deletion fails, we can also track the DELETE FAILED status and send notifications to an SNS Topic for manual intervention.

const failTopic = new Topic(this, 'fail-topic');
new Rule(this, 'delete-failed-rule', {
  eventPattern: {
    source: ['aws.cloudformation'],
    detailType: ['CloudFormation Stack Status Change'],
    detail: {
      resourceStatus: ['DELETE_FAILED'],
    },
  },
  targets: [new SnsTopic(failTopic)],
});

CloudFormation Event Function

This Lambda function is triggered by AWS Service Events. It retrieves information from the CloudFormation service and writes to the DynamoDB table.

Here's how the Lambda function is configured:

const cloudformationFn = new NodejsFunction(this, 'fn-cloudformation', {
  runtime: Runtime.NODEJS_18_X,
  memorySize: 1024,
  timeout: Duration.minutes(5),
  entry: join(__dirname, local ? 'destroyer-stack.fn-cloudformation.ts' : 'destroyer-stack.fn-cloudformation.js'),
  initialPolicy: [
    new PolicyStatement({
      effect: Effect.ALLOW,
      actions: [
        'cloudformation:Describe*',
        'cloudformation:Get*',
        'cloudformation:List*',
      ],
      resources: ['*'],
    }),
  ],
});
table.grantReadWriteData(cloudformationFn);
cloudformationFn.addEnvironment('DESTROY_TABLE_NAME', table.tableName);

And then we trigger the lambda on those AWS Service Events:

new Rule(this, 'cloudformation-rule', {
  eventPattern: {
    source: ['aws.cloudformation'],
    detailType: ['CloudFormation Stack Status Change'],
  },
  targets: [new LambdaFunction(cloudformationFn)],
});

In our case we don't really care if the stack successfully deployed or not. We reset the ttl with every deployment (failure or not). Since a developer is actively working on the project, we don't want to delete it.

The lambda handler code simply describes the stack and if the STACK_LIFE tag exists, it puts the item into DynamoDB with the StackName as the primary key.

const StackName = event.detail['stack-id'];
const describeCommand = new DescribeStacksCommand({
StackName,
});
const stacks = await cf.send(describeCommand);
const stack = stacks.Stacks?.[0];
const stackLife = stack?.Tags?.find((tag) => tag.Key === 'STACK_LIFE')?.Value;
if (stackLife) {
    try {
      await ddbDocClient.send(
        new PutCommand({
          TableName: process.env.DESTROY_TABLE_NAME,
          Item: {
            pk: stack.StackName,
            ttl: Math.ceil(new Date().getTime() / 1000 + Number(stackLife)),
          },
        }),
      );
    } catch (e) {
      console.log(e);
    }
}

Destroy Function

The destroy function operates similarly. We make sure that it is triggered from the DynamoDB Stream and that it has access to cloudformation:DeleteStack.

destroyFn.addEventSource(
  new DynamoEventSource(table, {
    startingPosition: StartingPosition.LATEST,
  }),
);
destroyFn.addToRolePolicy(
  new PolicyStatement({
    actions: ['cloudformation:DeleteStack'],
    resources: ['*'],
    effect: Effect.ALLOW,
  }),
);

The destroy function handler code filters the dynamodb stream records to make sure that the item is being removed and the the ttl is actually expired. For safety there's an escape hatch that you can remove an item from DynamoDB if it's before the expiration, and it won't delete the stack.

const currentTimeInSeconds = new Date().getTime() / 1000;
if (item.ttl > currentTimeInSeconds) {
  // item was manually removed and not expired
  console.log('item was manually removed and not expired', currentTimeInSeconds, item.ttl);
  return [...p];
}

Then it removes the the valid expired stacks:

const client = new CloudFormationClient({});
await Promise.all(
  stacksToDestroy.map(
    async (stackName) =>
      await client.send(
        new DeleteStackCommand({
          StackName: stackName,
        }),
      ),
  ),
);

How to Use @aws-community/ephemeral

Example Code for this section is located here: https://github.com/martzcodes/blog-ephemeral

First, you need to deploy the DestroyerStack. You can do this in a separate project or by manually deploying the stack with npx cdk deply DestroyerStack

import { DestroyerStack } from '@aws-community/ephemeral';

const app = new cdk.App();
new DestroyerStack(app, 'DestroyerStack');

Once the DestroyerStack is in-place and monitoring the AWS Service Events, you can make any of your stacks ephemeral by extending the DestroyMeStack or adding the DestroyMeConstruct.

Here, we have extended the stack:

import { DestroyMeStack, DestroyMeStackProps } from '@aws-community/ephemeral';
import { Construct } from 'constructs';

export class BlogEphemeralStack extends DestroyMeStack {
  constructor(scope: Construct, id: string, props: DestroyMeStackProps) {
    super(scope, id, props);
    // your stuff here
  }
}

and then we can deploy it using npx cdk deploy EphemeralStack

new BlogEphemeralStack(app, 'EphemeralStack', {
  destroyMeEnable: true,
  destroyMeDuration: cdk.Duration.minutes(3),
});

It is important to note that the Dynamo TTL timing is NOT exact

TTL typically deletes expired items within a few days. Depending on the size and activity level of a table, the actual delete operation of an expired item can vary. Because TTL is meant to be a background process, the nature of the capacity used to expire and delete items via TTL is variable (but free of charge).

If you need to delete the stack sooner, you can manually do it or delete the item from DynamoDB after the ttl has expired.

Conclusion

In this blog post, we dove into enhancing our ephemeral stack architecture by centralizing the stack destruction process and employing a stack life tag with the MakeDestroyable aspect from the @aws-community/ephemeral npm library. This approach ensures that all of the AWS resources in the stack are set to a DESTROY retention and also sets a STACK_LIFE tag, indicating the lifetime of the stack in the absence of updates.

To summarize the key enhancements:

Centralized Destruction Service : The centralization of destruction using the DestroyerStack minimizes the risks of conflicts and complications, making it more efficient.
AWS Service Events : Utilizing AWS Service Events to detect stacks with the STACK_LIFE tag enables automation and efficiency in monitoring and managing the lifetime of resources.
Automated Cleanup : The architecture now has an automated cleanup mechanism, which will be triggered based on the STACK_LIFE tag, and if there's a failure in the cleanup process, you will be notified via SNS.
Enhanced Resource Management : With this setup, resources can be more efficiently managed, particularly during development stages where resource provisioning might be ephemeral.

This enhancement is particularly beneficial for DevOps environments, where teams frequently create and destroy resources for testing and development purposes. By automating the destruction of temporary resources, teams can ensure that only necessary resources are retained, leading to cost savings and more manageable infrastructure.

However, do remember that the timing for deletion with DynamoDB's TTL is not precise. If you require more exact timing for resource cleanup, additional manual steps may be necessary.

By integrating these enhancements into your ephemeral stack architecture, youll enable more streamlined, automated, and efficient resource management within your AWS environment.

Creating an Aurora MySQL Database and Setting Up a Kinesis CDC Stream with AWS CDK

Matt Martz — Mon, 26 Jun 2023 15:39:26 +0000

Welcome to this comprehensive guide where we will be using the AWS Cloud Development Kit (CDK) to create an Aurora MySQL Database, initialize it using Custom Resources, and set up a Change Data Capture (CDC) Stream with Amazon Data Migration Service (DMS) and Kinesis.

This post builds upon the concepts introduced in How to Use BinLogs to Make an Aurora MySQL Event Stream. Instead of relying on a lambda to parse the BinLog periodically, we'll be leveraging the capabilities of AWS DMS. The future integration of Serverless DMS with CloudFormation promises to further enhance this system.

You can find the code for this project on GitHub.

To ensure clarity and organization, our project will be structured into two separate stacks: the DatabaseStack and the DMS Stack. The DatabaseStack includes the VPC, the Aurora MySQL database, and the lambdas responsible for initializing and seeding the database. The DMS Stack encompasses DMS, the CustomResources that manage the DMS Replication Task, and the target Kinesis Stream.

This division allows us to accommodate those who already have a VPC and Aurora MySQL database in place. If you fall into this category, you can easily integrate your existing resources into the DMS stack.

Step 1: Creating the VPC and Aurora MySQL Database

Our first step is to create the DatabaseStack, which involves setting up the Aurora MySQL database and the VPC. You can find the code for this step here.

When creating the VPC, it's crucial to ensure that it includes a NAT Gateway. This gateway allows instances in a private subnet to connect to the internet or other AWS Services while preventing inbound connections from the internet. This is essential because our resources within the VPC need to communicate with AWS Services. Fortunately, VPCs are equipped with a NAT Gateway by default.

const vpc = new Vpc(this, "vpc", {
  maxAzs: 2,
});

Next, we create the database cluster using the appropriate code.

const db = new DatabaseCluster(this, "db", {
  clusterIdentifier: `db`,
  credentials: Credentials.fromGeneratedSecret("admin"),
  defaultDatabaseName: dbName,
  engine: DatabaseClusterEngine.auroraMysql({
    version: AuroraMysqlEngineVersion.VER_3_03_0,
  }),
  iamAuthentication: true,
  instanceProps: {
    instanceType: InstanceType.of(InstanceClass.T4G, InstanceSize.MEDIUM),
    vpc,
    vpcSubnets: {
      onePerAz: true,
    },
  },
  removalPolicy: RemovalPolicy.DESTROY,
  parameters: {
    binlog_format: "ROW",
    log_bin_trust_function_creators: "1",
    // https://aws.amazon.com/blogs/database/introducing-amazon-aurora-mysql-enhanced-binary-log-binlog/
    aurora_enhanced_binlog: "1",
    binlog_backup: "0",
    binlog_replication_globaldb: "0"
  },
});
db.connections.allowDefaultPortInternally();

Now that the database is created, we need to initialize the schema. We achieve this by utilizing a CustomResource, which triggers actions during a CloudFormation stack deployment. In our case, we'll trigger a lambda function that connects to the database and creates a table. This CustomResource can also be used to create users or seed the database with data, but for now, we'll focus on creating an empty table.

The first step in this process is to create the lambda. We ensure that the lambda has access to the database's secret (which is automatically created) with db.secret?.grantRead(initFn). This secret contains the credentials that the lambda needs to connect to the database.

const initFn = new NodejsFunction(this, `db-init`, {
  ...lambdaProps,
  entry: join(__dirname, "lambda/db-init.ts"),
  environment: {
    SECRET_ARN: secret.secretArn,
    DB_NAME: dbName,
    TABLE_NAME: tableName,
  },
  vpc,
  vpcSubnets: {
    onePerAz: true,
  },
  securityGroups: db.connections.securityGroups,
});
db.secret?.grantRead(initFn);
initFn.node.addDependency(db);

The lambda handler code is responsible for creating the table, and we ensure that this action is carried out when the stack is created:

import type {
  CloudFormationCustomResourceEvent,
  CloudFormationCustomResourceFailedResponse,
  CloudFormationCustomResourceSuccessResponse,
} from 'aws-lambda';

import { getConnectionPool } from './utils/connection';

export const handler = async (
  event: CloudFormationCustomResourceEvent,
): Promise<CloudFormationCustomResourceSuccessResponse | CloudFormationCustomResourceFailedResponse> => {
  switch (event.RequestType) {
    case 'Create':
      try {
        const connection = await getConnectionPool();

        await connection.query(
          "CALL mysql.rds_set_configuration('binlog retention hours', 24);"
        );

        await connection.query(`DROP TABLE IF EXISTS ${process.env.DB_NAME}.${process.env.TABLE_NAME};`);
        await connection.query(`CREATE TABLE ${process.env.DB_NAME}.${process.env.TABLE_NAME} (id INT NOT NULL AUTO_INCREMENT, example VARCHAR(255) NOT NULL, PRIMARY KEY (id));`);

        return { ...event, PhysicalResourceId: `init-db`, Status: 'SUCCESS' };
      } catch (e) {
        console.error(`initialization failed!`, e);
        return { ...event, PhysicalResourceId: `init-db`, Reason: (e as Error).message, Status: 'FAILED' };
      }
    default:
      console.error('No op for', event.RequestType);
      return { ...event, PhysicalResourceId: 'init-db', Status: 'SUCCESS' };
  }
};

To ensure that the lambda is invoked as part of the stack deployment, we create a provider for the lambda and a CustomResource. The provider specifies the lambda to be invoked, and the CustomResource triggers the invocation when the stack is deployed. This ensures that the database initialization is fully integrated into the stack deployment process.

const initProvider = new Provider(this, `init-db-provider`, {
  onEventHandler: initFn,
});

new CustomResource(this, `init-db-resource`, {
  serviceToken: initProvider.serviceToken,
});

Step 2: Understanding CloudFormation and DMS Streams

DMS Change Data Capture replication relies on MySQL's Binlog. To enable DMS, binlog must be enabled in MySQL. When creating the database in the previous step, we included parameters that enable Aurora's enhanced binlog for improved performance. More information about this feature can be found here.

binlog_format: "ROW",
log_bin_trust_function_creators: "1",
aurora_enhanced_binlog: "1",
binlog_backup: "0",
binlog_replication_globaldb: "0"

Moving on, we can now create the stack that contains the DMS Replication Task and Kinesis stream. You can access the relevant code here.

First, we create the Kinesis stream that will serve as the target for the events.

const dbStream = new Stream(this, `db-stream`, {
  streamName: `db-stream`,
  streamMode: StreamMode.ON_DEMAND,
});

DMS requires a role called dms-vpc-role to function correctly, but it doesn't have the necessary permissions by default. Therefore, we need to manually create this role.

const dmsRole = new Role(this, `dms-role`, {
  roleName: `dms-vpc-role`, // need the name for this one
  assumedBy: new ServicePrincipal("dms.amazonaws.com"),
});
dmsRole.addManagedPolicy(
  ManagedPolicy.fromManagedPolicyArn(this, `AmazonDMSVPCManagementRole`, `arn:aws:iam::aws:policy/service-role/AmazonDMSVPCManagementRole`)
);

Next, we create the Replication Subnet Group that DMS will use to connect to the database. Since it would attempt to create the dms-vpc-role with the wrong permissions, we need to ensure that it uses the existing role we created. This requires adding a dependency between the two resources.

const dmsSubnet = new CfnReplicationSubnetGroup(this, `dms-subnet`, {
  replicationSubnetGroupDescription: "DMS Subnet",
  subnetIds: vpc.selectSubnets({
    onePerAz: true,
  }).subnetIds,
});
dmsSubnet.node.addDependency(dmsRole);

Now we can create the replication instance itself, utilizing the subnet we just created. For simplicity, we are using the smallest instance class, although ideally, we would support using Serverless DMS. Unfortunately, CloudFormation does not yet provide support for this.

const dmsRep = new CfnReplicationInstance(this, `dms-replication`, {
  replicationInstanceClass: "dms.t2.micro",
  multiAz: false,
  publiclyAccessible: false,
  replicationSubnetGroupIdentifier: dmsSubnet.ref,
  vpcSecurityGroupIds: securityGroups.map(
    (sg) => sg.securityGroupId
  ),
});

To enable DMS to connect to Aurora, we need to grant it access to the role created by the database. We accomplish this by manually creating a Role, granting it permission to read the database's secret, and providing it as the source endpoint for DMS.

const dmsSecretRole = new Role(this, `dms-secret-role`, {
  assumedBy: new ServicePrincipal(
    `dms.${Stack.of(this).region}.amazonaws.com`
  ),
});
secret.grantRead(dmsSecretRole);

const source = new CfnEndpoint(this, `dms-source-endpoint`, {
  endpointType: "source",
  engineName: "aurora",
  mySqlSettings: {
    secretsManagerAccessRoleArn: dmsSecretRole.roleArn,
    secretsManagerSecretId: secret.secretName,
  },
});

Since our target is Kinesis, we also need to create a "target" endpoint and assign a role that has access to put records on the Kinesis stream.

const streamWriterRole = new Role(this, `dms-stream-role`, {
  assumedBy: new ServicePrincipal(
    `dms.${Stack.of(this).region}.amazonaws.com`
  ),
});

streamWriterRole.addToPolicy(
  new PolicyStatement({
    resources: [dbStream.streamArn],
    actions: [
      "kinesis:DescribeStream",
      "kinesis:PutRecord",
      "kinesis:PutRecords",
    ],
  })
);

const target = new CfnEndpoint(this, `dms-target-endpoint`, {
  endpointType: "target",
  engineName: "kinesis",
  kinesisSettings: {
    messageFormat: "JSON",
    streamArn: dbStream.streamArn,
    serviceAccessRoleArn: streamWriterRole.roleArn,
  },
});

Finally, we create the replication task itself. We provide a generic table mapping that emits events for changes to any table. It's worth noting that wildcards can be used to restrict the mapping to specific tables if desired. For more information about table mappings take a look at the docs

const dmsTableMappings = {
  rules: [
    {
      "rule-type": "selection",
      "rule-id": "1",
      "rule-name": "1",
      "object-locator": {
        "schema-name": dbName,
        "table-name": "%",
        "table-type": "table",
      },
      "rule-action": "include",
      filters: [],
    },
  ],
};
const task = new CfnReplicationTask(this, `dms-stream-rep`, {
  replicationInstanceArn: dmsRep.ref,
  migrationType: "cdc",
  sourceEndpointArn: source.ref,
  targetEndpointArn: target.ref,
  tableMappings: JSON.stringify(dmsTableMappings),
  replicationTaskSettings: JSON.stringify({
    BeforeImageSettings: {
      EnableBeforeImage: true,
      FieldName: "before",
      ColumnFilter: "all",
    }
  }),
});

Additionally, we provide BeforeImageSettings in the replicationTaskSettings, which enables us to include a before image for row updates, allowing us to infer deltas on table row updates. For Change Data Capture, we are using the migration type cdc since we are not migrating existing data.

Important Considerations for CloudFormation and DMS

CloudFormation can NOT update DMS tasks that are actively running. It also does not automatically start a DMS Replication Task as part of the deployment. In order to get around this we'll set up some CustomResources and enforce their order that one will run before DMS changes, and one will run after.

The "pre" lambda will check if there are changes to DMS in the CloudFormation change set, if there are it will check if DMS is running, and if it is it will stop the task. It will also wait for the task to finish stopping before responding.

const StackName = `${process.env.STACK_NAME}`;
if (!ReplicationTaskArn) {
  ReplicationTaskArn = await getDmsTask({ cf, StackName });
}
const status = await getDmsStatus({ dms, ReplicationTaskArn });
if (status === 'running') {
  if (event.RequestType === 'Delete' || await hasDmsChanges({ cf, StackName })) {
    // pause task
    const stopCmd = new StopReplicationTaskCommand({
      ReplicationTaskArn,
    });
    await dms.send(stopCmd);
    // wait for task to be fully paused
    await waitForDmsStatus({ dms, ReplicationTaskArn, targetStatus: 'stopped' });
  }
}

On the other end, the "post" lambda will do the opposite. It will start (or resume) the DMS replication and wait for it to finish spinning up.

  const startCmd = new StartReplicationTaskCommand({
    ReplicationTaskArn,
    StartReplicationTaskType: "resume-processing",
  });
  await dms.send(startCmd);
  await waitForDmsStatus({
    dms,
    ReplicationTaskArn,
    targetStatus: "running",
  });

Additionally, we set up a lambda function that is invoked by the Kinesis stream. We add the stream as an event source for this lambda function.

const kinesisFn = new NodejsFunction(this, `stream-kinesis`, {
  ...lambdaProps,
  entry: join(__dirname, "lambda/stream-subscriber.ts"),
  tracing: Tracing.ACTIVE,
});

kinesisFn.addEventSource(
  new KinesisEventSource(dbStream, {
    batchSize: 100, // default
    startingPosition: StartingPosition.LATEST,
    filters: [
      { pattern: JSON.stringify({ partitionKey: [`${dbName}.${tableName}`] }) },
    ],
  })
);

Step 3: Testing the Event Stream

With both stacks deployed, we can now test DMS. To facilitate this process, a lambda function has been created, and its code can be accessed here. You can invoke this function using test events via the AWS console.

By logging in to the DMS console, we can observe that the replication task is already running, thanks to the CustomResources.

To view the table statistics for the task, we can see that our schema has been identified. If there were additional tables, they would also be listed here, but in our case, we only have the examples table.

Invoking our seed lambda function will insert a row into the table. After a short time, the table statistics page will reflect the insert operation.

If we invoke a lambda from the kinesis stream, it will get the following event:

{
    "record": {
        "kinesis": {
            "kinesisSchemaVersion": "1.0",
            "partitionKey": "blog.examples",
            "sequenceNumber": "49642050638404656466522708801490648817992453925189451794",
            "data": "ewoJImRhdGEiOgl7CgkJImlkIjoJMSwKCQkiZXhhbXBsZSI6CSJoZWxsbyA2MzkiCgl9LAoJIm1ldGFkYXRhIjoJewoJCSJ0aW1lc3RhbXAiOgkiMjAyMy0wNi0yNVQxNToyMToxNC4wNTUxMzdaIiwKCQkicmVjb3JkLXR5cGUiOgkiZGF0YSIsCgkJIm9wZXJhdGlvbiI6CSJpbnNlcnQiLAoJCSJwYXJ0aXRpb24ta2V5LXR5cGUiOgkic2NoZW1hLXRhYmxlIiwKCQkic2NoZW1hLW5hbWUiOgkiYmxvZyIsCgkJInRhYmxlLW5hbWUiOgkiZXhhbXBsZXMiLAoJCSJ0cmFuc2FjdGlvbi1pZCI6CTEyODg0OTAyNjA5Cgl9Cn0=",
            "approximateArrivalTimestamp": 1687706474.102
        },
        "eventSource": "aws:kinesis",
        "eventVersion": "1.0",
        "eventID": "shardId-000000000001:49642050638404656466522708801490648817992453925189451794",
        "eventName": "aws:kinesis:record",
        "invokeIdentityArn": "arn:aws:iam::359317520455:role/BlogDmsStreamStack-streamkinesisServiceRole6A79529-7U8Q9JUVULLO",
        "awsRegion": "us-east-1",
        "eventSourceARN": "arn:aws:kinesis:us-east-1:359317520455:stream/db-stream"
    }
}

It's worth noting that Kinesis Base64 encodes the data, so decoding is necessary to make it usable. By decoding the event's data we get the following:

{
    "data": {
        "id": 1,
        "example": "hello 639"
    },
    "metadata": {
        "timestamp": "2023-06-25T15:21:14.055137Z",
        "record-type": "data",
        "operation": "insert",
        "partition-key-type": "schema-table",
        "schema-name": "blog",
        "table-name": "examples",
        "transaction-id": 12884902609
    }
}

By examining the decoded event, we can determine that it was an "insert" operation, and the "data" field contains the full row. In this case, since it was an insert, there is no "before" image.

If a row is updated, the event will contain an image representing the changes.

{
    "parsed": {
        "data": {
            "id": 1,
            "example": "hello 297"
        },
        "before": {
            "id": 1,
            "example": "hello 639"
        },
        "metadata": {
            "timestamp": "2023-06-25T15:50:51.449661Z",
            "record-type": "data",
            "operation": "update",
            "partition-key-type": "schema-table",
            "schema-name": "blog",
            "table-name": "examples",
            "transaction-id": 12884903827
        }
    }
}

From there you could calculate a diff to see that the example column went from hello 639 to hello 297.

Conclusion

In conclusion, this comprehensive guide has provided you with the knowledge and steps necessary to create an Aurora MySQL Database, initialize it using Custom Resources, and set up a Change Data Capture (CDC) Stream with AWS CDK, AWS Data Migration Service (DMS), and Kinesis. By leveraging AWS DMS and event-driven architecture principles, you can unlock the full potential of real-time data replication and event streaming.

As you move forward, there are several ways you can expand on the concepts and ideas covered in this guide. Here are a few suggestions:

Explore Advanced CDC Stream Configurations : Dive deeper into the configuration options available with DMS CDC streams. Experiment with table mappings, filtering options, and advanced settings to tailor the replication process to your specific use cases.
Integrate Additional AWS Services : Consider integrating other AWS services into your event-driven architecture. For example, you could explore using AWS Lambda to process the replicated events, Amazon S3 for data storage, or AWS Glue for data cataloging and ETL operations.
Implement Event-Driven Microservices : Build event-driven microservices that consume the CDC stream events to trigger actions or updates across different systems. Explore how you can use services like AWS Step Functions or AWS EventBridge to orchestrate complex workflows based on the captured events.
Scale and Optimize : Experiment with scaling and optimizing your CDC stream setup. Explore strategies for handling high-velocity data streams, optimizing performance, and implementing fault-tolerant architectures.
Monitor and Analyze : Set up monitoring and analytics solutions to gain insights into your event-driven system. Utilize services like Amazon CloudWatch, AWS X-Ray, or AWS AppSync to track and analyze the performance, reliability, and usage patterns of your CDC stream and associated components.

By expanding on the ideas presented in this guide, you can harness the full potential of a Change Data Capture stream in an event-driven architecture. This approach allows you to build scalable, real-time systems that react to changes in your data and drive intelligent decision-making in your applications. The possibilities for innovation and optimization are vast, so take this foundation and continue exploring the exciting world of event-driven architectures.

Blink and It's Gone: Embracing Ephemeral CDK Stacks for Efficient DevOps

Matt Martz — Tue, 30 May 2023 18:27:45 +0000

I'm excited to announce that I'll be speaking at AWS Summit Washington, DC on June 8th, 2023, at 2:15PM (DEV206). My DevChat will discuss the benefits of ephemeral CDK Stacks for development workflows and CI/CD pipelines. If you're attending, I'd love to see you there and answer any questions you might have.

This post serves as a supplement to my talk (spoilers), providing more insights into ephemeral CDK Stacks, their implementation, and best practices. If you're exploring the topic or haven't yet decided on attending the AWS Summit, I hope this post sparks your interest and encourages you to join me for an engaging discussion. See you there! 🎉

In the fast-paced DevOps world, managing and cleaning up temporary cloud resources can be challenging. Forgotten stacks from testing or PoC stages lead to resource wastage and inflated cloud bills. To address this, ephemeral AWS CDK Stacks are a game changer.

This blog post explores integrating ephemeral CDK Stacks into CI/CD pipelines and development workflows. Powered by Self-Destructing Constructs and CDK Aspects, they automate the cleanup process, ensuring a tidy AWS environment and resource savings.

Ephemeral stacks are a simple yet powerful addition to your DevOps toolkit, streamlining resource management and reducing costs. Let's dive into leveraging ephemeral stacks, saving you from manual cleanup and the perils of forgotten stacks.

Self-Destructing Construct and CDK Aspects

Ephemeral CDK Stacks are made possible by combining the concepts from two of my previous posts on Self-Destructing Constructs and CDK Aspects.

Self-Destructing Constructs : As discussed in my previous post, Say Goodbye to Your CDK Stacks: A Guide to Self-Destruction, these are unique AWS CDK constructs that employ Step Functions to automatically delete the stack after a defined duration. This construct helps ensure that unnecessary resources aren't lingering around, reducing costs and freeing up space in your AWS account.

CDK Aspects : My last post, Breaking Bad Practices with CDK Aspects, explained how CDK Aspects allow for implementing cross-cutting concerns across your stack, such as applying an aggressive removal policy to all resources. When paired with self-destructing stacks, this ensures a clean slate post-destruction, leaving no stray resources behind.

Integrating Ephemeral Stacks with CI/CD Pipelines

CI/CD pipelines, a cornerstone of modern DevOps practices, can greatly benefit from ephemeral CDK Stacks. In a typical CI/CD pipeline, each code commit triggers a process that includes building, testing, and deploying the application. This often involves deploying a stack and, once the tests are executed, cleaning up the resources.

However, sometimes stacks are left behind due to failures in the pipeline or prematurely terminated tests. These forgotten stacks lead to unnecessary costs and clutter. Ephemeral stacks resolve this by auto-deleting after a specific duration, ensuring a clean AWS environment and reducing the wastage of resources.

To illustrate this, let's compare the sequence of events in a typical CI/CD pipeline and one enhanced with ephemeral stacks.

Typical CI/CD pipeline:

In the traditional CI/CD pipeline, the stack is explicitly deleted as part of the pipeline, which could fail or be skipped, resulting in lingering stacks.

CI/CD pipeline with Ephemeral Stacks:

With ephemeral stacks, the stack deletion is automated and independent of the CI/CD pipeline, ensuring that stacks are always cleaned up.

This approach reduces the complexity of your CI/CD pipeline and ensures cleaner resource management in your AWS environment. Additionally, you can set up an aggressive removal policy using CDK Aspects for a more comprehensive cleanup of all resources associated with the stack.

It doesn't sound like a lot, but in practice, it can save hours (over the course of weeks) while ensuring AWS resources (and money) aren't being wasted. 🚀

Implementing Ephemeral Stacks in Development Workflows

Developers often deploy proof of concept (PoC) stacks to test new features, validate concepts, or debug issues. These stacks provide a sandboxed environment to experiment without affecting the production infrastructure. However, once the purpose is served, these stacks often become "forgotten" entities in the cloud environment. They no longer serve a meaningful purpose and, over time, contribute to clutter and unnecessary costs. Implementing ephemeral stacks in development workflows can be an excellent solution to this common oversight.

The Problem of Forgotten Stacks

In the energetic world of development work, the adrenaline rush of solving complex problems or moving onto the next exhilarating task can often eclipse the essential, albeit less exciting, cleanup step. This oversight, often spurred by the thrill of innovation 💡 or the satisfaction of squashing a bug 🐛, can lead to the pile-up of forgotten temporary stacks. Over time, these lingering stacks clutter your environment and inflate your cloud bill 💸.

Consider some common scenarios where these temporary stacks crop up:

Proof of Concept Testing: During the innovation process, PoC stacks are often crafted to assess feasibility or demonstrate the practicality of a concept. Upon approval or rejection of the concept, these stacks fulfill their purpose and, ideally, should vanish 🗑.
Feature Testing: To ensure isolated and accurate testing, developers frequently deploy separate stacks for new features. Once validated and merged into the primary codebase, these stacks have served their purpose and become redundant 🔄.
Debugging: In the process of troubleshooting intricate issues, developers may create replica stacks to isolate and understand the problem. After resolving the issue, these stacks lose their relevance and ought to be removed 🔎.

Let me illustrate this with a personal anecdote to drive the point home:

In my role, I once assumed the responsibility of cleaning up unused stacks in our development accounts. On this particular day, I found myself navigating through and deleting over 200 of these forgotten stacks. As a serverless-first shop, this exercise didn't incur exorbitant costs, but it did consume resources and impacted our resource quotas . This served as a stark reminder of the importance of efficient stack management, and how easily these forgotten stacks can clutter our environment 🧹.

Ephemeral stacks can be the silver bullet to these common oversights, introducing an automated cleanup process to ensure your development environment stays neat, tidy and cost-effective 💰.

The Ephemeral Stack Solution

Ephemeral stacks can serve as a fail-safe, ensuring that even if a developer forgets to delete a stack, it won't linger indefinitely. By setting a self-destruct timer at the time of stack creation, developers can rest easy knowing the stack will automatically clean itself up after a specific period.

Here's how this can be integrated into the common scenarios mentioned above:

Proof of Concept Testing : Set the stack to auto-delete after the meeting where the PoC will be demonstrated. This way, if the concept is rejected, the stack is automatically cleaned up. If the concept is approved, the stack can be manually preserved or redeployed as a more permanent resource.
Feature Testing : Set a short lifespan for the stack perhaps a few hours or a day to allow for feature validation. After that period, the stack, if not needed, will self-destruct.
Debugging : Given the unpredictable nature of debugging, a slightly longer lifespan could be set. Once the issue is resolved, if the developer forgets to clean up, the stack will still auto-delete after the set duration.

Integrating ephemeral stacks into your development workflow can lead to more efficient resource utilization, a cleaner cloud environment, and cost savings. It's a practical way to safeguard against human error without adding an extra burden on the developers.

Best Practices and Practical Insights

Incorporating ephemeral stacks into your development workflow requires careful planning and adherence to best practices. Here are some insights to help you avoid common pitfalls and get the most out of self-destructing stacks.

Set a Reasonable Lifespan

While the primary goal is to prevent forgotten stacks from lingering, setting the self-destruction timer too short might interrupt development or testing work. Consider the typical time required for the task at hand and add some buffer to determine the optimal lifespan.

Integrate with CI/CD Pipeline

To get the most out of ephemeral stacks, they should be integrated with your CI/CD pipeline. This ensures that the stacks are created as part of your automated testing and deployment process and that they clean up after themselves when no longer needed.

Manage Permissions Carefully

Remember, self-destructing stacks need permission to delete resources. Ensure that these permissions are granted judiciously, keeping in line with the principle of least privilege. Be especially cautious when dealing with production environments.

Clearly Label Ephemeral Stacks

To avoid confusion and potential mishaps, it's important to clearly label ephemeral stacks. This could be through a naming convention or tagging. Clear labels also make it easier to locate and manage these stacks in the AWS Management Console.

Employ a Monitoring System

While the self-destruction mechanism should work reliably, it's a good idea to have a monitoring system in place. This will alert you to any stacks that didn't delete as expected or if there are any issues with the self-destruction process.

Consider Exceptions

Not every stack should be ephemeral. Some stacks may need to persist for longer periods for certain tasks, like long-running data processing or scenarios where manual intervention is required. Ensure that your system allows for such exceptions.

Educate Your Team

Finally, make sure that your development team is fully aware of the ephemeral stack concept and its implications. They should understand the purpose, the lifespan of these stacks, and what they can expect during the self-destruction process.

Implementing ephemeral stacks requires more than just technical setup it's a shift in the development mindset. With proper planning and adherence to these best practices, you can seamlessly integrate ephemeral stacks into your development workflow, leading to more efficient resource utilization and cost savings.

Conclusion

In the realm of DevOps, resource management efficiency is critical, and ephemeral CDK Stacks provide a practical, automated solution to a common problem. By incorporating these self-destructing constructs into your CI/CD pipelines and development workflows, you can ensure the timely cleanup of temporary stacks, reducing resource wastage and maintaining a cleaner AWS environment.

Ephemeral stacks offer a powerful combination of convenience and economy, alleviating developers from the burden of manual cleanup and saving valuable time and costs. They also guard against human error and oversight, a common cause of lingering, unnecessary cloud resources.

Remember, the effective implementation of ephemeral stacks involves more than just technical setup. It also requires a shift in mindset, careful planning, and adherence to best practices. But with these in place, ephemeral stacks can become a vital part of your DevOps toolkit, promoting efficiency, tidiness, and cost-effectiveness in your cloud journey.

Breaking Bad Practices with CDK Aspects

Matt Martz — Wed, 17 May 2023 13:58:16 +0000

In the ever-evolving landscape of cloud infrastructure, AWS Cloud Development Kit (CDK) continues to stand as a groundbreaking tool, simplifying the process of defining cloud resources. Within this universe, Aspectsa feature within CDKhold a distinctive position. Aspects act as autonomous agents within your CDK constructs, systematically traversing and applying consistent modifications.

This article aims to dissect the intricacies of CDK Aspects, shedding light on their fundamental purpose, operation, and advanced use cases. Aspects, in many ways, embody the balance between consistency and flexibility in cloud infrastructure development, a concept that's growing increasingly important in this era of complex, scalable applications.

Whether you are a seasoned AWS CDK user or a newcomer looking to expand your cloud development toolkit, this deep dive into CDK Aspects will provide valuable insights into this powerful feature. As we peel back the layers, you'll discover how Aspects can enhance resource management, improve security protocols, and promote code efficiency. Let's 'cook' up some knowledge on CDK Aspects.

The example code for this repository is located here: https://github.com/martzcodes/blog-aspects

This article by @JannikWempe is another great resource: https://aws.hashnode.com/the-power-of-aws-cdk-aspects

Understanding CDK Aspects - The Basics

At its core, the AWS Cloud Development Kit (CDK) is a software development framework that allows developers to define cloud infrastructure in code. This is where CDK Aspects come into play. Aspects are a feature within CDK that act like intelligent filters, traversing your code, identifying specific constructs, and applying modifications to them.

Consider this simple TypeScript code snippet of an AWS S3 bucket defined using CDK:

import { Stack, StackProps } from 'aws-cdk-lib';
import { Bucket } from 'aws-cdk-lib/aws-s3';
import { Construct } from 'constructs';

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

    new Bucket(this, 'MyBucket', {
      versioned: false,
    });
  }
}

Now, let's say you want to ensure that every S3 bucket in your CDK application has versioning enabled. With CDK Aspects you can do this in two ways.

Validation - Create a CDK Aspect to validate all Buckets in the Stack and throw an Error if it is not set
Modification - Create a CDK Aspect to automatically set the versioned property on all buckets

In this context, your CDK code is like a complex chemistry experiment that needs careful management to prevent unwanted reactions.

Validation (the Chemistry Professor): In the validation role, the Chemistry Professor is like a vigilant observer, watching you perform your experiment. If they notice you're about to mix incompatible substances or your measurements are incorrect, they intervene immediately (throw an error) to prevent a potential disaster and ensure the effectiveness of your experiment.
Modification (the Chemistry Assistant): In the lab, an Assistant stands by to help with the experiment, offering a slight adjustment to ensure the reactions go as planned. They don't conduct the experiment for you but provide just enough assistance to keep you on track. This is akin to the modification role of Aspects, which scan your constructs and make slight but important tweaks to ensure consistency and conformity to standards.

To draw the parallel back to our CDK Aspects, the Aspect could, like a Chemistry Assistant, automatically adjust certain aspects of your resources (like enabling versioning for all S3 buckets), ensuring your infrastructure maintains the proper 'formula' throughout its configuration.

Here's how you might define that Aspect:

// For validation
export class ValidateVersioningAspect implements IAspect {
  public visit(node: IConstruct): void {
    if (node instanceof CfnBucket) {
      if (!node.versioningConfiguration
        || (!Tokenization.isResolvable(node.versioningConfiguration)
            && node.versioningConfiguration.status !== 'Enabled')) {
              Annotations.of(node).addError('Bucket versioning is not enabled');
      }
    }
  }
}

const app = new App();
const stack = new MyCDKStack(app, 'MyStack');
Aspects.of(stack).add(new ValidateVersioningAspect());

In this code, the ValidateVersioningAspect Aspect will add an error Annotation if it finds an S3 bucket with versioning disabled, ensuring that all S3 buckets comply with the requirement for versioning to be enabled. On synth, the error would look like this:

[Error at /MyTestStack/MyBucket/Resource] Bucket versioning is not enabled

Found errors

Annotations can also be tested and have support from CDK's built-in assertions: https://docs.aws.amazon.com/cdk/api/v2/docs/aws-cdk-lib.assertions.Annotations.html

// For modification
export class EnableVersioningAspect implements IAspect {
  public visit(node: IConstruct): void {
    if (node instanceof CfnBucket) {
      if (!node.versioningConfiguration
        || (!Tokenization.isResolvable(node.versioningConfiguration)
            && node.versioningConfiguration.status !== 'Enabled')) {
              node.versioningConfiguration = {
                status: 'Enabled'
              };
      }
    }
  }
}

const app = new App();
const stack = new MyCDKStack(app, 'MyStack');
Aspects.of(stack).add(new EnableVersioningAspect());

In this code, the EnableVersioningAspect class defines an Aspect that will "visit" every construct in the stack. If the construct is an instance of the Bucket class, the Aspect will set its versioned property to true, effectively enabling versioning for every bucket in the stack.

Deep Dive into CDK Aspects

In this section, we'll delve deeper into the inner workings of CDK Aspects and uncover the magic behind the scenes. We'll explain the crucial role of the visit method, discuss the Aspects.of(scope).add(aspect) pattern, and illustrate how Aspects interact with the CDK's synthesis process. When using Aspects, it's crucial to be aware of how the AWS CDK uses tokenization to manage resources' properties.

The `visit` Method

At the heart of any CDK Aspect is the visit method. As an implementer of the IAspect interface, this method is called when the Aspect is applied to a construct. The visit method takes a single argumentIConstructwhich is the construct the Aspect is visiting. What you do inside this method is the meat of your Aspect: whether you choose to throw an error for validation, or modify a property of the construct.

The Intricacies of Tokenization in AWS CDK

Tokens are placeholders used by the CDK to represent values that are not known until deployment time. For example, if you create an S3 bucket without specifying a bucket name, CDK generates a unique name and represents it with a token in your code.

When you inspect the bucketName property during the visit method, you might expect to see an actual bucket name. However, you'll instead see a token, something like ${Token[TOKEN.12]}.

The tokenization system can lead to unexpected results when using Aspects. For instance, if you attempt to modify a property that uses a token, your Aspect might not behave as expected. This is because tokens aren't resolved until the CDK synthesizes your app into a CloudFormation template.

Here's an example:

export class TokenAwareAspect implements IAspect {
  visit(node: IConstruct): void {
    if (node instanceof Bucket) {
      console.log(`Bucket name is ${node.bucketName}`);
    }
  }
}

const app = new App();
const stack = new Stack(app, 'MyStack');
new Bucket(stack, 'MyBucket');
Aspects.of(stack).add(new TokenAwareAspect());

In the console output, you'll see a token as the bucket name, not a real bucket name. Keep this in mind when designing your Aspects!

Applying Aspects

The Aspects.of(scope).add(aspect) pattern is the standard way to apply an Aspect to a construct. In this pattern, Aspects.of(scope) returns an Aspects object associated with a construct, and add(aspect) adds an Aspect to this object. The scope here could be any construct to which you want to apply the Aspecttypically an instance of a Stack or an App.

Aspects and the Synthesis Process

CDK Aspects play a crucial role during the CDK's synthesis process. The synthesis process is a multi-stage operation where CDK translates your code into a CloudFormation template, which AWS can understand. During this process, Aspects are invoked after the construct tree has been fully initialized, but before synthesis. This allows Aspects to validate or modify constructs right before the CloudFormation templates are generated.

Just as Skyler White had to understand the sequence of money laundering, let's delve deeper into the sequence of CDK Aspects with a diagram.

sequenceDiagram
    participant User
    participant CDK App
    participant Aspect
    participant CloudFormation
    User->>CDK App: Runs CDK Synth
    CDK App->>CDK App: Initializes Construct Tree
    CDK App->>Aspect: Invokes Aspects
    Aspect-->>CDK App: Validates/Modifies Constructs
    CDK App->>CloudFormation: Generates CloudFormation Template

CDK Aspects in Action: An Architecture Diagram Generator

In this section, we'll explore a concrete example of using CDK Aspects in a real-world scenario. We'll delve into the internals of a recently published npm library, @aws-community/arch-dia, which uses a CDK Aspect to generate a pseudo-architecture diagram of a project. Not only does it visualize your AWS infrastructure, but it also tracks changes between synthesis stages, providing a visual diff.

The Architecture Diagram Aspect

The key component in @aws-community/arch-dia is the ArchitectureDiagramAspect, an implementation of the IAspect interface. This Aspect traverses the constructs in a given Stack to generate a Mermaid diagram representing the architecture of your AWS resources. Here's an overview of the code:

export class ArchitectureDiagramAspect implements IAspect {
  private readonly mermaidDiagram: string[];
  private stackName = '';

  constructor () {
    this.mermaidDiagram = [];
  }

  visit (node: IConstruct): void {
    if (node instanceof Stack) {
      this.stackName = node.stackName;
      this.traverseConstruct(node, '');
    }
  }
  ...
}

This Aspect, like all Aspects, has a visit method. It checks if the visited construct is an instance of the Stack class. If it is, it initiates a traversal of the constructs in that stack.

The traverseConstruct method iteratively visits all children of a given construct, building up a Mermaid diagram string in the process:

private traverseConstruct (construct: IConstruct, parentPath: string): void {
  ...
  construct.node.children.forEach((child) => {
    this.traverseConstruct(child, currentPath);
  });
}

Generating and Comparing Diagrams

Once all constructs have been visited, the Aspect can generate a Mermaid diagram of the entire Stack using the generateDiagram method. This method also handles comparing the newly generated diagram with the previous one, if it exists, to create a visual diff:

generateDiagram (): string {
  ...
  const addedElements = [...newElements].filter((e) => !oldElements.has(e));
  const removedElements = [...oldElements].filter((e) => !newElements.has(e));
  const added = this.mermaidDiagram.filter((line) => !old.includes(line));
  const removed = old.filter((line) => !this.mermaidDiagram.includes(line));
  ...
}

This visual diff highlights the changes between the old and new architectures, providing a clear visualization of how your resources have evolved.

By traversing the constructs in a Stack, @aws-community/arch-dia can generate a visual representation of your AWS resources and track changes over time. This not only aids in understanding and documenting your infrastructure but can also serve as a powerful tool for communicating changes to stakeholders.

Best Practices and Tips: Using CDK Aspects Effectively

Once you've got a handle on the basics of CDK Aspects, here are a few additional best practices and tips to help you use them more effectively.

1. Use Aspects for Cross-Cutting Concerns

CDK Aspects are ideal for applying changes or enforcing rules that cut across different layers or types of resources in your infrastructure. Consider using Aspects when you want to apply a consistent policy or setting across multiple resources, especially when they are of different types.

2. Be Cognizant of the Construct Tree Traversal

CDK Aspects traverse the construct tree using a depth-first approach. This means that the visit method is invoked on a construct only after it has been invoked on all of its children. In certain scenarios, you may need to be aware of this order of traversal to achieve the desired results.

3. Account for CDK Tokenization

As we discussed earlier, the CDK uses tokenization to handle values that aren't known until deployment time. Be aware of this while designing your Aspects, especially when inspecting or modifying properties that might be tokenized. If necessary, consider using the Token.isUnresolved method to check if a value is a token.

4. Avoid Making Changes Outside the Visit Method

The visit method is the only place where you should make changes to constructs when using Aspects. While it might be technically possible to modify constructs outside this method, doing so can lead to unexpected behavior and hard-to-debug issues.

5. Test Your Aspects

As with any code, you should thoroughly test your Aspects. Given that Aspects can modify constructs across your app, a small error in an Aspect can have a broad impact. Consider using the AWS CDK's built-in testing tools, like the aws-cdk-lib/assertions library, to write unit tests for your Aspects.

My example code includes tests for the aspects: https://github.com/martzcodes/blog-aspects/tree/main/test as does the @aws-community/arch-dia library

CDK Aspects offer a powerful way to enforce consistency and automate modifications across your cloud infrastructure code. With these best practices and tips, you'll be well-equipped to use Aspects effectively in your AWS CDK applications. 🚀

Wrap Up

To wrap it up, here are some final thoughts:

Harnessing the Power of Aspects : CDK Aspects are a powerful tool for AWS developers, offering a way to automate cross-cutting concerns and enforce consistency across an entire application. While they may seem complex at first, understanding how they work and how to use them effectively can greatly enhance your AWS CDK toolkit.
Exploration and Experimentation : Don't be afraid to explore and experiment with Aspects. Whether you're trying to create an architecture diagram generator or a recursive Aspect, there's a lot of potential for creative and effective solutions.
Caution and Diligence : Despite their power, it's important to be cautious when working with Aspects. Be aware of potential pitfalls, such as tokenization and the performance implications of using Aspects. Always test your Aspects thoroughly to avoid introducing broad-reaching errors into your application.

In the end, CDK Aspects can be your 'Heisenberg' in managing cloud infrastructure - they have the potential to be influential, powerful, and transforming. They provide a way to simplify and automate many tasks that would otherwise require manual, error-prone work.

Say Goodbye to Your CDK Stacks: A Guide to Self-Destruction

Matt Martz — Wed, 22 Feb 2023 20:29:48 +0000

Are you tired of constantly managing your CDK Stacks and dealing with the associated costs? If so, self-destructing CDK Stacks might be the solution you've been looking for. With the ability to automatically delete themselves after a set time, these stacks can help free up resources and streamline your development process.

In this guide, we'll show you how to set up self-destructing CDK Stacks and integrate them into your CI/CD pipeline. By doing so, you can reduce costs and improve the efficiency of your development process. We'll also share some best practices and tips to help you make the most out of this feature. So, if you're ready to optimize your development process, read on to learn how to implement self-destructing CDK Stacks! 🤯

Code: https://github.com/martzcodes/blog-cdk-self-destruct

What Will We Make?

We'll create a Step Function that will be executed during the deployment of a Stack and will wait for a specified period of time. Since Step Functions are charged based on state transitions, and not the duration of the run, this will not result in additional costs. Additionally, Standard Step Functions can run for up to a year, providing us with plenty of flexibility. Once the Wait period is over, the Step Function will use the AWS SDK to automatically delete the Stack. 🗑️

Creating a SelfDestruct Construct

We're going to get started by creating a new CDK Construct that can be used in any project. The only thing this Construct will need as a property input will be the Duration that we want the stack to destroy itself after.

export interface SelfDestructProps {
  duration: Duration;
}

export class SelfDestruct extends Construct {
  constructor(scope: Construct, id: string, props: SelfDestructProps) {
    super(scope, id);
    const { duration } = props;
  }
}

From here, we're going to want the Step Function to handle a few things. It should:

Re-execute the Step Function on every Stack deployment
Close out old executions on new deployments (only have one execution running at any given time)
Wait for a pre-defined duration
Delete the Stack after the Wait period

List Already Running Step Functions

First, we need to get the list of running executions of this Step Function. We can do that with the states:ListExecutions SDK Command.

const listExecutions = new CallAwsService(this, `ListExecutions`, {
  action: "listExecutions",
  iamAction: "states:ListExecutions",
  iamResources: ["*"],
  parameters: {
    "StateMachineArn.$": "$$.StateMachine.Id",
    StatusFilter: "RUNNING",
  },
  service: "sfn",
});

🏃‍♂️We pass in the StatusFilter: "RUNNING" to make sure we only get back executions that are still in the RUNNING state. Typically there should only be one of these (from the last deployment).

Stop Other Executions

Next we'll want to Map over the returned Executions. Maps are Step Function for-loops, effectively.

const executionsMap = new Map(this, `ExecutionsMap`, {
  inputPath: "$.Executions",
});

In this loop, we're going to want to make sure that the execution isn't going to kill itself (not yet at least). We do this by checking the map item's Execution Id versus the current running execution's Arn:

const stopExecution = new CallAwsService(this, `StopExecution`, {
  action: "stopExecution",
  iamAction: "states:StopExecution",
  iamResources: ["*"],
  parameters: {
    Cause: "Superceded",
    "ExecutionArn.$": "$.ExecutionArn",
  },
  service: "sfn",
});

executionsMap.iterator(
  new Choice(this, "NotSelf?")
    .when(
      Condition.not(
        Condition.stringEqualsJsonPath("$.ExecutionArn", "$$.Execution.Id")
      ),
      stopExecution
    )
    .otherwise(new Pass(this, "self"))
);

$.ExecutionArn refers to the mapped execution's item and $$.Execution.Id refers to the Step Function itself... that is $$ is an escape to "top-level".

Check and Wait to Delete

Next, we can check the State Machine to make sure this resource isn't invoking because of a Stack that is already destroying itself. If it is, we can exit. This is actually very nice because since we just killed the other executions, we're tying up loose ends from previous deployments by making sure that there won't be any executions running.

const wait = new Wait(this, "Wait", {
  time: WaitTime.duration(duration),
});
const wasDelete = new Choice(this, "WasDelete?")
  .when(
    Condition.stringEquals("$$.Execution.Input.Action", "Delete"),
    new Succeed(this, "DeleteSuccess")
  )
  .otherwise(wait);

As part of this, we end up Waiting the duration we set. This could be anywhere from seconds to days (up to 1 year).

After the Wait is over, we need to delete the stack:

const deleteStack = new CallAwsService(this, `DeleteStack`, {
  action: "deleteStack",
  iamAction: "cloudformation:DeleteStack",
  iamResources: ["*"],
  parameters: {
    "StackName.$": "$$.Execution.Input.StackName",
  },
  service: "cloudformation",
});

This is done by an AWS SDK Call cloudformation:DeleteStack.

Creating the State Machine

With all the steps created, we can tie them together to create the actual Step Function:

const finished = new Succeed(this, `Finished`);

listExecutions.next(executionsMap);
executionsMap.next(wasDelete);
wait.next(deleteStack);
deleteStack.next(finished);

const sm = new StateMachine(this, `SelfDestructMachine`, {
  definition: listExecutions,
});

Running the Step Function with Every Deployment

This construct is only useful if it is consistently run with Stack Deployments. So, let's add a Custom Resource that executes the Step Function as part of the Deployment. We can do this with an AwsCustomResource construct:

new AwsCustomResource(this, `SelfDestructCR`, {
  onCreate: {
    action: "startExecution",
    parameters: {
      input: JSON.stringify({
        Action: "Create",
        StackArn: Stack.of(this).stackId,
        StackName: Stack.of(this).stackName,
      }),
      stateMachineArn: sm.stateMachineArn,
    },
    physicalResourceId: PhysicalResourceId.of("SelfDestructCR"),
    service: "StepFunctions",
  },
  onDelete: {
    action: "startExecution",
    parameters: {
      input: JSON.stringify({
        Action: "Delete",
        StackArn: Stack.of(this).stackId,
        StackName: Stack.of(this).stackName,
      }),
      stateMachineArn: sm.stateMachineArn,
    },
    physicalResourceId: PhysicalResourceId.of("SelfDestructCR"),
    service: "StepFunctions",
  },
  onUpdate: {
    action: "startExecution",
    parameters: {
      input: JSON.stringify({
        Action: "Update",
        Version: new Date().getTime().toString(),
        StackArn: Stack.of(this).stackId,
        StackName: Stack.of(this).stackName,
      }),
      stateMachineArn: sm.stateMachineArn,
    },
    physicalResourceId: PhysicalResourceId.of("SelfDestructCR"),
    service: "StepFunctions",
  },
  policy: AwsCustomResourcePolicy.fromSdkCalls({
    resources: [sm.stateMachineArn],
  }),
});

When the Stack deploys it makes a different SDK call based on the type of Stack operation (Create, Update, Delete). Custom Resources only execute when input parameters change. onCreate and onDelete are considered "new" since the stack is being created or destroyed, but in order to make sure the onUpdate call happens we have to touch an input parameter within it. That's why we set the Version to the current time.

Tips for Self-Destruction

💡 Did you notice that the code above didn't explicitly set any IAM permissions? CDK + Step Functions handle all of that for you. By defining the action, and iamActions / services as part of the Step and AwsCustomResource constructs CDK automatically infers IAM permissions and make sure those are attached to the Resources so that they have access to perform their functions!

Creating a DeveloperStack

For a better DevEx you could create a standardized Stack template that includes the self-destruct Construct by default. For example, you could publish BlogCdkSelfDestructStack as your common stack in an npm library:

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

    new SelfDestruct(this, `SelfDestruct`, {
      duration: Duration.minutes(3),
    });
  }
}

When teams create new projects, instead of creating a stack and basing it off of cdk.Stack .... they would base it off of BlogCdkSelfDestructStack which has self-destruction built in!

Automatically Detecting Temporary Stacks

Clearly you don't want your production stacks to delete themselves. Another tip would be to introduce a property into your Base stack that indicates whether it should self-destruct or not. You could do this by stack naming conventions, or have a developer or CI/CD property. For example:

export interface BlogCdkSelfDestructStackProps extends cdk.StackProps {
  cicd?: boolean;
  developer?: boolean;
  production?: boolean;
}
export class BlogCdkSelfDestructStack extends cdk.Stack {
  constructor(scope: Construct, id: string, props: BlogCdkSelfDestructStackProps) {
    super(scope, id, props);
    const { cicd, developer, production } = props;

    if (developer && production) {
      throw new Error("Don't use developer stacks in production");
    }

    if (!production && (developer || cicd)) {
      new SelfDestruct(this, `SelfDestruct`, {
        duration: Duration.minutes(3),
      });
    }
  }
}

And then in your bin file, you would pass in the appropriate properties (which could come from node config, environment variables / etc. CDK Best Practices recommend Configure with properties and methods, not environment variables which is why you would place these properties into your bin file.

Many CI/CD systems have pre-defined system environment variables, and those could be used to automatically detect the CI/CD for self-destruction. For example you could create a namespaced Stack that gets deployed as part of an automated PR integration check. Then succeed or fail the stack would automatiaclly clean up after itself without CI/CD having to do it.

Can I Extend the Wait Without Re-Deploying?

Absolutely! Simply re-execute the Step Function! This will reset the timer giving you more time if you need it.

Conclusion

And just like that, you're a self-destructing CDK Stack pro! You can now confidently say "adios" to stacks that are taking up too much space and draining your resources.

With this newfound knowledge, you can save on infrastructure costs and keep your AWS account looking fresh and tidy. Plus, you'll have the satisfaction of knowing that you're incorporating a little excitement and danger into your development process.

Just remember, with great power comes great responsibility. Be sure to set a reasonable Wait period and test your code thoroughly before deploying. And don't worry, we won't tell anyone if you shed a tear or two as your stacks go boom.

Improving a Serverless App To Cross-Post Blogs

Matt Martz — Tue, 21 Feb 2023 15:44:39 +0000

Allen Helton is an AWS Hero and absolute LEGEND. In December he wrote a post titled "I Built a Serverless App To Cross-Post My Blogs" and after some begging from some AWS Community Builders he published his code to our shiny new AWS Community Projects GitHub Org.

Allen is quite a prolific writer and publishes his articles in (at least) four places. He has a self-hosted static blog built with Amplify using Hugo, as well as using dev.to, hashnode, and medium. His self-hosted blog on his personal domain is his primary platform and dev.to, hashnode, and medium all get canonical URLs for SEO purposes. 🌟

While Allen's code is great, it does have some limitations. For instance, it's written using SAM/yaml, requires a Hugo/Amplify built blog, effectively has no optional features, and he still manually uploads image assets to S3 for all of his articles. 😱

In this article, we'll go over my fork of Allen's code, where I have:

Converted the project to use AWS CDK
Made Hugo/Amplify and most of the other platforms optional 🚀
Added a direct (private) GitHub webhook integration
Automatically parsed images committed to GitHub and uploaded them to a public S3 Bucket (and updated the content to use them)

I'm excited to share these improvements with you and hope you find them useful!

Code: https://github.com/martzcodes/blog-crossposting-automation

Converting the Project to CDK

Let's talk about converting projects from a format, like SAM, to CDK. It can be a bit tricky, but the easiest way is to focus on the architecture. Get the architecture skeleton right first, and everything else will fall into place. 💪

So, looking at Allen's project structure, we can see that he has one DynamoDB table, five lambda functions, and a step function. One lambda is triggered by an Amplify EventBridge Event. That lambda then triggers a step function where the other four lambdas are used. 🤓

To improve this, we're going to make Amplify optional and add the ability to pull images used in GitHub and re-store them in S3, bringing the S3 bucket into our CloudFormation Stack. 🚀

We can start by creating a Construct for the DynamoDB Table lib/dynamo.ts

export class DynamoDb extends Construct {
  table: Table;
  constructor(scope: Construct, id: string) {
    super(scope, id);
    this.table = new Table(this, `ActivityPubTable`, {
      partitionKey: { name: "pk", type: AttributeType.STRING },
      sortKey: { name: "sk", type: AttributeType.STRING },
      billingMode: BillingMode.PAY_PER_REQUEST,
      timeToLiveAttribute: "ttl",
      removalPolicy: RemovalPolicy.DESTROY,
    });

    this.table.addGlobalSecondaryIndex({
      indexName: "GSI1",
      partitionKey: { name: "GSI1PK", type: AttributeType.STRING },
      sortKey: { name: "GSI1SK", type: AttributeType.STRING },
      projectionType: ProjectionType.ALL,
    });
  }
}

We create the secret via CDK (and then manually put the secrets into it):

const secret = Secret.fromSecretNameV2(
  this,
  `CrosspostSecrets`,
  secretName
);

Allen had a single lambda do the data transformations for the three blog services... I opted to split that up for better traceability. My architecture will end up having somewhere between 3-7 lambdas depending on what options you turned on. The lambdas are only created if you pass in the properties. They're all created the same general way (side note... I also updated Allen's code from javascript to TypeScript #scopecreep):

const lambdaProps: NodejsFunctionProps = {
  architecture: Architecture.ARM_64,
  memorySize: 1024,
  timeout: Duration.minutes(5),
  runtime: Runtime.NODEJS_18_X,
  environment: {
    TABLE_NAME: table.tableName,
    SECRET_ID: secret.secretName,
  },
};

const sendApiRequestFn = new NodejsFunction(this, `SendApiRequestFn`, {
  ...lambdaProps,
  entry: join(__dirname, `../functions/send-api-request.ts`),
});
sendApiRequestFn.addEnvironment("DRY_RUN", dryRun ? "1" : "0");
secret.grantRead(sendApiRequestFn);

Finally, we need to create the Step Function. Step Functions are notoriously hard to code since they use Amazon States Language (ASL) to define all of the steps. I created a separate CrossPostStepFunction construct.

My step function adds the ability to pick which service creates the Canonical URL and it will first post to that service... get the canonical URL and use that in the subsequent services. There's also a lot of logic to remove things from the State Machine if properties weren't configured... which makes this very flexible.

We were able to abstract out the process for posting to a service to a State Machine Fragment. This fragment is a CDK construct that allows us to re-use a lot of the underlying logic used in the parallel paths for posting to the services. When I configured my stack to not send status emails, not use Hugo and have Hashnode be the primary blog post we get a Step Function that looks like this:

A lot of this is 1:1 with what Allen had in his ASL json file. One interesting fact is that Allen's JSON is 953 lines while my two files of TypeScript code that make up the Step Function ends up being 596 lines (431 + 165)... so almost half while adding a few additional features.

Adding a Direct GitHub Webhook Integration

For our next trick, we will use GitHub Webhook events to trigger our cross-posting, instead of Amplify Events. We can do this by adding a Function URL to the Identify Content Lambda:

const fnUrl = identifyNewContentFn.addFunctionUrl({
  authType: FunctionUrlAuthType.NONE,
  cors: {
    allowedOrigins: ["*"],
  },
});
new CfnOutput(this, `GithubWebhook`, { value: fnUrl.url });

We can then enter this lambda into our GitHub repo's webhook settings so that it will use the webhook for Push events. This enables us to skip some of the identify lambda's code... since the push event happens for every commit and pre-includes the list of files that were added.

export const handler = async (event: any) => {
  try {
    await initializeOctokit();

    let newContent: { fileName: string; commit: string }[] = [];
    if (event.body) {
      const body = JSON.parse(event.body);
      console.log(JSON.stringify({ body }, null, 2));
      if (body.commits) {
        newContent = body.commits.reduce(
          (
            p: { fileName: string; commit: string }[],
            commit: {
              id: string;
              added: string[];
              modified: string[];
              // ... there is more stuff here, but this is all we need
            }
          ) => {
            const addedFiles = commit.added.filter(
              (addedFile: string) =>
                (!blogPathDefined ||
                  addedFile.startsWith(`${process.env.BLOG_PATH}/`)) &&
                addedFile.endsWith(".md")
            );
            return [
              ...p,
              ...addedFiles.map((addedFile) => ({
                fileName: addedFile,
                commit: commit.id,
              })),
            ];
          },
          [] as { fileName: string; commit: string }[]
        );
      } else {
        const recentCommits = await getRecentCommits();
        if (recentCommits.length) {
          newContent = await getNewContent(recentCommits);
        }
      }
    }
    if (newContent.length) {
      const data = await getContentData(newContent);
      const imagesProcessed = await saveImagesToS3(data);
      await processNewContent(imagesProcessed);
    }
  } catch (err) {
    console.error(err);
  }
};

The webhook's event body includes a list of the commits. The Amplify event doesn't have this same list, so we can save some GitHub API calls here. I think this would also be compatible with Allen's code (just in case he wants to switch to that 😈).

Parse and Store Images in S3

But what do we do about images? My overall idea here (for my personal use) was to use a private GitHub repo to store these posts (to avoid SEO shenanigans) and just use relative image linking within the repo for the draft images... that way I could use VS Code's Markdown Preview or Obsidian.md to draft my posts. I asked Allen what he does and was surprised to hear that he hasn't automated this part yet... and as part of his writing he manually uploads images to S3.

So, I got a little creative with some Regular Expressions and parsed out any embedded markdown links... which are formatted with an exclamation point in front of a markdown link (ironically, I can't post an example because my RegExp would incorrectly ingest that 😅)

const contentData: {
  fileName: string;
  commit: string;
  content: string;
  sendStatusEmail: boolean;
}[] = [];
const imgRegex = /!\[(.*?)\]\((.*?)\)/g;
for (let j = 0; j < newContent.length; j++) {
  const workingContent = { ...newContent[j] };
  const imageSet = new Set<string>([]);
  let match;
  while ((match = imgRegex.exec(newContent[j].content)) !== null) {
    imageSet.add(match[2]);
  }
  const images = [...imageSet];
  if (images.length === 0) {
    // no images in the post... passthrough
    contentData.push(newContent[j]);
    continue;
  }
  const blogFile = newContent[j].fileName;
  const blogSplit = `${blogFile}`.split("/");
  blogSplit.pop();
  const blogBase = blogSplit.join("/");
  const s3Mapping: Record<string, string> = {};
  for (let k = 0; k < images.length; k++) {
    const image = images[k];
    const githubPath = join(blogBase, image);
    const imageSplit = image.split(".");
    const imageExtension = imageSplit[imageSplit.length - 1];
    const s3Path = `${blogFile}/${k}.${imageExtension}`.replace(/\ /g, "-");
    const s3Url = `https://s3.amazonaws.com/${process.env.MEDIA_BUCKET}/${s3Path}`;
    const postContent = await octokit.request(
      "GET /repos/{owner}/{repo}/contents/{path}",
      {
        owner: `${process.env.OWNER}`,
        repo: `${process.env.REPO}`,
        path: githubPath,
      }
    );

    const buffer = Buffer.from((postContent.data as any).content, "base64");

    // upload images to s3
    const putImage = new PutObjectCommand({
      Bucket: `${process.env.MEDIA_BUCKET}`,
      Key: s3Path,
      Body: buffer,
    });
    await s3.send(putImage);

    s3Mapping[image] = s3Url;
  }
  const rewriteLink = (match: string, text: string, url: string) => {
    return `![${text}](${s3Mapping[url]})`;
  }
  workingContent.content = workingContent.content.replace(imgRegex, rewriteLink);
  contentData.push(workingContent);
}
return contentData;

This code parses out the image links, fetches them from GitHub, uploads them to S3 and replaces the public S3 URLs in the blog post before proceeding. I suppose a requirement here is that the images are required to be in GitHub and if they aren't... things will break. That would be an easy thing for someone to fix/make more flexible 😉

Final Thoughts

That was quite the journey! Although this project took me longer than expected, it was still a lot of fun to work on. I had a tough time trying to limit myself from adding more and more features to it. 😂

After spending some time with it, I'm not entirely convinced that the return on investment is worth it for my specific needs. I only post to two platforms, hashnode and dev.to, it's simple enough for me to copy and paste from one to the other and add the canonical URL to the dev.to metadata. In fact, the two platforms even have an integration that might allow me to skip the copy/paste step entirely. 🤔

But even though I may not use this stack myself, I do hope that it showcases the power and flexibility of creating with CDK. In comparing SAM to CDK... the CDK code clocked in at 907 lines of code (including the Step Function + additional features) while the SAM YAML + ASL JSON came in at 1259 lines of configuration.

This project would have been much quicker to build if I already had a Hugo/Amplify setup or if I hadn't converted everything to TypeScript or added all the other features. 😅

What do you think? Have you ever worked on a project that ended up taking longer than you expected? Did you find it hard to limit yourself from adding more and more features? What do you think about the differences between SAM and CDK here? Let's chat about it! 💬

Core Web Vitals, CDK Constructs and YOU!

Matt Martz — Wed, 01 Feb 2023 23:01:53 +0000

As a web developer, you know the importance of delivering a fast and smooth user experience. But with the constantly evolving web landscape, it can be challenging to keep up with the latest best practices. In this blog post, I'll take you through the ins and outs of integrating Core Web Vitals into your development projects. With its focus on real-world user experience, Core Web Vitals is quickly becoming an essential part of any web development process. So buckle up, grab a coffee and let's dive in together to see how you can elevate your website's performance and provide a top-notch user experience for your visitors!

What are Core Web Vitals?

Core Web Vitals are a set of metrics defined by Google to measure the user experience on the web. They focus on the key aspects of website performance that directly impact user experience, such as loading speed, interactivity, and visual stability. The basics of Core Web Vitals are:

Largest Contentful Paint (LCP): measures loading performance and is calculated as the time it takes for the largest content element on the page (e.g. an image or text block) to load and become visible to the user.
First Input Delay (FID): measures interactivity and is calculated as the time it takes for a page to become responsive after a user first interacts with it (e.g. clicks a button).
Cumulative Layout Shift (CLS): measures visual stability and is calculated as the total amount of unexpected layout shifts that occur during the page load.

These metrics are considered important because they directly impact user experience and are tied to search ranking factors. Websites that score well on Core Web Vitals are likely to have better search engine rankings and provide a better user experience. In other words, they lead to:

Happy Users: By optimizing Core Web Vitals, your website will load faster, be more interactive, and have less visual instability. This leads to a better overall user experience, which means visitors will stay on your site longer and be more likely to return in the future.
Better SEO: Google uses Core Web Vitals as part of its ranking algorithm, so websites that score well on these metrics are likely to have better search engine rankings. That means more visibility, more traffic, and more potential customers!
Increased Conversions: A great user experience leads to higher engagement and increased conversions. By optimizing Core Web Vitals, you'll give your visitors a smooth and seamless experience that will keep them coming back for more.
Industry Standard: Core Web Vitals are becoming the industry standard for measuring website performance and user experience. By optimizing these metrics, you'll ensure that your website is up-to-date and providing the best possible experience for your visitors.

Real User Monitoring with CloudWatch RUM and CDK

Let's get started with Core Web Vitals by writing some reusable components: A CDK Construct and Typescript snippet so that we can add CloudWatch RUM (Real User Monitoring) to our application.

The code for this section is located at http://github.com/martzcodes/blog-cdk-rum

We're going to start with a baseline project that includes a simple website deployed to S3 and hosted by a CloudFront distribution. This is similar to the site we created in my article about how to Protect a Static Site with Auth0 Using Lambda@Edge and CloudFront

We're going to focus on the 3 most important files:

CDK Construct

Our RumRunnerConstruct, /lib/rum-runner-construct.ts, will take in two properties to its interface:

bucket - the UI's deployment bucket
cloudFront - the UI's CloudFront distribution

CloudWatch RUM requires a Cognito Identity Pool to allow unauthenticated access for the CloudWatch RUM web client to publish events.

We create the Identity Pool

const cwRumIdentityPool = new CfnIdentityPool(
  this,
  "cw-rum-identity-pool",
  { allowUnauthenticatedIdentities: true }
);

A role for unauthenticated users to use:

const cwRumUnauthenticatedRole = new Role(
  this,
  "cw-rum-unauthenticated-role",
  {
    assumedBy: new FederatedPrincipal(
      "cognito-identity.amazonaws.com",
      {
        StringEquals: {
          "cognito-identity.amazonaws.com:aud": cwRumIdentityPool.ref,
        },
        "ForAnyValue:StringLike": {
          "cognito-identity.amazonaws.com:amr": "unauthenticated",
        },
      },
      "sts:AssumeRoleWithWebIdentity"
    ),
  }
);

And we make sure that role has access to put events into CloudWatch RUM:

cwRumUnauthenticatedRole.addToPolicy(
  new PolicyStatement({
    effect: Effect.ALLOW,
    actions: ["rum:PutRumEvents"],
    resources: [
      `arn:aws:rum:${Stack.of(this).region}:${
        Stack.of(this).account
      }:appmonitor/${cloudFront.distributionDomainName}`,
    ],
  })
);

Then we attach the role to the unauthenticated users:

new CfnIdentityPoolRoleAttachment(
  this,
  "cw-rum-identity-pool-role-attachment",
  {
    identityPoolId: cwRumIdentityPool.ref,
    roles: {
      unauthenticated: cwRumUnauthenticatedRole.roleArn,
    },
  }
);

Next, we need to create the app monitor, which we do by using the Level 1 CDK Construct CfnAppMonitor:

const cwRumAppMonitor = new CfnAppMonitor(this, "cw-rum-app-monitor", {
  domain: cloudFront.distributionDomainName,
  name: cloudFront.distributionDomainName,
  appMonitorConfiguration: {
    allowCookies: true,
    enableXRay: false,
    sessionSampleRate: 1,
    telemetries: ["errors", "performance", "http"],
    identityPoolId: cwRumIdentityPool.ref,
    guestRoleArn: cwRumUnauthenticatedRole.roleArn,
  },
  cwLogEnabled: true,
});

Now, to automatically include the newly created app monitor client into our app... we need to take a few extra steps in our Construct. We'll need to run a Custom Resource to fetch some metadata and store it in the UI's bucket for the UI to load. The RUM App Monitor web client needs the CloudWatch RUM App Monitor Id, the Role ARN and the Identity Pool Id.

We create the NodeJS Function:

const rumRunnerFn = new NodejsFunction(this, "rum-runner", {
  runtime: Runtime.NODEJS_18_X,
  environment: {
    BUCKET_NAME: bucket.bucketName,
    RUM_APP: cloudFront.distributionDomainName,
    GUEST_ROLE_ARN: cwRumUnauthenticatedRole.roleArn,
    IDENTITY_POOL_ID: cwRumIdentityPool.ref,
  },
  timeout: Duration.seconds(30),
  entry: join(__dirname, "./rum-runner-fn.ts"),
});

And give it the right permissions:

bucket.grantWrite(rumRunnerFn);
rumRunnerFn.addToRolePolicy(
  new PolicyStatement({
    effect: Effect.ALLOW,
    resources: [
      `arn:aws:rum:${Stack.of(this).region}:${
        Stack.of(this).account
      }:appmonitor/${cloudFront.distributionDomainName}`,
    ],
    actions: ["rum:GetAppMonitor"],
  })
);

Then we create the Custom Resource, with a dependency on the App Monitor so that it runs AFTER the App Monitor is created:

const rumRunnerProvider = new Provider(this, "rum-runner-provider", {
  onEventHandler: rumRunnerFn,
});

const customResource = new CustomResource(this, "rum-runner-resource", {
  serviceToken: rumRunnerProvider.serviceToken,
  properties: {
    // Bump to force an update
    Version: "2",
  },
});

customResource.node.addDependency(cwRumAppMonitor);

Custom Resource Function

CloudFormation Custom Resources are a way to write some provisioning logic that is executed as part of a CDK (CloudFormation) deployment. The Custom Resource will invoke our lambda (/lib/rum-runner-fn.ts ) which will use the AWS SDK to fetch the App Monitor Id after it's created and store it in S3, along with the Role ARN and Identity Pool Id.

We import and create two clients:

import { S3Client, PutObjectCommand } from "@aws-sdk/client-s3";
import { RUMClient, GetAppMonitorCommand } from "@aws-sdk/client-rum";

const s3 = new S3Client({});
const rum = new RUMClient({});

Fetch the App Monitor config using the RUMClient:

export const handler = async () => {
  const app = await rum.send(
    new GetAppMonitorCommand({ Name: `${process.env.RUM_APP}` })
  );
};

And then upload them to the UI bucket:

export const handler = async () => {
  // ...
  const command = new PutObjectCommand({
    Key: "rum.json",
    Bucket: process.env.BUCKET_NAME,
    Body: JSON.stringify({
      APPLICATION_ID: `${app?.AppMonitor?.Id}`,
      guestRoleArn: `${process.env.GUEST_ROLE_ARN}`,
      identityPoolId: `${process.env.IDENTITY_POOL_ID}`,
    }),
  });
  await s3.send(command);
};

Typescript Snippet

The final piece of the puzzle is injecting this into our front end. The front-end will need to include our front-end typescript snippet/ui/rum.ts

This snippet extends the official/boilerplate snippet, that you would download from the CloudWatch RUM Console, by including some code to fetch the required metadata we stored using the Custom Resource above.

We fetch the configuration by calling:

const res = await fetch('/rum.json');
const rum = await res.json();

And then using the fetched metadata in the configuration of the web client:

const config: AwsRumConfig = {
  sessionSampleRate: 1,
  guestRoleArn: `${rum?.guestRoleArn}`,
  identityPoolId: `${rum?.identityPoolId}`,
  endpoint: "https://dataplane.rum.us-east-1.amazonaws.com",
  telemetries: ["errors","performance","http"],
  allowCookies: true,
  enableXRay: false
};

const APPLICATION_ID: string = `${rum?.APPLICATION_ID}`;
const APPLICATION_VERSION: string = "1.0.0";
const APPLICATION_REGION: string = "us-east-1";

if (APPLICATION_ID) {
  const awsRum: AwsRum = new AwsRum(
    APPLICATION_ID,
    APPLICATION_VERSION,
    APPLICATION_REGION,
    config
  );
  console.log(awsRum);
}

Then we only need to make sure we import and run the rumRunner function at the start of our front-end code (ui/main.ts):

import { rumRunner } from "./rum";

rumRunner();

Deploying and Integrating with Other Web Applications

By deploying this code we can start to gain insights from our applications including Core Web Vitals and other performance metrics.

By packaging this as a CDK Construct and Typescript snippet... we could easily add this to other CDK projects by adding in FOUR lines of code 🤯

Two lines in your CDK App:

import { RumRunnerConstruct } from './rum-runner-construct';
new RumRunnerConstruct(this, `Rum`, { bucket, cloudFront, });

And two lines in your front-end app:

import { rumRunner } from "./rum";
rumRunner();

(and I'm being generous with the line counts)

Conclusion

Measuring the quality of user experience is key to delivering a seamless and enjoyable experience for your website visitors. Core Web Vitals play a crucial role in this measurement, providing objective metrics to assess the performance of your website. To make the most of these metrics, it's important to consider Core Web Vitals early on in the development process. One way to do this is by using reusable CDK constructs, which can help you identify areas for improvement and optimize the user experience of your website.

Automate Documenting EventBridge Schemas in EventCatalog

Matt Martz — Thu, 27 Oct 2022 12:46:15 +0000

In this series we're going to SUPERCHARGE developer experience by implementing Event Driven Documentation. In part 1 we used CDK to deploy EventCatalog to a custom domain using CloudFront and S3. In part 2 we used AWS Service Events from CloudFormation to detect when an API Gateway has deployed and export the OpenAPI spec from AWS to bundle it in our EventCatalog. In this post, we'll export the JSONSchema of EventBridge Events using schema discovery and bundle them into the EventCatalog.

🛑 Not sure where to start with CDK? See my CDK Crash Course on freeCodeCamp

The architecture we'll be deploying with CDK is:

In this part we'll focus on the final bit of architecture for subscribing to EventBridge Schema Registry Events and bootstrapping them into the EventCatalog. We'll also talk about strategies for integrating this into CI/CD to make it fully automated.

💻 The code for this series is published here: https://github.com/martzcodes/blog-event-driven-documentation

🤔 If you have any architecture or post questions/feedback... feel free to hit me up on Twitter @martzcodes.

EventBridge Schema Discovery

Amazon EventBridge offers a Schema Registry and Discovery feature. This feature monitors Event traffic and creates JSON Schemas based on the events it sees. The awesome thing about this is every time it creates a new schema or updates a new one... it emits an AWS Event that we can trigger off of! We'll use these events to export the discovered event's schema and bundle them in to EventCatalog, similar to how we did with API Gateways in part 2.

If you have inconsistent Event Schemas (schemas with "optional" fields) a new version will be created every time the optional fields appear/disappear. A best practice for Event Schemas would be to make sure the event interfaces stay consistent (no optional fields and try not to use objects with changing keys).

Enabling Schema Discovery

First, we'll create a new construct for our Account Stack:

export interface EventsConstructProps {
  bus: IEventBus;
  specBucket: Bucket;
}

export class EventsConstruct extends Construct {
  constructor(scope: Construct, id: string, props: EventsConstructProps) {
    super(scope, id);
    const { bus, specBucket } = props;

    new CfnDiscoverer(this, `Discoverer`, {
      sourceArn: bus.eventBusArn,
      description: "Schema Discoverer",
      crossAccount: false,
    });
  }
}

This construct uses CDK's level 1 construct called CfnDiscoverer. We provide it with our default bus and tell it not to track events that came from outside of the account we're currently in (that could get noisy).

🌈 Level 1 Constructs are 1:1 mappings with the equivalent CloudFormation(e.g. CloudFormation vs CDK L1)

Exporting Event Schemas

Creating the Infrastructure

With Schema Discovery enabled, we can create our lambda and invoke that lambda based on the AWS Service Events.

const eventsFn = new NodejsFunction(this, `eventsFn`, {
  runtime: Runtime.NODEJS_16_X,
  entry: join(__dirname, `./events-lambda.ts`),
  logRetention: RetentionDays.ONE_DAY,
  initialPolicy: [
    new PolicyStatement({
      effect: Effect.ALLOW,
      actions: ["schemas:*"],
      resources: ["*"],
    }),
  ],
});
specBucket.grantReadWrite(eventsFn);
eventsFn.addEnvironment("SPEC_BUCKET", specBucket.bucketName);
bus.grantPutEventsTo(eventsFn);

We make sure to grant the lambda the right permissions (read/write to the bucket, the bucket name as an environment variable and putEvents to the default bus).

new Rule(this, `eventsRule`, {
  eventBus: props.bus,
  eventPattern: {
    source: ["aws.schemas"],
    detailType: ["Schema Created", "Schema Version Created"],
  },
  targets: [new LambdaFunction(eventsFn)],
});

AWS Schema events offer two detail types: "Schema Created" and "Schema Version Created". You can see the contents of these on the Explore page in the EventBridge console. We invoke our lambda using these detail types.

Processing the Events

Unlike Part 2... processing these events are a lot easier because we have everything we need via the Event and only need to make one aws-sdk call. The event includes the Schema Name and Version and we use that to export the JSONSchema via the aws sdk:

const RegistryName = event.detail!.RegistryName;
const SchemaName = event.detail!.SchemaName;
const SchemaVersion = event.detail!.Version;
const SchemaDate = event.detail!.CreationDate;

const exportSchemaCommand = new ExportSchemaCommand({
  RegistryName,
  SchemaName,
  Type: "JSONSchemaDraft4",
});
const schemaResponse = await schemasClient.send(exportSchemaCommand);

From there we put it in our spec bucket:

const schema = JSON.parse(schemaResponse.Content);

const fileLoc = {
  Bucket: process.env.SPEC_BUCKET,
  Key: `events/${SchemaName}/spec.json`,
};

const putObjectCommand = new PutObjectCommand({
  ...fileLoc,
  Body: JSON.stringify(schema),
});
await s3.send(putObjectCommand);

And emit the event with our presigned URL:

const getObjectCommand = new GetObjectCommand({
  ...fileLoc,
});
const url = await getSignedUrl(s3, getObjectCommand, { expiresIn: 60 * 60 });

const eventDetail: EventSchemaEvent = {
  SchemaName,
  SchemaVersion,
  RegistryName,
  SchemaDate,
  url,
};

const putEvent = new PutEventsCommand({
  Entries: [
    {
      Source,
      DetailType: BlogDetailTypes.EVENT,
      Detail: JSON.stringify(eventDetail),
    },
  ],
});
await eb.send(putEvent);

Updating the Watcher to Copy the Schemas

In Part 2 we added a utility method to our spec construct that creates a lambda with a rule. We need to use that here to add a lambda for these Event schemas:

this.addRule({
  detailType: BlogDetailTypes.EVENT,
  lambdaName: `eventWatcher`,
});

This lambda simply copies the spec files using a certain S3 Key naming convention:

export const handler = async (
  event: EventBridgeEvent<string, EventSchemaEvent>
) => {
  const res = await fetch(event.detail.url);
  const spec = (await res.json()) as Record<string, any>;

  const fileLoc = {
    Bucket: process.env.SPEC_BUCKET,
    Key: `events/${event.account}/${event.detail.SchemaName}/${event.detail.SchemaVersion}.json`,
  };

  const putObjectCommand = new PutObjectCommand({
    ...fileLoc,
    Body: JSON.stringify(spec, null, 2),
  });
  await s3.send(putObjectCommand);
};

Bootstrapping the Markdown files for EventCatalog

Now that we have our event JSONSchemas stored in our Watcher's Spec Bucket, we can update our prepare scripts to pull the files and bootstrap them (similar to how we did the API Gateway files in Part 2). One notable difference is that EventCatalog's Event interface offers "Consumers and Producers" and Event Versioning. We're going to create a pseudo-service that represents our Account's EventBus and specify that as the Producer for these events. This is kind of a hack, but it's a useful one. We're also going to create the files needed to version our events.

The folder structure for a domain will end up looking like this:

acct-<account>/
 events/
  blog.dev.catalog@Spec.event/
   index.md
   schema.json
  blog.dev.catalog@Spec.openapi/
   versioned/
    1/
     changelog.md
     index.md
     schema.json
    2/
      changelog.md
      index.md
      schema.json
   index.md
   schema.json
 services/
 <account>-bus/
   index.md
   openapi.json
  iam-backed-api/
    index.md
    openapi.json
 index.md

Fetch the Events

To fetch the events we use aws-sdk's ListObjectsCommand to get the files prefixed with events/.

const listBucketObjectsCommand = new ListObjectsCommand({
  Bucket,
  Prefix: "events/",
});
const bucketObjects = await s3Client.send(listBucketObjectsCommand);
const specs = bucketObjects.Contents!.reduce((p, c) => {
  const key: string = c.Key!;
  const splitKey = key.split("/");
  const account = splitKey[1];
  const schemaName = splitKey[2];
  const schemaVersion = splitKey[3].split(".")[0];
  if (!Object.keys(p).includes(`${account}-${schemaName}`)) {
    return {
      ...p,
      [`${account}-${schemaName}`]: {
        key,
        account,
        schemaName,
        schemaVersion,
        versions: [{ schemaVersion, key }],
      },
    };
  }
  p[`${account}-${schemaName}`].versions.push({ schemaVersion, key });
  return p;
}, {} as Record<string, { key: string; account: string; schemaName: string; schemaVersion: string; versions: { schemaVersion: string; key: string }[] }>);

We store these S3 keys in an object so that we can determine the latest version of each spec, and we process them by schema.

const specKeys = Object.keys(specs);
for (let j = 0; j < specKeys.length; j++) {
  const specMeta = specs[specKeys[j]];
  const versionInfo = {
    schemaVersion: 0,
    key: "",
    index: -1,
  };
  specMeta.versions.forEach((version, versionInd) => {
    if (Number(version.schemaVersion) > versionInfo.schemaVersion) {
      versionInfo.schemaVersion = Number(version.schemaVersion);
      versionInfo.key = version.key;
      versionInfo.index = versionInd;
    }
  });
  if (versionInfo.index > -1) {
    specMeta.key = versionInfo.key;
    specMeta.schemaVersion = `latest`;
    specMeta.versions.splice(versionInfo.index, 1);
  }

  const getSpecCommand = new GetObjectCommand({
    Bucket,
    Key: specMeta.key,
  });

  const specObj = await s3Client.send(getSpecCommand);
  const spec = await streamToString(specObj.Body as Readable);
  // ...
}

Ensure the Domain folder exists

In Part 2 we created a makeDomain shared method. To ensure the domain folder exists we just need to call it:

const domainPath = makeDomain(specMeta.account);

Create the Pseudo Bus Service

Next, we create the pseudo service:

const pseudoServiceName = `${specMeta.account}-bus`;
const pseudoServicePath = join(
  domainPath,
  `./services/${pseudoServiceName}`
);
mkdirSync(pseudoServicePath, { recursive: true });
const apiMd = [
  `---`,
  `name: ${pseudoServiceName}`,
  `summary: |`,
  ` This is a pseudo-service that represents the Default Event Bus in the AWS Account. It isn't a real service.`,
  `owners:`,
  ` - martzcodes`,
  `badges:`,
  ` - content: EventBus`,
  ` backgroundColor: red`,
  ` textColor: red`,
  `---`,
];
writeFileSync(join(pseudoServicePath, `./index.md`), apiMd.join("\n"));

Create the Events

We create the latest (parent) event:

const eventPath = join(domainPath, `./events/${specMeta.schemaName}`);
mkdirSync(eventPath, { recursive: true });
writeFileSync(join(eventPath, `./schema.json`), spec);
if (!existsSync(join(eventPath, `./index.md`))) {
  const apiMd = [
    `---`,
    `name: ${specMeta.schemaName}`,
    `version: latest`,
    `summary: |`,
    ` This is the automatically stubbed documentation for the ${specMeta.schemaName} Event in the ${specMeta.account} AWS Account.`,
    `producers:`,
    ` - ${pseudoServiceName}`,
    `owners:`,
    ` - martzcodes`,
    `---`,
    ``,
    `<Schema />`,
  ];
  writeFileSync(join(eventPath, `./index.md`), apiMd.join("\n"));
}

Add Versioning

And finally the version:

for (let k = 0; k < specMeta.versions.length; k++) {
  const specMetaVersion = specMeta.versions[k];

  const getSpecVersionCommand = new GetObjectCommand({
    Bucket,
    Key: specMeta.key,
  });

  const specVersionObj = await s3Client.send(getSpecVersionCommand);
  const specVersion = await streamToString(
    specVersionObj.Body as Readable
  );

  const versionPath = join(
    eventPath,
    `./versioned/${specMetaVersion.schemaVersion}`
  );
  mkdirSync(versionPath, { recursive: true });
  writeFileSync(join(versionPath, `./schema.json`), specVersion);
  const apiMd = [
    `---`,
    `name: ${specMeta.schemaName}`,
    `version: ${specMetaVersion.schemaVersion}`,
    `summary: |`,
    ` This is the automatically stubbed documentation for the ${specMeta.schemaName} Event in the ${specMeta.account} AWS Account. This is an old version of the spec.`,
    `producers:`,
    ` - ${pseudoServiceName}`,
    `owners:`,
    ` - martzcodes`,
    `---`,
    ``,
    `<Schema />`,
  ];
  writeFileSync(join(versionPath, `./index.md`), apiMd.join("\n"));

  const changelog = [`### Changes`];
  writeFileSync(
    join(versionPath, `./changelog.md`),
    changelog.join("\n")
  );
}

The Final Result

You can see this in action at docs.martz.dev

CI/CD Strategies

There are a few factors when determining your own CI/CD strategy for this. Right now everything is automatically updated when we do CDK deploys... but the CDK deploys themselves aren't automated.

The big factor is how many things are you tracking. At work we monitor 30+ AWS accounts used by > 100 developers. That runs the risk of being too much to do something like having the watched events kick off a deployment pipeline. Instead we'll likely use a scheduled CI/CD build to periodically update the documentation.

For CI/CD you could:

Create a CodeBuild/CodePipeline project to automatically deploy the EventCatalog based on "watched" events.
Connect your normal CI/CD up to a schedule (maybe you have a lot of events from many accounts and only want to update documentation every hour or so).
Continue manually deploying it (which is what I'll do for my personal account since I don't deploy there often)

What's Next?

AWS Service Events offer a lot of useful insights in to your applications deployed to AWS.

💡Want to see what other Service Events are available? Check out the EventBridge "Explore" page in the console

From here you could:

You could extend the schemas by Improving EventBridge Schema Discovery
Maybe you want to store additional information from GitHub webhooks into DynamoDB
Track EventBridge Rule changes via CloudFormation deployments

What would you do next?

🙌 If anything wasn't clear or if you want to be notified on future posts... feel free to hit me up on Twitter @martzcodes.