DEV Community: Trek10

3 Guiding Principles for Building New SaaS Products on AWS

Jared Short — Tue, 05 May 2020 17:04:31 +0000

I won't start this article saying there is "one true-way" for building SaaS on cloud providers, specifically AWS. I will confidently say that there are many wrong ways. At Trek10, we find ourselves helping clients that have seen their AWS usage skyrocket and need to organize the chaos of an organic, home-grown crop of AWS Cloud. This article is distilled from years of working with folks at various points in their AWS journey in an effort to help guide you away from the wrong ways, and towards a successful path.

You know the story, and you may even have a part in the story yourself. A company is pivoting to the Software-as-a-Service model to modernize its offerings. Someone at the top hears that the cloud "accelerates the pace of innovation" and proclaims, "we must get on board or get left behind; this company won't be the laggards of the adoption curve!" If you are really on the cutting edge, an engineer or two has heard about this new "serverless" thing and is just plain tired of ssh-ing in and patching their fleet of "totally-automated everything away boss" EC2 instances.

Based on what I have seen and learned over the years, and some discussion with trusted colleagues, I want to talk about how I would (and in fact have) set up new organizations (products, SaaS, whathaveyou) from day one for future success. Here are a few guiding beacons to help you make the right long-term decisions.

Let's dive in.

#1 Build as if you may sell at any time

This may seem silly, especially if your organization has been around for a century. However, in new products and old companies alike the approach of building as if you may sell at any time has a similar effect; it forces you to build with best practices and isolation.

To achieve this goal, I’d lean on a few well known best practices, and perhaps some lesser-known tooling.

AWS Accounts are the ultimate unit of isolation

With the introduction of AWS Organizations, AWS made it clear that the multi-account strategy is the cut path in the deep jungles of account management. Stack on Control Tower and various Landing Zone offerings and you can rest assured that in this day and age you can easily leverage accounts for isolation in a practiced manner in even your most trivial projects.

These days, one of my favorite tools to orchestrate things is nothing more than a thin wrapper around native AWS tooling is AWS OrganizationFormation. OrgFormation works with a few simple tagging and logic schemes to set up accounts and deploy/maintain CloudFormation templates across them.

AWS Organizations also simplifies your technical auditing needs by centralizing AWS Config and GuardDuty.

The AWS account is also one of the most effective tools in your kit for blast radius limiting.

Finally, AWS Organizations centralizes your billing. Any sufficiently large cloud operation ends up requiring a Cloud Economist to make any sense of the madness, but with Organizations you can pretend to keep things under control for a while with the centralized billing as well as some simple alarms or dashboards.

A basic organization setup looks something like this.

Following this structure, you will note that each of the “products” is actually distributed into its own “organization unit” and each environment is broken up into its own AWS account. Billing, CI/CD and even Security & Auditing are centralized which can help maintain insight across the company.

Build for the cloud, in the cloud

This one may seem a bit odd, but let’s take a direct quote from my friend Ben Kehoe, Cloud Robotics Research Scientist and AWS Community Hero.

Move your development environment towards the cloud, do not try to move the cloud down to your dev environment.

There are an undeniable amount of tools and initiatives to bring familiar development cycles to local developer environments. Some are better than others. Some achieve more parity than others. As good as some of these are, inevitably you end up in a situation where something is not quite perfect and you spend days or weeks trying to work around that issue for your team. Even worse, you spend cycles debugging when something isn't quite right in your deployed cloud version.

These days, I personally do the majority of my development on AWS Cloud9. The fast, reliable internet on the box and what I'd call "good enough" feature set and language support are truly sufficient about 90% of the time.

In addition to Cloud9, I would also highly suggest either a shared "developer" AWS Sandbox account, or for more mature organizations a Sandbox per developer. If you are feeling extremely ambitious, maybe even ephemeral AWS accounts.

I'd ask most developers to start their day in Cloud9, and only eject to their local machines if they really need to. I would expect that they are doing unit tests or simple mocks locally to get their tests into a place where they are rapid and valuable locally, but that their real development and testing is pushing to their sandbox AWS accounts.

Simply put, there is no sufficient simulation or substitute for actual cloud resources.

This also encourages and requires good practice around integration and end-to-end testing.

#2 Build as if you may open-source at any time

This one is a bit more nuanced but let’s think about the decisions it forces us to make. We need to be a bit more introspective on our internal practices and scrutinize our codebase as if it is open to the world.

This means that security by obscurity, while never a good practice, is a definite no-go. We can’t rely on people not knowing we moved our admin endpoint to /unfindable-except-by-everyone. It also means no secrets strewed about in code, and no cert files stored in the repository.

