Module documentation for 0.6.0

There are no documented modules for this package.

Stratosphere: AWS CloudFormation in Haskell

AWS CloudFormation is a system that provisions and updates Amazon Web Services
(AWS) resources based on declarative templates. Common criticisms of
CloudFormation include the use of JSON as the template language and limited
error-checking, often only available in the form of run-time errors and stack
rollbacks. By wrapping templates in Haskell, we are able to easily construct
them and help ensure correctness.

The goals of stratosphere are to:

Build a Haskell EDSL to specify CloudFormation templates. Since it is
embedded in Haskell, it is type-checked and generally much easier to work
with than raw JSON.

Have a simple checking/linting system outside of the types that can find
common errors in templates.

Be able to also read valid CloudFormation JSON templates so they can be
type-checked. This also gives us free integration tests by using the huge
amount of example templates available in the AWS docs.

Example

Here is an example of a Template that creates an EC2 instance, along with the
JSON output:

Value Types

CloudFormation resource parameters can be literals (strings, integers, etc),
references to another resource or a Parameter, or the result of some function
call. We encapsulate all of these possibilities in the Val a type.

We recommend using the OverloadedStrings extension to reduce the number of
Literals you have to use.

Lenses

Almost every CloudFormation resource has a handful of required arguments, and
many more optional arguments. Each resource is represented as a record type
with optional arguments wrapped in Maybe. Each resource also comes with a
constructor that accepts required resource parameters as arguments. This allows
the user to succinctly specify the resource parameters they actually use
without adding too much noise to their code.

To specify optional arguments, we recommend using the lens operators & and
?~. In the example above, the ec2Instance function takes the AMI as an
argument, since it is required by the EC2Instance resource type. Then, the
optional EC2 key name is specified using the & and ?~ lens operators.

This approach is very similar to the approach taken by the amazonka library.
See this
blog post
for an explanation.

Auto-generation

All of the resources and resource properties are auto-generated from
a
JSON schema file and
are placed in library-gen/. The gen/ directory contains the auto-generator
code and the JSON model file. We include the library-gen/ directory in git so
the build process is simplified. To build library-gen from scratch and then
build all of stratosphere, just run the very short build.sh script. You can
pass stack args to the script too, so run ./build.sh --fast to build the
library without optimization. This is useful for development.

In the future, it would be great to not have to include the auto-generated code
in git.

Contributing

Feel free to raise any issues, or even just make suggestions, by filing a
Github issue.

Future Work

Implement basic checker for things like undefined Refs and duplicate field
names. This stuff would be too unwieldy to do in types, and performing a
checking pass over a template should be pretty straightforward.

Use a custom JSON encoder so the templates look a little more idiomatic. We
also create a lot of empty whitespace and newlines using aeson-pretty. There
are limits on the size of CloudFormation templates, and we want readable
output without hitting the limits. Also, we have some newtypes that just
exist to override aeson instances, and we could get rid of those.

Use a custom JSON decoder with useful error messages. Although we don’t use
them, we have implemented FromJSON instances for everything. Theoretically,
stratosphere could be used as a checker/linter for existing JSON
CloudFormation templates.

Changes

Change Log

0.24.4

Update resource specification document to new unspecified version

0.24.3

Update resource specification document to new unspecified version

0.24.2

Update resource specification document to version 2.5.0

0.24.1

Update resource specification document to support EKS

0.24.0

Update resource specification document to version 2.4.0

0.23.0

Update resource specification document to version 2.3.0

0.22.3

Update resource specification document to new unspecified version

0.22.2

Update resource specification document to version 2.2.0

0.22.1

Update resource specification document to version 2.1.0

0.22.0

Bug fix: AWSTemplateFormatVersion was being formatted incorrectly in JSON.

0.21.0

Update resource specification document to some new unspecified version.

0.16.0

0.15.2

Update resource specification document to some unspecified new version.

stratosphere now compiles with no warnings.

0.15.1

Update resource specification document to version 1.13.0

0.15.0

Update resource specification document to some unspecified new version.

0.14.0

Update resource specification document to version 1.12.0

0.13.0

Update resource specification document to version 1.11.0

0.12.0

Update resource specification document to version 1.10.0

0.11.0

Update resource specification document to version 1.8.0

0.10.0

Update resource specification document to version 1.7.0

0.9.0

Update resource specification document to version 1.6.0

0.8.0

Update resource specification document (no version given in doc)

GHC 8.2.1 compatibility

0.7.1

Add Export field to the Output type. This allows you to declare
cross-stack references.

0.7.0

Made Val and ValList more type-safe by moving some constructors to
ValList and being more specific with types in functions that only accept
Text parameters. Specific examples include:

Join and Select now require a ValList argument

Base64 and Join now work only on Val Text, not Val a

GetAZs and Split are now in ValList, not Val

Created ImportValueList as a ValList alternative to ImportValue.

Added support for Fn::Sub intrinsic function.

0.6.0

BREAKING CHANGE: Added ValList type. This new type allows you to
reference parameters that are already list types. Previously you had to use
some kludgy workarounds. For example, you can now Ref a parameter of type
List<AWS::EC2::AvailabilityZone::Name>.

Every type that used to be [Val a] is now ValList a. If you use the
OverloadedLists pragma, you might not have to change any of your code.
Otherwise, you must wrap existing lists in the ValList constructor.

BREAKING CHANGE: The newtype wrappers Integer', Bool', and Double'
are no longer required. CloudFormation expects numbers and bools to be JSON
strings. These newtypes used to be necessary so we didn’t use JSON
numbers/bools. Now the conversion is handled internally, and users don’t need
to worry about this when using stratosphere.

0.5.0

Update resource specification document (no version given)

0.4.4

Update the resource specification document to version 1.4.2

0.4.3

Update the resource specification document to version 1.4.1

0.4.2

Update the resource specification document to version 1.2.1

0.4.1

Manually write out all JSON instances to speed up compilation

Fix bug in CloudFormation specification where EvaluationPeriods was
accidentally set to Double.

0.4.0

Derive the Eq type class for everything. This is useful when comparing two
templates.

Added the new Fn::Split function.

Fix error in resource specification document where
AWS::AutoScaling::AutoScalingGroup.Tags was mistakenly called AsTags.

Fix error in resource specification document where the two properties Image
and Name in AWS::ECS::TaskDefinition.ContainerDefinition were incorrectly
marked as not required, even though they are required.

Fix JSON instances for auto scaling group update policies

0.3.1

Updated resource specification document to version 1.1.1.

0.3.0

Backwards-incompatible: We now use the official AWS JSON spec document to
auto-generate types. This means there is no more Python scraper and custom
JSON schemas. The behavior of the library is exactly the same, but a ton of
resource names changed to match official the official AWS names. On the plus
side, we now have 100% service coverage!

0.2.2

Fixed a test suite failure caused by bleeding edge HLint version.

0.2.1

Added Dynamo DB table resources (@ababkin)

Fix the Python docs scraper mishandling the required value in some cases,
and also missing some properties of resources (@amar47shah)