DEV Community: Mahmut Canga

Value Created by Testing Infrastructure Code

Mahmut Canga — Sun, 30 Jan 2022 15:42:24 +0000

The simplest answer is Customer Trust.

As you can see from above screenshot, I’m able to get a quick feedback, as fast as 5 seconds, from my Infrastructure Code, CDK Application if I’m going to be earning more Customer Trust or not after the deployment…

In this tiny setup, I have an important DynamoDB Table that stores important Customer data. This data needs to be available all the time and if I get higher demand, I should be able to quickly scale up the table at 80% utilisation. All of these are possible with DynamoDB but none of this could work if you don’t invest on it. The investment can be manually configuring these on AWS Console or even worse, with no investment, you can configure these when your system slows down or you get customer complaints. Of course, no business prefers their customers complaining about their service. So, you would be able to proactively handle it by investing in automation and Infrastructure as Code using CDK.

However, even in this setup, you may face issues. When you would like to go faster, errors could happen and you would like to get a fast feedback instead of long and painful customer feedback in production. In order to achieve this, TDD and CI/CD are used reasonably and responsibly. CDK in this context is no foreigner to these concepts and provides great tooling and support to test your Infrastructure as you create it via unit tests.

The biggest value of these tests is being able to reflect Operational Excellence (OpEx) concerns as early as at the unit test stage. By writing unit tests according to your OpEx concerns in your CDK application, it will provide a higher confidence when running the service in production. This confidence will yield more Customer trust as you will be able to reliably run a service and fortunately find out issues before Customer does.

In the above example screenshot, my OpEx concerns are well covered with unit tests. Now, every time I deploy my application, I can simply run npm run test on my infrastructure code and make sure that there is no drift in my OpEx concern in production. You can take this to another level by scanning existing repositories in your organisation and alert service owners if company wide OpEx concerns are not covered at code level using some Bots. Also, these metrics could be extremely useful to reflect on service dashboards.

Speaking of these OpEx concerns, I can easily say almost 90%+ incidents I was part of in the past had an action item or two about alerting, monitoring and more observability as a result of the incident report. These now can be part of the code and forever guard the concerns. Also, it would be much easier to close the loop on an incident report by simply reflecting these on a dashboard and sharing the code change (PR/MR/CR whatever your organisation refers to) into the report. Long term learnings of an incident from OpEx point of view can be internalised and automated with this simple methodology.

While talking about the business value of this, let’s look at the code and connect the dots. Next section quickly summarise the code setup and hopefully will influence you write more tests for your infrastructure code.

Sample Setup

I have a very simple CDK application stack with 2 NestedStack constructs. One stack is for Monitoring (alert topic, sns, dashboards) and the other one is the Database. I also use CDK v2 for these sample codes.

From AWS Docs, NestedStacks are:

The NestedStack construct offers a way around the AWS CloudFormation 500-resource limit for stacks. A nested stack counts as only one resource in the stack that contains it, but can itself contain up to 500 resources, including additional nested stacks.

The scope of a nested stack must be a Stack or NestedStack construct. The nested stack needn’t be declared lexically inside its parent stack; it is necessary only to pass the parent stack as the first parameter (scope) when instantiating the nested stack. Aside from this restriction, defining constructs in a nested stack works exactly the same as in an ordinary stack.

Monitoring Stack

Below creates a dedicated CloudWatch Dashboard and exports the dashboard to be used in other stacks. This way, you will be able to put all related metrics and alerts of your service into a central dashboard.


import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
import * as sns from 'aws-cdk-lib/aws-sns';
import * as subscriptions from 'aws-cdk-lib/aws-sns-subscriptions';

export class MonitoringStack extends cdk.NestedStack {

    public readonly dashboard: cloudwatch.Dashboard;

    public readonly alarmTopic: sns.Topic;

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

        this.dashboard = new cloudwatch.Dashboard(this, 'Dashboard', {});

        this.alarmTopic = new sns.Topic(scope, 'AlarmTopic', {
            displayName: 'My Service Alarms',
        });

        const emailSubscription = new subscriptions.EmailSubscription('dev@mycompany.com');

        this.alarmTopic.addSubscription(emailSubscription);
    }
}

