{
    "info": {
        "author": "Ryan Armstrong",
        "author_email": "ryan@cavaliercoder.com",
        "bugtrack_url": null,
        "classifiers": [],
        "description": "puppet-enc-ec2\n==============\n\nA Puppet ENC which assigns Nodes based on their AWS EC2 Tags. Additionally, all\nEC2 Tags are made available to Puppet as trusted Top Level Variables with the\n``ec2_tag_`` prefix.\n\n\nProblem summary\n---------------\n\nHistorically, I used the `ec2tagfacts`_ module to classify Puppet Nodes in AWS\nEC2. This works great! The Puppet Agents enumerate their own EC2 Tags using the\nmodule and they report the Tags to the Puppet Master as Untrusted Facts. These\nFacts can then be used by the Enterprise Node Classifier to assign Classes to\nthe Node.\n\nBy example, I created an ``Environment`` and ``Role`` tag in EC2 that are\nreported by the Puppet Agent and used to assign the Node to the matching\nPuppet Environment and Role class.\n\nThere are a few problems with this approach:\n\n* Every EC2 Instance must be assigned permission to read its own tags, and\n  consequently, the tags of any other EC2 Instance\n* A managed agent could spoof the EC2 Tag Facts to retrieve configuration for\n  and other class or environment\n* When using the Puppet Enterprise console, a Classification Group had to be\n  created for every Role in every Environment\n\nThis solution mitigates these issues as:\n\n* Only the Puppet Master needs permission to read tags\n* EC2 tags are provided by the ENC as Top Level Variables - these cannot be\n  spoofed by an agent and are therefore more secure\n* No additional configuration is required in the Enterprise Console\n\n.. _ec2tagfacts: https://www.bryanandrews.org/ec2tagfacts/\n\n\nUsage\n-----\n\nThis ENC assumes you are using the `Roles and Profiles`_ paradigm and intend to\nassign a single Role class to each node, with the ``role::`` prefix.\n\nEach managed EC2 Instance must have the following EC2 Tags assigned:\n\n* ``Environment`` - The Puppet Environment to assign (default: ``production``)\n* ``Role`` - the Role class to assign, excluding the ``role::`` prefix\n\n.. _Roles and Profiles: https://puppet.com/docs/pe/latest/managing_nodes/roles_and_profiles_example.html\n\n\nInstallation\n------------\n\nInstall the classifier on your Puppet Master with the following:\n\n.. code-block:: shell\n\n    $ pip install puppet-enc-ec2\n\n    # or\n\n    $ curl -o /usr/local/bin/puppet-enc-ec2 \\\n        https://raw.githubusercontent.com/cavaliercoder/puppet-enc-ec2/master/bin/puppet-enc-ec2\n    $ chmod +x /usr/local/bin/puppet-enc-ec2\n\n\nConfigure the Puppet Master to use the executable Node Classifier in\n``puppet.conf`` as follows:\n\n.. code-block:: ini\n\n    [master]\n      node_terminus = exec\n      external_nodes = /usr/local/bin/puppet-enc-ec2\n\n\nThe Puppet Master will also need the following IAM Policy applied so that is can\nquery the EC2 API for Instance metadata:\n\n.. code-block:: json\n\n    {\n        \"Version\": \"2012-10-17\",\n        \"Statement\": [\n            {\n                \"Effect\": \"Allow\",\n                \"Action\": [\"ec2:DescribeInstances\"],\n                \"Resource\": \"*\"\n            }\n        ]\n    }\n\nFor for information about installing a custom ENC, see:\nhttps://puppet.com/docs/puppet/latest/nodes_external.html\n\n\nConfiguration\n-------------\n\nThe script uses the Amazon AWS SDK (``boto3``) to connect to AWS. The SDK must\nbe configured with credentials to connect to the AWS APIs. Please see the `Boto3\ndocumentation`_ for instruction.\n\n.. _Boto3 Documentation: http://boto3.readthedocs.io/en/latest/guide/quickstart.html#configuration\n\nIn addition, the desired AWS Region should be configured by modifying the\nscript, or setting the ``AWS_DEFAULT_REGION`` environment variable.\n\n\nExample\n-------\n\n.. code-block:: shell\n\n    # test the classifier for an EC2 Instance\n    $ puppet-enc-ec2 i-deadbeefcafebabe\n    ---\n    classes:\n      role::web_server:\n    environment: production\n    parameters:\n      ec2_tag_name: WebServer\n      ec2_tag_description: Web Application Server\n      ec2_tag_environment: production\n      ec2_tag_role: web_server\n      ec2_tag_aws_cloudformation_logical_id: WebServer\n      ec2_tag_aws_cloudformation_stack_id: arn:aws:cloudformation:us-east-1:123456789000:stack/cf-web-server/0f7b6bb0-9d1a-11e7-848e-50fa575f68fe\n      ec2_tag_aws_cloudformation_stack_name: cf-web-server\n      ec2_tags:\n        Name: WebServer\n        Description: Web Application Server\n        Environment: production\n        Role: web_server\n        aws:cloudformation:logical-id: WebServer\n        aws:cloudformation:stack-id: arn:aws:cloudformation:us-east-1:123456789000:stack/cf-web-server/0f7b6bb0-9d1a-11e7-848e-50fa575f68fe\n        aws:cloudformation:stack-name: cf-web-server\n",
        "description_content_type": null,
        "docs_url": null,
        "download_url": "",
        "downloads": {
            "last_day": -1,
            "last_month": -1,
            "last_week": -1
        },
        "home_page": "http://github.com/cavaliercoder/puppet-enc-ec2",
        "keywords": "",
        "license": "MIT",
        "maintainer": "",
        "maintainer_email": "",
        "name": "puppet-enc-ec2",
        "package_url": "https://pypi.org/project/puppet-enc-ec2/",
        "platform": "",
        "project_url": "https://pypi.org/project/puppet-enc-ec2/",
        "project_urls": {
            "Homepage": "http://github.com/cavaliercoder/puppet-enc-ec2"
        },
        "release_url": "https://pypi.org/project/puppet-enc-ec2/1.0.0/",
        "requires_dist": null,
        "requires_python": "",
        "summary": "A Puppet ENC which assigns Nodes based on their AWS EC2 metadata.",
        "version": "1.0.0"
    },
    "last_serial": 3357392,
    "releases": {
        "1.0.0": [
            {
                "comment_text": "",
                "digests": {
                    "md5": "dc299d9380a2cd590bc3d093288fe5aa",
                    "sha256": "afb5f5fad10ef4657c93501b02ccbfa3ba74a48ad17502a7fbac170a4c52fa68"
                },
                "downloads": -1,
                "filename": "puppet-enc-ec2-1.0.0.tar.gz",
                "has_sig": false,
                "md5_digest": "dc299d9380a2cd590bc3d093288fe5aa",
                "packagetype": "sdist",
                "python_version": "source",
                "requires_python": null,
                "size": 4761,
                "upload_time": "2017-11-23T05:38:45",
                "url": "https://files.pythonhosted.org/packages/eb/81/d4396ff76ba0daf8d7049e11b11da9fba24e6308dd0e3b7bcdb1f8454508/puppet-enc-ec2-1.0.0.tar.gz"
            }
        ]
    },
    "urls": [
        {
            "comment_text": "",
            "digests": {
                "md5": "dc299d9380a2cd590bc3d093288fe5aa",
                "sha256": "afb5f5fad10ef4657c93501b02ccbfa3ba74a48ad17502a7fbac170a4c52fa68"
            },
            "downloads": -1,
            "filename": "puppet-enc-ec2-1.0.0.tar.gz",
            "has_sig": false,
            "md5_digest": "dc299d9380a2cd590bc3d093288fe5aa",
            "packagetype": "sdist",
            "python_version": "source",
            "requires_python": null,
            "size": 4761,
            "upload_time": "2017-11-23T05:38:45",
            "url": "https://files.pythonhosted.org/packages/eb/81/d4396ff76ba0daf8d7049e11b11da9fba24e6308dd0e3b7bcdb1f8454508/puppet-enc-ec2-1.0.0.tar.gz"
        }
    ]
}