Enhanced scaffolding for Ansible best practices directory structure

[shatakshiiii]

Related issue: #41

[cidrblock]

We prompt the for the future destination github org and repo and name the playbook adjacent collection after that

[NilashishC]

@cidrblock Not sure I fully understand this. Do you mean we'll also scaffold a playbook adjacent collection with --project=ansible-project?

[cidrblock]

yes, with just a role and task file in it.

[cidrblock]

I was thinking we could use the GH org and repo for the playbook adjacent collection name.

[shatakshiiii]

For the proposal to enhance scaffolding for Ansible best practices directory structure, we have collected some ideas to implement this feature.

We would be adding a new CLI parameter --project to specify the project you want to scaffold. This will default to collection.

On CLI, it will look something like this:
ansible-creator init --project=ansible-project --scm-org=company --scm-project=myproject --init-path /home/ansible/ansible-automation-project

Proposed Directory Structure -

ansible-project/
├── playbooks/
├── ansible.cfg
├── group_vars/
├── hosts_vars/
├── collections/ansible_collections
├── inventory

Next Steps -

We're reaching out to gather feedback and suggestions from our team and the wider Ansible community. Your feedback is crucial in refining and finalizing this proposal.

Any thoughts, suggestions would be more than welcome.

Thanks!

[priyamsahoo]

Well, last time I checked with the ansible-playbook command, the playbook adjacent collection only works when the playbook is in the root folder and not inside the playbooks folder. This means that validation, auto-completion, hovering, and other language features will not be available for the collection in the playbooks.

So, if we want to support playbook adjacent collections out of the box, we might have to scaffold the playbook in the root and not inside the playbooks directory.

[shatakshiiii]

Updated directory structure based on the above discussion:

ansible-project/
 |── .devcontainer/
 |    └── docker/
 |        └── devcontainer.json
 |    └── podman/
 |        └── devcontainer.json
 |    └── devcontainer.json
 |── .github/
 |    └── workflows/
 |        └── tests.yml
 |    └── ansible-code-bot.yml
 |── .vscode/
 |    └── extensions.json
 |── collections/
 |   └── requirements.yml
 |   └── ansible_collections/
 |       └── project_org/
 |           └── project_repo/
 |               └── README.md
 |               └── roles/sample_role/
 |                         └── README.md
 |                         └── tasks/main.yml
 |── inventory/
 |   └── groups_vars/
 |   └── host_vars/
 |   └── hosts.yml
 |── ansible-navigator.yml
 |── ansible.cfg
 |── linux_playbook.yml
 |── network_playbook.yml
 |── README.md
 |── site.yml

[anshulbehl]

This structure looks really cool, thanks for working on this. Thinking platform focus, I would also add a default ansible-code-bot.yml file inside the .github directory as well.

[adworjan]

Is there a plan to add a roles folder from the project root with the requirements.yml and a basic role structure? Forcing collections for every role (especially roles that are only written to be used within that repo which is incredibly common) is a lot of extra and unnecessary overhead. This is a major change to every single existing repo that customers have (and ones that our services teams have delivered)

[cidrblock]

There has been a lot of conversation about this. The only real extra overhead here is the nested directories and the need for a fully qualified role name. The benefit here is that it is much easier to move from a playbook ajacent collection to a standalone, redistributable collection if reusability is needed/identified. If and when the playbook ajacent collection requires an external python package, the transtion to stand alone collection and/or execution environment is also much smoother. It is a little different, but I think it provides a much smoother path than a roles folder.

For net-new playbook/content authors, which is the target audience here, I think it is better to introduce a collection early on, even if it remains playbook ajacent and only ever contains roles.

[trishnaguha]

@shatakshiiii @cidrblock @NilashishC Are we not generating CI pipeline (ansible-content-action) example with Lint as part of the playbook project?
Refer to the JIRA ticket please.

[shatakshiiii]

@trishnaguha The file tests.yml mentioned inside .github/workflow directory will take care of that CI pipeline!

[cidrblock]

Let's also include a devcontainer file #112

[netopsengineer]

Thank you to everyone involved in this feature, as the original requester, using it for the first time today, and seeing all of your intuitive ideas come together to make this a reality was exciting, excellent work!