{"id":21213869,"url":"https://github.com/z0mbix/rolecule","last_synced_at":"2025-07-10T09:33:12.534Z","repository":{"id":101974567,"uuid":"584189383","full_name":"z0mbix/rolecule","owner":"z0mbix","description":"Small, simple tool to test your ansible roles","archived":false,"fork":false,"pushed_at":"2024-10-16T22:12:13.000Z","size":127,"stargazers_count":10,"open_issues_count":1,"forks_count":2,"subscribers_count":5,"default_branch":"main","last_synced_at":"2024-10-18T22:22:10.817Z","etag":null,"topics":["ansible","configuration-management","docker","goss","podman","testinfra"],"latest_commit_sha":null,"homepage":"","language":"Go","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/z0mbix.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,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-01-01T18:55:48.000Z","updated_at":"2024-10-16T22:10:50.000Z","dependencies_parsed_at":null,"dependency_job_id":"47c4e20d-b11e-4098-896c-8298278e640f","html_url":"https://github.com/z0mbix/rolecule","commit_stats":null,"previous_names":[],"tags_count":4,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0mbix%2Frolecule","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0mbix%2Frolecule/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0mbix%2Frolecule/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/z0mbix%2Frolecule/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/z0mbix","download_url":"https://codeload.github.com/z0mbix/rolecule/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":225631076,"owners_count":17499547,"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","configuration-management","docker","goss","podman","testinfra"],"created_at":"2024-11-20T21:24:23.863Z","updated_at":"2025-07-10T09:33:12.527Z","avatar_url":"https://github.com/z0mbix.png","language":"Go","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Rolecule\n\n## Description\n\n`rolecule` is a simple tool to help you test your ansible roles by creating systemd enabled containers with either docker or podman, then converging them with ansible. We're basically treating containers as mini VMs.\n\nOnce converged, it will run a verifier to test it all. Currently, the only supported provisioner is [goss](https://github.com/goss-org/goss), but others may be added at some point in the future.\n\nThis should speed up testing your roles if you're currently using local or remote virtual machines.\n\n## Usage\n\nFirst, you need to create a simple `rolecule.yml` file in either the root of your role or in the `tests` directory, e.g.:\n\n```yaml\n---\nengine:\n  name: podman\n\nprovisioner:\n  name: ansible\n\nverifier:\n  name: goss\n\ninstances:\n  - name: rockylinux-9.1\n    image: rockylinux-systemd:9.1\n  - name: ubuntu-22.04\n    image: ubuntu-systemd:22.04\n\n```\n\nThen, from the root of your role (e.g. [sshd](testing/ansible/roles/sshd/tests/rolecule.yml)), run `rolecule test`, e.g.:\n\n```text\n» rolecule test\n   • creating container rolecule-sshd-rockylinux-9.1 with podman\n   • creating container rolecule-sshd-ubuntu-22.04 with podman\n   • converging container rolecule-sshd-rockylinux-9.1 with ansible\nUsing /etc/ansible/ansible.cfg as config file\n\nPLAY [test] ********************************************************************\n...\n\nPLAY RECAP *********************************************************************\nlocalhost                  : ok=5    changed=4    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0\n\n   • converging container rolecule-sshd-ubuntu-22.04 with ansible\nNo config file found; using defaults\n\nPLAY [test] ********************************************************************\n...\n\nPLAY RECAP *********************************************************************\nlocalhost                  : ok=5    changed=4    unreachable=0    failed=0    skipped=0    rescued=0    ignored=0\n\n   • verifying container rolecule-sshd-rockylinux-9.1 with goss\n............\n\nTotal Duration: 0.016s\nCount: 12, Failed: 0, Skipped: 0\n\n   • verifying container rolecule-sshd-ubuntu-22.04 with goss\n............\n\nTotal Duration: 0.015s\nCount: 12, Failed: 0, Skipped: 0\n\n   • destroying container rolecule-sshd-rockylinux-9.1\n   • destroying container rolecule-sshd-ubuntu-22.04\n   • complete\n```\n\n## Help\n\n```text\n» rolecule --help\nrolecule uses docker or podman to test your\nansible roles in a systemd enabled container,\nthen tests them with a verifier (goss).\n\nUsage:\n  rolecule [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  converge    Run your configuration management tool to converge the container(s)\n  create      Create a new container(s) to test the role in\n  destroy     Destroy everything\n  exec        Execute a command in a container\n  help        Help about any command\n  init        Initialise the project with a tests directory and a rolecule.yml file\n  list        List the running containers for this role/module/recipe\n  shell       Open a shell in a container\n  test        Create the container(s), converge them, and test them\n  verify      Verify your containers are configured how you expect\n  version     Show version\n\nFlags:\n  -d, --debug   enable debug output\n  -h, --help    help for rolecule\n\nUse \"rolecule [command] --help\" for more information about a command.\n```\n\n## Individual sub command examples\n\nCreate the containers:\n\n```text\n» rolecule create\n   • creating container rolecule-sshd-rockylinux-9.1 with podman\n   • creating container rolecule-sshd-ubuntu-22.04 with podman\n```\n\nList all containers:\n\n```text\n» rolecule list\nCONTAINER ID  IMAGE                             COMMAND         CREATED         STATUS             PORTS       NAMES\ne9638f571210  localhost/rockylinux-systemd:9.1  /usr/sbin/init  21 minutes ago  Up 21 minutes ago              rolecule-sshd-rockylinux-9.1\n0e07e4214fd5  localhost/ubuntu-systemd:22.04                    21 minutes ago  Up 21 minutes ago              rolecule-sshd-ubuntu-22.04\n```\n\nOpen a shell:\n\n```text\n» rolecule shell -n rolecule-sshd-ubuntu-22.04\nroot@0e07e4214fd5:/src#\n```\n\nDestroy the containers:\n\n```text\n» rolecule destroy\n   • destroying container rolecule-sshd-rockylinux-9.1\n   • destroying container rolecule-sshd-ubuntu-22.04\n```\n\n## Provisioners\n\n### Ansible\n\nThe default for the ansible provisioner is the equivalent to setting the following in the `rolecule.yml` config file:\n\n```yaml\nprovisioner:\n  name: ansible\n  command: ansible-playbook\n  playbook: playbook.yml\n  args:\n    - --connection\n    - local\n    - --inventory\n    - localhost,\n    - tests/playbook.yml\n  extra_args: []\n  env:\n    ANSIBLE_ROLES_PATH: .\n    ANSIBLE_NOCOWS: True\n```\n\nIf you want to add extra environment variables you can just add them to the `env` map, e.g.:\n\n```yaml\nprovisioner:\n  name: ansible\n  env:\n    ANSIBLE_NOCOLOR: True\n```\n\nIf you want to run a completely different ansible command, you can override the command and all the args with the `command` and `args` keys respectively, but if you just want to add other args like `--diff` or `--verbose`, add them to the `extra_args` array, e.g.:\n\n```yaml\nprovisioner:\n  name: ansible\n  extra_args:\n    - --diff\n    - --verbose\n```\n\n## Role dependencies\n\nIf you have role dependencies in your `meta/main.yml` file using local roles in the same location\nas the current role, they will be mounted at `/etc/ansible/roles` in the container so\nansible can find them. Currently, only local roles and ansible galaxy roles are supported.\n\n## Instances\n\nThese are instances of each test scenario, allowing you to test different ansible tags with specific test files.\n\nA simple example for a single Ubuntu test would be:\n\n```yaml\ninstances:\n  - name: ubuntu-22.04\n    image: ubuntu-systemd:22.04\n```\n\nSomething more elaborate:\n\n```yaml\ninstances:\n  - name: ubuntu-22.04\n    image: ubuntu-systemd:22.04\n    playbook: ubuntu/playbook.yml\n    volumes:\n      - /var/run/docker.sock:/var/run/docker.sock\n  - name: ubuntu-22.04-build\n    image: ubuntu-systemd:22.04\n    arch: amd64\n    playbook: ubuntu/playbook.yml\n    testfile: goss-build.yaml\n    tags:\n      - build\n  - name: rockylinux-9.1\n    image: rockylinux-systemd:9.1\n  - name: rockylinux-9.1-build\n    image: rockylinux-systemd:9.1\n    testfile: goss-build.yaml\n    tags:\n      - build\n    skip_tags:\n      - provision\n```\n\nWhere the above will test two different scenarios for each of the Ubuntu and Rocky Linux containers.\n\nIf you do not specify the testfile in the instance config, it will use the one specified in the verifier config.\n\nIf you do not specify the playbook in the instance config, it will use the one specified in the provisioner config.\n\nTesting multiple architectures is support, but untested as I don't currently have an easy way to test it, but should be as simple as something like:\n\n```yaml\ninstances:\n  - name: ubuntu-22.04-amd64\n    image: ubuntu-systemd:22.04\n    arch: amd64\n  - name: ubuntu-22.04-arm64\n    image: ubuntu-systemd:22.04\n    arch: arm64\n```\n\nIf you don't specify the arch, it will use the current host's architecture\n\nPlease note that if you do want to test using a different architecture to the host your are running it on,\nyou will need to have the relevant container image for that architecture.\n\n## Verifiers\n\n### Goss\n\nThe default goss configuration when you only specify the name, is equivalent to this:\n\n```yaml\nverifier:\n  name: goss\n  testfile: goss.yaml\n  extra_args: []\n```\n\nThis will execute:\n\n```text\ngoss --gossfile tests/goss.yaml validate\n```\n\nIf you want to customise how goss validate is executed, you can change the gossfile and add extra arguments to the validate subcommand, e.g. with this in your `rolecule.yml`:\n\n```yaml\nverifier:\n  name: goss\n  testfile: goss-build.yaml\n  extra_args:\n    - --format\n    - tap\n```\n\nIt will execute:\n\n```text\ngoss --gossfile tests/goss-build.yaml validate --format tap\n```\n\n### FAQ\n\n**How do I get this working on macOS?**\n\nYou'll need to make sure you create a rootful podman machine with your home directory mounted for volume mounts to work, e.g.:\n\n```text\n» podman machine init --now --rootful -v $HOME:$HOME\n```\n\nDocker Desktop should just work\n\n**How do I get this working on Windows?**\n\nYou'll need to make sure you create a rootful podman machine, e.g.:\n\n```text\n» podman machine init --now --rootful\n```\n\nDocker Desktop should just work\n\n**How do I create a suitable container image for this?**\n\nYou can use the `Dockerfile` files in the testing directory to build suitable images:\n\n```text\n» podman build -t rockylinux-systemd:9.1 -f testing/ansible/rockylinux-9.1-systemd.Dockerfile .\n» podman build -t ubuntu-systemd:22.04 -f testing/ansible/ubuntu-22.04-systemd.Dockerfile .\n» podman build -t amazonlinux2-systemd:2 -f testing/ansible/amazonlinux2-systemd.Dockerfile .\n```\n\nor\n\n```text\n» docker build -t rockylinux-systemd:9.1 -f testing/ansible/rockylinux-9.1-systemd.Dockerfile .\n» docker build -t ubuntu-systemd:22.04 -f testing/ansible/ubuntu-22.04-systemd.Dockerfile .\n» docker build -t amazonlinux2-systemd:2 -f testing/ansible/amazonlinux2-systemd.Dockerfile .\n```\n\n**How do I install collections?**\n\nFor now, I've been building in my collections in to the container images in the default location so they\nare discovered automatically by ansible.\n\n## TODO\n\n- ~~Test with podman on Mac~~\n- ~~Test docker on Linux~~\n- ~~Make provisioner output unbuffered~~\n- ~~Support installing role dependencies~~\n- Support installing ansible collections?\n- ~~Support scenarios, making it possible to test a role with different tags~~\n- ~~Support using custom provisioner command/args/env vars from rolecule.yml~~\n- ~~Support using custom verifier command/args/env vars from rolecule.yml~~\n- ~~Implement `rolecule init` to generate a rolecule.yml file (use current directory structure to determine configuration management provisioner)~~\n- ~~Implement `rolecule list` subcommand to list all running containers~~\n- ~~Write some tests :/~~\n- ~~Document what is required for a container image~~\n- ~~Test with docker on Linux~~\n- ~~Test with docker desktop on Mac~~\n- ~~Test with podman desktop on Windows~~\n- ~~Test with docker desktop on Windows~~\n- ~~Add goreleaser config to release to Github Releases~~\n- ~~Add Github actions workflow to build, test and release~~\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz0mbix%2Frolecule","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fz0mbix%2Frolecule","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fz0mbix%2Frolecule/lists"}