Your project dependencies need to be regularly audited and remain up to date. You need to be able to roll-out new patched versions of your software soon after critical Common Vulnerabilities and Exposures (CVE) are released against those dependencies. The only way this is safe and feasible is with automated and comprehensive pipelines for deploying your code.

There is also the implied "embarrassment" angle. Sure, a little bit of sloppy coding is evident even in many open source projects. But knowing (or pretending) that some external force is looking over your shoulder may help you take the extra hour or two to properly pull out modules or add those tests you know should be done.

The final bit of advice that falls under this principle is documentation. An open-source project is only as good as its documentation. You could have the most elegant API in the world, but if there isn't enough documentation to communicate that point to new-comers there won't be anyone using your project. Good documentation extends beyond just your code or API. It encompasses your infrastructure practices, your guiding principles as a project, your on-boarding for new developers, and yes, your code and APIs.

#3 Build with a cloud-native mindset

Look ma’ my biases are showing! Clearly, I am an advocate for building with the tools provided by my platform of choice.

If AWS doesn't have it (or really, if CloudFormation doesn't support it) does it really exist? I get that this is a pretty aggressive, if not flippant, statement. However, any time I stray from a platform-native offering it's a reasonably high likelihood that I will regret it.

This also means leaning heavily into all the service offerings and orchestration tooling that is afforded to you by your platform. Don't be afraid to set some boundaries for your teams, but don't dogmatically enforce them.

As Alex DeBrie put it for me...

Provide standards but allow experimentation. AWS is a broad ecosystem, and there are some holes. Your company will choose some services and patterns that you prefer and others that you don't. Help your engineers understand what the preferred and supported patterns are. Make it clear that they can go off those paths, but they're going to be more on their own. This is akin to Charity's 'Golden Path' approach, but it's not really AWS specific.

To expand, there are certainly cases where staying within the platform isn't the most optimal solution. There are cases where the market is a few steps ahead of your platform provider. For instance, AWS doesn't have anything quite as tuned to fast frontend search experiences like Algolia. But the point remains that going outside of the platform should be an exception and something you do only when truly needed. While going out to the market isn't my first option, but it definitely fits with how I think about serverless still in 2020.

// Detect dark theme var iframe = document.getElementById('tweet-1100887501047132160-919'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1100887501047132160&theme=dark" }

Now, going out to the market and buying something doesn't always work out great. But my regret is lower than if I tried to build something in its place. To illustrate, I'll lean on my good friend Forrest Brazeal for the next thousand words.

Infrastructure as Code is one of the few "no compromise" issues

While writing for this piece, I reached out to 5 or so trusted folks to ask their guidance for organizations building on the cloud. Every single person explicitly stated that Infrastructure as Code (IaC) is an essential piece of the puzzle.

If you are not managing your infrastructure via CloudFormation, Terraform, or any of the other myriad of ways to model and deploy your infrastructure in repeatable ways you will eventually come to regret it. Whether you pay for it via needing to painstakingly rebuild a new environment as your application grows, or if you forget to check a box during a 3 hour manual deployment from staging to production and inexplicably bring down your application for a couple of harrowing hours.

If you take nothing else away from this post, please let it be that IaC is a cornerstone of a health product lifecycle on cloud.

Don't take my word for it

These 3 "guiding principles" are just that. Guidelines. They are not tenets that followed dogmatically guarantee success. They are in fact generalized snippets boiled out of some years of working with clients and on various AWS projects.

Evaluate every technology decision as a long term decision of partnership. Sure, you are billed by the second/day/month, but really you are electing to take on that technology as a partner in the growth of your SaaS. Some decisions are easier replaced than others, some choices you outgrow. That's natural and expected. In the same vein, don't evaluate your past choices in the current context. You will always know more now than you did then.

When it comes to those decisions, give your team authority and power to build and innovate. Don't shy away from the strengths of the cloud to augment your teams, and don't shy away from trusting your teams.

As Richard Boyd so eloquently put it for me...

