Skip to content

Latest commit

 

History

History
131 lines (89 loc) · 4.69 KB

README.md

File metadata and controls

131 lines (89 loc) · 4.69 KB
Raw

The Exosphere Compiler

Build Status Build Status

Pull Requests

A high level AWS CloudFormation language and compiler.

The exosphere is the uppermost region of Earth's atmosphere as it gradually fades into the vacuum of space.

The goal of Exosphere is to simplify the creation of Amazon Web Service CloudFormation templates and create useful compile-time feedback to the user. This should hopefully make maintaining cloudformation stacks much easier. The aim then is that exosphere is capable of turning exo files into CloudFormation templates and the exo files are parsed and validated to ensure any generated CloudFormation is valid.

Features

  • Easy to write DSL! 💥
  • Property validation (WIP)! 🎉
  • Compile-time feedback (WIP)! 🎊

Table of Contents

  1. Getting started
  2. Stability
  3. Examples
  4. Documentation
    1. Format
    2. Comments
    3. Supported CloudFormation Types
  5. Examples
  6. Grammar
  7. Contributing

Getting started

Build Exosphere from source:

git clone [email protected]:exosphere-lang/compiler.git && cd compiler
stack build --copy-bins

Ensure that the executable generate from stack build is in your $PATH.

Create a valid Exosphere file such as ExosphereBucket.exo:

ExosphereBucket S3Bucket
FamilyPhotosBackup S3Bucket { AccessControl Private }

Run exospherec on the input file. This will create a template for creating a new S3 bucket with the name ExosphereBucket, and one with the access properties.

$ exospherec ./ExosphereBucket.exo

Inspect the generated CloudFormation template ExosphereBucket.exo.json

$ cat ./ExosphereBucket.exo.json
{
    "AWSTemplateFormatVersion": "2010-09-09",
    "Resources": {
        "ExosphereBucket": {
            "Type": "AWS::S3::Bucket",
        },
        "FamilyPhotosBackup": {
            "Type": "AWS::S3::Bucket",
            "Properties": {
                "AccessControl": "Private",
            }
        }
    }
}

Finally, upload to AWS CloudFormation to create your stack!

Stability

The Exosphere grammar is still subject to change, using Exosphere in production isn't recomended at this time.

Documentation

Format

The format for an exosphere (.exo) file is:

resource_name resource_type { propKey1 propValue1, propKey2 propValue2, ... }

The properties are optional. If you omit them, then the brackets are not needed. If you include properties, then the brackets are required. However, the brackets and properties can span multiple lines. Please see the table below for more details

key description sample
resource_name The name you want the cloud formation resource to have MyResource, FestivePictures, MyWebiste, etc
resource_type The service you want to use - corresponds to the AWS::xx::xx format EC2, S3, Lambda, etc
properties The properties you want the resource to have - seperated by a comma, where each key and value is seperated by whitespace

Putting this together, you will have something like:

MyS3Bucket S3Bucket

which will create an S3 bucket called MyS3Bucket.

Comments

Comments are single line only denoted by two slashes at the beginning of a declaration, e.g:

// Bucket for website assets
MyWebsiteAssets S3Bucket

Currently Supported CloudFormation Types

All AWS CloudFormation resource types are supported. The convention is to camel case the resource type and drop "AWS" and the colons, for example. AWS::S3::Bucket in CloudFormation becomes S3Bucket in Exosphere.

Examples

Examples can be found at exosphere-lang/examples. All example source code can be compiled into valid CloudFormation JSON.

Grammar

You can find the formal grammar for Exosphere at exosphere-lang/grammar.

Contributing

Contributions are considered, please raise a pull request or an issue.