ref: v0.2.0 straw/README.md -rw-r--r-- 5.2 KiB View raw
                                                                                
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
# straw [![builds.sr.ht status](https://builds.sr.ht/~mna/straw.svg)](https://builds.sr.ht/~mna/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 convention and minimal configuration, the `straw` command generates [terraform][tf]
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][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, `func`s, `queue`s, `topic`s 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][mnaht], [github][mnagh]).

## License

The [BSD 3-Clause license][bsd].

[bsd]: http://opensource.org/licenses/BSD-3-Clause
[tf]: https://www.terraform.io/
[toml]: https://github.com/toml-lang/toml
[mnaht]: https://git.sr.ht/~mna/
[mnagh]: https://github.com/mna