{
    "info": {
        "author": "Joseph Wright",
        "author_email": "rjosephwright@gmail.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "# bossformation\n\n[![Build Status](https://travis-ci.org/cloudboss/bossformation.svg?branch=master)](https://travis-ci.org/cloudboss/bossformation)\n\n`bossformation` is a preprocessor that allows [CloudFormation](https://aws.amazon.com/cloudformation/) templates to be written in YAML instead of JSON. In addition to this, templates may contain [Jinja2](http://jinja.pocoo.org/docs/dev/) tags, allowing for dynamic template generation.\n\n# Installation\n## Install from [PyPI](https://pypi.python.org/pypi)\n```\npip install bossformation\n```\n## Install from source\n```\ngit clone https://github.com/cloudboss/bossformation.git\ncd bossformation\npip install -r requirements.txt\npip install .\n```\n\n# Usage\nAfter installation, the `bf` command is provided with subcommand `render`.\n\n## Rendering templates\nAt its simplest, you may write a CloudFormation template that maps YAML to JSON, such as the following file `test.yml`:\n\n```\n# The date must be quoted or the YAML parser will try to convert it to a datetime object\nAWSTemplateFormatVersion: '2010-09-09'\n\nDescription: CloudFormation Example\n\nResources:\n  MySecurityGroup:\n    Type: AWS::EC2::SecurityGroup\n    Properties:\n      GroupDescription: My group description\n      SecurityGroupIngress:\n        - SourceSecurityGroupId: sg-00000000\n          IpProtocol: TCP\n          FromPort: 443\n          ToPort: 443\n  MyInstance:\n    Type: AWS::EC2::Instance\n    Properties:\n      AvailabilityZone: us-east-1a\n      SecurityGroupIds:\n        - Ref: MySecurityGroup\n      ImageId: ami-00000000\n```\n\nThen run `render` on it (`-P` tells it to pretty-print the output).\n\n```\nbf render -t test.yml -P\n```\n\nThe resulting output would be:\n\n```\n{\n  \"AWSTemplateFormatVersion\": \"2010-09-09\",\n  \"Description\": \"CloudFormation Example\",\n  \"Resources\": {\n    \"MySecurityGroup\": {\n      \"Type\": \"AWS::EC2::SecurityGroup\",\n      \"Properties\": {\n        \"SecurityGroupIngress\": [\n          {\n            \"SourceSecurityGroupId\": \"sg-00000000\",\n            \"IpProtocol\": \"TCP\",\n            \"ToPort\": 443,\n            \"FromPort\": 443\n          }\n        ],\n        \"GroupDescription\": \"My group description\"\n      }\n    },\n    \"MyInstance\": {\n      \"Type\": \"AWS::EC2::Instance\",\n      \"Properties\": {\n        \"AvailabilityZone\": \"us-east-1a\",\n        \"SecurityGroupIds\": [\n          {\n            \"Ref\": \"MySecurityGroup\"\n          }\n        ],\n        \"ImageId\": \"ami-00000000\"\n      }\n    }\n  }\n}\n```\n\n## Adding Properties\nAt this point, you may want to change the template so that it is region-agnostic. To do this, you can provide properties in a separate file that will be available within the template.\n\nCreate a file `properties.yml`:\n\n```\nAvailabilityZone: us-east-1a\nSuperSecurityGroup: sg-00000001\n```\n\nThen modify the original template to include the properties within Jinja2 tags.\n\n```\n# The date must be quoted or the YAML parser will try to convert it to a datetime object\nAWSTemplateFormatVersion: '2010-09-09'\n\nDescription: CloudFormation Example\n\nResources:\n  MySecurityGroup:\n    Type: AWS::EC2::SecurityGroup\n    Properties:\n      GroupDescription: My group description\n      SecurityGroupIngress:\n        - SourceSecurityGroupId: sg-00000000\n          IpProtocol: TCP\n          FromPort: 443\n          ToPort: 443\n  MyInstance:\n    Type: AWS::EC2::Instance\n    Properties:\n      AvailabilityZone: {{ AvailabilityZone }}\n      SecurityGroupIds:\n        - {{ SuperSecurityGroup }}\n        - Ref: MySecurityGroup\n      ImageId: ami-00000000\n```\n\nRun `render` again, passing the path to the properties file with `-p`:\n\n```\nbf render -p properties.yml -t test.yml -P\n```\n\n## Dynamic Properties\nTemplates themselves are meant to be stateless. That is, if the properties passed into a template are the same, then the rendered output should be the same. However, properties files may contain dynamic lookups into AWS, which are enabled by a Jinja2 context that is passed to the properties.\n\nIf you use this feature, you must authenticate to AWS and provide a region:\n```\nexport AWS_PROFILE=heavyk\nexport AWS_DEFAULT_REGION=us-east-1\n```\n\nNow you may include dynamic lookups within `properties.yml`:\n```\nAvailabilityZones: {{ azs() }}\nAmiId: {{ ami_id_for('amzn-ami-hvm-2015.09.2.x86_64-gp2') }}\n```\n\nProperties files have the following functions available within their Jinja2 context:\n\n* `azs()`:\n\n Returns a list of the availability zones for the current region.\n\n* `ami_id_for(name)`:\n\n Returns the AMI ID for the given AMI name. If `name` is an AMI ID, then it is returned verbatim.\n\n* `sg_id_for(name)`:\n\n Returns the security group ID for the given security group name. If `name` is a security group ID, then it is returned verbatim.\n\n* `subnet_id_for(name)`:\n\n Returns the subnet ID for the given subnet name. If `name` is a subnet ID, then it is returned verbatim.\n\n### Authenticating with AWS\n`bossformation` uses standard AWS SDK environment variables for authentication, which are described in the [boto3 documentation](http://boto3.readthedocs.org/en/latest/guide/configuration.html#configuration).\n\nThe simplest way to authenticate if you are not running `bossformation` on an EC2 instance is to configure `~/.aws/credentials` with a [profile](http://docs.aws.amazon.com/cli/latest/userguide/cli-chap-getting-started.html#cli-multiple-profiles) and pass its name in the environment variable `AWS_PROFILE`.\n\nIf you are running `bossformation` on an EC2 instance, you may assign the instance an [IAM role](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) upon creation, and then you do not need to pass any credentials. The following IAM policy may be applied to the role, and will enable \"describe\" access for all EC2 resources. If you wish, you may further limit the policy by explicitly allowing or denying specific resources.\n\n```\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"ec2:Describe*\"\n            ],\n            \"Resource\": \"*\"\n        }\n    ]\n}\n```\n\n### Region\nYou must set the AWS region you are running in. To do this, set the `AWS_DEFAULT_REGION` environment variable.",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "https://github.com/cloudboss/bossformation/releases/0.1.0",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "https://github.com/cloudboss/bossformation",
        "keywords": null,
        "license": "UNKNOWN",
        "maintainer": null,
        "maintainer_email": null,
        "name": "bossformation",
        "package_url": "https://pypi.org/project/bossformation/",
        "platform": "UNKNOWN",
        "project_url": "https://pypi.org/project/bossformation/",
        "project_urls": {
            "Download": "https://github.com/cloudboss/bossformation/releases/0.1.0",
            "Homepage": "https://github.com/cloudboss/bossformation"
        },
        "release_url": "https://pypi.org/project/bossformation/0.1.0/",
        "requires_dist": null,
        "requires_python": null,
        "summary": "Tool to enhance AWS CloudFormation",
        "version": "0.1.0"
    },
    "last_serial": 2102182,
    "releases": {
        "0.1.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "705c837788938e224c9ed32dcc6bd496",
                    "sha256": "e67809843726b1bf6342d0fef24317aeb8b27b552c5bf93857355ad612a8a1e0"
                },
                "downloads": -1,
                "filename": "bossformation-0.1.0.tar.gz",
                "has_sig": false,
                "md5_digest": "705c837788938e224c9ed32dcc6bd496",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 6095,
                "upload_time": "2016-05-06T06:26:41",
                "url": "https://files.pythonhosted.org/packages/41/98/62f999e8696ff6df95523a58dffb53726618e078346e6cf0d55ed3b44857/bossformation-0.1.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "705c837788938e224c9ed32dcc6bd496",
                "sha256": "e67809843726b1bf6342d0fef24317aeb8b27b552c5bf93857355ad612a8a1e0"
            },
            "downloads": -1,
            "filename": "bossformation-0.1.0.tar.gz",
            "has_sig": false,
            "md5_digest": "705c837788938e224c9ed32dcc6bd496",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 6095,
            "upload_time": "2016-05-06T06:26:41",
            "url": "https://files.pythonhosted.org/packages/41/98/62f999e8696ff6df95523a58dffb53726618e078346e6cf0d55ed3b44857/bossformation-0.1.0.tar.gz"
        }
    ]
}