~mna/straw

ref: v0.2.0 straw/README.md -rw-r--r-- 5.2 KiB View raw
325babacMartin Angers add api doc, v0.2.0 changelog 1 year, 7 months ago

straw builds.sr.ht status

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

Description

Using convention 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". Each stage is fully isolated.

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.
  • func: AWS Lambda functions.
  • queue: AWS SQS queues.
  • topic: AWS SNS topics.
  • storage: AWS S3 buckets.
  • site: AWS S3-hosted websites.

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.

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
    - func
      - hello
        * index.js
        * straw.toml
    - queue
      - queue1
        * straw.toml
    - site
      - example.com
        * index.pug
        * straw.toml
    - storage
      - docsbucket
        * straw.toml
      - miscbucket
        * 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, 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).
  • 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.