appliscale/perun

A command-line validation tool for AWS Cloud Formation that allows to conquer the cloud faster!

Perun

A command-line validation tool for AWS Cloud Formation that allows to conquer the cloud faster!

Goal

Perun was created to improve work experience with CloudFormation. The idea came from the team constantly using AWS CloudFormation - it runs a template online in AWS infrastructure and fails after first error - which in many cases is trivial (e.g. maximum name length is 64 characters). Instead of doing a round-trip, we would like to detect such cases locally.

Building and Installation

OSX

Homebrew:

$ brew install Appliscale/tap/perun

From binaries:

• Go to Perun’s releases https://github.com/Appliscale/perun/releases
• Find and download perun-darwin-amd64.tar.gz
• Unpack the archive

Debian

Dpkg package manager:

• Go to https://github.com/Appliscale/perun-dpkg
• Download perun.deb
• Install:

$ dpkg -i perun.deb

From binaries:

• Go to Perun’s releases https://github.com/Appliscale/perun/releases
• Find and download perun-linux-amd64.tar.gz
• Unpack:

$ tar xvzf perun-linux-amd64.tar.gz

Linux

Rpm package manager:

• Go to: https://github.com/Appliscale/rpmbuild/tree/master/RPMS/x86_64
• Download perun-linux-amd64-1.2.0-1.x86_64.rpm
• Install:

$ rpm -ivh perun-linux-amd64-1.2.0-1.x86_64.rpm

From binaries:

• Go to Perun’s releases https://github.com/Appliscale/perun/releases
• Find and download perun-linux-amd64.tar.gz
• Unpack:

tar xvzf perun-linux-amd64.tar.gz

Building from sources

First of all you need to download Perun to your GO workspace:

$GOPATH $ go get github.com/Appliscale/perun
$GOPATH $ cd perun

Then build and install configuration for the application inside perun directory by executing:

perun $ make

After this, application will be compiled as a perun binary inside bin directory in your $GOPATH/perun workspace.

Working with Perun

Commands

Validation

To validate your template, just type:

~ $ perun validate <PATH TO YOUR TEMPLATE>

Your template will be then validated using both our validation mechanism and AWS API (aws validation).

Configuration

To create your own configuration file use configure mode:

~ $ perun configure

Then type path and name of new configuration file.

Stack Parameters

Bored of writing JSON parameter files? Perun allows you to interactively create parameters file for a given template. You can either pass the parameters interactively or as a command-line argument.

Command Line Parameter way:

~ $ perun create-parameters <PATH TO YOUR TEMPLATE> <OUTPUT PARAMETER FILE> --parameter=MyParameter1:<PARAMETER VALUE>

The greatest thing is that you can mix those in any way you want. Perun will validate the given parameters from command line. If everything is OK, it will just create the parameters file. If anything is missing or invalid, it will let you know and ask for it interactively.

Working with stacks

Perun allows to create and destroy stacks.

Cloud Formation templates can be in JSON or YAML format.

Example JSON template which describe S3 Bucket:

{
    "Resources" : {
        "HelloPerun" : {
            "Type" : "AWS::S3::Bucket"
        }
    }
}

Before you create stack Perun will validate it by default 😉. You can disable it with flag --no-validate.

To create new stack you have to type:

~ $ perun create-stack <NAME OF YOUR STACK>  <PATH TO YOUR TEMPLATE>

To destroy stack just type:

~ $ perun delete-stack <NAME OF YOUR STACK>

You can use option --progress to show the stack creation/deletion progress in the console, but note, that this requires setting up a remote sink.

Remote sink

To setup remote sink type:

~ $ perun setup-remote-sink

This will create an sns topic and sqs queue with permissions for the sns topic to publish on the sqs queue. Using above services may produce some cost: According to the AWS SQS and SNS pricing:

• SNS:
  • notifications to the SQS queue are free
• SQS:
  • The first 1 million monthly requests are free.
  • After that: 0.40$ per million requests after Free Tier (Monthly)
  • Typical stack creation uses around a hundred requests

More information about pricing can be found here.

To destroy remote sink just type:

~ $ perun destroy-remote-sink

Cost estimation

~ $ perun estimate-cost <PATH TO YOUR TEMPLATE>