Push authority down (don't push the CEO down a flight of stairs). A Software team that is responsible for the operational requirements of their application will drive the ops burden down. Typically this is done at an organizational level because Dev and Ops are separate teams/org. By forcing dev teams to own the ops of their applications, they have the responsibility (and the authority) to make changes in it that make the application more stable. Note, this is true in many places but it much more pronounced in the cloud where most software runs as a service

All said I'd build a new SaaS product without hesitation on AWS, and others should strongly consider it, but do so with a plan of action for your tech decisions and your teams.

What I Learned Starting My First Tech Job During a Global Pandemic

Matt Skillman — Mon, 27 Apr 2020 15:52:54 +0000

The pandemic that started in the US in early 2020 has necessitated the shift to remote work for those of us who can make this shift; I started my first tech job during this time period and after a few weeks in the office, I found myself working from home.

In the past, I had considered working from home to be an impossibility, or, at best, something fundamentally inefficient and undesirable for both employer and employee. In truth, when it comes to the software development industry, remote work is an enabling factor, rather than being a hindrance.

That all said, I have a few takeaways learned while starting a new job at Trek10 during this global pandemic.

Silence is golden, even when working from home and alone

Coding requires at least a few hours of deep concentration daily and a remote work environment has enabled me to more easily meet this requirement. The essence of programming is the construction of very specific, logically coherent statements that must take into account the behavior and expectations of the system they reside within. This is exactly the sort of task that demands an individual’s full attention and focus.

For me, working at home means that I can guarantee that, when necessary, I can silence all notifications on both my computer and phone and attend to my job with complete concentration. Once I have completed the most complex parts of whatever it is that I am working on, or whenever I need clarifications, I can open Slack and communicate with the appropriate people.

In my previous workplaces, communicating with team members required a walk from one building to another or a series of phone calls; because of Slack and my current remote work environment, communication is far more efficient and sensible. Slack features channels intended for the distribution of information which concerns large groups of people. In my opinion, this feature trumps its real-world counterparts, which are intercom systems, cork boards with sheets of paper posted on them, or even worse, word-of-mouth propagation of business-critical knowledge. Additionally, ad hoc group discussions no longer require that several people physically relocate themselves just to have a three-minute conversation.

Asking for help early and often is fine, it doesn't show weakness or ineptitude

These new digital mediums reduce the need to delay conversations out of concern for the potential of interrupting the other party. If an engineer is presently occupied and wishes not to be interrupted, Slack offers a variety of features that allow her to signal to her teammates that she is busy and not currently available.

Personally, it is rare for me to use these features which indicate unavailability for discussions, because, relative to the people I am working with, I lack experience and it is especially important that I communicate with them to accelerate my learning.

I think the biggest challenges that a remote work environment could present to a new hire relate primarily to personality traits or work habits. In my case, I happen to be intrinsically motivated to do my job and attempt to learn from people more experienced than me, so working from home has not presented any issues. The reality of my situation is that I am a new hire and have much to learn, so it is important to be humble and ask questions when necessary. Because it is so easy to communicate through Slack, working remotely has also enabled me in this regard.

Tribal knowledge still exists, learning where things are and how things work is still a necessary soft skill

Despite all this, remote work environments are obviously not infallible; individuals do bear some responsibility in becoming comfortable with the workflow. From what I have experienced, it is important to understand where all the needed resources are located within your organization.

In a purely physical work environment, an employee can visually see where everything is located. The only barriers are locked doors or campuses too large to easily navigate. In a completely digital work environment, the tools necessary to complete the job often take the form of various URLs, nested folders within a Google drive UI, etc.

I have learned the importance of soft skills such as paying attention to the locations of these digital resources so that anything I need is within quick reach.

I'm excited to continue learning and growing in my roles in tech, and even post-pandemic I am sure these learnings will serve me well.

3 Big Things I Wish Someone had Told Me When I Started Using AWS

Jared Short — Fri, 24 Apr 2020 17:17:56 +0000

I've been working with AWS for the past 6 years or so. I've run into many highs and lows during the work. With emotions ranging from feeling like a mythic god, bending the cloud to my will, to debating seeking a job doing something with my hands far away from a computer.

I introspected over the past years and asked a few co-workers and friends things that they wish they had known before they got started using AWS. I dug for more than "I wish I knew technology X better," because that is circumstantial and not all that helpful in many cases. Instead, view this compilation of observations by folks that have been in the cloud and things we think would have been nice to know.

AWS is a massive ecosystem. You can't understand it all, let alone be an expert in most of it.

In the early days when we were building Trek10 as a company (an AWS consulting shop), we dabbled in helping folks with Azure and other clouds. We quickly realized these projects drained resources and mental capacity, and simply put, distracted us from our ultimate goals of being recognized serverless and AWS experts. We decided to hyper-focus on our goals and reject all projects that didn't get us closer to that work.

On a personal level, this holds true for individuals as well. I make an effort to read at least one AWS service's documentation from cover to cover once a week. Rough calculations suggest I have spent 500+ hours just reading AWS service documentation (There are 221 doc repos on the official GitHub). I regularly reach out to AWS folks and colleagues for help understanding interactions between services, implications of a design choice, or even just an overview or refresher of a feature.

So don't take it personally on day 1 when nothing makes sense. This stuff is hard. My general suggestion is to have an end goal of what you want to build and break it into pieces you think are solvable by various services. Pick one service, read the docs cover to cover, and create that part to get your hit of endorphins. Then, wire that thing to a second service in the same manner.

Consider your knowledge base of AWS a living source. As features are added and best practices evolved, even what you knew a year ago may soon be obsolete. It's not bad, just a natural consequence of the cloud platform. Saying "I don't know, but I can find out" isn't a shameful thing, even to a client or boss.

Understanding a service's use-cases is very different than understanding the service.

I can tell you what most of the services on AWS do at a decent level of detail. Given a use case, I could probably rough out a couple of options for architectures pretty quickly. What I can't tell you is, based on exact needs, what problems you may run into with all of the service options that may fit. To do that, I would need to research service limits and other tidbits that are scattered around AWS documentation (notice a theme here yet?).

AWS Services have limits, both service limits and other functional restrictions. Usually they are quite reasonable, but other times, they will make your life genuinely miserable. Especially if your system needs to scale or evolve if you didn't consider things ahead of time.

For example, a real-world use case. Let's say you want to process a queue of transactions. We do some Googling and find that AWS has the Simple Queue Service (SQS). We look up limits and see we there can be 120,000 inflight messages by default and practically unlimited stored and incoming messages. Great, queue solved. To process the queue we can hook things up to AWS Lambda. Lambda will handle processing messages as they come in, so no messages mean no cost, and we can scale up to high volume transactions per second without much consideration.

Our system is humming along, but then we realize we are getting some problems in our backend during higher load times. Some numbers aren't adding up quite right. Ah, a race condition! Lambda and SQS do not guarantee order. We frantically search and find we can guarantee order with SQS FIFO (first in, first out). We are saved! Except... FIFO queues don't support Lambda function triggers. That's a heck of a limitation to run into this late in the project.

We are going to have to rearchitect or reconsider our whole set of service choices to address this problem (perhaps with Amazon Kinesis which can guarantee order and still works great with Lambda)!

You are going to get caught on sharp edges when you are exploring and learning. Your best defense is to review and re-review the limitations of the services before you choose them and ask in-depth questions about future states. Do we need to guarantee the order of anything? What size of payloads might we need? How many transactions per second if we are wildly successful? Do we need searchability of the data?

Inline bonus thing: AWS Improves around you

The AWS savvy among you may have been shouting at your screen "AWS Lambda Support FIFO Queues!" and you would be absolutely right. It does now. This wasn't the case a year ago. This brings me to the point that a proper solution today isn't the best solution tomorrow.

One of the unique properties of AWS (or the cloud in general), is that the services may improve around you. DynamoDB and S3 have addressed numerous pitfalls like hotkeys, scaling, etc. You'll see performance increases as AWS iterates on the underlying architectures. I've had solutions out in AWS Land that just got more performant or started costing less just based on AWS changes without me having to do anything.

Cost is really hard; leveraging the cloud is just as much about the business and people as it is the technology.

There are a lot of arguments for and against the cloud on cost models. Nearly every case I have read or heard toys around on raw pricing comparisons. On one end we have, "An EC2 instance on AWS costs $$$ per year, hardware in my data center amortized costs $$ per year. You are silly if you move to the cloud." With the other end saying, "Lambda functions cost $ per year, and I can serve a billion transactions without needing to order new hardware ever."

Most arguments don't dive into what it takes to build and maintain a data center, or staff folks in the data center or colo. What isn't talked about is the cost to retrain staff to leverage the cloud: the opportunity cost of pursuing cloud and retraining, or of building a data center and staffing developers to maintain internal systems just to keep the data center working.

While some of these conversations are starting to happen, I think the thing I wish I had realized was that cloud cost is less about optimizing raw infrastructure cost and more about optimizing opportunity, maintenance, and people costs. This frame of mind would have made a lot of conversations much smoother early in my career.

Corey Quinn, AWS Billing maverick explains it better than I can.
// Detect dark theme var iframe = document.getElementById('tweet-1101616132681752576-864'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1101616132681752576&theme=dark" } // Detect dark theme var iframe = document.getElementById('tweet-1101616133235339264-907'); if (document.body.className.includes('dark-theme')) { iframe.src = "https://platform.twitter.com/embed/Tweet.html?id=1101616133235339264&theme=dark" }

Speed round

There was a lot to think about for this post. Here are some other things to consider.

Always, always practice good AWS account hygiene. Separate AWS accounts for environments and projects to get a built-in security blast radius and more effective costing practices.
AWS services sometimes aren't that practical or useful when they release, but they get progressively better. Check back on them as cases arise.
It's usually cheaper to try stuff out than do a ton of research, Proof-of-Concept early and often. Do it in a new account and with infrastructure as code so you can throw away the environment when you are done without losing any work.
There will be regional outages of services. This doesn't mean AWS is less available or stable than your data center. Build with these outages in mind. Review the AWS Well-Architected Framework. It will help you make better decisions from day 1.
Moving to cloud from traditional data centers is usually easier for developers than previously infrastructure and ops folks. Have a plan to turn your people into cloud natives, not just your services.
"Lift and Shift" is never as smart or short-term of a strategy as you want to believe.

From FaaS and Furious by Forrest Brazeal

I imagine there is a lot more someone could be told, more that I wish I had been told, but I can only hope to save someone a few troubles or moments of worry as they start their cloud journey. I'm always available on Twitter or in the comments to help!

CI/CD, AWS, and Serverless: 5 tips I learned the hard way

Forrest Brazeal — Wed, 29 May 2019 18:42:16 +0000

So you want to build a serverless app on AWS?

Great! There are lots of cool posts that show you how to get started.

An Intro to the Power of Serverless with AWS Amplify

Jared Short for Trek10 ・ May 29 '19

#aws #graphql #tutorial

But how do you get that app off your laptop and into the cloud? You could zip your code and upload it manually into the AWS console every time you change something, but that would get old pretty fast.

What you probably want is some kind of CI/CD (continuous integration / continuous delivery) system, where code is automatically tested and released to your environment when you push changes to a source control repository.

An example CI/CD pipeline

I've been building CI/CD pipelines for serverless on AWS for years, and I've picked up a few tricks along the way. Here are five tips I wish somebody had told me when I first got started.

Test code locally and services in the cloud

There are several ways to run a Lambda function on your local developer machine -- for example, the Serverless Framework's serverless-offline plugin or the AWS SAM CLI.

This works great for quickly testing changes to your code. But a serverless app is a lot more than just code: permissions, service configurations, and other things can go wrong as you glue services together to build a truly cloud-native application.

So local testing is not enough. The more external services you integrate with, the more you'll have to mock, and the more your tests will take on a tinge of unreality. You'll be testing a system that doesn't exist.

Instead, my rule of thumb is to test code locally and services in the cloud. This might involve the following steps:

Make an initial deployment in AWS that contains the definitions for services your code depends on (for example, deploying an underlying IAM role or a DynamoDB table).
Run your Lambda function locally as you develop and test the code, reaching out to cloud services for your dependencies.

This way, you can quickly iterate on code, but if something breaks on the cloud side, you'll know! When your Lambda function works locally as expected, you can push it to the cloud as well, where you should...

Prioritize end-to-end functionality tests over unit tests

As a general rule, we want to be writing less code in the serverless world. It's quite possible to write a useful service in AWS using mostly configuration. For example, you can build a CRUD API using API Gateway and DynamoDB alone - no Lambda functions in the middle required.

The more "serverless" you get, the less code you can usefully unit test, and the more you have to rely on tests of your deployed infrastructure.

Lately I've been using Cypress for end-to-end tests of serverless APIs. It's a Javascript test framework that works with assertion libraries like Jest and Chai. You can query your API directly, no inside knowledge of the code required. This is testing your service the way your users will experience it, so you can be sure your expectations match reality.

If you want to test AWS resources directly, a cool project to check out is Erez Rokah's AWS Testing Library, which lets you write tests directly against deployed resources like DynamoDB tables or SQS queues.

If you're writing tests, of course, you'll need some place to run them. AWS provides a managed build service called CodeBuild that you should be paying attention to, because...

AWS CodeBuild is hugely underrated

Ever had to babysit a build server that was constantly crashing because one rogue job ate all the disk space? That's not a very "serverless" thing to do.

Fortunately, AWS CodeBuild spins up a completely separate Docker-based build environment for every invocation of a build job. It's truly ephemeral compute, pay only for what you use, and it's pretty cheap -- 500 build minutes a month will run you a cool $2.00. The containers can take a few seconds to initialize, but that's way better than managing a pool of build runners that may flake out on you at any time.

Once you've got CodeBuild in your corner, you should take a look at another AWS tool for developers, because ...

AWS CodePipeline is the single best way to manage CloudFormation releases

CloudFormation is AWS's infrastructure-as-config service: you create a template that defines your Lambda functions, IAM roles, etc. (The Serverless Application Model, or SAM, which makes it easier to define serverless apps on AWS, is just CloudFormation with a little special sauce.)

Another annoying CI/CD thing I've had to do a lot is write scripts that poll AWS CloudFormation for updates. CodePipeline is really good at doing that for me. So I can trust it to manage my serverless infrastructure deployments as they roll from development, to staging, to production environments.

None of these services come without gotchas, of course. The most important one I can warn you about right now is this:

CodePipeline only supports one branch per pipeline (at least for now)

No doubt this will change someday, but at present you can trigger a CodePipeline from only one source, such as a repository branch. If you have branch-based workflows, this gets frustrating quickly.

One workaround is to dynamically create a new CodePipeline per branch using a Lambda function, which has worked pretty well for us at Trek10 -- well enough that we recently open-sourced the idea as an AWS Quickstart. That Quickstart contains the CloudFormation templates needed to spin up dynamic CodePipelines that include CodeBuild jobs, Lambda tests, and lots more -- so what are you waiting for? Give it a try, and hit me up in the comments if you have other questions.

An Intro to the Power of Serverless with AWS Amplify

Jared Short — Wed, 29 May 2019 14:41:56 +0000

A little story about serverless

Since 2014, my day job has been helping folks build and maintain stuff on Amazon Web Services (AWS). I've helped organizations from the most niche startups to household names on everything from real-time inventory management to machine learning on pizzas and everything in between.

I've seen containers get popular. I've seen the word Serverless get used so much that I am not even sure what it means anymore. One thing does remain for sure though, the real world Serverless systems I've been part of creating that have handled billions of transactions are some of the most pleasant to maintain and operate of any I've seen in my career.

So why do I love serverless, why does it matter? Y'all remember the Spectre/Meltdown insanity in early 2018 where chip level vulnerabilities were discovered, and everyone was freaking out and scrambling to fix it? The serverless environments I operated were patched before most orgs even had the conference rooms booked to build the response plan.

Here is a real depection of myself and the Trek10 team patching our Clients' serverless environments the night of the Spectre/Meltdown.

Some of my most fun tickets and replies of all time were along the lines of "Hello, we are from Company X's security team, and we need a full plan for maintenance and audits for the environment you maintain for us ASAP to address the recent security issues." Nothing like saying "already handled" with a link to the AWS patch notes completed before the vulnerability was even public.

At the end of the day, you want to deliver business value. You, too, can leverage the operations of the best and brightest in computing for pennies on the dollar by using serverless practices. Instead of worrying about server patching, networking, ssh keys, and the ilk, you get to focus on delivering your core value.

Tools of the Trade

There are a lot of options out there today from the Serverless Framework to Apex Up and many other providers and frameworks (many of them focusing on a niche use-case or language).

Most of my new projects kick off with AWS Amplify CLI these days. AWS Amplify CLI is somewhat of a wrapper on the complexities of the cloud, offering opinionated solutions while still offering customizability where you need.

Make sure you have Node.js 8.11.x or later and an AWS Account (don't worry about configuring anything yet, we simply need the account), and away we go.

Our project today is going to be a blast from the past, with a little twist. Remember those small "visitor counter" badges everyone used to have at the bottom of their website, usually right next to an animated gif of their countries flag?

Let's do that, but better... we are going to make it real-time™!

Start by installing the Amplify CLI with npm install -g @aws-amplify/cli and running amplify configure in your terminal. You'll be walked through various steps in a combination of your terminal and browser window, at the end of which you will have created and configured a new IAM user.

$ npm install -g @aws-amplify/cli
$ amplify configure
Follow these steps to set up access to your AWS account:

Sign in to your AWS administrator account:
https://console.aws.amazon.com/
Press Enter to continue

Specify the AWS Region
? region:  us-east-1
Specify the username of the new IAM user:
? user name:  captain-counter
Complete the user creation using the AWS console
https://console.aws.amazon.com/iam/home?region=undefined#/users$new?step=final&accessKey&userNames=captain-counter&permissionType=policies&policies=arn:aws:iam::aws:policy%2FAdministratorAccess
Press Enter to continue

Enter the access key of the newly created user:
? accessKeyId:  AKIAWTXIHO**********
? secretAccessKey:  AfGA3kTlGyv6F0GMyzQS********************
This would update/create the AWS Profile in your local machine
? Profile Name:  captain-counter

Successfully set up the new user.

Let's set up our project directory and initialize our amplify app.

$ mkdir counter && cd counter
$ amplify init
Note: It is recommended to run this command from the root of your app directory
? Enter a name for the project counter
? Enter a name for the environment dev
? Choose your default editor: Visual Studio Code
? Choose the type of app that you're building javascript
Please tell us about your project
? What javascript framework are you using none
? Source Directory Path:  src
? Distribution Directory Path: dist
? Build Command:  npm run-script build
? Start Command: npm run-script start
Using default provider  awscloudformation

For more information on AWS Profiles, see:
https://docs.aws.amazon.com/cli/latest/userguide/cli-multiple-profiles.html

? Do you want to use an AWS profile? Yes
? Please choose the profile you want to use captain-counter
⠙ Initializing project in the cloud...

These steps (and mostly using default answers) will end up with a base amplify app running in your AWS account. It doesn't do much now, but let's keep coding. Do note; I opted not to use any particular framework. I want to keep this extremely lightweight since we'll be loading the script in other websites and there is no need for a framework where we are going.

Adding the API

Our little project wouldn't be very successful if we didn't have a way to track hits. We are going to leverage a GraphQL API with a service called AWS AppSync. AppSync is a fully managed GraphQL solution that allows you to quickly and easily map to various data sources, I've personally used it for many things, and it's everything it says on the label and then some.

$ amplify add api
? Please select from one of the below mentioned services: GraphQL
? Provide API name: counter
? Choose an authorization type for the API API key
? Do you have an annotated GraphQL schema? No
? Do you want a guided schema creation? No
? Provide a custom type name Counter
Creating a base schema for you...

Great, now let's open up amplify/backend/api/counter/schema.graphql and change the schema.

type Counter 
    @model
{
    id: String!
    hits: Int
}

Now for the fun part, let's deploy our API. Behind the scenes, Amplify compiles your schema to various queries and mutations, updates your CloudFormation templates to manage all the resources you need for your API, code generates a small client to access your API, and finally deploys everything via CloudFormation to your AWS account.

$ amplify push

Current Environment: dev

| Category | Resource name | Operation | Provider plugin   |
| -------- | ------------- | --------- | ----------------- |
| Api      | counter       | Create    | awscloudformation |
? Are you sure you want to continue? Yes

GraphQL schema compiled successfully.
Edit your schema at /Users/jshort/Work/counter/amplify/backend/api/counter/schema.graphql or place .graphql files in a directory at /Users/jshort/Work/counter/amplify/backend/api/counter/schema
? Do you want to generate code for your newly created GraphQL API Yes
? Choose the code generation language target javascript
? Enter the file name pattern of graphql queries, mutations and subscriptions src/graphql/**/*.js
? Do you want to generate/update all possible GraphQL operations - queries, mutations and subscriptions Yes
? Enter maximum statement depth [increase from default if your schema is deeply nested] 2
⠦ Updating resources in the cloud. This may take a few minutes...

....sometime later

GraphQL endpoint: https://ol2t5s4qlvbidcx2mwmigeya4m.appsync-api.us-east-1.amazonaws.com/graphql
GraphQL API KEY: da2-rbk5t2xpuvevlm6qza4onbly7m

At the end of the process, you'll get a GraphQL endpoint and API key. You can use these to start playing with and exploring your API immediately. Using something like GraphQL Playground or Insomnia may be the fastest way to play around with things.

Example configured GraphQL Playground, note the HTTP headers for authorization and all the pre-generated CRUD operations

If you check out your API, you will notice a TON of pre-built functionality for normal CRUD operations (Create, Read, Update, Delete). For our use-case, we don't need any of it, and we are going to substitute our own.

Change your amplify/backend/api/counter/schema.graphql to reflect this more locked down schema. We are taking away nearly all of the CRUD operations, renaming some of the operations, and adding a filtered subscription method. If you want to learn more about this, check out the AWS Amplify docs for GraphQL Transforms.

type Counter
    @model(
        queries: { get: "counter" },
        mutations: { create: "hit" },
        subscriptions: null
    )
{
    id: String!
    hits: Int
}

type Subscription {
    hits(id: String!): Counter
        @aws_subscribe(mutations: ["hit"])
}

Behind the scenes, Amplify is managing a DynamoDB table for us. A managed NoSQL database that can handle a tremendous load (In my experience one of the best serverless databases).

Next, We are going to customize our GraphQL resolver to take advantage of atomic updates within Amazon DynamoDB, meaning that every "hit" mutation for a counter, we increment the "hits" column by adding 1.

Amplify gives us a convenient way to override default resolver implementations with a resolvers folder in amplify/backend/api/counter/resolvers. Create a file call Mutation.hit.req.vtl and pop in the Velocity Template Language code below.

$util.qr($context.args.input.put("__typename", "Counter"))

#if( $util.isNullOrBlank($context.args.input.id) )
    $util.error("You MUST pass an `id` parameter")
#else

{
  "version": "2017-02-28",
  "operation": "UpdateItem",
  "key": {
      "id": $util.dynamodb.toDynamoDBJson($ctx.args.input.id)
  },
  "update": {
    "expression": "SET #typename = :typename ADD hits :one",
    "expressionNames": {
        "#typename": "__typename"
    },
    "expressionValues": {
        ":one": $util.dynamodb.toDynamoDBJson(1),
        ":typename": $util.dynamodb.toDynamoDBJson("Counter")
    }
  }
}
#end

Another quick amplify push (go ahead and agree to the prompts) grab yourself a beverage of choice and come back to a shiny new API ready for us to use.

Go ahead and try it out in your GraphQL Editor.

mutation{
  hit(input: {
    id: "test"
  }){
    id
    hits
  }
}

And you should get a response similar to this.

{
  "data": {
    "hit": {
      "id": "test",
      "hits": 118
    }
  }
}

Awesome. Next order of business, make ourselves a little counter.

cd src from your project root. You will see some other files and folder in there, like aws-exports.js and graphql. Create a new file called package.json with the following content.

{
  "name": "counter",
  "version": "1.0.0",
  "description": "",
  "main": "index.js",
  "scripts": {
    "test": "echo \"Error: no test specified\" && exit 1",
    "start": "parcel index.html"
  },
  "author": "",
  "license": "ISC",
  "devDependencies": {
    "parcel-bundler": "^1.12.3"
  },
  "dependencies": {
    "aws-amplify": "^1.1.28"
  },
  "browserslist": [
    "last 2 Chrome versions"
  ]
}

Once you've got the file in place and saved run npm install, this may take a few minutes. As part of this, we are installing the aws-amplify Javascript SDK, as well as Parcel, a zero-config bundler so we can bundle up our module and leverage the SDK as well as making it easy to develop on later.

Don't give up now, we are almost there!

Alright, the final two bits before the big payoff.

First, create an index.html file in src.

<!DOCTYPE html>
<html>
<head>
    <title>Counter Widget</title>
</head>
<body>
    <div data-counter-id="test">Loading...</div>
    <script type="text/javascript" src="/index.js"></script>
</body>
</html>

We need this for Parcel to hook in to. Please note, you could be doing most of this in React, Vue, Svelte, and using WebPack or whatever floats your boat. Amplify SDK was leveraged and the rest of the code was written to keep things simple and illustrate the power behind the scenes, I am not trying to proselytize any particular frontend approach.

Finally, we have arrived at the big payoff. Let's create index.js in src as well.

import Amplify, { API, graphqlOperation } from 'aws-amplify';
import awsmobile from './aws-exports';

Amplify.configure(awsmobile);

import * as mutations from "./graphql/mutations";
import * as subscriptions from "./graphql/subscriptions";

/*
Find all the unique counter id on the page.
Send a single hit request for each unique ID.
Subscribe to all updates for each one as well.
*/

const init = function createUpdateCounters() {
    const countersToUpdate = document.querySelectorAll(`[data-counter-id]`);
    const counterHitIdSet = new Set();

    countersToUpdate.forEach((counter) => {
        counterHitIdSet.add(counter.dataset.counterId);
    })

    counterHitIdSet.forEach((id) => {
        hitCounter(id);
    });
}

/*
Send a mutation to your GraphQL to let it know we hit it.
This also means we get back the current count, including our own hit.
*/
async function hitCounter(id) {
    const counter = await API.graphql(graphqlOperation(mutations.hit, { input: { id } }));
    updateText(counter.data.hit)
    subscribeCounter(id)
}

function updateText(counter) {
    const countersToUpdate = document.querySelectorAll(`[data-counter-id=${counter.id}]`);
    countersToUpdate.forEach(function (elem) {
        elem.innerHTML = counter.hits;
    })
}

/*
Subscribe via WebSockets to all future updates for the counters
we have on this page.
*/
function subscribeCounter(id) {
    const subscription = API.graphql(
        graphqlOperation(subscriptions.hits, { id })
    ).subscribe({
        next: (counter) => updateText(counter.value.data.hits)
    });
}

// On dom loaded, kick things off
document.addEventListener("DOMContentLoaded", function () {
    init();
});

The comments contain most the hints about what is going on, but Amplify and GraphQL do a significant amount of the heavy lifting for us.

Go ahead and run npm start in the terminal and visit the URL it says your local dev server is started on. If everything works as expected, you should be able to see a counter after a brief Loading... message.

Open multiple tabs to see the counters increase as more hits accumulate, hit refresh once or twice to see that change propagate across all your open tabs in real-time.

Check out the little demo below, see how many visits have hit this page and codepen! Open it in a couple tabs and hit "rerun" button to watch real-time updates.

So, we made it! There are a couple of important takeaways to think about here. What we've done is running on production ready, massively scalable services. This can easily scale to thousands of requests per second (after lifting some default limits). Our actual code written was quite minimal, allowing Amplify to do the heavy lifting, not to mention everything is actually "infrastructure as code" which means we can create whole new app instances and environments on demand.

The mindset of serverless is all about offloading "undifferentiated heavy lifting", leveraging tools and services like AWS Amplify and AppSync get us closer to producing business value and further from managing infrastructure.