Document ansible-core architecture

[mariolenz]

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]

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

[mariolenz]

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

[samccann]

related issue #1295

[sivel]

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]

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

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.

[bcoca]

ai generated https://github.com/matburt/ansible-core-arch-claude