{"id":19039456,"url":"https://github.com/aia/ansible-amazon-base","last_synced_at":"2025-09-20T14:32:03.649Z","repository":{"id":45006363,"uuid":"428148241","full_name":"aia/ansible-amazon-base","owner":"aia","description":"MVP monorepo to rapidly develop scalable, reliable, high-quality components for Amazon Linux instance configuration management","archived":false,"fork":false,"pushed_at":"2023-03-20T04:53:10.000Z","size":93,"stargazers_count":5,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-01-05T19:43:39.783Z","etag":null,"topics":["ansible","ansible-playbook","aws","infrastructure-as-code","playbooks","test-kitchen","test-kitchen-ansible"],"latest_commit_sha":null,"homepage":"","language":"YAML","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/aia.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE.md","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2021-11-15T06:30:18.000Z","updated_at":"2023-05-03T04:56:14.000Z","dependencies_parsed_at":"2023-02-17T02:31:44.934Z","dependency_job_id":null,"html_url":"https://github.com/aia/ansible-amazon-base","commit_stats":null,"previous_names":[],"tags_count":1,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aia%2Fansible-amazon-base","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aia%2Fansible-amazon-base/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aia%2Fansible-amazon-base/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/aia%2Fansible-amazon-base/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/aia","download_url":"https://codeload.github.com/aia/ansible-amazon-base/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":233670654,"owners_count":18711696,"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":["ansible","ansible-playbook","aws","infrastructure-as-code","playbooks","test-kitchen","test-kitchen-ansible"],"created_at":"2024-11-08T22:13:02.307Z","updated_at":"2025-09-20T14:32:03.351Z","avatar_url":"https://github.com/aia.png","language":"YAML","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Ansible Amazon Base Repository\n\u003c!-- markdownlint-disable-file MD014 --\u003e\n\n- [Ansible Amazon Base Repository](#ansible-amazon-base-repository)\n  - [About](#about)\n  - [Setting Up Ansible Environment](#setting-up-ansible-environment)\n    - [Configuring Python VENV and Ansible](#configuring-python-venv-and-ansible)\n    - [Editor Configuration](#editor-configuration)\n  - [Setting Up VirtualBox Environment](#setting-up-virtualbox-environment)\n    - [Install VirtualBox and Vagrant](#install-virtualbox-and-vagrant)\n    - [Configuring Test Kitchen](#configuring-test-kitchen)\n    - [Downloading Amazon Linux v2 Vagrant Box](#downloading-amazon-linux-v2-vagrant-box)\n    - [Build an Optimized Amazon Linux 2 Vagrant Box](#build-an-optimized-amazon-linux-2-vagrant-box)\n    - [Environment Variable Overwrites for Kitchen](#environment-variable-overwrites-for-kitchen)\n  - [Running Test Kitchen](#running-test-kitchen)\n  - [Running Integration Tests](#running-integration-tests)\n  - [Running Ansible Playbooks on AWS Instances](#running-ansible-playbooks-on-aws-instances)\n  - [Example Project: Build a Local Docker/Containerd Server VM](#example-project-build-a-local-dockercontainerd-server-vm)\n  - [Ansible References](#ansible-references)\n\n## About\n\nAnsible Amazon Base Repository is an MVP monorepo to rapidly develop scalable, reliable,\nhigh-quality components for Amazon Linux instance configuration management.\n\n## Setting Up Ansible Environment\n\n### Configuring Python VENV and Ansible\n\nNote: This document assumes that you are working on Mac\n\n1. Create a new virtual environment with pyenv\n\n   ```text\n   $ pyenv virtualenv miniconda3-latest ansible\n   ```\n\n2. Activate your new python virtual environment\n\n   ```text\n   $ pyenv activate ansible\n   ```\n\n3. Install poetry\n\n   ```text\n   $ conda install poetry\n   ```\n\n4. Install dependencies\n\n   ```text\n   $ poetry install\n   ```\n\n5. Check ansible\n\n   ```text\n   $ ansible --version\n   ```\n\n### Editor Configuration\n\nCode editors are major software development productivity tools. VSCode is a game changer.\n\nVSCode should be configured for typical Python development with the following extensions:\n\n- [Ansible](https://marketplace.visualstudio.com/items?itemName=redhat.ansible)\n- [YAML](https://marketplace.visualstudio.com/items?itemName=redhat.vscode-yaml)\n- [Code Spell Checker](https://marketplace.visualstudio.com/items?itemName=streetsidesoftware.code-spell-checker)\n- [Trailing Spaces](https://marketplace.visualstudio.com/items?itemName=shardulm94.trailing-spaces)\n- [Blank line at the End of File](https://marketplace.visualstudio.com/items?itemName=riccardoNovaglia.missinglineendoffile)\n- [Markdown All in One](https://marketplace.visualstudio.com/items?itemName=yzhang.markdown-all-in-one)\n- [Markdownlint](https://marketplace.visualstudio.com/items?itemName=DavidAnson.vscode-markdownlint)\n- [Pylance](https://marketplace.visualstudio.com/items?itemName=ms-python.vscode-pylance)\n- [Python](https://marketplace.visualstudio.com/items?itemName=ms-python.python)\n- [Test Explorer](https://marketplace.visualstudio.com/items?itemName=hbenl.vscode-test-explorer)\n- [Python Test Explorer](https://marketplace.visualstudio.com/items?itemName=LittleFoxTeam.vscode-python-test-adapter)\n- [Docker](https://marketplace.visualstudio.com/items?itemName=ms-azuretools.vscode-docker)\n- [Remote SSH](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-ssh)\n- [Remote Containers](https://marketplace.visualstudio.com/items?itemName=ms-vscode-remote.remote-containers)\n- [VirtualBox](https://marketplace.visualstudio.com/items?itemName=acherkashin.virtualbox-extension)\n- [Vagrant](https://marketplace.visualstudio.com/items?itemName=bbenoist.vagrant)\n- [Ruby](https://marketplace.visualstudio.com/items?itemName=rebornix.Ruby)\n- [Ruby Solargraph](https://marketplace.visualstudio.com/items?itemName=castwide.solargraph)\n- [Github](https://marketplace.visualstudio.com/items?itemName=KnisterPeter.vscode-github)\n- [Github Actions](https://marketplace.visualstudio.com/items?itemName=cschleiden.vscode-github-actions)\n- [Gitlens](https://marketplace.visualstudio.com/items?itemName=eamodio.gitlens)\n\nVSCode should be configured to associate most of the files in the repository with Ansible.\nCheck that your ansible files have Ansible set in the \"Select Language Mode\".\nIn VSCode the difference between YAML and Ansible Language Mode is night and day.\nExample .vscode/settings.json\n\n```json\n{\n  \"files.associations\": {\n    \"kitchen*\": \"yaml\",\n    \"*.yml\": \"ansible\"\n  },\n}\n```\n\nPython should be setup with the following:\n\n```json\n    \"editor.renderWhitespace\": \"all\",\n    \"editor.rulers\": [\n        80,\n        100,\n        120\n    ],\n    \"[python]\": {\n        \"editor.tabSize\": 4,\n        \"editor.insertSpaces\": true,\n        \"editor.formatOnSave\": true\n    },\n    \"[yaml]\": {\n        \"editor.insertSpaces\": true,\n        \"editor.tabSize\": 2,\n        \"editor.autoIndent\": \"none\",\n        \"editor.quickSuggestions\": {\n            \"other\": true,\n            \"comments\": false,\n            \"strings\": true\n        },\n        \"editor.formatOnPaste\": true\n    },\n    \"python.linting.enabled\": true,\n    \"python.linting.pylintEnabled\": true,\n    \"python.linting.banditEnabled\": true,\n    \"python.linting.banditArgs\": [\n        \"-x\",\n        \"./tests\",\n        \"-r\",\n    ],\n    \"python.linting.pylintArgs\": [\n        \"--disable=C0301,C0111,E0402,W0702,W0108,W0703\"\n    ],\n    \"python.linting.pycodestyleEnabled\": true,\n    \"python.linting.pycodestyleArgs\": [\n        \"--ignore E501\"\n    ],\n    \"python.formatting.provider\": \"black\",\n    \"python.languageServer\": \"Pylance\",\n    \"python.envFile\": \"/Users/current.user/.vspyenv\",\n    \"python.testing.pytestArgs\": [\n        \"-s\",\n        \"-vvvv\"\n    ],\n    \"pythonTestExplorer.testFramework\": \"pytest\",\n    \"markdownlint.config\": {\n        \"MD013\": {\n            \"line_length\": 120,\n            \"tables\": false,\n            \"code_blocks\": false\n        },\n        \"MD025\": false,\n        \"MD033\": false,\n        \"MD036\": false,\n        \"MD041\": false\n    },\n    \"testExplorer.hideEmptyLog\": false,\n```\n\n## Setting Up VirtualBox Environment\n\nAccess to local VMs running Amazon Linux helps rapidly and safely iterate on Ansible code.\n\n### Install VirtualBox and Vagrant\n\n[VirtualBox](https://www.virtualbox.org/) can be installed with Homebrew. However, every once in a while the latest build\nof VirtualBox has a broken functionality. At the time of writing, VirtualBox 6.1.28 has a broken Host Network Manager.\nGood build of VirtualBox is [6.1.26](https://download.virtualbox.org/virtualbox/6.1.26/VirtualBox-6.1.26-145957-OSX.dmg).\nInstall Virtual Box from the link.\n\n[Vagrant](https://github.com/hashicorp/vagrant) is a HashiCorp Ruby project to provide VirtualBox abstraction.\nUse Homebrew to install vagrant\n\n```text\n$ brew install vagrant\n```\n\n### Configuring Test Kitchen\n\n[Test Kitchen](https://github.com/test-kitchen/test-kitchen) is a Ruby project to automate\nInfrastructure as Code development life-cyle.\n\nInstall RVM\n\n```text\n$ gpg --keyserver hkp://pool.sks-keyservers.net --recv-keys 409B6B1796C275462A1703113804BB82D39DC0E3 7D2BAF1CF37B13E2069D6956105BD0E739499BDB\n\n$ \\curl -sSL https://get.rvm.io | bash -s stable --ruby\n```\n\nAdd RVM to your profile\n\n```bash\n# Add RVM\n[[ -s \"$HOME/.rvm/scripts/rvm\" ]] \u0026\u0026 source \"$HOME/.rvm/scripts/rvm\"\n```\n\nChange directory to anything other than ansible-amazon-base and change back to have RVM pull a ruby version\nand create a gemset.\n\n```text\n$ cd ..\n$ cd ansible-amazon-base/\nruby-3.0.0 - #gemset created /home/current.user/.rvm/gems/ruby-3.0.0@ansible-kitchen\nruby-3.0.0 - #generating ansible-kitchen wrappers.............\n```\n\nAfter RVM configures Gemset, run bundler to install gems\n\n```text\n$ bundle install\n```\n\n### Downloading Amazon Linux v2 Vagrant Box\n\nAmazon Linux v2 is a feature-rich Linux distribution maintained by Amazon. Amazon page about [Amazon Linux Images](https://docs.aws.amazon.com/AWSEC2/latest/UserGuide/amazon-linux-2-virtual-machine.html#amazon-linux-2-virtual-machine-download)\nlists various formats available, including [Amazon Linux v2 virtualbox](https://cdn.amazonlinux.com/os-images/2.0.20211005.0/virtualbox/).\n\nOlder Amazon Linux v2 vagrant box can be downloaded from [HashiCorp Vagrant Cloud](https://app.vagrantup.com/bento/boxes/amazonlinux-2).\n\nImport vagrant box:\n\n```text\n$ vagrant box add amazon2 \u003cdownloaded box\u003e\n$ vagrant box list\n```\n\nLatest Amazon Linux v2 box can be built from [Chef Bento](https://github.com/chef/bento/blob/main/packer_templates/amazonlinux/README_FIRST.md)\nproject. Disabling Amazon SSM is a consideration.\n\n### Build an Optimized Amazon Linux 2 Vagrant Box\n\nDefault Amazon Linux 2 vagrant box does not come with Ansible installed.\nAny time we run kitchen with the default Amazon Linux 2 box, kitchen will spend time installing Ansible.\nIn order to save development time, we will build a box that includes Ansible and Docker.\n\nRun kitchen converge with kitchen.box.yml\n\n```text\n$ KITCHEN_YAML=kitchen.box.yml kitchen converge box\n```\n\nList running VirtualBox VMs and make note of the full name of the kitchen-ansible-amazon-base-box-amazon VM\n\n```text\n$ VBoxManage list vms\n\"kitchen-ansible-amazon-base-box-amazon-cb9dedd7-fd27-4344-b026-bd3a2b7a340e\" {9cf5ed90-d3a0-4e95-b742-6c9249c0cf34}\n```\n\nRun vagrant to export kitchen-ansible-amazon-base-box-amazon\n\n```text\n$ vagrant package --base kitchen-ansible-amazon-base-box-amazon-cb9dedd7-fd27-4344-b026-bd3a2b7a340e\n==\u003e kitchen-ansible-amazon-base-box-amazon-cb9dedd7-fd27-4344-b026-bd3a2b7a340e: Attempting graceful shutdown of VM...\n==\u003e kitchen-ansible-amazon-base-box-amazon-cb9dedd7-fd27-4344-b026-bd3a2b7a340e: Clearing any previously set forwarded ports...\n==\u003e kitchen-ansible-amazon-base-box-amazon-cb9dedd7-fd27-4344-b026-bd3a2b7a340e: Exporting VM...\n==\u003e kitchen-ansible-amazon-base-box-amazon-cb9dedd7-fd27-4344-b026-bd3a2b7a340e: Compressing package to: /Users/current.user/work/ansible-amazon-base/package.box\n```\n\nImport package.box as amazon2-ansible\n\n```text\n$ vagrant box add amazon2-ansible package.box\n$ vagrant box list\namazon2         (virtualbox, 0)\namazon2-ansible (virtualbox, 0)\n```\n\nRemove kitchen instance\n\n```text\nKITCHEN_YAML=kitchen.box.yml kitchen destroy box\n```\n\nRemove package.box from the local folder\n\n### Environment Variable Overwrites for Kitchen\n\nKitchen will use amazon2-ansible box by default.\nIf you are using a different box, you can set KITCHEN_ANSIBLE_BOX environment variable.\n\n## Running Test Kitchen\n\nChange directory to playbooks and run\n\n```text\n$ kitchen list\n```\n\nTo create a VirtualBox VM and apply an Ansible playbook run\n\n```text\n$ kitchen converge docker\n```\n\nTo destroy a created VM run\n\n```text\n$ kitchen destroy docker\n```\n\nTo connect to a VM run\n\n```text\n$ kitchen ssh docker\n```\n\n## Running Integration Tests\n\nIntegration tests are written in [TestInfra](https://github.com/pytest-dev/pytest-testinfra).\nTo run tests\n\n```text\n$ kitchen verify docker\n```\n\n## Running Ansible Playbooks on AWS Instances\n\nIn order to run Ansible Playbooks on AWS instances, first configure\nANSIBLE_ROLES_PATH to point to the roles directory of the repository, e.g.\n\n```text\n$ export ANSIBLE_ROLES_PATH=/Users/current.user/work/ansible-amazon-base/roles\n```\n\nAlso configure ~/.ansible.cfg to format Ansible output as a more readable YAML\n\n```ini\n[defaults]\nstdout_callback = yaml\n```\n\nChoose a playbook and run Ansible\n\n```text\n$ ansible-playbook -v -u ec2-user --private-key ~/.ssh/\u003cinstance\u003e.pem -i \u003cinstance_ip\u003e, playbooks/gst/gst_jupyter.yml\n```\n\n## Example Project: Build a Local Docker/Containerd Server VM\n\nWhy bother with Docker Desktop when you can build your own Containerd Server?\n\nCheck \"Host Network Manager\" in the File menu of your VirtualBox. Add an interface and make note of the subnet.\n\nEdit kitchen.yml containerd suit and set private_network to a static IP of your choice.\n\n```yaml\n  - name: containerd\n    provisioner:\n      name: ansible_playbook\n      playbook: ./playbooks/docker/docker.yml\n    driver:\n      vm_hostname: containerd.local\n      network:\n        - ['private_network', {ip: '192.168.56.121'}]\n```\n\nRun kitchen converge\n\n```text\n$ kitchen converge containerd\n...\n       PLAY RECAP *********************************************************************\n       localhost                  : ok=5    changed=1    unreachable=0    failed=0    skipped=2    rescued=0    ignored=0\n\n       Downloading files from \u003ccontainerd-amazon\u003e\n       Finished converging \u003ccontainerd-amazon\u003e (0m5.54s).\n-----\u003e Test Kitchen is finished. (1m15.18s)\n```\n\nSSH into your Containerd VM.\nChange vagrant's user password from 'vagrant' to something secure.\nAdd your SSH key to ~/.ssh/authorized_keys. Change permissions on /var/run/docker.sock.\n\n```text\n$ ssh vagrant@192.168.56.121\nvagrant@192.168.56.121's password:\nLast login: Mon Nov 15 05:47:31 2021 from 10.0.2.2\n\n       __|  __|_  )\n       _|  (     /   Amazon Linux 2 AMI\n      ___|\\___|___|\n\nhttps://aws.amazon.com/amazon-linux-2/\n\nThis system is built by the Bento project by Chef Software\nMore information can be found at https://github.com/chef/bento\n\n[vagrant@containerd ~]$ passwd\nChanging password for user vagrant.\nChanging password for vagrant.\n(current) UNIX password:\nNew password:\nRetype new password:\npasswd: all authentication tokens updated successfully.\n[vagrant@containerd ~]$ vi ~/.ssh/authorized_keys\n[vagrant@containerd ~]$ sudo chmod a+rw /var/run/docker.sock\nexit\nlogout\nConnection to 192.168.56.121 closed.\n```\n\nCreate a new Docker context:\n\n```text\n$ docker context create containerd1 --docker \"host=ssh://vagrant@192.168.56.121\"\ncontainerd\nSuccessfully created context \"containerd1\"\n$ docker context use containerd1\n$ docker context ls\nNAME            DESCRIPTION                               DOCKER ENDPOINT                KUBERNETES ENDPOINT   ORCHESTRATOR\ncontainerd1 *                                             ssh://vagrant@192.168.56.121\ndefault         Current DOCKER_HOST based configuration   unix:///var/run/docker.sock                          swarm\n```\n\nStart using your new Containerd server:\n\n```text\n$ docker version\nClient: Docker Engine - Community\n Version:           20.10.10\n API version:       1.41\n Go version:        go1.17.2\n Git commit:        b485636f4b\n Built:             Fri Oct 15 14:45:13 2021\n OS/Arch:           darwin/amd64\n Context:           containerd1\n Experimental:      true\n\nServer:\n Engine:\n  Version:          20.10.7\n  API version:      1.41 (minimum version 1.12)\n  Go version:       go1.15.14\n  Git commit:       b0f5bc3\n  Built:            Tue Sep 28 19:56:28 2021\n  OS/Arch:          linux/amd64\n  Experimental:     false\n containerd:\n  Version:          1.4.6\n  GitCommit:        d71fcd7d8303cbf684402823e425e9dd2e99285d\n runc:\n  Version:          1.0.0\n  GitCommit:        84113eef6fc27af1b01b3181f31bbaf708715301\n docker-init:\n  Version:          0.19.0\n  GitCommit:        de40ad0\n```\n\n## Ansible References\n\n- [Ansible 101 - Episode 1 - Introduction to Ansible](https://www.youtube.com/watch?v=goclfp6a2IQ)\n- [Ansible 101 - Episode 2 - Ad-hoc Tasks and Inventory](https://www.youtube.com/watch?v=7kVfqmGtDL8)\n- [Ansible 101 - Episode 3 - Introduction to Playbooks](https://www.youtube.com/watch?v=WNmKjtWtqIc)\n- [Ansible 101 - Episode 4 - Your First Real-World Playbook](https://www.youtube.com/watch?v=SLW4LX7lbvE)\n- [Ansible 101 - Episode 5 - Playbook Handlers, Environment Vars, and Variables](https://www.youtube.com/watch?v=HU-dkXBCPdU)\n- [Ansible 101 - Episode 6 - Ansible Vault and Roles](https://www.youtube.com/watch?v=JFweg2dUvqM)\n- [Make Your Ansible Playbooks Flexible, Maintainable, and Scalable](https://www.youtube.com/watch?v=kNDL13MJG6Y)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faia%2Fansible-amazon-base","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Faia%2Fansible-amazon-base","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Faia%2Fansible-amazon-base/lists"}