appliscale / perun Goto Github PK
View Code? Open in Web Editor NEWA command-line validation tool for AWS Cloud Formation that allows to conquer the cloud faster!
Home Page: https://perun-for-aws.appliscale.io
License: Apache License 2.0
A command-line validation tool for AWS Cloud Formation that allows to conquer the cloud faster!
Home Page: https://perun-for-aws.appliscale.io
License: Apache License 2.0
We need:
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:
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.
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
.
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.
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.
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).
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.
Problem is well described in the following article:
https://www.unixdaemon.net/cloud/cloudformation-annoyance-deletion-policy-parameters/.
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.
After releasing 1.0.0
we would like introduce couple of improvements 1.1.0
:
validate_offline
is a pretty long name - how about lint
or check
?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
.
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 ]
As in the title, it may be misleading putting it by default.
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.
1.1
.
1.0
?
1.0
internally, so officially announced version is a more polished version of 1.0
.perun
website and this repository, and encourage for participation, testing the tool and providing us feedback and creating issues in our repository.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.
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.
Region
and Profile
(but you can also pass those as command line parameters - as you may configure that tool without user interaction).
autoconf
(just fetching URLs) and configure
modes (interactive one).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.
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! π
We need to prepare:
We're missing couple of points regarding code quality - let's address most important ones in 1.0
release.
go
tooling - e.g. go vet
and other stuff (static code analysis) and include it in the build pipeline.Add ability to update created cloudformation stack, e.g.:
$ perun update-stack <stack-name> <path-to-template>
So we need 2 things in that task:
stdout
.stdin
.-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.We need to prepare:
perun-for-aws.io
perun-cloud.io
.gh-pages
mechanism.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.
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.
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.
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.
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
.
Sigh.
We cannot trust entirely Resource Specification from AWS API, because we've already found inconsistencies:
a) Real URL to docs:
b) URL from specifications:
The one from specifications does not exists π Small difference between those two, but still.
"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.
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:
Type
annotations.>
if lines are too long for YAML.Remember about:
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:
We would like to:
After releasing 1.0.0
we would like introduce couple of improvements 1.1.0
:
JSON
(done by @SylwiaGargula).!importValue
.Currently we have online validation based on AWS API, which is usual one, but far from ideal.
Issues with current approach:
In the first milestone we need:
1.0
.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.
Missing support for functions in our intrinsicsolver
module:
!Ref
!GetAtt
!ImportValue
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.
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?
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
For other cases - compiling from source.
It is related to #28 as it will require cross-platform building and integration tests.
We need to choose and add license to the repository.
Let's discuss here what we would love to see as a next step of validation / linting capabilities, our list so far:
Fn::Sub
instead of Fn::Join
and so on.
${AWS::Region}
instead of your own variable.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
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:
aws-cli
profile.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.
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):
/etc/
.~/.[name]
or ~/.config/[name]
..git
resides) with project specific configuration file called .[name]
.
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.
This is a ticket for combining all changes that should be applied to documentation for 2.0
release:
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.
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:
Open questions:
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.
Our subjective list:
perun
?A swiss army knife that helps you with every single step of workflow related to AWS CloudFormation templates.
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.
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).
A declarative, efficient, and flexible JavaScript library for building user interfaces.
π Vue.js is a progressive, incrementally-adoptable JavaScript framework for building UI on the web.
TypeScript is a superset of JavaScript that compiles to clean JavaScript output.
An Open Source Machine Learning Framework for Everyone
The Web framework for perfectionists with deadlines.
A PHP framework for web artisans
Bring data to life with SVG, Canvas and HTML. πππ
JavaScript (JS) is a lightweight interpreted programming language with first-class functions.
Some thing interesting about web. New door for the world.
A server is a program made to process requests and deliver data to clients.
Machine learning is a way of modeling and interpreting data that allows a piece of software to respond intelligently.
Some thing interesting about visualization, use data art
Some thing interesting about game, make everyone happy.
We are working to build community through open source technology. NB: members must have two-factor auth.
Open source projects and samples from Microsoft.
Google β€οΈ Open Source for everyone.
Alibaba Open Source for everyone
Data-Driven Documents codes.
China tencent open source team.