Infrastructure as Text:

Standardizing Serverless Deployments /w .Architect

DarcyClarke

developer, designer, speaker,
entrepreneur, mentor & ux advocate

JS Devs Zone

Conversations with the people supporting projects you depend on now and
driving innovation in the projects of the future

js.foundation/community/js-devs-zone

Episode #0 - sonar http://sonarwhal.com

Episode #1 - .architect http://arc.codes

Brian Leroux

Cofounder/CTO @begin

tldr;
Manual setup & provisioning of infra sucks

Standardizing Serverless
Deployments with .architect

The problems it tries to solve...

"Manifest checked into your revision control system so you can version your infrastructure beside your code"
"Tooling for managing the manifest-based infrastructure"

.arc is a plaintext manifest file

Infrastructure as text

Architecture as text

The existing ecosystem

AWS Serverless Application Model (SAM) Template

AWSTemplateFormatVersion: '2010-09-09'
             Transform: AWS::Serverless-2016-10-31
             Description: Simple CRUD webservice. State is stored in a SimpleTable (DynamoDB) resource.
             Resources:
             GetFunction:
               Type: AWS::Serverless::Function
               Properties:
                 Handler: index.get
                 Runtime: nodejs4.3
                 CodeUri: s3:///api_backend.zip
                 Policies: AmazonDynamoDBReadOnlyAccess
                 Environment:
                   Variables:
                     TABLE_NAME: !Ref Table
                 Events:
                   GetResource:
                     Type: Api
                     Properties:
                       Path: /resource/{resourceId}
                       Method: get
             
             PutFunction:
               Type: AWS::Serverless::Function
               Properties:
                 Handler: index.put
                 Runtime: nodejs4.3
                 CodeUri: s3:///api_backend.zip
                 Policies: AmazonDynamoDBFullAccess
                 Environment:
                   Variables:
                     TABLE_NAME: !Ref Table
                 Events:
                   PutResource:
                     Type: Api
                     Properties:
                       Path: /resource/{resourceId}
                       Method: put
             
             DeleteFunction:
               Type: AWS::Serverless::Function
               Properties:
                 Handler: index.delete
                 Runtime: nodejs4.3
                 CodeUri: s3:///api_backend.zip
                 Policies: AmazonDynamoDBFullAccess
                 Environment:
                   Variables:
                     TABLE_NAME: !Ref Table
                 Events:
                   DeleteResource:
                     Type: Api
                     Properties:
                       Path: /resource/{resourceId}
                       Method: delete
             
             Table:
               Type: AWS::Serverless::SimpleTable

Serverless

# serverless.yml
             
             service: users
             
             provider:
               name: aws
               runtime: nodejs6.10
               stage: dev # Set the default stage used. Default is dev
               region: us-east-1 # Overwrite the default region used. Default is us-east-1
               profile: production # The default profile to use with this service
               memorySize: 512 # Overwrite the default memory size. Default is 1024
               deploymentBucket:
                 name: com.serverless.${self:provider.region}.deploys # Overwrite the default deployment bucket
                 serverSideEncryption: AES256 # when using server-side encryption
               versionFunctions: false # Optional function versioning
               stackTags: # Optional CF stack tags
                key: value
               stackPolicy: # Optional CF stack policy. The example below allows updates to all resources except deleting/replacing EC2 instances (use with caution!)
                 - Effect: Allow
                   Principal: "*"
                   Action: "Update:*"
                   Resource: "*"
                 - Effect: Deny
                   Principal: "*"
                   Action:
                     - Update:Replace
                     - Update:Delete
                   Condition:
                     StringEquals:
                       ResourceType:
                         - AWS::EC2::Instance
            &nsbp;
             functions:
               usersCreate: # A Function
                 handler: users.create
                 events: # The Events that trigger this Function
                   - http: post users/create
               usersDelete: # A Function
                 handler: users.delete
                 events:  # The Events that trigger this Function
                   - http: delete users/delete
             
             # The "Resources" your "Functions" use.  Raw AWS CloudFormation goes in here.
             resources:
               Resources:
                 usersTable:
                   Type: AWS::DynamoDB::Table
                   Properties:
                     TableName: usersTable
                     AttributeDefinitions:
                       - AttributeName: email
                         AttributeType: S
                     KeySchema:
                       - AttributeName: email
                         KeyType: HASH
                     ProvisionedThroughput:
                       ReadCapacityUnits: 1
                       WriteCapacityUnits: 1

Terraform HCL

resource "aws_iam_role" "iam_for_lambda" {
                 name = "iam_for_lambda"
                 assume_role_policy = <<EOF
               {
                 "Version": "2012-10-17",
                 "Statement": [{
                     "Action": "sts:AssumeRole",
                     "Principal": {
                     "Service": "lambda.amazonaws.com"
                   },
                   "Effect": "Allow",
                   "Sid": ""
                 }]
               }
               EOF
               }
             
               resource "aws_lambda_function" "test_lambda" {
                 filename         = "lambda_function_payload.zip"
                 function_name    = "lambda_function_name"
                 role             = "${aws_iam_role.iam_for_lambda.arn}"
                 handler          = "exports.test"
                 source_code_hash = "${base64sha256(file("lambda_function_payload.zip"))}"
                 runtime          = "nodejs4.3"
                 environment {
                   variables = {
                     foo = "bar"
                   }
                 }
               }

Takeaways

Deep proprietary knowledge is required to configure and maintain common infrastructure primatives
Painful manifest files; JSON and YAML are not ideal
Tooling was designed for the last generation of metaphors

.arc

this is an .arc file

The schema is...

Comments start with #
Sections start with @

`@html` defines text/html routes

A Lambda function wired to API Gateway handles requests to `/`.

.arc is Expressive

Workflows supported: `@html`, `@json`, `@events`, `@tables` & more....

https://arc.codes/reference/

Demo

Getting started...

1. Start your node project: npm i
2. Install .architect: npm install @architect/workflows --save
3. Add config into your package.json

4. Create your .arc file
5. Create your app: npm run create
6. Deploy when necessarry

What's next?

What's next...

Working with partners to contribute support (Azure Functions, Firebase Cloud Functions etc.)
@js for text/javascript lambda route handlers
@css for text/css lambda route handlers
npm run dns should generate a static.domainname.com CNAME that points to an S3 CloudFront Distribution from @domain value
@views support added to .arc for universal render support
arc-env env variables and configuration management

Thanks!

http://arc.codes