Architecture documentation should better explain how services interact, including ports and communication flows

[webvictim]

Details

We need to improve https://goteleport.com/teleport/docs/architecture/overview/

1) The page has diagrams of Teleport's architecture, but makes no mention at all of the newer model where nodes/agents join via the proxy (which is now very relevant with app_service, kube_service and the upcoming db_service)

2) The diagrams do not show any default port numbers or even categorisation of different traffic flows, so aren't useful for crafting network policies or firewall rules to permit/deny Teleport traffic appropriately.

We should overhaul these diagrams to clearly demonstrate the two different methods (nodes joining via auth server, nodes/agents joining via proxy) and give a detailed list of all the ports used in both situations and where the traffic flow happens.

This should cover on-prem deployments as well as Cloud.

Category

• Improve Existing
• Remove Outdated

Which platform(s)

• Teleport Open Source
• Teleport Cloud
• Teleport Enterprise

Which component(s)

• Server Access
• Kubernetes Access
• Application Access
• Database Access
• CLI Clients
• Web Clients

[ptgott]

@webvictim Now that we have a networking reference page that lists ports, is there any more work we should do on this issue?

[webvictim]

IMO there is still not a good, fully up-to-date architecture page which clearly explains and lists the differences between joining proxies/SSH nodes to the auth server and joining any other Teleport service to the proxy server. There is no graphical reference of how traffic flows in these situations with port numbers included and reference firewall configurations or similar.

For example:

• https://goteleport.com/docs/architecture/overview/ only covers what the auth, proxy and "node" services do (with no mention of the newer kube/db/app/windows services) rather than explaining how they fit together. It has high level diagrams that explain the relationship from a marketing standpoint, but aren't factually useful for deployment.

• https://goteleport.com/docs/architecture/proxy/ partly explains the differences between direct and IoT joins, but doesn't provide an overall view of how the traffic flows in these situations.

One of the things I think people find hardest to understand about Teleport is how its different services interact, why people might want to deploy them separately and the considerations/trade-offs involved with doing so. More concise diagrams would help a lot with this.