Database Stack

Below creates a DynamoDB Table, sets Read and Write capacity to 5 while enabling point in time recovery. It also enables to auto-scale to 5x of the table capacity at 80% utilisation. It also adds Read and Write capacity alarms and metrics on CloudWatch Dashboard created in Monitoring Stack.


import * as cdk from 'aws-cdk-lib';
import { Construct } from 'constructs';
import * as dynamodb from 'aws-cdk-lib/aws-dynamodb';
import * as cloudwatch from 'aws-cdk-lib/aws-cloudwatch';
import * as sns from 'aws-cdk-lib/aws-sns';
import * as cloudwatchActions from 'aws-cdk-lib/aws-cloudwatch-actions';

interface DatabaseStackProps extends cdk.NestedStackProps {
    dashboard: cloudwatch.Dashboard;
    alarmTopic: sns.Topic;
}

export class DatabaseStack extends cdk.NestedStack {

  public readonly customerOrdersTable: dynamodb.Table;

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

    this.customerOrdersTable = this.setupTable(scope, props, 'CustomerOrdersTable');
  }

  private setupTable(scope: Construct, props: DatabaseStackProps, id: string): dynamodb.Table {
    //
    const table = new dynamodb.Table(scope, id, {
      partitionKey: { name: 'customerId', type: dynamodb.AttributeType.STRING },
      sortKey: { name: 'orderId', type: dynamodb.AttributeType.STRING },
      billingMode: dynamodb.BillingMode.PROVISIONED,
      readCapacity: 5,
      writeCapacity: 5,
      encryption: dynamodb.TableEncryption.DEFAULT,
      pointInTimeRecovery: true,
      stream: dynamodb.StreamViewType.NEW_AND_OLD_IMAGES,
    });

    this.setupAutoScaling(scope, table);
    this.setupDashboard(scope, props, table, id);

    return table;
  }

  private setupAutoScaling(scope: Construct, table: dynamodb.Table) {

    const tableReadScaling = table.autoScaleReadCapacity({ minCapacity: 5, maxCapacity: 25 });
    tableReadScaling.scaleOnUtilization({
      targetUtilizationPercent: 80,
    });

    const tableWriteScaling = table.autoScaleWriteCapacity({ minCapacity: 5, maxCapacity: 25 });
    tableWriteScaling.scaleOnUtilization({
      targetUtilizationPercent: 80,
    });
  }



  private setupDashboard(scope: Construct, props: DatabaseStackProps, table: dynamodb.Table, tableName: string){

    const readCapacityAlarm = new cloudwatch.Alarm(scope, `${tableName}ReadCapacity`, {
      metric: table.metricConsumedReadCapacityUnits({
        period: cdk.Duration.minutes(5),
        statistic: 'sum',
      }),
      threshold: 25,
      alarmDescription: `${tableName} Table Read Capacity`,
      evaluationPeriods: 1,
    });

    readCapacityAlarm.addAlarmAction(new cloudwatchActions.SnsAction(props.alarmTopic));

    const readCapacityAlarmWidget = new cloudwatch.AlarmWidget({
      title: `${tableName} Table Read Capacity`,
      alarm: readCapacityAlarm,
    });

    const writeCapacityAlarm = new cloudwatch.Alarm(scope, `${tableName}WriteCapacity`, {
      metric: table.metricConsumedWriteCapacityUnits({
        period: cdk.Duration.minutes(5),
        statistic: 'sum',
      }),
      threshold: 25,
      alarmDescription: `${tableName} Table Write Capacity`,
      evaluationPeriods: 1,
    });

    writeCapacityAlarm.addAlarmAction(new cloudwatchActions.SnsAction(props.alarmTopic));

    const writeCapacityAlarmWidget = new cloudwatch.AlarmWidget({
      title: `${tableName} Table Write Capacity`,
      alarm: writeCapacityAlarm,
    });

    props.dashboard.addWidgets(readCapacityAlarmWidget, writeCapacityAlarmWidget);
  }
}

Now that my stack is setup, this is how I test them. I didn’t share the full test suite but the below is showing the important OpEx concerns under cover.

Testing Database OpEx Concerns

