https://blog.thundra.io/introduction-to-the-architect-framework
4 minutes read
In the era of cloud computing, infrastructure as code (IaC) is the way to go for managing your resources. With the rise of serverless, which often leads to finer granular deployments, it’s even more important to have one source of truth for your whole infrastructure.
Sadly, though, things aren’t as straightforward as they seem. IaC tools like CloudFormation (CFN) have grown over the years. CFN includes most resources AWS has to offer, and it uses YAML as a file format to define those resources. However, if you want to define your serverless systems with plain CFN, you run into problems.
Every Lambda function needs permissions to access other AWS services, and every AWS service that wants to access a Lambda function also needs permissions to do so. A dozen Lambda functions multiplied by all those permissions can get quite cumbersome. You also need to link up your events to connect them with API gateways and databases.
All this has led to the creation of tools that automate the ceremony of explicitly provisioning supporting services. One of them is the Architect framework (ARC), a project of the OpenJS foundation. ARC is an IaC framework that lets developers define their serverless infrastructure in a concise way. It’s used as the IaC framework of choice by Begin, a service built on top of AWS that tries to ease the building and deployment of serverless apps and APIs.
ARC lets you define your infrastructure in .arc files that have a very simple flat syntax. A serverless REST API for books could look like this:
@app
books-api
@http
post /books # create
get /books # list
get /books/:bookID # read
patch /books/:bookID # update
delete /books/:bookID # delete
The @app pragma defines the name of the app, and the @http pragma lets you define serverless functions triggered by HTTP requests.
ARC favors “convention over configuration,” so it will assume the actual code for the serverless function is in a predefined place, with the default runtime being Node.js. In our example above, the file for our list function should be located in src/http/get-books/index.js. If you run ARC’s init command in a directory with an app.arc file, it will automatically generate those JavaScript files for you in the right places.
If we want to save files into an S3 bucket, we can use the @static pragma. To run a Lambda function on a schedule instead of an HTTP request, we can use @scheduled. We can even drop our files onto CloudFront by using @cdn; there’s no need to define API Gateway and Lambda resources independently.
Another nice feature that’s also missing from CFN is local sandboxing. This allows you to run Lambda functions on a development machine without having to deploy it to AWS first. The ability to run and debug locally drastically increases development velocity and helps you find problems right when a new feature is created.
If you run the following code inside an ARC project, it will start a development server on a free port for you:
Let’s build a sample application with ARC, a small website that talks to a serverless API.