I'm constantly confused by this, and I'm not the only one. A diagram illustrated with routing and filtering rules would go a long way towards clearing things up. I'll draw the picture, if someone else fills in the relevant info here.
|Resolved||Lea_Lacroix_WMDE||T187319 Documentation sprint @Hackathon 2018|
|Declined||None||T101659 Run a documentation sprint for Cloud VPS and Toolforge|
|Open||None||T100529 Document, explain, diagram labs vlans and network setup|
If you are willing to have the diagram in git puppet.git (together with the hiera file hieradata/common/network.yaml to keep config and doc in sync), there is a neat Graphviz like python module that let one programmatically generate network diagrams: http://blockdiag.com/en/nwdiag/nwdiag-examples.html
It has several other modules. I have used for Zuul documentation http://docs.openstack.org/infra/zuul/gating.html and we adopted it to describe the scap3 architecture https://doc.wikimedia.org/mw-tools-scap/scap3/architecture.html