In this simple Jest setup, I’m creating a new test stack and add the stack under test to it. By generating a CloudFormation Template, I’m able to unit test if my CDK setup is covering my concerns or not.


import * as cdk from 'aws-cdk-lib';
import { Template } from 'aws-cdk-lib/assertions';
import { MonitoringStack } from '../lib/stacks/monitoring-stack';
import { DatabaseStack } from '../lib/stacks/database-stack';
import { Stack } from 'aws-cdk-lib';

describe('Test Database Stack', () => {
    let template: Template | null;

    beforeEach(() => {
        const app = new cdk.App();

        const testStack = new Stack(app, 'TestStack');

        const monitoringStack = new MonitoringStack(testStack, 'TestMonitoringStack', {});

        new DatabaseStack(testStack, 'TestDatabaseStack', {
            dashboard: monitoringStack.dashboard,
            alarmTopic: monitoringStack.alarmTopic,
        });

        template = Template.fromStack(testStack);
    });

    afterEach(() => {
        template = null;
    });

    test('Tables have point in time recovery', () => {
        template?.hasResourceProperties('AWS::DynamoDB::Table', {
            PointInTimeRecoverySpecification: {
                PointInTimeRecoveryEnabled: true,
            },
            ProvisionedThroughput: {
                ReadCapacityUnits: 5,
                WriteCapacityUnits: 5,
            },
        });
    });

    test('Tables have READ capacity alarms', () => {
        template?.hasResourceProperties('AWS::CloudWatch::Alarm', {
            MetricName: 'ConsumedReadCapacityUnits',
            Namespace: 'AWS/DynamoDB',
        });
    });

    test('Tables have WRITE capacity alarms', () => {
        template?.hasResourceProperties('AWS::CloudWatch::Alarm', {
            MetricName: 'ConsumedWriteCapacityUnits',
            Namespace: 'AWS/DynamoDB',
        });
    });

    test('Tables have READ capacity scalable target', () => {
        template?.hasResourceProperties('AWS::ApplicationAutoScaling::ScalableTarget', {
            ScalableDimension: 'dynamodb:table:ReadCapacityUnits',
            ServiceNamespace: 'dynamodb',
        });
    });

    test('Tables have WRITE capacity scalable target', () => {
        template?.hasResourceProperties('AWS::ApplicationAutoScaling::ScalableTarget', {
            ScalableDimension: 'dynamodb:table:WriteCapacityUnits',
            ServiceNamespace: 'dynamodb',
        });
    });

    test('Tables have READ auto-scaling policy at 80% utilization', () => {
        template?.hasResourceProperties('AWS::ApplicationAutoScaling::ScalingPolicy', {
            TargetTrackingScalingPolicyConfiguration: {
                PredefinedMetricSpecification: {
                    PredefinedMetricType: 'DynamoDBReadCapacityUtilization',
                },
                TargetValue: 80,
            },
        });
    });

    test('Tables have WRITE auto-scaling policy at 80% utilization', () => {
        template?.hasResourceProperties('AWS::ApplicationAutoScaling::ScalingPolicy', {
            TargetTrackingScalingPolicyConfiguration: {
                PredefinedMetricSpecification: {
                    PredefinedMetricType: 'DynamoDBWriteCapacityUtilization',
                },
                TargetValue: 80,
            },
        });
    });
});

Closing Notes

I hope the above sample codes and overall context could influence you write more unit tests to your infrastructure. To my knowledge, Terraform doesn’t support such setup or even if it is supported, I couldn’t find the productivity and tooling support in my recent attempts like running a simple npm run test in WebStorm or VSCode. This is why I believe CDK is a game changer for developer confidence and productivity when it comes to building and running services that delight customers on AWS.

Where to Next?

For further details on why OpEx is important, you can dive into AWS Well Architected white paper.

AWS Well Architected

Also, there is great tutorials on CDK documentation to get started:

CDK Getting Started

CDK documentation itself teaches how to use services in great detail

DynamoDB Module – CDK

To 5XX or Not to 5XX?

Mahmut Canga — Thu, 30 Dec 2021 07:48:38 +0000