To estimate template's cost run the command above with path to file. Perun resolves parameters located in the template and checks if it’s correct. Then you get url to Simple Monthly Calculator which will be filled with data from the template.

Protecting Stack

You can protect your stack by using Stack Policy file. It's JSON file where you describe which action is allowed or denied. This example allows to all Update Actions.

{
  "Statement": [
    {
      "Effect": "Allow",
      "Principal": "*",
      "Action": "Update:*",
      "Resource": "*"
    }
  ]
}

To apply your Stack Policy file you have to type:

~ $ perun set-stack-policy <NAME OF YOUR STACK>  <PATH TO YOUR TEMPLATE>

Perun has some default flags:

• --block - Block all Update actions in stack.

• --unblock - Unblock all Update actions in stack.

• --disable-stack-termination - Protect stack from being deleted.

• --enable-stack-termination - Allow to destroy stack.

You use flag instead of template.

~ $ perun set-stack-policy <NAME OF YOUR STACK> <FLAG>

Configuration files

Perun will help you in setting up all the needed configuration files on you first run - no previous setup required.

You can find an example configuration file in the main directory of the repository in file defaults/main.yml.

perun supports multiple configuration files for different locations. Configuration files take precedence, according to the typical UNIX convention. The application will be looking for the configuration file in the following order:

1. CLI argument (-c=<CONFIG FILE>, --config=<CONFIG FILE>).
2. Current working directory (.perun file).
3. Current user local configuration (~/.config/perun/main.yaml).
4. System global configuration (/etc/perun/main.yaml).

Having a configuration file is mandatory. Minimal configuration file requires only AWS CloudFormation Resource Specification URLs, listed under SpecificationURL key:

SpecificationURL:
  us-east-2: "https://dnwj8swjjbsbt.cloudfront.net"
  ...

There are 6 other parameters:

• DefaultProfile (default taken by default, when no value found inside configuration files).
• DefautRegion (us-east-1 taken by default, when no value found inside configuration files).
• DefaultDurationForMFA: (3600 taken by default, when no value found inside configuration files).
• DefaultDecisionForMFA: (false taken by default, when no value found inside configuration files).
• DefaultVerbosity: (INFO taken by default, when no value found inside configuration files).
• DefaultTemporaryFilesDirectory: (. taken by default, when no value found inside configuration files).

Supporting MFA

If you account is using MFA (which we strongly recommend to enable) you should add --mfa flag to the each executed command or set DefaultDecisionForMFA to true in the configuration file.

~ $ perun validate <PATH TO YOUR TEMPLATE> --mfa

In that case application will use [profile]-long-term from the ~/.aws/credentials file ([profile] is a placeholder filled with adequate value taken from configuration files).

Example profile you need to setup - in this case default:

[default-long-term]
aws_access_key_id = <YOUR ACCESS KEY>
aws_secret_access_key = <YOUR SECRET ACCESS KEY>
mfa_serial = <IDENTIFICATION NUMBER FOR MFA DEVICE>

You do not need to use Perun for validation, you can just use it to obtain security credentials and use them in AWS CLI. To do this type:

~ $ perun mfa

Capabilities

If your template includes resources that can affect permissions in your AWS account, you must explicitly acknowledge its capabilities by adding --capabilities=CAPABILITY flag.

Valid values are CAPABILITY_IAM and CAPABILITY_NAMED_IAM. You can specify both of them by adding --capabilities=CAPABILITY_IAM --capabilities=CAPABILITY_NAMED_IAM.

Inconsistencies between official documentation and Resource Specification

Perun uses Resource Specification provided by AWS - using this we can determine if fields are required etc. Unfortunately, during the development process, we found inconsistencies between documentation and Resource Specification. These variances give rise to a mechanism that allows patching those exceptions in place via configuration. In a few words, inconsistency is the variation between information which we get from these sources.

To specify inconsistencies edit ~/.config/perun/specification_inconsistency.yaml file.

Example configuration file:

  SpecificationInconsistency:
    AWS::CloudFront::Distribution.DistributionConfig:
      DefaultCacheBehavior:
        - Required

License

Apache License 2.0

Maintainers

• Maksymilian Wojczuk
• Piotr Figwer
• Sylwia Gargula
• Mateusz Piwowarczyk

Contributors

