search

ansible / ansible-documentation

Ansible community documentation
https://docs.ansible.com/
GNU General Public License v3.0
84 stars 503 forks source link

Document ansible-core architecture #2131

Open mariolenz opened 1 week ago

mariolenz commented 1 week ago

I'm looking for documentation about the architecture and inner workings of ansible-core. I didn't find anything about this. Maybe it exists, in that case it should be made easier to find.

I think knowing more about ansible-core, which is the base of the Ansible ecosystem, would help people to contribute. Not only to ansible-core itself, but also to other projects.

For example, I was looking for a way to cache sessions to a remote API. I learned that each task is a separate process. But I think this isn't documented. At least, I didn't find this anywhere. Someone had to tell me.

I think documenting the inner workings of ansible-core would be helpful to the Ansible community at large. Not everyone has the time to find out by reading (and understanding!) the source code.

webknjaz commented 1 week ago

I think this is mentioned @ https://docs.ansible.com/ansible/latest/dev_guide/developing_locally.html#modules-and-plugins-what-is-the-difference

mariolenz commented 1 week ago

@webknjaz Your link doesn't explain or document how ansible-core really works...

samccann commented 1 week ago

related issue https://github.com/ansible/ansible-documentation/issues/1295

sivel commented 1 week ago

fwiw, we have no real documentation about this internal or otherwise. I think some people have little bits and pieces, and some really old whiteboard photos. This is, however, roughly on our TODO list to get something together by June 2025 as part of onboarding documentation we are in need of.

I'll attach a photo of a flow diagram we needed a few years back, and a script I created a while ago called fakesible.py that attempts to show in much less code an overall idea of how core works.

core-flow

https://gist.github.com/sivel/cd0ebabf9fea5401099e7820c58fb0dc

mariolenz commented 1 week ago

@sivel Thanks! The flow diagram doesn't make everything clear to me, but it's a start :smiley:

Would be great if you (as in you, the core team and not you personally) could work a bit on it publish this somewhere.

I agree that this would, apart from helping the community at large, be a good thing to have for your onboarding documentation.