Speaking of 5XX errors, I have a strong opinion from a good API design perspective. I developed these opinions by working at both client level and at server level in different projects or even at the same project. Also, seeing how HTTP Clients of popular frameworks in NodeJS, Javascript, Java and even .Net, 5XX is something we should never return in a programmatic way. This is maybe in the realm of checked vs unchecked exceptions but I’m more at the good API design realm.

Perceptions

Error Code	API	Client
2XX	I have handled all you requested and here is the result of this operation	Show the result of the requested operation, happy days!
4XX	I have handled an exception in my API and I know what it is, here is a bad request response. I might fail fast and return you this bad request response in milliseconds and may not even try any downstream services at all to avoid downfall spiral…	I know I sent a valid request but for some reason(s) API didn’t process my request. I’ll go retry or show an updated result (error screen, retry with new input etc). However, I’ll need to make it harder every time so I will leave some space to API to recover. I’ll also note down this in case needed for future resolutions…
5XX	There is something that stops my program flow and it is an exceptional case, my engineers need to look at this and later on either fix this issue or catch it and give a meaningful result (4XX) to my clients if this exceptional case is an expected outcome due to service design… Or there is some big meltdown happening and my API is not even receiving anything about it as the infrastructure or whole service is down…	Something exceptional happening in the API. API doesn’t know what it is, I’m not even sure if my request reached to API, I’ll not retry but rather show something to user that there is something going on that engineers are fixing. I’ll note this down but will not retry after a meaningful time or budget. It is not great but everything fails all the time…

Leaky Abstractions is your enemy!

In distributed systems, everything fails all the time. Good API design captures failures and handles them gracefully. Returning 5XX to clients will create a false perception. It will also leak the abstractions. Knowing that APIs are here forever, leaking an abstraction will create a dependency on clients that will be just a tech debt from day 1.

To explain this further, knowing that my DB fails time to time (hardware ceiling, SLAs, downstream issues, tech debt etc.) and if I return 5XX in those occasions to my consumers, the consumer of my API will accept this as a design decision, assuming how this API works in certain way (leaking the abstraction). Client may implement some logic that every time 5XX means API might have failed and retry the request. However, while the system is down, sending more traffic will only create further bigger issues. Returning 5XX will not only create a leaky abstraction but also it will always escalate the system issues to further levels that is hard to recover. If API would actually design the failure gracefully and return 4XX, it could create an abstract system that could put these requests in an expiring queue (i.e. expire the requests in the next 5 mins) so that even if the client keeps trying, I’ll have a way to catch up. From Client perspective, it is abstract, reliable and predictable API behaviour. Also, because API is able to handle DB failure and can put the upcoming requests in a queue while DB is recovering, it will be performant and fast too…

Observing Failures

In this sense, clearly, If an API is up & running but only a dependency is failing, it is 4XX. 5XX is when the API is broken for a reason that we cannot capture the details at all. If we cannot write to db due to DynamoDB service is down, it is 4XX because as an API, I know what part of my dependency is failing and I know how to catchup. (put failed requests to SQS and retry later on etc). If API Gateway is down, without that request is ever reaching to my API, I know AWS will throw 5XX. If Lambda service is not able to run my function code because I have a defect in my code pipeline due to wrong compilation, missing a package in dependencies, wrong packaging etc, I know Lambda will throw 5XX.

As engineer, in above cases, you will immediately know that there is a 5XX going on in my system and I’ll know where to look up. Otherwise, for every 5XX, I’ll need to search through logs to see if 5XX is an API response or an exception in the distributed system or at AWS level…

This perspective will also lead meaningful alerts and observability. Alerts will be thrown at the right level and in exceptional cases. Otherwise, returning 5XX programmatically will create a complex benchmark data for observability and alerting. Deciding when there is more than 0 5XX is much more cleaner operational action than constantly tweaking 5XX levels in my monitoring system and dashboards. As an engineer, I need to look at under the hood only when there is a real issue, 5XX and not when an arbitrary programming decision in the control flow throws 5XX like when a field is missing in the request and API returning 5XX 🤦🏻‍♂️

Conclusion

To conclude this opinion piece, 5XX is something we should see in rare times as exceptional issues and fixed at infrastructure, system design or wider distributed system levels. Anything above should be handled by the program flow and should be 4XX with a meaningful message to API consumers. Failing fast, gracefully handling failure, having a plan to recover from dependency failures are hard things at API design but when invested early and carefully planned as part of the implementation, it will earn trust, help running the API more reliable and will lead happier engineers & operations.