• Wojciech Gawroński (originator)
• Jakub Lamparski
• Aleksander Mamla
• Kacper Patro
• Paweł Pikuła
• Michał Połcik
• Tomasz Raus

perun's Issues

Moving notification about dead resources and nil to the verbose mode

As in the title, it may be misleading putting it by default.

Showing details about used Profile and Configuration

In order to avoid problems and accidental misuse, we need to be a little bit more verbose.
Good example of well behaving tools are ones from Hashicorp - as they're reporting progress, and e.g. what is picked from defaults, configuration files and profiles.

For now we would like to have following elements displayed when we are calling AWS API:

• Name of the used aws-cli profile.
• Region that will be used.
• Configuration file used by the tool (related to #5).
• Token expiration date.
  • In user friendly format, maybe not always - but showing that it will expire shortly.
  • That can be useful also as a separate command inside tool.

Generate parameters file based on Parameters section inside the Template

In order to use aws-cli with CloudFormation that has a lot of Parameters, you need to pass huge amount of command arguments to fill it, or prepare a JSON file with all those values.

We would like to have it available as a command in our tool - we would like to generate a file (sending output to the stdout) or command line arguments string only. Values should be read from the standard input (both - interactively or passed as a stdin via pipe or something similar).

Validate deletion policy when its value is taken form a parameter

Problem is well described in the following article:
https://www.unixdaemon.net/cloud/cloudformation-annoyance-deletion-policy-parameters/.

Dependency Resolution (Imports / Exports / Nested Stacks)

More complicated CloudFormation environments consists of multiple files. Also there are nested stacks available for us, in order to increase reuse.

Dependencies between those stacks are mostly bound to:

• Imports and exports.
• Nested stacks availability.

We would like to:

• Detect uniqueness for exported values across multiple files in the project.
• Detect import and export dependencies between multiple files (predicable, valid execution order).
• Validate nested stacks usage and its presence, also for proper execution order.

Removing .preprocessed.yml

As we decided to workaround, some inconsistencies/deficiencies of goformation @jlampar introduced debugging element that allows generating an intermediate representation of the YAML file.

This can be enabled only via source code and recompiling tool locally, anyway after we test this element thoroughly and we backport features to the upstream we should be able to get rid of this functionality. This task is a reminder of that.

Packaging

Currently, we need to build perun locally in order to use it. It is very inconvenient - we would like to distribute it in packaged form (binary distribution).

We would like to support:

• brew (done by @ppikula)
• rpm
• deb
• Chocolatey

For other cases - compiling from source.

It is related to #28 as it will require cross-platform building and integration tests.

More advanced Offline Validation and Linting

Let's discuss here what we would love to see as a next step of validation / linting capabilities, our list so far:

• In many cases fails during CloudFormation run are related with particular name length:
  • E.g. maximum length is 64 characters for a particular value.
  • Problem: there is no specification for that, only way to determine that is trial and error. 😭
• Validating IP and CIDR.
  • Also helpful will be checking relations between:
    • E.g. Subnets inside VPC should be a subset of VPC CIDR and so on.
• Uniqueness / Missing exports for a project (we need a notion of project first).
• Check general state of infrastructure before run:
  • E.g. check before starting the CF stack that your subnet has expected number of IPs to assign EC2.
• Suggestions regarding programming constructs.
  • E.g. use Fn::Sub instead of Fn::Join and so on.
    • Or you can use ${AWS::Region} instead of your own variable.

Support for creating and destroying stacks

We would like to have the ability to create and destroy CloudFormation stacks with use of perun. We can implement them as separate commands:

~ $ perun create --stack <STACK_NAME>
~ $ perun destroy --stack <STACK_NAME>

We need to adjust our documentation in the repository as well.
Feature requested after internal review.

Translating CloudFormation to the other Languages

• Seems hardcore and very high-level, but let's tackle it. 😉
  • Imagine having tool that will convert your AWS infrastructure CloudFormation templates to the Azure Resource Templates or even to the Terraform definitions?

Open questions:

• What about compatibility when it comes to resources between cloud providers?
  • Even if they're providing similar service details will be different e.g. SLA.
  • In such case: is partial migration an added value?
• How to tackle different languages?
  • E.g. YAML or even JSON conversion seems feasible, converting to any DSL - like Hashicorp HSL - seems slightly more difficult.

MFA should not be required parameter

When running:

$ perun create-stack my-stack-name path/to/template --region us-east-1 --profile some-profile

I got:

 INFO: Configuration file from the following location will be used: /Users/myuser/.config/perun/main.yaml
ERROR: There is no mfa_serial for the profile some-profile-long-term

If you don't specify --mfa the check for mfa_serial should be probably omitted. It is up to users if they are going to use mfa or not.

Additionally if something is throwing an error I would expect the whole command to fail, but in this case the stack was created.

New YAML parser

Curently we are using ghodss/yaml library for unmarshalling yaml files into GO structures. It is nice and easy to use, but it converts YAML to JSON then uses JSON to unmarshal into an object and cause some problems in our case (see #23). We need a library, that converts YAML straight into GO structures. https://github.com/go-yaml/yaml is a good candidate. So lets start with trying it out in our code! 😃

Validation - Improvements

After releasing 1.0.0 we would like introduce couple of improvements 1.1.0:

• We are stopping after finding a first error.
• We are missing line and column when listing errors.
• validate_offline is a pretty long name - how about lint or check?

Basic Styling Guidelines

Goal of our tool is to be a watchdog when it comes to best practices and project related guidelines for CloudFormation templates. At the beginning we would like to have following checks:

• Indentation (e.g. always use 2 spaces etc.)
• Suggestions about style:
  • Good practices working with YAML (e.g. formatting, always use / do not use double quotes).
  • Good practices working with JSON (e.g. formatting, line length).
  • Good practices working with CloudFormation:
    • Missing Type annotations.
    • Highlight missing Description or Hints fields.
    • Not using > if lines are too long for YAML.
  • Naming conventions for logical names (inside a template).
  • Naming conventions for external names (part of ARNs).

Remember about:

• Using multi-level configuration for both:
  • Naming conventions (e.g. project related prefixes).
  • Configuration for enabling / disabling particular options.
• Providing documentation - list of checks, and how to use that command.

Add --capabilities flag to perun create-stack

Right now if you try to create cloudformation stack with e.g. AWS::IAM::Role, you will get following error:

[1] % perun create-stack lambda-ec2-backup-role lambda-role.yml
 INFO: Configuration file from the following location will be used: /Users/mpolcik/.config/perun/main.yaml
 INFO: Profile: aol
 INFO: Region: us-east-1
ERROR: InsufficientCapabilitiesException: Requires capabilities : [CAPABILITY_NAMED_IAM]
        status code: 400, request id: c195e7fb-2e9d-11e8-b33c-f705a4379654

In order to resolve that we need to add sth similar to --capabilities flag in aws cli. You can look for more details here: https://docs.aws.amazon.com/cli/latest/reference/cloudformation/create-stack.html

Website and Domain name

We need to prepare:

• Domain name - our proposals:
  • perun-for-aws.io
  • perun-cloud.io.
• Graphics Design for such landing page.
• Nice video / screencast about installation or use cases (we may use asciinema.org for that).
• Front-end that should be able to leverage gh-pages mechanism.

Mode parameters should be available also with explicit flag names

I would like to open discussion here about the usability of our CLI modes.

Currently, most of the modes uses implicit order of parameters, e.g.,

perun convert A.json B.yaml
perun convert A.yaml B.json --pretty-print

That's good. However, I would love to have it available also under explicit parameter names:

perun convert A.json B.yaml
perun convert --from=A.json --to=B.yaml

perun convert A.yaml B.json --pretty-print
perun convert --from=A.yaml --to=B.json --pretty-print

I know that will complicate the implementation, but maybe advantages are more significant than drawbacks.

Price Calculation - Improvements

Currently AWS API when asked for a price estimation for a CloudFormation template returns link to the AWS Calculator which is not exactly we want. 😉

We would like to have following functionality:

• Price should be extracted from the web page (AWS calculator) returned from API.
  • With distinction based on resource type.
• Summing up multiple stacks together in a project.
  • With distinction based on resource type or stack.

Open Source Advertising

StackOverflow has interesting platform for open source projects advertising - https://meta.stackoverflow.com/questions/362773/open-source-advertising-1h-2018.
We can create Perun poster, put it there and try to get some votes.

Cross-platform Integration Tests (includes Windows CI pipeline)

It seems that Travis CI support for Windows build pipelines is still in beta and immature. After some research, I found tool that might be handy and it's free for OSS:

https://www.appveyor.com/

Diff algorithm for CloudFormation stack knowledge and current resource state

We would like to be able to see diff state between what CloudFormation knows about particular stack from its state (based on the file) and how the current resource looks like (after possible manual modification).

Such feature would ease restoring resources after manual modification in order to reapply safely CloudFormation updates.

Marketing around Perun

We need to gather feedback from current users (internally - knowledge sharing sessions and externally - other meet-ups), improve documentation and make a little more noise around perun in social media.

Showing CloudFormation execution progress in the CLI

Goal of this task is to show output of the CloudFormation run in the console (with colors 😉). It is like an interactive mode for running it, without switching to the browser.

It may require additional setup - like SNS topic, subscribing to it or calling periodically describe-stack-events.

• Resources:
  • https://stackoverflow.com/questions/33664226/how-to-send-sns-notification-after-cloud-formation-is-completed
  • http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/using-cfn-updating-stacks-monitor-stack.html#using-cfn-updating-stacks-monitor-stack.CLI

Conversion - Improvements

After releasing 1.0.0 we would like introduce couple of improvements 1.1.0:

• There should be option for pretty printing outputted JSON (done by @SylwiaGargula).
• Auto-detection of input file format (done by @SylwiaGargula).
• We should transform shorthand syntax intrinsic functions e.g. !importValue.
• We should prepare very complete test suite for that feature that will handle various cases.

Protecting CloudFormation stacks

We can provide an added value when it comes to protecting stack resources.

Currently you need to apply such policy after stack is created and change it (remove it, most cases temporarily) if you want to update it. Such policy is a JSON document, that needs to be around when you want to enable / disable it.

In that feature we can accept any valid JSON policy (question is do we want to do more complicated validation on it). As an added value we can provide an opinionated templates for that - adding that to the enable / disable commands available close to your fingertips makes this feature extremely usable.

Source Code Quality - Architecture and Tests

We're missing couple of points regarding code quality - let's address most important ones in 1.0 release.

• As we did not know anything about road-map, we couldn't plan structure and architecture of this project. Now we know more and it is time to prepare more modular structure (more packages? Preparing places for a library that could be extracted?).
• Lack of unit tests. We need those. 😉
• We are not measuring code coverage (there is no goal for CC, but we can enable it in the build pipeline).
• We can leverage rest of go tooling - e.g. go vet and other stuff (static code analysis) and include it in the build pipeline.
• Reviewing dependencies and preparing a list with rationale "why we chose them" (Wiki).

Name, motivation and clear goal

We need:

• A catchy name for that project. 😉
  • "Catchyness" is one thing - it needs to have nice name / shortcut for a command line interface.
• Motivation and rationale - why we created it in the first place?
  • Section in README.md and maybe longer explanation on the wiki if needed.
• Clear goal - with what we want to help via this tool?
  • Section in README.md and maybe longer explanation on the wiki if needed.

Lack of resource validation for nested properties

We have received the report that are not validating nested properties in resources e.g.

SomeDistribution:
    Type: AWS::CloudFront::Distribution
    Properties:
      DistributionConfig:
        Origins:
        ...

Validator will confirm that DistributionConfig is present - it’s a required property, but it will not dive into the properties of DistributionConfig.

Profile as a command line parameter

Right now we need to set profile in the configuration file (if not specified it takes the default). We would like to have command line argument (-p, --profile) for all commands requiring such knowledge that will override the value read from settings.

Multi-Level Configuration - Base

Currently - as we're using official AWS SDK for Go - we should properly leverage ~/.aws configuration - including profiles, defaults (e.g. default region for profile or CLI rendering) and credentials management.

However from our experience that's not entirely enough, especially if you are switching between profiles. What I would like to propose is to add additional configuration layer for our tool based on typical hierarchical configuration that is in line with UNIX filesystem (overrides go from top to the bottom of following list):

• Machine global configuration in /etc/.
• User specific configuration in ~/.[name] or ~/.config/[name].
• Project directory (root of the project, e.g. where .git resides) with project specific configuration file called .[name].
  • Q: should we / how to do resolution, if someone calls the tool not from the root of the project?

For now we should have there only 2 configuration fields:

• profile - pointing on AWS CLI profile used by default.
• region - pointing, overriding default region used by AWS CLI.

After developing - it needs proper documentation section for setting it up correctly.

Add update-stack command

Add ability to update created cloudformation stack, e.g.:

$ perun update-stack <stack-name> <path-to-template>

Inconsistencies between official documentation and Resource Specification

Sigh.

We cannot trust entirely Resource Specification from AWS API, because we've already found inconsistencies:

Inconsistent URLs between specification and reality

a) Real URL to docs:

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudfront-distributionconfig.html#cfn-cloudfront-distributionconfig-defaultcachebehavior

b) URL from specifications:

