{"id":39137299,"url":"https://github.com/cloudboss/bossimage","last_synced_at":"2026-01-17T21:26:55.944Z","repository":{"id":4299014,"uuid":"52674223","full_name":"cloudboss/bossimage","owner":"cloudboss","description":null,"archived":false,"fork":false,"pushed_at":"2022-12-08T00:46:02.000Z","size":220,"stargazers_count":10,"open_issues_count":9,"forks_count":4,"subscribers_count":1,"default_branch":"master","last_synced_at":"2025-10-28T02:19:50.495Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/cloudboss.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2016-02-27T15:47:30.000Z","updated_at":"2024-01-18T22:00:03.000Z","dependencies_parsed_at":"2023-01-13T13:04:13.947Z","dependency_job_id":null,"html_url":"https://github.com/cloudboss/bossimage","commit_stats":null,"previous_names":[],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/cloudboss/bossimage","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudboss%2Fbossimage","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudboss%2Fbossimage/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudboss%2Fbossimage/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudboss%2Fbossimage/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cloudboss","download_url":"https://codeload.github.com/cloudboss/bossimage/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cloudboss%2Fbossimage/sbom","scorecard":{"id":292376,"data":{"date":"2025-08-11","repo":{"name":"github.com/cloudboss/bossimage","commit":"b0f559b7e05b175a29b7d91d61ff55b3429c536d"},"scorecard":{"version":"v5.2.1-40-gf6ed084d","commit":"f6ed084d17c9236477efd66e5b258b9d4cc7b389"},"score":1.6,"checks":[{"name":"Code-Review","score":0,"reason":"Found 0/9 approved changesets -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project requires human code review before pull requests (aka merge requests) are merged.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#code-review"}},{"name":"Token-Permissions","score":-1,"reason":"No tokens found","details":null,"documentation":{"short":"Determines if the project's workflows follow the principle of least privilege.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#token-permissions"}},{"name":"Maintained","score":0,"reason":"0 commit(s) and 0 issue activity found in the last 90 days -- score normalized to 0","details":null,"documentation":{"short":"Determines if the project is \"actively maintained\".","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#maintained"}},{"name":"Packaging","score":-1,"reason":"packaging workflow not detected","details":["Warn: no GitHub/GitLab publishing workflow detected."],"documentation":{"short":"Determines if the project is published as a package that others can easily download, install, easily update, and uninstall.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#packaging"}},{"name":"Dangerous-Workflow","score":-1,"reason":"no workflows found","details":null,"documentation":{"short":"Determines if the project's GitHub Action workflows avoid dangerous patterns.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#dangerous-workflow"}},{"name":"Pinned-Dependencies","score":0,"reason":"dependency not pinned by hash detected -- score normalized to 0","details":["Warn: pipCommand not pinned by hash: tests/resources/file-userdata.txt:2","Info:   0 out of   1 pipCommand dependencies pinned"],"documentation":{"short":"Determines if the project has declared and pinned the dependencies of its build process.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#pinned-dependencies"}},{"name":"Binary-Artifacts","score":10,"reason":"no binaries found in the repo","details":null,"documentation":{"short":"Determines if the project has generated executable (binary) artifacts in the source repository.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#binary-artifacts"}},{"name":"CII-Best-Practices","score":0,"reason":"no effort to earn an OpenSSF best practices badge detected","details":null,"documentation":{"short":"Determines if the project has an OpenSSF (formerly CII) Best Practices Badge.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#cii-best-practices"}},{"name":"Security-Policy","score":0,"reason":"security policy file not detected","details":["Warn: no security policy file detected","Warn: no security file to analyze","Warn: no security file to analyze","Warn: no security file to analyze"],"documentation":{"short":"Determines if the project has published a security policy.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#security-policy"}},{"name":"Fuzzing","score":0,"reason":"project is not fuzzed","details":["Warn: no fuzzer integrations found"],"documentation":{"short":"Determines if the project uses fuzzing.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#fuzzing"}},{"name":"License","score":10,"reason":"license file detected","details":["Info: project has a license file: LICENSE:0","Info: FSF or OSI recognized license: MIT License: LICENSE:0"],"documentation":{"short":"Determines if the project has defined a license.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#license"}},{"name":"Signed-Releases","score":-1,"reason":"no releases found","details":null,"documentation":{"short":"Determines if the project cryptographically signs release artifacts.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#signed-releases"}},{"name":"Branch-Protection","score":0,"reason":"branch protection not enabled on development/release branches","details":["Warn: branch protection not enabled for branch 'master'"],"documentation":{"short":"Determines if the default and release branches are protected with GitHub's branch protection settings.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#branch-protection"}},{"name":"SAST","score":0,"reason":"SAST tool is not run on all commits -- score normalized to 0","details":["Warn: 0 commits out of 28 are checked with a SAST tool"],"documentation":{"short":"Determines if the project uses static code analysis.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#sast"}},{"name":"Vulnerabilities","score":0,"reason":"68 existing vulnerabilities detected","details":["Warn: Project is vulnerable to: PYSEC-2021-358 / GHSA-2pfh-q76x-gwvm","Warn: Project is vulnerable to: PYSEC-2018-81 / GHSA-3xvg-x47j-x75w","Warn: Project is vulnerable to: GHSA-4r65-35qq-ch8j","Warn: Project is vulnerable to: PYSEC-2017-4 / GHSA-588w-w6mv-3cw5","Warn: Project is vulnerable to: PYSEC-2021-1 / GHSA-5rrg-rr89-x9mv","Warn: Project is vulnerable to: GHSA-74vq-h4q8-x6jv","Warn: Project is vulnerable to: PYSEC-2020-3 / GHSA-785x-qw4v-6872","Warn: Project is vulnerable to: PYSEC-2020-9 / GHSA-893h-35v4-mxqx","Warn: Project is vulnerable to: PYSEC-2021-124 / GHSA-8f4m-hccc-8qph","Warn: Project is vulnerable to: PYSEC-2020-11 / GHSA-923p-fr2c-g5m2","Warn: Project is vulnerable to: PYSEC-2020-10 / GHSA-f85h-23mf-2fwh","Warn: Project is vulnerable to: GHSA-fc4h-467w-46rh","Warn: Project is vulnerable to: PYSEC-2020-5 / GHSA-g4mq-6fp5-qwcf","Warn: Project is vulnerable to: PYSEC-2019-2 / GHSA-grgm-pph5-j5h7","Warn: Project is vulnerable to: PYSEC-2020-161 / GHSA-gwr8-5j83-483c","Warn: Project is vulnerable to: PYSEC-2020-6 / GHSA-h39q-95q5-9jfp","Warn: Project is vulnerable to: PYSEC-2019-171 / GHSA-h653-95qw-h2mp","Warn: Project is vulnerable to: PYSEC-2018-44 / GHSA-hwrm-63v2-42g4","Warn: Project is vulnerable to: GHSA-j569-fghw-f9rx","Warn: Project is vulnerable to: GHSA-j667-c2hm-f2wp","Warn: Project is vulnerable to: GHSA-jpvw-p8pr-9g2x","Warn: Project is vulnerable to: PYSEC-2019-4 / GHSA-pm48-cvv2-29q5","Warn: Project is vulnerable to: PYSEC-2021-105 / GHSA-r6h7-5pq2-j77h","Warn: Project is vulnerable to: PYSEC-2018-60 / GHSA-v735-2pp6-h86r","Warn: Project is vulnerable to: PYSEC-2020-12 / GHSA-vcg8-98q8-g7mj","Warn: Project is vulnerable to: GHSA-vp9j-rghq-8jhh","Warn: Project is vulnerable to: PYSEC-2021-106 / GHSA-wv5p-gmmv-wh9v","Warn: Project is vulnerable to: PYSEC-2018-41","Warn: Project is vulnerable to: PYSEC-2020-210","Warn: Project is vulnerable to: PYSEC-2020-220","Warn: Project is vulnerable to: PYSEC-2020-7","Warn: Project is vulnerable to: PYSEC-2020-8","Warn: Project is vulnerable to: PYSEC-2021-126","Warn: Project is vulnerable to: PYSEC-2023-135 / GHSA-xqr8-7jwr-rhp7","Warn: Project is vulnerable to: GHSA-3ww4-gg4f-jr7f","Warn: Project is vulnerable to: GHSA-5cpq-8wj7-hf2v","Warn: Project is vulnerable to: GHSA-9v9h-cgj8-h64p","Warn: Project is vulnerable to: PYSEC-2021-62 / GHSA-hggm-jpg3-v476","Warn: Project is vulnerable to: GHSA-jm77-qphf-c4w8","Warn: Project is vulnerable to: GHSA-w7pp-m8wf-vj6r","Warn: Project is vulnerable to: GHSA-x4qr-2fvf-3mr5","Warn: Project is vulnerable to: PYSEC-2024-60 / GHSA-jjg7-2v4v-x38h","Warn: Project is vulnerable to: PYSEC-2019-217 / GHSA-462w-v97r-4m45","Warn: Project is vulnerable to: GHSA-cpwx-vrp4-4pq7","Warn: Project is vulnerable to: PYSEC-2021-66 / GHSA-g3rq-g295-4j3m","Warn: Project is vulnerable to: GHSA-h5c8-rqwp-cp95","Warn: Project is vulnerable to: GHSA-h75v-3vvj-5mfj","Warn: Project is vulnerable to: GHSA-q2x7-8rv6-6q7h","Warn: Project is vulnerable to: GHSA-f2j6-wrhh-v25m","Warn: Project is vulnerable to: PYSEC-2022-166","Warn: Project is vulnerable to: PYSEC-2018-97 / GHSA-6528-wvf6-f6qg","Warn: Project is vulnerable to: PYSEC-2017-94 / GHSA-cq27-v7xp-c356","Warn: Project is vulnerable to: PYSEC-2021-142 / GHSA-8q59-q68h-6hv4","Warn: Project is vulnerable to: PYSEC-2018-49 / GHSA-rprw-h62v-c2w7","Warn: Project is vulnerable to: GHSA-9hjg-9r4m-mvj7","Warn: Project is vulnerable to: GHSA-9wx4-h78v-vm56","Warn: Project is vulnerable to: PYSEC-2023-74 / GHSA-j8r2-6x86-q33q","Warn: Project is vulnerable to: PYSEC-2018-28 / GHSA-x84v-xcm2-53pg","Warn: Project is vulnerable to: GHSA-34jh-p97f-mpxf","Warn: Project is vulnerable to: PYSEC-2023-212 / GHSA-g4mx-q9vg-27p4","Warn: Project is vulnerable to: PYSEC-2023-207 / GHSA-gwvm-45gx-3cf8","Warn: Project is vulnerable to: PYSEC-2019-133 / GHSA-mh33-7rrq-662w","Warn: Project is vulnerable to: GHSA-pq67-6m6q-mj2v","Warn: Project is vulnerable to: PYSEC-2019-132 / GHSA-r64q-w8jr-g9qp","Warn: Project is vulnerable to: PYSEC-2023-192 / GHSA-v845-jxx5-vc9f","Warn: Project is vulnerable to: PYSEC-2020-148 / GHSA-wqvq-5m8c-6g24","Warn: Project is vulnerable to: PYSEC-2018-32 / GHSA-www2-v7xj-xrc6","Warn: Project is vulnerable to: PYSEC-2021-108"],"documentation":{"short":"Determines if the project has open, known unfixed vulnerabilities.","url":"https://github.com/ossf/scorecard/blob/f6ed084d17c9236477efd66e5b258b9d4cc7b389/docs/checks.md#vulnerabilities"}}]},"last_synced_at":"2025-08-17T18:36:07.694Z","repository_id":4299014,"created_at":"2025-08-17T18:36:07.695Z","updated_at":"2025-08-17T18:36:07.695Z"},"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28518625,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-17T18:55:29.170Z","status":"ssl_error","status_checked_at":"2026-01-17T18:55:03.375Z","response_time":85,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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":[],"created_at":"2026-01-17T21:26:55.266Z","updated_at":"2026-01-17T21:26:55.933Z","avatar_url":"https://github.com/cloudboss.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# bossimage\n\n[![Build Status](https://travis-ci.org/cloudboss/bossimage.svg?branch=master)](https://travis-ci.org/cloudboss/bossimage)\n\nBossimage is a command line utility to convert an [Ansible role](http://docs.ansible.com/ansible/playbooks_roles.html) into an [Amazon EC2 AMI](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/AMIs.html).\n\nBossimage requires just one configuration file to be added to the base directory of an Ansible role. Once that is done, Bossimage may be used to build an EC2 instance, run the Ansible role on it, then \"bake\" it into an AMI. After the AMI is created, Bossimage can also build a test instance from it and run a test playbook on the instance.\n\nBossimage is inspired by both [Packer](https://www.packer.io/) and [Test Kitchen](http://kitchen.ci/), but much simpler than either. If you use both Ansible and AWS, you may find it useful.\n\nBossimage has been tested on both Linux and Windows targets in EC2.\n\n# Installation\n## Install from [PyPI](https://pypi.python.org/pypi)\n```\npip install bossimage\n```\n## Install from source\n```\ngit clone https://github.com/cloudboss/bossimage.git\ncd bossimage\npip install -r requirements.txt\npip install .\n```\n\n# Quick Start\n\nAll interaction with Bossimage is done through an executable command called `bi`, which must always be run from the base directory of an Ansible role.\n\nThis introduction to Bossimage will explain how to do three things:\n\n1. Make an EC2 instance and run Ansible on it (`bi make build`).\n2. Make an AMI from the EC2 instance (`bi make image`).\n3. Make a test instance from the AMI and run a test Ansible playbook on it (`bi make test`).\n\nLater it will be explained how to do a few other things as well.\n\nFirst, a small amount of configuration is necessary.\n\n\u003e Note: in this guide, all commands to be run from the shell are shown preceded by `\u003e ` to indicate the shell prompt.\n\n### Configuration\nBossimage requires a configuration file called `.boss.yml` to be placed in the root directory of the Ansible role. A minimal example of such a file is as follows:\n\n```\nplatforms:\n  - name: amz-2015092\n    instance_type: t2.micro\n    build:\n      source_ami: amzn-ami-hvm-2015.09.2.x86_64-gp2\n```\n\nThe example contains the most minimal configuration possible, using defaults for all settings except those which are required: the platform name, the [instance type](https://aws.amazon.com/ec2/instance-types/) and the source AMI used for the `build` phase.\n\nAlthough Bossimage creates resources in AWS, it does not include any AWS authentication code, instead preferring to pass all authentication through to the underlying [SDK](http://boto3.readthedocs.io/en/latest/guide/configuration.html#guide-configuration) using [standard environment variables](https://blogs.aws.amazon.com/security/post/Tx3D6U6WSFGOK2H/A-New-and-Standardized-Way-to-Manage-Credentials-in-the-AWS-SDKs). Here is an example of gaining credentials by setting `AWS_PROFILE` and `AWS_DEFAULT_REGION` environment variables, assuming a credentials file has already been created.\n```\n\u003e export AWS_PROFILE=uhuru\n\u003e export AWS_DEFAULT_REGION=us-west-1\n```\n\nIf Bossimage is being run from an EC2 instance, an [IAM instance profile](http://docs.aws.amazon.com/IAM/latest/UserGuide/id_roles_use_switch-role-ec2_instance-profiles.html) may be used instead of environment variables, as described later.\n\n### Running\nMost `bi` subcommands require an _instance_ argument to be passed to them. The _instance_ is derived from a _platform_ together with a _profile_, i.e., `\u003cplatform\u003e-\u003cprofile\u003e`. In the `.boss.yml` configuration shown above, a single platform is defined with name `amz-2015092`. The profile is not explicitly defined, and is therefore `default`. So the instance is `amz-2015092-default`, and that will be the argument passed to the commands in this introduction.\n\nPlatforms and profiles will be described in more detail later.\n\n#### bi make build\nThis builds an EC2 instance and runs the Ansible role on it. A unique ssh keypair is also created and assigned to the instance. This command, as with other `bi` commands, is idempotent and may be run multiple times without creating a new instance each time. Subsequent runs will simply run the Ansible role again on the existing instance.\n\nConsider `bi make build` the entrypoint of Bossimage: it must be run before `bi make image` or `bi make test`.\n\n```\n\u003e bi make build amz-2015092-default\nCreated keypair bossimage-oZL4NxUbAM\nCreated instance i-00000001\nWaiting for instance to be running ... ok\nWaiting for connection to 54.xxx.xxx.xxx:22 to be available ... ok\n\nPLAY ***************************************************************************\n\nTASK [setup] *******************************************************************\nok: [54.xxx.xxx.xxx]\n\nTASK [test-role : add package httpd] *******************************************\nchanged: [54.xxx.xxx.xxx]\n\nPLAY RECAP *********************************************************************\n54.xxx.xxx.xxx             : ok=1    changed=1    unreachable=0    failed=0\n```\n\n#### bi make image\nThe primary goal of Bossimage is to create an AMI from an Ansible role, and that is what this command does. It may be run when `bi make build` has completed.\n\n```\n\u003e bi make image amz-2015092-default\nCreated image ami-00000001 with name test-role.default.amz-2015092.hvm.x86_64.v2\nWaiting for image to be available ... ok\nImage is available\n```\n\n#### bi make test\nIt is useful to test that `bi make image` generated a correct AMI, and this is where `bi make test` comes into play.\n\nThis command is very similar to `bi make build`, in that it creates an EC2 instance and runs Ansible on it. However, it depends on a successful outcome of the `bi make image` command, as it uses the AMI created by that command as the source AMI of the EC2 test instance.\n\nIt also does not run the Ansible role on the instance, rather it runs a test playbook, which by default is `tests/test.yml`, relative to the root of the Ansible role directory. When creating an Ansible role with the `ansible-galaxy` command, this test playbook is added by default. For this default test playbook to work with Bossimage, only one small change is needed: to changed the `hosts` in the playbook from `localhost` to `test`.\n\n```\n\u003e bi make test amz-2015092-default\nCreated instance i-00000002\nWaiting for instance to be running ... ok\nWaiting for connection to 52.xxx.xxx.xxx:22 to be available ... ok\n\nPLAY [test] ********************************************************************\n\nTASK [setup] *******************************************************************\nok: [52.xxx.xxx.xxx]\n\nTASK [check that httpd is installed] *******************************************\nok: [52.xxx.xxx.xxx]\n\nTASK [check that port 80 is listening] **********************************************\nok: [52.xxx.xxx.xxx]\n\nPLAY RECAP *********************************************************************\n52.xxx.xxx.xxx               : ok=2    changed=0    unreachable=0    failed=0\n```\n\n### Conclusion\nHaving run these three commands, you will have seen the major functionality of Bossimage. You will have created an AMI and then tested it.\n\nContinue reading to learn:\n\n* How to build multiple \"flavors\" of AMIs for a given platform\n* A shortcut for logging into build and test instances\n* Clean up instances and keypairs used during the build and test phases\n* Clean up AMIs that did not pass tests\n\n# Bossimage\n\n### Instances, Platforms, and Profiles\nMost of the `bi` subcommands, such as `make build` or `make test`, take an argument called the _instance_. An instance is defined by a _platform_ and a _profile_, such as `rhel6-default`, where `rhel6` is the platform and `default` is the profile.\n\n#### Platform\nThe platform defines the source AMI and other settings related to creating an EC2 instance, such as security groups and block device mappings. It also defines connection settings for Ansible to reach the instance, such as ssh or winrm ports and default username.\n\n#### Profile\nThe profile defines variables that will be passed to Ansible through its `--extra-vars` argument. By defining multiple profiles, you can build multiple flavors of AMIs for a given platform.\n\nFor example, here is a `.boss.yml` with one platform and two profiles.\n\n```\nplatforms:\n  - name: ubuntu-16.04\n    build:\n      source_ami: ami-301f6f50\n    instance_type: t2.micro\n    inventory_args:\n      ansible_user: ubuntu\n      ansible_python_interpreter: /usr/bin/python3\n    security_groups: [bossimage]\n\nprofiles:\n  - name: apache\n    extra_vars:\n      packages:\n        - apache2\n  - name: nginx\n    extra_vars:\n      packages:\n        - nginx\n```\n\nRunning `bi list` will produce the output:\n\n```\nubuntu-16.04-apache     Not created\nubuntu-16.04-nginx      Not created\n```\n\nEach of these platform and profile combinations, or instances, can be made into its own AMI.\n\nIf `profiles` is not defined, every platform has an implicit profile, called `default`. The `default` profile does not define any variables. Note that if `profiles` is defined, there is no longer any implicit `default` profile. In such cases you can define one that has no `extra_vars` attribute, if desired.\n\n## .boss.yml\nThe `.boss.yml` file is placed in the root directory of an Ansible role. It is the only configuration necessary for using Bossimage.\n\nTo start, here is a full example for reference.\n\n```\ndefaults:\n  instance_type: m3.large\n\nplatforms:\n  - name: centos-6\n    instance_type: t2.micro\n    connection_timeout: 600\n    inventory_args:\n      ansible_user: centos\n    build:\n      source_ami: 'CentOS Linux 6 x86_64 HVM EBS 1602-74e73035-3435-48d6-88e0-89cc02ad83ee-ami-21e6d54b.3'\n    test:\n      instance_type: m3.medium\n    tags:\n      Billing: xyz\n      Description: Centos 6 Build Instance\n\n  - name: amz-2015092\n    build:\n      source_ami: amzn-ami-hvm-2015.09.2.x86_64-gp2\n    image:\n      ami_name: '%(role)s-%(profile)s-%(version)s-%(platform)s'\n    block_device_mappings:\n      - device_name: /dev/sdf\n        ebs:\n          volume_size: 100\n          volume_type: gp2\n          delete_on_termination: true\n    tags:\n      Billing: xyz\n      Description: Amazon Linux 201509 Build Instance\n\n  - name: win-2016\n    build:\n      source_ami: ami-2d360152\n      become: false\n    inventory_args:\n      ansible_connection: winrm\n      ansible_port: 5985\n      ansible_user: Administrator\n    image:\n      ami_name: '%(role)s-%(profile)s-%(version)s-%(platform)s'\n    tags:\n      Billing: xyz\n      Description: Windows Server 2016 Build Instance\n\nprofiles:\n  - name: default\n  - name: nginx\n    extra_vars:\n      packages:\n        - nginx\n        - tcpdump\n```\n\nA `.boss.yml` file has three possible sections:\n\n* `defaults`: This section is optional, and contains default values to be used within `platforms` when not provided there.\n* `platforms`: This section is required, and defines a list of platforms to build instances from. There must be at least one platform defined in a `.boss.yml` configuration. Each platform defined in the `platforms` section contains its own subsections for each of the three phases `build`, `image`, and `test`.\n* `profiles`: This section is optional. In here, sets of variables may be defined to modify each platform defined in the `platforms` section. If this section is not given, each platform will have a profile called `default`, with no additional variables set.\n\n### defaults\nThe `defaults` section may contain the following variables.\n\n* `instance_type` - type: _string_, default: `t2.micro`\n\n The EC2 instance type.\n\n* `username` - type: _string_, default: `ec2-user`\n\n The user that Ansible will use to connect to the instance. If `inventory_args` is defined, this value will be ignored, and `ansible_user` should be put into `inventory_args` instead.\n\n* `connection` - type: _string_, default: `ssh`\n\n The type of [connection that Ansible will use](https://docs.ansible.com/ansible/2.6/plugins/connection.html). If `inventory_args` is defined, this value will be ignored, and `ansible_connection` should be put into `inventory_args` instead. Note: Bossimage is known to work for `ssh` and `winrm` connections, but other types may need additional testing and development.\n\n* `connection_timeout` - type: _integer_, default: `300`\n\n The amount of time in seconds before Bossimage will give up trying to make an Ansible connection.\n\n* `port` - type: _integer_, default: 22\n\n The port used to connect with Ansible. If `inventory_args` is defined, this value will be ignored, and `ansible_port` should be put into `inventory_args` instead.\n\n* `associate_public_ip_address` - type: _bool_, default: `true`\n\n Whether or not to associate a public IP address to the instance.\n\n* `subnet` - type _string_\n\n The subnet in which the instance will be located.\n\n* `security_groups` - type _list_ of _string_, default `[]`\n\n The security groups that are associated with the instance.\n\n* `iam_instance_profile` - type _string_\n\n The name of the IAM instance profile to assign to the instance.\n\n* `inventory_args` - type _map_ of _string_ to _string_\n\n A map of key/value pairs which will be used for building the Ansible inventory. See [the official Ansible documentation](https://docs.ansible.com/ansible/2.3/intro_inventory.html#list-of-behavioral-inventory-parameters) for more details on available options. If this variable is defined, the `connection`, `username`, and `port` variables will be ignored if used, and should be replaced with inventory arguments `ansible_connection`, `ansible_user`, and `ansible_port`, respectively.\n\n Note: Bossimage normally sets `ansible_password` and `ansible_ssh_private_key_file` in the inventory based on runtime generated values, so it is not advised to define them in `inventory_args` unless you have good reason.\n\n* `tags` - type _map_ of _string_ to _string_, default `{}`\n\n A map of key/value pairs to be used for tagging the instance.\n\n* `user_data` - type: _map_ or _string_, default: `''`\n\n This is the [user data](http://docs.aws.amazon.com/AWSEC2/latest/UserGuide/user-data.html) that will be passed into the EC2 instance. If it is given as a map, then it must have the key `file`, which is the path to a file containing the user data.\n\n If the type is a string, then it is passed verbatim as the user data for the instance.\n\n Examples:\n\n```\ndefaults:\n  user_data:\n    file: ./user-data.txt\n```\n\n```\ndefaults:\n  user_data: |\n    #!/bin/sh\n    yum update -y\n```\n\n* `block_device_mappings` - type: _list_ of _map_, default: `[]`\n\n Devices to be attached to the EC2 instance that will be part of a baked image.\n\n Each item in the list is a map as described in the [BlockDeviceMappings](http://boto3.readthedocs.io/en/latest/reference/services/ec2.html#EC2.ServiceResource.create_instances) property passed to the boto3 create_instances operation. The only difference is that in. boss.yml, \"CamelCase\" properties should be converted to \"snake_case\".\n\n### platforms\nThe `platforms` section contains a list of configurations, one for each defined platform. Each platform configuration must have the keys:\n\n* `name` - type _string_, required\n\n* `build` - type _map_, required\n\n See [build](#build) below.\n\n* `image` - type _map_, optional\n\n See [image](#image) below.\n\n* `test` - type _map_, optional\n\n See [test](#test) below.\n\nThe platform configuration may also contain any of the variables from `defaults`, and will override any of the definitions from there.\n\n#### build\nThe `build` section of a platform is required and may include any of the variables from `defaults`. They will override any of the definitions given there or in the parent platform.\n\nThe `build` section also has the following keys:\n\n* `source_ami` - type: _string_, required\n\n This is the source AMI to build the instance from. It may be given as an AMI ID or name, from which the ID will be found.\n\n* `become` - type: _boolean_, default: `true`\n\n This tells Ansible whether or not to \"become\" the superuser.\n\n#### image\nThe `image` section of a platform may have the following key:\n\n* `ami_name` - type: _string_, default: `'%(role)s.%(profile)s.%(platform)s.%(vtype)s.%(arch)s.%(version)s'`\n\n This is a [Python formatting string](https://docs.python.org/2/library/stdtypes.html#string-formatting) to use for generating the AMI name. The string may contain any of the variables:\n\n * `role`: Name of Ansible role\n * `profile`: Name of profile used from `.boss.yml`\n * `platform`: Name of platform used from `.boss.yml`\n * `vtype`:  Virtualization type, e.g. `hvm`\n * `arch`:  Architecture, e.g. `x86_64`\n * `version`: Ansible role version, see [Role Versions](#role-versions).\n * `hv`:  Hypervisor, e.g. `xen`\n\nOf course, `ami_name` may also be a string used verbatim without any interpolated variables in it.\n\n#### test\nThe `test` section of a platform may include any of the variables from `defaults`. They will override any of the definitions given there or in the parent platforms.\n\nIn addition, the `test` section may have the following key:\n\n* `playbook` - type: _string_, default: `tests/test.yml`\n\n This is the playbook to run during the test phase. The default value is the same as the test playbook that is created by running `ansible-galaxy init` to create a new Ansible role.\n\n## Commands\nThe `bi` command must always be run from the root directory of an Ansible role, where the `.boss.yml` file is located.\n\n#### bi list\nList instances available to be built that are configured in .boss.yml. The status of the instance is shown, which may be either `Created` or `Not created`.\n\n```\n\u003e bi list\namz-2015092-default     Created\nubuntu-16.10-default    Not created\n```\n\n#### bi make build\n\n```\n\u003e bi make build \u003cinstance\u003e [-v|--verbosity]\n```\n\nThis builds an EC2 instance and runs the Ansible role on it. A unique ssh keypair is also created and assigned to the instance. This command is idempotent and may be run multiple times without creating a new instance each time. Subsequent runs will simply run the Ansible role again on the existing instance.\n\nIf your Ansible role has a `requirements.yml` file, then the `ansible-galaxy` command will be used to install the dependencies listed there.\n\nThe `-v`, or `--verbosity` option, gets passed through to Ansible. It may be repeated up to four times to increase Ansible's verbosity.\n\n#### bi make image\n\n```\n\u003e bi make image \u003cinstance\u003e [--no-wait]\n```\n\nThis builds an AMI from the instance created by running `bi make build`. This command will not run unless `bi make build` has run and written its state to `.boss/\u003cinstance\u003e-state.yml`.\n\nBy default this command will complete when the image is available. You may pass the option `--no-wait` to this command so that it does not wait for the image to be available.\n\n#### bi make test\n\n```\n\u003e bi make test \u003cinstance\u003e [-v|--verbosity]\n```\n\nThis builds an EC2 instance from the AMI created by running `bi make image`, then runs the test playbook on it. This command will not run unless `bi make image` has run and written its state to `.boss/\u003cinstance\u003e-state.yml`.\n\nAs with `bi make build`, `ansible-galaxy` will be used to install any role dependencies used by the test playbook, but `ansible-galaxy` will look for them in `tests/requirements.yml`.\n\nThe `-v`, or `--verbosity` option, gets passed through to Ansible. It may be repeated up to four times to increase Ansible's verbosity.\n\n#### bi clean build\n\n```\n\u003e bi clean build \u003cinstance\u003e\n```\n\nThis deletes the instance created by `bi make build`.\n\n#### bi clean image\n\n```\n\u003e bi clean image \u003cinstance\u003e\n```\n\nThis deletes the AMI created by `bi make image`.\n\n#### bi clean test\n\n```\n\u003e bi clean test \u003cinstance\u003e\n```\n\nThis deletes the instance created by `bi make build`.\n\n#### bi login\n\n```\n\u003e bi login \u003cinstance\u003e\n```\n\nThis command works only on instances where the platform is configured for ssh connections, which is the default. By default this command logs into the `build` phase instance, but this may be changed by passing the `-p|--phase` argument, which may be either `build` or `test`.\n\n```\n\u003e bi login -p test \u003cinstance\u003e\n```\n\n#### bi version\nThe command outputs the version of Bossimage.\n\n## Role Versions\nAnsible Galaxy does not provide a way to define a role's version in its metadata, it relies on git tags for versioning. So Bossimage does not have anything it can parse to discover the version of a role.\n\nInstead, you can put a file in the root of the repository called `.role-version` which contains the version string. Bossimage also supports defining the version in the environment variable `BI_ROLE_VERSION`.\n\nIf neither the `.role-version` file or the `BI_ROLE_VERSION` environment variable are present, then a default version `unset` is used.\n\n## Authenticating with AWS\n`bossimage` 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 `bossimage` 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 `bossimage` 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 IAM role should have the policy shown below.\n\n```\n{\n    \"Version\": \"2012-10-17\",\n    \"Statement\": [\n        {\n            \"Effect\": \"Allow\",\n            \"Action\": [\n                \"ec2:CreateImage\",\n                \"ec2:CreateKeyPair\",\n                \"ec2:CreateTags\",\n                \"ec2:DeleteKeyPair\",\n                \"ec2:DeregisterImage\",\n                \"ec2:DescribeImages\",\n                \"ec2:DescribeInstances\",\n                \"ec2:RunInstances\",\n                \"ec2:TerminateInstances\"\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.\n\n# Rationale\nAll I want is to spin up an EC2 instance in AWS, run an [Ansible](http://docs.ansible.com/ansible/index.html) role on it, bake it into an image, and run some tests to verify the correctness of the image.\n\n### Comparison with Packer\nPacker is a tool for creating VM and Docker images for a multitude of cloud providers and for local use.\n\nPacker does more than I need; I only need to create EC2 AMIs. But still it doesn't do quite enough: it doesn't provide a development phase for rapid iterative development of an Ansible role. You always have to start from the beginning with a new instance.\n\nBossimage creates EC2 images and provides a development phase before creating an image, and a testing phase for when the image has been created.\n\n### Comparison with Test Kitchen\nTest Kitchen is a tool for testing Chef cookbooks, but can be used to test Ansible and other configuration management tools using third party plugins. It can create VM instances with Vagrant and various cloud providers to use for developing.\n\nTest Kitchen does more than I need; I only need to test Ansible in EC2. But still it doesn't do quite enough: it doesn't provide an AMI creation phase.\n\nBossimage creates EC2 instances and runs Ansible on them, and provides image creation and image testing phases.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudboss%2Fbossimage","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcloudboss%2Fbossimage","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcloudboss%2Fbossimage/lists"}