Running NextJS SSR Apps on AWS

Mahmut Canga — Wed, 22 Dec 2021 14:50:23 +0000

At the time of writing this article, AWS is offering multiple options to run a NextJS SSR app. In the scale of self managed to AWS Managed, here are the options:

Out of these options, the best developer experience related AWS Managed offerings are Amplify Hosting and App Runner. They come with all the low level details handled by AWS in such a way that all you need is deploying via CI/CD pipeline and the rest is assured (scalability, logs, custom domains, auto-renewal of certificates etc.)

I have tried both Amplify Hosting and App Runner for a NextJS SSR app and ended up using and liking App Runner more. I’m hoping the context provided in this post can be useful to others too.

Constraints and Prerequisites of Amplify Hosting

Although Amplify Hosting does a great job for running SPAs that doesn’t require server side rendering, when it comes to SSR, the constraints and prerequisites are important to highlight.

First of all, in order to run a SSR app on Amplify Hosting as of writing this article, you need to connect a source code for Next.js apps can only be deployed with Continuous deployment. AWS currently do not support manual deployments of Next.js apps. This creates a huge challenge if your code is deployed to multiple environments from a single main branch. Because all environments in Amplify Hosting is required to listen to the same main branch and before any approval or testing, your code can go to production at the same time it goes to sandbox or dev environment. One workaround to this could be using a branch per environment but this conflicts with the idea of Continuous Delivery.

Second, you need to setup the build definition in a yaml file that requires changing how you export your NextJS SSR. I found this pretty confusing.

By following the below changes in your build step, you are exposed to issues like not being able to use some of the NextJS features. Currently, Amplify doesn’t fully support Image Component and Automatic Image Optimization available in Next.js 10. To manually deploy the next-app example, you must edit the index.js file to remove this feature.


"scripts": {
  "dev": "next dev",
  "build": "next build && next export",
  "start": "next start"
},

Third, as documented in AWS Docs, Amplify Hosting builds an S3 bucket, a CloudFront distribution and a Lambda@Edge stack in order to host SSR app. This may sound too many moving parts for a single frontend app while it is promising for a frontend app to have a global availability via CDN. The most interesting finding in this step was Lambda@Edge. As far as I understand, Amplify Hosting deploys some logic at Lambda@Edge with a very constraint timeout. In some Amplify Console Github issues, I have seen that Lambda@Edge constraints certain workloads in terms of quickly timing out. Also, due to how Lambda@Edge works, you will require deploying your app to us-east-1 where CloudFront and Lambda@Edge is centrally managed.

Last, when you choose Amplify Hosting, you are getting into an usual workflow. On top of your existing CI/CD pipelines, you are pushing your code to Amplify’s CD pipeline which is only visible via AWS Console. This means, you won’t have any realtime visibility in your existing CI/CD pipelines and rather check the progress of deployment from AWS Amplify Console. I’m not sure if there are any workarounds to this but having multiple disconnected tools for a CD pipeline is not a great developer experience. Also, from security point of view, it is tricky to allow all frontend developers touching the NextJS SSR app accessing the AWS Console. Even these frontend developers may not be familiar with the whole AWS Console experience so it is both a security concern and a learning curve issue.

AWS App Runner just works!

AWS App Runner is a fully managed service that makes it easy for developers to quickly deploy containerized web applications and APIs, at scale and with no prior infrastructure experience required.

This gives a huge advantage building a CI/CD pipeline for a NextJS SSR app using existing tools and a lot of flexibility on how you do it. To achieve this, all you need is couple of lines of CDK code and a docker file.

The following creates an App Runner app that auto-scales to 25 instances and scales down to 1 when there isn’t any HTTP requests to your system. It is pretty much how you deploy a container to Fargate without dealing with Route53, ALB, VPC, Security Groups etc. All of these lower level constructs are managed by AWS.


import * as cdk from "@aws-cdk/core";
import { Duration, NestedStack, NestedStackProps } from "@aws-cdk/core";
import * as apprunner from "@aws-cdk/aws-apprunner";
import * as ecrAssets from "@aws-cdk/aws-ecr-assets";