http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/aws-properties-cloudfront-distribution-distributionconfig.html#cfn-cloudfront-distribution-distributionconfig-defaultcachebehavior

The one from specifications does not exists 😕 Small difference between those two, but still.

Specs are not up to date in every case

    "AWS::CloudFront::Distribution.DistributionConfig": {
      "Properties": {
        ...
        "DefaultCacheBehavior": {
          "Type": "DefaultCacheBehavior",
          "Required": false,
          "Documentation": "https://...",
          "UpdateType": "Mutable"
        },
      ...
      }
    }

Look at the required property value - false.
And now take a look at the documentation:

DefaultCacheBehavior
The default cache behavior that is triggered if you 
do not specify the CacheBehavior property or if files 
don't match any of the values of PathPattern in 
the CacheBehavior property.

Required: Yes

Type: DefaultCacheBehavior type

When the first one issue is not so big, the second one may cause us some problems, I hope there are not too many inconsistencies like that.

Solution:

We need to create a patching mechanism inside perun that will allow patch in place via code / configuration those exceptions.

Adding support for short version of intrinsic functions missing from goformation

Missing support for functions in our intrinsicsolver module:

• !Ref
• !GetAtt
• !ImportValue

Blog post with survey about 5 worst things in CloudFormation

Main goal of the blog post

