{"id":13509079,"url":"https://github.com/Appliscale/perun","last_synced_at":"2025-03-30T13:31:29.162Z","repository":{"id":50589528,"uuid":"106666898","full_name":"Appliscale/perun","owner":"Appliscale","description":"A command-line validation tool for AWS Cloud Formation that allows to conquer the cloud faster!","archived":false,"fork":false,"pushed_at":"2023-10-19T07:06:42.000Z","size":691,"stargazers_count":90,"open_issues_count":16,"forks_count":8,"subscribers_count":30,"default_branch":"master","last_synced_at":"2024-04-22T04:50:52.536Z","etag":null,"topics":["amazon-cloud-formation","amazon-web-services","aws","aws-cli","aws-cloudformation","cloudformation","cloudformation-template","command-line","converter","go","golang","json","perun","perun-for-aws","stack-management","stack-template","template","tool","validator","yaml"],"latest_commit_sha":null,"homepage":"https://perun-for-aws.appliscale.io","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/Appliscale.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null}},"created_at":"2017-10-12T08:38:57.000Z","updated_at":"2024-02-19T13:50:39.000Z","dependencies_parsed_at":"2024-01-05T20:45:59.624Z","dependency_job_id":"34c24280-3a54-46cb-9aeb-fbf82ea3adce","html_url":"https://github.com/Appliscale/perun","commit_stats":null,"previous_names":[],"tags_count":6,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Appliscale%2Fperun","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Appliscale%2Fperun/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Appliscale%2Fperun/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/Appliscale%2Fperun/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/Appliscale","download_url":"https://codeload.github.com/Appliscale/perun/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":222376232,"owners_count":16974312,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["amazon-cloud-formation","amazon-web-services","aws","aws-cli","aws-cloudformation","cloudformation","cloudformation-template","command-line","converter","go","golang","json","perun","perun-for-aws","stack-management","stack-template","template","tool","validator","yaml"],"created_at":"2024-08-01T02:01:02.680Z","updated_at":"2024-11-01T09:30:32.450Z","avatar_url":"https://github.com/Appliscale.png","language":"Go","readme":"# Perun [![Release](https://img.shields.io/github/release/Appliscale/perun.svg?style=flat-square)](https://github.com/Appliscale/perun/releases/latest) [![Build_Status](https://travis-ci.org/Appliscale/perun.svg?branch=master)](https://travis-ci.org/Appliscale/perun) [![License](https://img.shields.io/badge/License-Apache%202.0-orange.svg)](https://github.com/Appliscale/perun/blob/master/LICENSE.md) [![Go_Report_Card](https://goreportcard.com/badge/github.com/Appliscale/perun?style=flat-square\u0026fuckgithubcache=1)](https://goreportcard.com/report/github.com/Appliscale/perun) [![GoDoc](https://godoc.org/github.com/Appliscale/perun?status.svg)](https://godoc.org/github.com/Appliscale/perun)\n\n\u003cp align=\"center\"\u003e\n\u003cimg src=\"perun_logo.png\" alt=\"Perun logo\" width=\"400\"\u003e\n\u003c/p\u003e\n\nA command-line validation tool for *AWS Cloud Formation* that allows to conquer the cloud faster!\n\n## Goal\n\nPerun 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. \n## Building and Installation\n\n### OSX\n#### Homebrew:\n```bash\n$ brew install Appliscale/tap/perun\n```\n#### From binaries:\n* Go to Perun’s releases https://github.com/Appliscale/perun/releases\n* Find and download perun-darwin-amd64.tar.gz\n* Unpack the archive\n\n### Debian\n#### Dpkg package manager:\n* Go to https://github.com/Appliscale/perun-dpkg\n* Download perun.deb\n* Install:\n```bash\n$ dpkg -i perun.deb\n```\n#### From binaries:\n* Go to Perun’s releases https://github.com/Appliscale/perun/releases\n* Find and download perun-linux-amd64.tar.gz\n* Unpack:\n```bash\n$ tar xvzf perun-linux-amd64.tar.gz\n```\n\n### Linux\n#### Rpm package manager:\n* Go to: https://github.com/Appliscale/rpmbuild/tree/master/RPMS/x86_64\n* Download perun-linux-amd64-1.2.0-1.x86_64.rpm\n* Install:\n```bash\n$ rpm -ivh perun-linux-amd64-1.2.0-1.x86_64.rpm\n```\n\n#### From binaries:\n* Go to Perun’s releases https://github.com/Appliscale/perun/releases\n* Find and download perun-linux-amd64.tar.gz\n* Unpack:\n```bash\ntar xvzf perun-linux-amd64.tar.gz\n```\n\n### Building from sources\n\nFirst of all you need to download Perun to your GO workspace:\n\n```bash\n$GOPATH $ go get github.com/Appliscale/perun\n$GOPATH $ cd perun\n```\n\nThen build and install configuration for the application inside perun directory by executing:\n\n```bash\nperun $ make\n```\n\nAfter this, application will be compiled as a `perun` binary inside `bin` directory in your `$GOPATH/perun` workspace.\n\n\n## Working with Perun\n\n### Commands\n\n#### Validation\nTo validate your template, just type:\n\n```bash\n~ $ perun validate \u003cPATH TO YOUR TEMPLATE\u003e\n```\nYour template will be then validated using both our validation mechanism and AWS API\n(*aws validation*).\n\n#### Configuration\nTo create your own configuration file use `configure` mode:\n\n```bash\n~ $ perun configure\n```\n\nThen type path and name of new configuration file.\n\n#### Stack Parameters\nBored of writing JSON parameter files? Perun allows you to interactively create parameters file\nfor a given template. You can either pass the parameters interactively or as a command-line argument.\n\n##### Command Line Parameter way:\n```bash\n~ $ perun create-parameters \u003cPATH TO YOUR TEMPLATE\u003e \u003cOUTPUT PARAMETER FILE\u003e --parameter=MyParameter1:\u003cPARAMETER VALUE\u003e\n```\n\nThe greatest thing is that you can mix those in any way you want. Perun will validate the\ngiven parameters from command line. If everything is OK, it will just create the parameters file.\nIf anything is missing or invalid, it will let you know and ask for it interactively.\n\n#### Working with stacks\n\nPerun allows to create and destroy stacks.\n\nCloud Formation templates can be in JSON or YAML format.\n\nExample JSON template which describe S3 Bucket:\n\n```json\n{\n    \"Resources\" : {\n        \"HelloPerun\" : {\n            \"Type\" : \"AWS::S3::Bucket\"\n        }\n    }\n}\n```\n\nBefore you create stack Perun will validate it by default :wink:. You can disable it with flag `--no-validate`.\n\nTo create new stack you have to type:\n\n```bash\n~ $ perun create-stack \u003cNAME OF YOUR STACK\u003e  \u003cPATH TO YOUR TEMPLATE\u003e\n```\n\nTo destroy stack just type:\n\n```bash\n~ $ perun delete-stack \u003cNAME OF YOUR STACK\u003e\n```\n\nYou can use option ``--progress`` to show the stack creation/deletion progress in the console, but\nnote, that this requires setting up a remote sink.\n\n##### Remote sink\n\nTo setup remote sink type:\n\n```bash\n~ $ perun setup-remote-sink\n```\n\nThis will create an sns topic and sqs queue with permissions for the sns topic to publish on the sqs\nqueue. Using above services may produce some cost:\nAccording to the AWS SQS and SNS pricing:\n\n- SNS:\n  - notifications to the SQS queue are free\n- SQS:\n  - The first 1 million monthly requests are free.\n  - After that: 0.40$ per million requests after Free Tier (Monthly)\n  - Typical stack creation uses around a hundred requests\n  \nMore information about pricing can be found [here](https://aws.amazon.com/sqs/pricing/).\n\nTo destroy remote sink just type:\n\n```bash\n~ $ perun destroy-remote-sink\n```\n\n#### Cost estimation\n\n```bash\n~ $ perun estimate-cost \u003cPATH TO YOUR TEMPLATE\u003e\n```\nTo 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.\n\n#### Protecting Stack\n\nYou 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.\n\n```json\n{\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Principal\": \"*\",\n      \"Action\": \"Update:*\",\n      \"Resource\": \"*\"\n    }\n  ]\n}\n```\n\nTo apply your Stack Policy file you have to type:\n\n```bash\n~ $ perun set-stack-policy \u003cNAME OF YOUR STACK\u003e  \u003cPATH TO YOUR TEMPLATE\u003e\n```\n\nPerun has some default flags:\n\n- ``--block`` - Block all Update actions in stack.\n\n- ``--unblock`` - Unblock all Update actions in stack.\n\n- ``--disable-stack-termination`` - Protect stack from being deleted.\n\n- ``--enable-stack-termination`` - Allow to destroy stack.\n\nYou use flag instead of template.\n\n```bash\n~ $ perun set-stack-policy \u003cNAME OF YOUR STACK\u003e \u003cFLAG\u003e\n```\n\n### Configuration files\n\nPerun will help you in setting up all the needed configuration files on you first run - no previous setup required.\n\nYou can find an example configuration file in the main directory of the repository in file `defaults/main.yml`.\n\nperun 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:\n\n1. CLI argument (`-c=\u003cCONFIG FILE\u003e, --config=\u003cCONFIG FILE\u003e`).\n2. Current working directory (`.perun` file).\n3. Current user local configuration (`~/.config/perun/main.yaml`).\n4. System global configuration (`/etc/perun/main.yaml`).\n\nHaving a configuration file is mandatory. Minimal configuration file requires only *AWS CloudFormation Resource Specification* URLs, listed under `SpecificationURL` key:\n\n```yaml\nSpecificationURL:\n  us-east-2: \"https://dnwj8swjjbsbt.cloudfront.net\"\n  ...\n```\n\nThere are 6 other parameters:\n\n* `DefaultProfile` (`default` taken by default, when no value found inside configuration files).\n* `DefautRegion` (`us-east-1` taken by default, when no value found inside configuration files).\n* `DefaultDurationForMFA`: (`3600` taken by default, when no value found inside configuration files).\n* `DefaultDecisionForMFA`: (`false` taken by default, when no value found inside configuration files).\n* `DefaultVerbosity`: (`INFO` taken by default, when no value found inside configuration files).\n* `DefaultTemporaryFilesDirectory`: (`.` taken by default, when no value found inside configuration files).\n\n### Supporting  MFA\n\nIf 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.\n\n```bash\n~ $ perun validate \u003cPATH TO YOUR TEMPLATE\u003e --mfa\n```\n\nIn 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).\n\nExample profile you need to setup - in this case `default`:\n\n```ini\n[default-long-term]\naws_access_key_id = \u003cYOUR ACCESS KEY\u003e\naws_secret_access_key = \u003cYOUR SECRET ACCESS KEY\u003e\nmfa_serial = \u003cIDENTIFICATION NUMBER FOR MFA DEVICE\u003e\n```\n\nYou 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:\n\n```bash\n~ $ perun mfa\n```\n\n### Capabilities\n\nIf your template includes resources that can affect permissions in your AWS account,\nyou must explicitly acknowledge its capabilities by adding `--capabilities=CAPABILITY` flag.\n\nValid values are `CAPABILITY_IAM` and `CAPABILITY_NAMED_IAM`.\nYou can specify both of them by adding `--capabilities=CAPABILITY_IAM --capabilities=CAPABILITY_NAMED_IAM`.\n\n### Inconsistencies between official documentation and Resource Specification\n\nPerun 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.\n\nTo specify inconsistencies edit `~/.config/perun/specification_inconsistency.yaml` file.\n\nExample configuration file:\n\n```yaml\n  SpecificationInconsistency:\n    AWS::CloudFront::Distribution.DistributionConfig:\n      DefaultCacheBehavior:\n        - Required\n```\n\n## License\n\n[Apache License 2.0](LICENSE)\n\n## Maintainers\n\n- [Maksymilian Wojczuk](https://github.com/maxiwoj)\n- [Piotr Figwer](https://github.com/pfigwer)\n- [Sylwia Gargula](https://github.com/SylwiaGargula)\n- [Mateusz Piwowarczyk](https://github.com/piwowarc)\n\n## Contributors\n\n- [Wojciech Gawroński](https://github.com/afronski) (originator)\n- [Jakub Lamparski](https://github.com/jlampar)\n- [Aleksander Mamla](https://github.com/amamla)\n- [Kacper Patro](https://github.com/morfeush22)\n- [Paweł Pikuła](https://github.com/ppikula)\n- [Michał Połcik](https://github.com/mwpolcik)\n- [Tomasz Raus](https://github.com/rusty-2)\n","funding_links":[],"categories":["Go","aws","Open Source Repos"],"sub_categories":["CloudFormation"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAppliscale%2Fperun","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FAppliscale%2Fperun","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FAppliscale%2Fperun/lists"}