export class WebStack extends NestedStack {
    constructor(scope: cdk.Construct, id: string, props: NestedStackProps) {
        super(scope, id, props);

        /**
         * Create a docker image and push to ECR
         */
        const imageAsset = new ecrAssets.DockerImageAsset(this, "WebAppImage", {
            directory: "../src",
        });

        /**
         * Deploy to App Runner from the docker image pushed to ECR
         */
        const service = new apprunner.Service(this, "WebApp", {
            source: apprunner.Source.fromAsset({
                asset: imageAsset,
            }),
            cpu: apprunner.Cpu.TWO_VCPU,
            memory: apprunner.Memory.FOUR_GB,
        });
    }
}

There are couple things to note in this setup.

The minimum CPU that requires a responsive and performance NextJS SSR app is apprunner.Cpu.TWO_VCPU. Otherwise, if you have an API connecting to a downstream service and receiving data, it quickly times out and gives 500 Server Error
The minimum Memory is unfortunately needed to be the maximum App Runner supports, apprunner.Memory.FOUR_GB. This is again to make sure the node server has enough head room to process.

The next step is basically just dockerizing your NextJS SSR. For this, NextJS already provides a straightforward Docker file. All you need is putting this on your src folder. The rest is handled by CDK auto-magically.


# Install dependencies only when needed
FROM node:14-alpine AS deps
# Check https://github.com/nodejs/docker-node/tree/b4117f9333da4138b03a546ec926ef50a31506c3#nodealpine to understand why libc6-compat might be needed.
RUN apk add --no-cache libc6-compat
WORKDIR /app
COPY package.json ./
RUN npm install

# Rebuild the source code only when needed
FROM node:14-alpine AS builder
WORKDIR /app
COPY . .
COPY --from=deps /app/node_modules ./node_modules
RUN npm run build

# Production image, copy all the files and run next
FROM node:14-alpine AS runner
WORKDIR /app

ENV NODE_ENV production

RUN addgroup -g 1001 -S nodejs
RUN adduser -S nextjs -u 1001

# You only need to copy next.config.js if you are NOT using the default configuration
COPY --from=builder /app/next.config.js ./
COPY --from=builder /app/public ./public
COPY --from=builder --chown=nextjs:nodejs /app/.next ./.next
COPY --from=builder /app/node_modules ./node_modules
COPY --from=builder /app/package.json ./package.json
COPY --from=builder /app/.env ./

USER nextjs

EXPOSE 3000

ENV PORT 3000

# Next.js collects completely anonymous telemetry data about general usage.
# Learn more here: https://nextjs.org/telemetry
# Uncomment the following line in case you want to disable telemetry.
ENV NEXT_TELEMETRY_DISABLED 1

CMD ["node_modules/.bin/next", "start"]

This really is an uncompromising build process to get the best out of your NextJS build.

When you need to deploy this stack, all you need to is following in your CI/CD pipeline.

cdk bootstrap
cdk deploy

Some other benefits of App Runner

Following are other good parts of App Runner worths mentioning.

Custom Domains and Auto Renewed HTTPS Certificate

You can link a custom domain and within a couple of minutes your NextJS SSR app can be accessed via HTTPS only. For this to really work, as of writing this article, you need to update Route53 records and add a couple of CNAME entries

You can also link multiple domains to the same app…

Logs are welcome!

Your console.log is visible via App Runner console auto-magically. Although CloudWatch is a better option generally, for simple workloads, this saves a lot of time when something goes wrong and you need logs.

Of course, metrics!

Some basic metrics without any effort, out of box are available.

Conclusion

If your frontend app doesn’t require server side rendering, go all the way Amplify Hosting for great user experience by leveraging S3 and CDN provided out of box by Amplify. It is really one of the best frontend developer experience available in the market.

However, to improve site’s SEO ranking, Time to first byte (TTFB) and First contentful paint (FCP) and most importantly, connecting to downstream / backend services at the API layer without leaking anything to browser and client side for a better security, using App Runner is much more flexible choice. Not only for NextJS SSR but for any NodeJS app that requires SSR (Express, Gatsby, React SSR (experimental) etc), App Runner seems to be the easier setup and with very low effort CI/CD pipeline.