We need to gather feedback from the community about worst things that are available in AWS CloudFormation and address them appropriately. For the reference, what CloudFormation is here.

A survey should be in the form of a blog post on Appliscale's blog, with our subjective five worst things. Then we should include a call to action to the community about what are their problems and their point of view. We are counting on their feedback in issues in our repository on Github (https://github.com/Appliscale/perun).

Why we do it? We can mention here, that based on our experiences we are working on the tool that helps with working on that, and we are almost ready with releasing publicly announced version 1.1 - next blog post, an announcement, will be a follow up to this post.

List

Our subjective list:

1. Very long feedback cycle - developing templates locally and then doing validation is very cumbersome, because we need to validate created a template with an external API - that consumes time. Moreover, that validation is very preliminary - actual errors are popping up when we are trying to create resources from that template, so in the run-time, which is very late in the process - that wastes developer time.
2. Very hard to bootstrap - at the beginning, CloudFormation templates are overwhelming because you need to provide a lot of structure from the very first step. Then after establishing the structure of couple first templates, you do copy and paste to start quickly, which is cumbersome. Especially in the situation when you are trying to unify conventions, see below.
3. Hard to enforce code conventions and consistency - in short words templates are human-friendly and human-readable configuration. It may become a tangled mess and maintenance nightmare if you do not implement any convention. Especially when it comes to applying changes consistently everywhere, e.g., unifying namings, enforcing policies and many other things. All of those require manual work, so you are losing time.
4. Hard to get standardized approach and convention - referring to issue above, it is hard to get "one true way" when it comes standard how to write and structure CF templates (e.g., how big, how isolated they should be). Amazon does not propose anything, and because of that, we have almost like the free-text possibilities. And each separate voices (e.g., developers, companies) are offering their standard.
5. Repetition, repetition, repetition - we need to repeat a lot when writing it. It is error-prone, it is hard to maintain. YAML and JSON flavors do not support any fragments or smaller templating engine, so it is hard to reuse and work in line with DRY principle (don't repeat yourself).

References

What is perun?

A swiss army knife that helps you with every single step of workflow related to AWS CloudFormation templates.

Motivation

Perun was created to support work with CloudFormation templates. We are providing the tool that helps sysop/developer/cloud architect on every step when working CloudFormation templates. We are handling everything - starting from designing, developing, then validating linting, enforcing code conventions, validation, cost management, managing, and maintaining them later.

Adding LICENSE

We need to choose and add license to the repository.

Official announcement on Appliscale's blog

Official Announcement

We need a blog post with an official announcement after we complete designing new logo and website (with proper tutorial). After that, we need to prepare social media noise around it.

• Primary goals for such blog post:
  • Announcing that we have 1.1.
    • A tool that covers our needs, and in the current form we believe it is valuable to share it with the community.
  • Why not 1.0?
    • Because we used 1.0 internally, so officially announced version is a more polished version of 1.0.
  • What does it provide?
  • It addresses previously aforementioned five worst things when it comes to CloudFormation development.
• A blog post should redirect traffic to our perun website and this repository, and encourage for participation, testing the tool and providing us feedback and creating issues in our repository.

Context (Long Term Plan)

First, we will publish the worst top 5 things in CloudFormation; then we gather the feedback from the community, then we show our approach how we tackled those problems. Then again, we will collect feedback, usage notes, and issues from 1.1, and we address them in implementation and another blog post.

How? So, after 1.1 announcement, we can do a follow-up blog post about 2.0 release - a sneak peek (with screenshots), and plans for future versions - maybe even a visual roadmap presentation. In that article, we will take into account community proposals and adjust our plans.

Validation of Parameters section for AWS-specific parameter types.

Parameters section shouldn't pass validation, when AllowedValues field is provided for AWS-specific parameter types.

Currently both Perun and AWS assumes that the template is valid.

Template example:

AWSTemplateFormatVersion: "2010-09-09"

Description: >
  Example which uses allowed values for AWS-specific types
Parameters:
  VpcIdNotWorkingExample:
      Description: >
        If we use AllowedValues here, it will pass the validation, but will cause errors while invoking the template.
        What is more, when creating a stack using AWS console, dropdown with values for this parameter will cease to work.
        The solution is to either remove AllowedValues, or change the parameter type to String.
      Type: AWS::EC2::VPC::Id
      AllowedValues:
        - vpc-deadbeef
        - vpc-d9999999
  VpcIdWorkingExampleWithStringType:
      Description: >
        Using string type solves the problem.
      Type: String
      AllowedValues:
        - vpc-deadbeef
        - vpc-d9999999
  VpcIdWorkingExampleWithNoAllowedValues:
      Description: >
        Removing AllowedValues solves the problem.
      Type: AWS::EC2::VPC::Id

Resources:
  mySubnet:
    Type: AWS::EC2::Subnet
    Properties:
      VpcId: !Ref VpcIdNotWorkingExample
      CidrBlock: 10.0.0.0/24
      AvailabilityZone: "us-east-1a"
      Tags:
      - Key: foo
        Value: bar

Perun should detect this kind of error, especially that AWS documentation is not explicit about the way AllowedValues is handled for other types than String.

Default duration for MFA token as a setting

Right now each time we're refreshing / generating for a first time MFA token we need to pass duration. Let's shorten that cycle and introduce new optional setting, without default value - when no value is set we will ask about it (as we currently do).

Updating documentation for 2.0 changes

This is a ticket for combining all changes that should be applied to documentation for 2.0 release:

• Adding information that there are arguments and named parameters available for all commands.

Basic Offline Validation

Currently we have online validation based on AWS API, which is usual one, but far from ideal.

Issues with current approach:

• Occurrence of first failure causes bail out.
• It needs internet connectivity.
• It provides just basic validation, most of the errors could be avoided after introducing more complicated validators (e.g. which are aware of the field type).

In the first milestone we need:

• Multiple syntax validation errors for JSON (if possible to parse) and showing place where is it.
• Multiple syntax validation errors for YAML (if possible to parse) and showing place where is it.
• Offline validation for CloudFormation resources based on AWS CloudFormation Resource Specificaion, from here.
  • If that will be too much work - we can prioritize most important resources that should land in 1.0.
  • Again - multiple validation errors (if possible to parse).
  • What should we validate?
    • Values provided as a base types (Number, String, Boolean).
    • Presence of Type annotations.
  • This task should built a foundation that will allow to monitor more complicated types (e.g. IP, CIDR etc.).
    • Still, we don't want to built a DSL / plug-in here system yet.

Remember to use that YAML / JSON validation also when converting between those.

And we need to document a list of validation checks and how to use such command on our Wiki or inside README file.

Polishing the internals and simplifying

There are things that can be polished in 1.1. One of them is reducing the enormous, over-coded loop in offlinevalidator's obtainResources function to more elegant form. This is not a new feature - just doing some tidying and simplifications. If there is possibility somewhere to make it look better, let's do a spring cleaning before 2.0.

Maintenance commands

We need two additional commands that are necessary from maintenance perspective:

• perun --mode=configure - application should work without configuration files, but it should detect that fact and show the helpful message, that you should configure it.
  • This command should fetch list of URLs for AWS CloudFormation Resource Specification and save it in the file.
  • This should interactively ask for Region and Profile (but you can also pass those as command line parameters - as you may configure that tool without user interaction).
    • Maybe a good idea will be to provide autoconf (just fetching URLs) and configure modes (interactive one).
  • This will remove necessity for copying default configuration file and so on.
• perun --version - we need store and print out version and name of the release, with additional metadata with which version of Go we built the tool and on which OS.

Please keep in mind that commands will be treated differently after #39.

Blog post "Getting started with Perun"

We need a blog post about how to install, validate and create a first CF stack with perun.
We can reuse existing documentation and asciinema animations.

Visualizing CloudFormation Templates

• Rendering infrastructure as a image based on the conent of one or mulitple CloudFormation templates.
  • Similar ideas:
    • https://github.com/milo-minderbinder/AWS-PlantUML
    • https://cloudcraft.co
    • AFAIR: It has just graphing, no support for CloudFormation, but also:
      • It has nice icons and isometric view looks cool on those.
      • It has pricing calculation enabled.
  • Nice icon sets:
    • https://aws.amazon.com/architecture/icons (EFS / SVG most important for us I guess 😉).

Quiet / Verbose modes for a CLI

So we need 2 things in that task:

• We need a Logger subsystem - that will be available for all modules of our application.
  • And starting from that day - we need to use it everywhere instead of printing directly to the stdout.
  • We may need similar subsystem for interacting with stdin.
• Then we need couple of command line switches:
  • -quiet (short version: -q) - no output at all, just error code.
  • -yes (short version: -y) - answering yes to all questions, no interactive answers from stdin.
  • -verbosity=[trace|debug|info|error] (short version: -v=) - for setting proper communication verbosity.

Language Server Protocol

We did some research before we started and @pfigwer found couple of interesting facts - in most cases integration with editors for CloudFormation is based on basically auto-completion (crude and simple one), syntax validation and using API for basic stuff - nothing more.

What if we could leverage those specs in order to deliver Language Server Protocol inside our tool and integrate it properly with the editors and IDEs?

• https://github.com/Microsoft/language-server-protocol
• http://langserver.org

Support for commands and passing modes more like git

Currently in order to execute particular command we need to pass an argument - either -m or --mode. We would like to achieve something more closer to the git commands syntax:

~ $ perun validate template.yaml --mfa
~ $ perun convert template.yaml template.json --pretty-print

Feature requested after internal review.

Adding support for FindInMap validation

It would be great if the tool could check if the key referenced in FindInMap function is present in mappings section.

It might not be that straightforward to implement it properly, because of possibility of using other functions nested inside FindInMap function. Example from AWS documentation mentioned earlier:
ImageId: !FindInMap [ RegionMap, !Ref "AWS::Region", 32 ]

Logo

We need to prepare:

• Concept for a logo.
• Professional graphics design for it.

Templating Engine / Generators

• Templates / Generators for new files (like in case of Rails or Phoenix framework) - in a project in most cases you will reuse a lot of elements between files, which needs to be copied - I personally think that some kind of templating / bootstrapping would eliminate the boilerplate and mundane work.
• I used to use CloudFormer to do a snapshot / conversion of existing infrastructure to the CloudFormation in order to start-up and build-up some skeleton quickly:
  • http://docs.aws.amazon.com/AWSCloudFormation/latest/UserGuide/cfn-using-cloudformer.html
  • Maybe we can simplify that process to a single command execution. 😉