Updating Ansible Collections

As part of our move to more havily using VyOS, we've needed to update the vyos collections from ansible, due to some changes in some of the syntax for 1.4+ of VyOS.

There are some pitfalls to setting up and editing ansible collections, especially ones that are for network devices, so I wanted to put in a reminder for when I do this next.


  1. The ansible-collections test code is very particular about the structure on disk. Generally, you'll need to be in a directory that is under a directory structure that contains ansible_collections/. In my case, I was working on the vyos collection, so I needed to check out the vyos collection git repo into ~/Development/ansible_collections/vyos (the ~/Development part is peculiar to me, but it's good to know this doesn't need to be right at the top of ~).

    As an additional recommendation, I'd further isolate this inside of another folder, especially if you are using an IDE like VSCode.

  2. I'm using VSCode these days for most of my python work, so I wanted to set up an appropriate workspace. The vyos collection appropriately ignores all the vscode configuration files, so you can just create them in the root of the collection. I put the .vscode directory in the vyos collection root and added paths so that the python interpreter would appropraitely see the modules (and the adjacent collection modules):

         "python.envFile": "${workspaceFolder}/.env",
         "python.autoComplete.extraPaths": [
         "python.analysis.extraPaths": [
  3. For tests to work, you need to have key dependencies in the same ansible_collection directory. It's not clear to me why, but the sanity tests failed without it.

    ansible-galaxy collection install ansible.netcommon -p ~/Development --force

    seemed to do the trick.

  4. The vyos collection uses network resource modules which are a bit different than the normal modules. They have a different structure and need to be in a different directory.

    In particular, you need the build playbook installed somewhere that you can get to it. And, in the case of the "standard" modules (like yvos, ios, eos, etc.), you also need to fork the repository for the resource modules from resource module models repository.

  5. Make changes to the module parameters and documention using the resource modules directly.

  6. Run the resource module build playbook, pointing the output at your module (in my case vyos). This will generate the module documentation, parsers, and validators for you.

    ansible-playbook -e rm_dest=~/Development/ansible_collections/vyos/vyos \
                  -e structure=collection \
                  -e collection_org=vyos \
                  -e collection_name=vyos \
                  -e model=~/Development/resource_module_models/models/vyos/firewall_rules/vyos_firewall_rules.yaml \

    All of the parameters appear to be required. For isolation, I created a venv and run the playbook from there.

    A couple of notes about generation here (specifically the sanity checks):

    • Run yaml-lint on the source *.txt files to make sure they are valid yamllint -d "{extends: default, rules: {line-length: {max: 120}, document-start: disable}}" <path>
    • you may need to run black on the generated files to get them to pass the sanity tests
    • aliases does not work in the existing sanity check
    • type values for the returns were missing from the build playbook, so I had to add them manually


Testing is it's own fun. There's some information in the contribution documentation on the testing:

  1. ansible-test sanity to run the sanity checks. These should mostly succeed
  2. Create or use existing (or modify) unit tests:
    ansible-test units tests/unit/modules/network/vyos/test_vyos_firewall_rules.py --docker -v --python 3.12
    Run using docker with verbose output.
  3. ansible-test integration --docker -v to run the integration tests. These are more involved and require a running instance of VyOS to test against.
  4. ansible-test units --docker -v to run all the unit tests. These are the most basic tests and should be run first.