One long term benefit of using App Runner is dockerising your SSR web app. This gives opportunities to move your web app into more complex setups like Fargate and even EKS (yes, I have seen SPAs with SSR served from their own k8s clusters at scale 🤓).

Connecting Postman to Amazon Cognito User Pools for API Access Tokens

Mahmut Canga — Tue, 26 Oct 2021 23:21:08 +0000

Photo by Khwanchai Phanthong on Pexels.com

Majority of the time in my recent projects, I use Amazon Cognito for user authentication (sign in, sign up, login with identity providers etc) in front of an Amazon API Gateway. Usually the API endpoints control access using Amazon Cognito user pools as authorizer

In these type of APIs, testing the API using Postman is a good practice. Use of Postman helps distributing the API contracts easily while helping you as a developer to run different types of tests without a full-blown client implementation.

The expected way to connect and consume these APIs are providing an id token from Amazon Cognito authorization in the headers. This token is auto-validated by Amazon API Gateway by leveraging Cognito Authorizers. A typical request to these endpoints would look like below:

curl --location --request GET 'https://{API-ID}.execute-api.eu-west-2.amazonaws.com/v1/profiles/123' \
--header 'Authorization: eyJraWQiOiJOZjB0clFHanRG.....'

To add this token in every request, Postman supports Collection based Authorization setting. (I assume you follow putting all requests under a collection in Postman). As you can see, Postman supports variety of authorization techniques.

What we are going to use from these alternatives is OAuth 2.0 which Amazon Cognito supports out of box. There is a detailed deep dive on different grant types available on AWS Blog.

As part of your Amazon Cognito setup, you are expected to create an App Client which has access to this user pool. Using this App Client, we will be able to sign in using an existing user and grab an id token that will be used for API calls.

[Step 1] – App Client Id and Callback URL(s)

In order to setup this, go to App Client Settings section of the Cognito pool.

You will use the App Client Id and Callback URL(s) from this page in your OAuth 2.0 setup in Postman.

[Step 2] OAuth 2.0 Flows

Also make sure the following OAuth 2.0 flows are enabled on the same App Client Settings page.

The way to sign in with an existing user account is via Hosted UI feature of Amazon Cognito. This UI is a very basic sign in/sign up screen that conforms the User Pool settings. It is actually a nice way of testing your Cognito setup out of box

(nice as in available and working, not as in with a slick UI 🙂)

[Step 3] Hosted UI Domain

As you may realise from above screenshot, Hosted UI needs to be setup. In order to do that, go to App Integration section and click Add Domain

In Add Domain screen, you can set a domain name for your Hosted UI. This URL will be used for OAuth 2.0 settings in Postman. Also, this URL will be used for the sign-up and sign-in pages that are hosted by Amazon Cognito. The prefix must be unique across the selected AWS Region. Domain names can only contain lower-case letters, numbers, and hyphens. Learn more about domain prefixes.

[Step 4] Collection Authorization Settings

Next part is setting up Postman Collection in order to sign in / sign up and get an id token for making authenticated API calls. Fill in the following details by editing the Collection Authorization settings:

Grant Type: Implicit
- Uncheck Authorise using browser option
Callback URL: https://example.com
Auth URL: {Hosted UI URL}/login
Client ID: {App Client Id}
Scope: phone email openid profile aws.cognito.signin.user.admin
Client Authentication: Send client credentials in the body

[Step 5] Generate Access Token

When you enter these details and click Get New Access Token button, Postman will open the Hosted UI URL for you to sign in or sign up.

What is nice about this setup is, you can just create a test user and use it for all API calls accordingly using the above UI. Above UI is enabled by setting Cognito Pool setting called User sign ups allowed? Users can sign themselves up

As you can see, this UI complies with the user pool settings and gives you a nice way to test your setup. Here is the screenshot of signup screen and look at the password policy in place….

Hosted UI even provides the email and/or phone validation during setup. In my user pool setup, I require users to have validated emails. So, in this below screenshot I can see that Hosted UI shows related information and input. As Cognito sends real emails for verification code, I suggest to use a real email here to avoid any confusion…

