stratosphere: EDSL for AWS CloudFormation

This is a package candidate release! Here you can preview how this package release will appear once published to the main package index (which can be accomplished via the 'maintain' link below). Please note that once a package has been published to the main package index it cannot be undone! Please consult the package uploading documentation for more information.

[maintain] [Publish]

Warnings:

EDSL for AWS CloudFormation


[Skip to Readme]

Properties

Versions 0.1.0, 0.1.1, 0.1.2, 0.1.2.1, 0.1.3, 0.1.4, 0.1.5, 0.1.6, 0.2.0, 0.2.1, 0.2.2, 0.3.0, 0.3.1, 0.4.0, 0.4.1, 0.4.2, 0.4.3, 0.4.4, 0.5.0, 0.6.0, 0.7.0, 0.7.1, 0.8.0, 0.9.0, 0.10.0, 0.11.0, 0.12.0, 0.13.0, 0.14.0, 0.15.0, 0.15.1, 0.15.2, 0.16.0, 0.17.0, 0.18.0, 0.19.0, 0.19.1, 0.20.0, 0.21.0, 0.22.0, 0.22.2, 0.22.3, 0.23.0, 0.24.0, 0.24.1, 0.24.2, 0.24.3, 0.24.4, 0.25.0, 0.26.0, 0.26.1, 0.26.2, 0.27.0, 0.28.0, 0.28.1, 0.29.0, 0.29.1, 0.30.0, 0.30.1, 0.31.0, 0.32.0, 0.33.0, 0.34.0, 0.35.0, 0.36.0, 0.37.0, 0.38.0, 0.39.0, 0.40.0, 0.41.0, 0.42.0, 0.43.0, 0.44.0, 0.45.0, 0.46.0, 0.47.0, 0.48.0, 0.49.0, 0.50.0, 0.51.0, 0.52.0, 0.53.0, 0.54.0, 0.55.0, 0.56.0, 0.57.0, 0.58.0, 0.59.0, 0.59.1, 0.60.0
Change log CHANGELOG.md
Dependencies aeson (>=0.11), aeson-pretty (>=0.8), aeson-qq, base (>=4.8 && <5), bytestring, containers, hashable, lens (>=4.5), stratosphere, template-haskell (>=2.0), text (>=1.1), unordered-containers (>=0.2) [details]
License MIT
Author
Maintainer David Reaver
Category AWS, Cloud
Home page https://github.com/frontrowed/stratosphere#readme
Bug tracker https://github.com/frontrowed/stratosphere/issues
Source repo head: git clone https://github.com/frontrowed/stratosphere
Uploaded by jdreaver at 2018-05-02T13:13:35Z

Modules

Flags

Manual Flags

NameDescriptionDefault
library-only

Don't compile examples

Enabled

Use -f <flag> to enable a flag, or -f -<flag> to disable that flag. More info

Downloads

Maintainer's Corner

Package maintainers

For package maintainers and hackage trustees


Readme for stratosphere-0.22.0

[back to package description]

Stratosphere: AWS CloudFormation in Haskell

Circle CI

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:

Example

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

{-# LANGUAGE OverloadedLists #-}
{-# LANGUAGE OverloadedStrings #-}

module Main where

import qualified Data.ByteString.Lazy.Char8 as B
import Stratosphere

main :: IO ()
main = B.putStrLn $ encodeTemplate instanceTemplate

instanceTemplate :: Template
instanceTemplate =
  template
  [ resource "EC2Instance" (
    EC2InstanceProperties $
    ec2Instance
    "ami-22111148"
    & eciKeyName ?~ (Ref "KeyName")
    )
    & deletionPolicy ?~ Retain
  ]
  & description ?~ "Sample template"
  & parameters ?~
  [ parameter "KeyName" "AWS::EC2::KeyPair::KeyName"
    & description ?~ "Name of an existing EC2 KeyPair to enable SSH access to the instance"
    & constraintDescription ?~ "Must be the name of an existing EC2 KeyPair."
  ]
{
  "Description": "Sample template",
  "Parameters": {
    "KeyName": {
      "Description": "Name of an existing EC2 KeyPair to enable SSH access to the instance",
      "ConstraintDescription": "Must be the name of an existing EC2 KeyPair.",
      "Type": "AWS::EC2::KeyPair::KeyName"
    }
  },
  "Resources": {
    "EC2Instance": {
      "DeletionPolicy": "Retain",
      "Type": "AWS::EC2::Instance",
      "Properties": {
        "KeyName": {
          "Ref": "KeyName"
        },
        "ImageId": "ami-22111148"
      }
    }
  }
}

Please see the examples directory for more in-depth examples.

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