controller_configuration
controller_configuration copied to clipboard
redhat-cop
Removing the examples to a seperate Repo
After the last week we've had multiple people using the examples and playbooks without really understanding the collection and running into problems, Do we want to move the examples to a new repo like https://github.com/redhat-cop/aap_configuration_examples
and/or remove the playbooks? We previously had things in that repo, and moved them here, but it seem to be a crutch that users are leaning on, creating more support issues.
I'm on the fence on this, but thought the question should be raised.
If the playbooks are just examples then and not meant to be used OOTB directly running or importing the playbook then they shouldn't be in the playbooks directory.
I think at a minimum they should be moved to an examples or sample-playbooks directory. The other option would be to just have simple playbook examples in the README.md for each role and one or two simple examples in the main README.md.
I don't think moving them to another repo would be beneficial. IMHO that would be just one more place users would have to be pointed to and the possibility of them getting outdated and forgetting to update is pretty high. Keeping them all in one repo whether in an examples directory or in the READMEs I think would make them less likely to be forgotten about.
I am 100% for this, I am working on creating an example repo which will be public soon and maintained. I want to remove all examples and playbooks from this repo (outside of the readme's) or if we use them for automated tests change them to a tests folder to make it clear they are not to be examples nor should they be expected to work outside of automated tests
Agree on using a proper tests folder for CI pipelines.
Not sure about a separate repo for examples. Agree with @branic about his opinion on that. If we have a separate repo it's going down the road of a full blown demo to run against AAP, which sure, that is valuable for anyone, but maybe not necessary and I see more value in committing our time to this repo and letting folks build their own wonderful repo to manage AAP.
Seems a few issues in this repo are referencing examples, either that are outdated, don't work, or whatever. I think the docs you have are great and I didn't need many of the existing example code. I honestly went to the existing examples in the awx.awx docs: https://docs.ansible.com/ansible/latest/collections/awx/awx/workflow_job_template_module.html#examples
That worked fine for me.
I find using the playbooks in the playbooks directory very useful to get up and running quickly. Having to use a playbook from another project is not as convenient as running the playbook included in collection.
I think the general example is that the playbooks stay, however I am thinking of removing the job launch aspect of them, and/or just having it invoke dispatch.
I do agree with @branic and @ansiblejunky that yet more repos may be confusing to some users. However, I could see a dedicated repo that covers using all of the other related repos (controller_configuration, aap_utilities, ee_utilities, etc) together would be useful. And I do think we should provide some useful playbooks in the collection/playbooks dir as a bare minimum starting point. The upstream docs mention some strategies for how to include playbooks in collections https://docs.ansible.com/ansible/latest/dev_guide/developing_collections_structure.html#playbooks-directory we should stick to. If we don't intend for the playbooks in this collection to be used, we should remove them. Someone on our team was using the playbook directly, but didn't make sense in all cases so we've moved to writing our own.
@vvaldez and that is exactly what was intended by the playbooks repo, was a starting point for people, and once they grew comfortable that they move away from it to invoking things in their own fashion, I think part of it is we have SO many examples for different use cases now, and the playbooks handle a lot, that people are grabbing them and using the example ones, or trying to make the example playbook as a kitchen sink.
I didn't think we should remove them entirely, but the question was raised so I made this issue for debate.
So after discussion here and internally I am going to put the following up for a vote.
- We simplify the playbooks to invoke the normal configuration roles, and remove the tasks sections, and the import section. Rewrite the readme to use inventory as a source.
- We move some of the explicit examples of the roles like automatetheautomation, to their respective roles. We remove the testing examples and the export to the .github directory to be used for testing only. And provide a simple examples for people to use, rather then ones that cover many tests.
- Encourage use of other repos to do more complicated examples of use cases and create a Readme that links to them in the Examples repo. That way they are more discoverable, but still the burdon on keeping them up to date is on the creators and not all of us.
If you agree with this react with a Thumbs up, if you agree in part or have comments do so in more comments :)
My primary vote would be to delete examples folder and update all the readme's with up to date simple examples but that seems unpopular so I will take the proposed solutions with the addition of deleting all the comments in defaults files that were used as examples at one point.
I do think we need to update the roles readmes and test with up to date examples, Should that be the standard, No examples, but every role has a tested example itself?
Yeah that aligns with our best practices. Having a test playbook inside the role in the tests/ folder to ensure it works. Might be a pipeline down the line :)
I do think we need to update the roles readmes and test with up to date examples, Should that be the standard, No examples, but every role has a tested example itself?
I like this idea as well.