perun

command module
v0.0.0-...-a4d1c73 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Mar 4, 2019 License: Apache-2.0 Imports: 14 Imported by: 0

README

Perun Release Build_Status License Go_Report_Card GoDoc

Perun logo

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:
Debian
Dpkg package manager:
$ dpkg -i perun.deb
From binaries:
$ tar xvzf perun-linux-amd64.tar.gz
Linux
Rpm package manager:
$ rpm -ivh perun-linux-amd64-1.2.0-1.x86_64.rpm
From binaries:
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

Contributors

Documentation

Overview

A tool for CloudFormation template validation.

Source Files

View all Source files

Directories

Path Synopsis
Package awsapi contains interface with all functions which use AWS CloudFormation API.
 Package awsapi contains interface with all functions which use AWS CloudFormation API.
Package checkingrequiredfiles checks if .aws/config, .aws/credentials main.yaml and other configuration files exist.
 Package checkingrequiredfiles checks if .aws/config, .aws/credentials main.yaml and other configuration files exist.
mocks
Package mocks is a generated GoMock package.
 Package mocks is a generated GoMock package.
Package cliparser provides tools and structures for parsing and validating perun CLI arguments.
 Package cliparser provides tools and structures for parsing and validating perun CLI arguments.
Package configuration provides reader for perun configuration.
 Package configuration provides reader for perun configuration.
Package configurator allows to create configuration file main.yaml.
 Package configurator allows to create configuration file main.yaml.
Package context provides context for perun.
 Package context provides context for perun.
Package helpers has some useful functions to choose parser and ease scan maps and slices.
 Package helpers has some useful functions to choose parser and ease scan maps and slices.
Package linter provides revision of templates.
 Package linter provides revision of templates.
Package logger provides logger tool for perun for control standard I/O usage.
 Package logger provides logger tool for perun for control standard I/O usage.
Package myuser provides function which ease work with user information e.g path to home directory.
 Package myuser provides function which ease work with user information e.g path to home directory.
Package parameters provides tools for interactive creation of parameters file for aws cloud formation.
 Package parameters provides tools for interactive creation of parameters file for aws cloud formation.
Package progress provides displaying of progress e.g during stack creation.
 Package progress provides displaying of progress e.g during stack creation.
Package specification privides tools for downloading and parsing AWS CloudFormation Resource Specification.
 Package specification privides tools for downloading and parsing AWS CloudFormation Resource Specification.
Package stack provides methods to manage AWS CloudFormation stacks.
 Package stack provides methods to manage AWS CloudFormation stacks.
stack_mocks
Package stack_mocks is a generated GoMock package.
 Package stack_mocks is a generated GoMock package.
Package utilities provides various helpers used here and there over the code base.
 Package utilities provides various helpers used here and there over the code base.
Package awsvalidator provides tools for online CloudFormation template validation using AWS API.
 Package awsvalidator provides tools for online CloudFormation template validation using AWS API.
parsers
Package parsers provides some parsers to prepare Template.
 Package parsers provides some parsers to prepare Template.
template
Package template provides struct which describes AWS Template.
 Package template provides struct which describes AWS Template.
validators
Package validators contains additional validators.
 Package validators contains additional validators.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.