~mna/straw

#straw

The straw command generates an AWS "serverless"-type infrastructure from the project layout.

Repository: https://git.sr.ht/~mna/straw
Issues: https://todo.sr.ht/~mna/straw
Builds: https://builds.sr.ht/~mna/straw
Wiki (user guide): https://man.sr.ht/~mna/straw

#Description

Using a convention-based directory layout and minimal configuration, the straw command generates terraform configuration files to build an AWS "serverless"-type infrastructure. The resources created are isolated per "stage", so that exact replicas can be built e.g. for "test", "staging" or "prod".

What we mean by "serverless" is that the services used do not require explicit management of servers or manual intervention to scale up or down. The following resources are currently supported:

api: AWS API Gateway APIs.
event: AWS CloudWatch events.
func: AWS Lambda functions.
queue: AWS SQS queues.
site: AWS S3-hosted websites.
storage: AWS S3 buckets.
terraform: Custom terraform files.
topic: AWS SNS topics.

Links between those resources can be created with a little configuration - e.g. to use a function as handler for a queue, an API method handler, a subscriber for a topic, etc. Configuration is done in a TOML file named straw.toml in the resource's directory, and straw takes care of generating the required permissions.

#Install

In this early stage, there are no pre-built binaries available. To install, clone the repository and build the command with the go compiler (or use go get).

#Usage

usage: straw [OPTIONS] STAGE

The straw command generates terraform configuration from a project's
directory layout. Each directory under "src/" can be associated
with a serverless service and be used to generate resources (instances
of that service).

The following options are available:
  -app
      The name of the generated app. (default: basename of the directory)
  -a, -apply
      Run 'terraform apply' automatically on the generated configuration.
      (default: true)
  -aws-provider-version
      Version condition for the terraform AWS provider. (default: ~> 1.43)
  -dir
      Root directory of the project to generate. (default: current
      directory)
  -h, -help
      Display this help message and exit. (default: false)
  -A, -no-apply
      Do not run 'terraform apply' automatically on the generated
      configuration. (default: false)
  -I, -no-init
      Do not run 'terraform init' automatically before running
      'terraform apply'. (default: false)
  -out
      Output directory where terraform configuration files are
      generated, with the stage appended as sub-directory.
      (default: ./terraform)
  -terraform-version
      Version condition for the terraform command. (default: > 0.11.0)

By convention, a specific directory layout is expected. For example, the following layout:

* app
  - src
    - api
      - pet_store
        - pets
          - {id}
            * straw.toml
          * straw.toml
        * straw.tom
    - event
      - cronjob
        *straw.toml
    - func
      - hello
        * index.js
        * straw.toml
    - queue
      - queue1
        * straw.toml
    - site
      - example.com
        * index.pug
        * straw.toml
    - storage
      - docsbucket
        * straw.toml
      - miscbucket
        * straw.toml
    - terraform
      - prod
        * prod_specific.tf
      * general_config.tf
      * straw.toml
    - topic
      - appnotif
        * straw.toml
  - dist
    - func
      - hello
        * hello.zip
    - site
      - example.com
        * index.html

The following directories are recognized:

Both src/ and dist/ folders must exist under the app's root directory
The src/ directory defines the resources to generate:
- api, event, func, queue, site, storage and topic sub-directories are recognized and generate the expected resources.
- Under each of those directories, all sub-directories are distinct instances of this resource, provided they contain:
  - a (possibly empty) straw.toml file
  - a (possibly empty) straw_<stage>.toml file, where <stage> exactly matches the current stage
  - both straw.toml and straw_<stage>.toml files, where straw_<stage>.toml overrides configuration set by straw.toml
- For api, directories under the API resource represent path parts (if they have a relevant straw configuration file).
- Terraform and template files under terraform are copied over to the output stage directory (template files are executed with the list of resources as data).
Under dist/, the build system must package the functions in a zip file as expected by AWS Lambda
- Any tool can be used to write the function, as long as it generates a Node or Go zipped package
Under dist/, the build system must generate the static files for the site
- Again, any tool can be used to write the web pages and assets

#Changelog

v0.2.0 : refactor into maintainable code with Service, Resource, Validator, Generator and Hook abstractions, add API Gateway support with Lambda handlers.
v0.1.0 : proof-of-concept, funcs, queues, topics and storage (and site) are supported, along with dependencies (queue handlers, topic subscribers, bucket notifications, function dead letters).

#Contributing

Creator and current maintainer: Martin Angers (sr.ht, github).

#License

The BSD 3-Clause license.

refs

clone