When you finish a successful sign in or sign up, Postman confirms this and grabs the token.

Following screen is shown with the token details. You will see that this screen has an Access Token and an id_token.

For API Gateway Cognito Authorizer workflow, you will need to use id_token.

!!! IMPORTANT DETAIL !!!

Simply copy the value of id_token and put it in Access Token value of the Current Token setting. This will make the id_token available for all requests in that collection.

[Step 6] Setup Collection Authorization Settings

Last step is updating API requests to use the Collection Authorization settings. Setting the Authorization setting of requests as Inherit auth from parent will let Postman inject Access Token in the Authorization header value.

Conclusion

I hope you will be able to easily test your APIs behind Cognito using this setup via Postman. You can export the Collection as .json and even make part of your codebase so you will be embracing API Contract Testing as Code – ACTaC (I made this up now…)

Lambda Result Package is Live!

Mahmut Canga — Sun, 03 Oct 2021 00:14:37 +0000

I have been tinkering with this idea of releasing something open source for a while. Recently, I have started to use a pattern in my Lambda code that became so much handy and productive.

Today, I’m happy to release it and hopefully it will be useful for you too!

https://github.com/macromania/lambda-result

A Moment of Testing

Mahmut Canga — Sun, 20 Jun 2021 12:27:20 +0000

Sometimes you may question _ “Why should I write tests? Why TDD is important?” _

I think this little moment of success can explain a lot of things…

My tests here are run under 3seconds. This means, I’ll get an immediate feedback from my tests if I break anything….

What is the result of not writing tests?

Instead of only spending 3 seconds of my dev time , I’m going to waste a lot of other people’s time in my team by expecting them finding out the issues by manual testing. Immediate feedback as in 3 seconds is extremely valuable during development.
Plus, I’ll loose trust of my customers too by unintentionally asking them wasting their time using my software and only finding out the bugs…

Of course, there are moments we have to ask our team to test manually but it should be as minimum as possible….

Refactoring or Retiring Can be a A Feature

Mahmut Canga — Sun, 18 Apr 2021 13:27:34 +0000

A really good article from Nature lays out why the bias towards additive solutions might be further compounded by the fact that subtractive solutions are also less likely to be appreciated.

In product development, friction points around refactoring and retiring features are widely popular in discussions among the engineers in any organisation. However, the bias towards additive solutions as found out in the article can be a strong root cause.

When business expects all the charts going top right corner, we may be relating this demand to additive solutions unconsciously. I have not seen any success stories at large mentioning why retiring features made their overall KPIs better.

After reading this article, I’ll try to challenge my bias towards additive solutions. It is going to be harder to come up with ideas subtracting by nature. However, in the grand schema of leaving a better legacy behind us and sustainability, I don’t see myself being challenged with counter arguments.

People tend to solve problems by adding features.

Source: Adding is favoured over subtracting in problem solving

Simple, very dumb system that constantly works

Mahmut Canga — Mon, 22 Feb 2021 15:16:43 +0000

A great article from Amazon’s Builder Library.

These patterns have three key features. One, they don’t scale up or slow down with load or stress. Two, they don’t have modes, which means they do the same operations in all conditions. Three, if they have any variation, it’s to do less work in times of stress so they can perform better when you need them most. There’s that anti-fragility again.

Even when there are only a few health checks active, the health checkers send a set of results to the aggregators that is sized to the maximum. For example, if only 10 health checks are configured on a particular health checker, it’s still constantly sending out a set of (for example) 10,000 results, if that’s how many health checks it could ultimately support. The other 9,990 entries are dummies. However, this ensures that the network load, as well as the work the aggregators are doing, won’t increase as customers configure more health checks. That’s a significant source of variance … gone.

Something important to remember is that O(1) doesn’t mean that a process or algorithm only uses one operation. It means that it uses a constant number of operations regardless of the size of the input. The notation should really be O(C).

A unicycle has fewer moving parts than a bicycle, but it’s much harder to ride. That’s not simpler. A good design has to handle many stresses and faults, and over enough time “survival of the fittest” tends to eliminate designs that have too many or too few moving parts or are not practical.

More on https://aws.amazon.com/builders-library/reliability-and-constant-work/