Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

doc: add some diagrams #4678

Merged
merged 8 commits into from
Jan 21, 2025
Merged

doc: add some diagrams #4678

Show file tree
Hide file tree
Changes from 6 commits
Commits
Show all changes
8 commits
Select commit Hold shift + click to select a range
0788ea4
doc: add some diagrams
jiceatscion Jan 10, 2025
8aa0687
Merge branch 'master' into doc_diagrams
jiceatscion Jan 13, 2025
e73a781
Merge branch 'master' into doc_diagrams
jiceatscion Jan 15, 2025
b3ad654
Merge branch 'master' into doc_diagrams
jiceatscion Jan 16, 2025
efc0e65
Merge branch 'master' into doc_diagrams
jiceatscion Jan 20, 2025
1539c97
Implement some reviewer's suggestion.
jiceatscion Jan 20, 2025
a16e580
Update stack diagram based on reviwer's comment.
jiceatscion Jan 20, 2025
0a93cdd
Improve diagram.
jiceatscion Jan 21, 2025
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions doc/data-plane.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -15,4 +15,5 @@ Data Plane
protocols/authenticator-option
protocols/bfd
protocols/assigned-protocol-numbers
protocols/stack

Binary file added doc/fig/overview-topology.excalidraw.png
View file
Open in desktop
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
26 changes: 25 additions & 1 deletion doc/overview.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -98,6 +98,31 @@ There are three types of links between ASes in SCION:
- A **peering link** also includes at least one non-core AS. The ASes may be in different ISDs.
Peering links are only available for use by children (direct or indirect) of the two linked ASes.

Topology summary
^^^^^^^^^^^^^^^^

The following diagram provides a visual summary of the topology of a SCION network.

.. figure:: fig/overview-topology.excalidraw.png

Core links (in bright red) connect core ASes, thereby providing inter-ISD connectivity. Intra ISD
links (in green) connect ASes within an ISD. AS-internal networks (in blue) connect the various
hosts within an AS (including border routers). Peering links (in purple) provide restricted use
shortcuts between ISDs.

This diagram attempts to illustrate the variety of valid configurations. For example, notice that:

- There may be multiple core ASes per ISD.
- There may be connections between a non-core AS and multiple core-ASes.
- There may be multiple connections between any two ASes.
- There may be multiple border routers per AS.
- There may be any number of end-hosts (includng none) in an AS.
- Border routers need not be dedicated to one particular kind of links.
- Excludig core links, the ASes within an ISD form a directed acyclic graph (no other constraint).
- The core ASes themselves form an arbitrary graph.

The dark red dashed arrows show examples of possible paths through the network.

Routing
^^^^^^^

Expand All @@ -123,7 +148,6 @@ The process of creating an end-to-end forwarding path consists of the following

.. figure:: fig/overview-routing.excalidraw.png


.. seealso::

:doc:`control-plane`
Expand Down
Binary file added doc/protocols/fig/stack.excalidraw.png
View file
Open in desktop
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

  • 'QUIC': I think many applications do not use QUIC, just plain UDP (over SCION)?
  • Grpc Most applications probably do not use Grpc. Or if they do (as JPAN does, or the daemon) for communication with the control service, I think they are not (and I think should not be) using Grpc over SCION?
  • Scion Router: why is the SCION router a different color than everything else? Isn't it in the same category as e.g. the Control Service?

Copy link
Contributor Author

@jiceatscion jiceatscion Jan 20, 2025 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Isn't the control service API used via grpc over SCION? I find that part awfully confusing, I must admit. That many application do not use quic and grpc at all is depicted in the diagram by the fact that grpc and quic are not occupying the entire width belong application or CS. However I agree that it's not obvious. Adding arrows, to see if that helps.

As for the color; I was trying to attract attention to the fact that it is in a slightly unsual position in the stack: it does technically consume and produce packets of the highest possible layer, but does not look at anything but the SCION header. Nothing new for a router, but I find it difficult to place on a network stack diagram. I could put it at the top of the SCION layer too. Suggestions?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

As I understand it, the control service API is used via grpc over SCION only when one control server talks to a different control server in a different AS. An application or daemon will only talk to the control server API that is in the local AS, hence no SCION underneath.

I would probably move the router to the top of the diagram, I think it is very similar to the control server, except that applications connect to it for dataplane reasons, while they connect to the control server for controlplane reasons.

Maybe I would also move the SCMP around, it is also consumed by applications (SCMP errors) and even produced by applications (SCMP echo/traceroute). The only thing that is a pure router protocol is BFD.

And maybe add a small note to the text that GRPC and QUIC are optional?

Also, I don't know what the current state is, but I think grpc is over UDP, not QUIC? GRPC over QUIC is only planned? I really don't know this, it's just something I seem to remember...

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

grpc not over quic: Indeed, I was confused. All fixed...I think.

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Sorry, actually, applications are also using grpc, e.g. JPAN uses Grpc directly, and PAN/snet applications use it indirectly via the daemon.

Another proposal: I wonder what the relevance of grpc (and QUIC) is in this context. Maybe the easiest is to remove GRPC from the diagram? And maybe remove QUIC as well?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Not sure how much detail we want to show in the diagram but the protocol stacks for the control service are as follows:

  • Intra-AS: gRPC/HTTP2/TCP/IP
  • Inter-AS: gRPC/HTTP2/QUIC/UDP/SCION

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

What I can do is show intra-AS communications as a dotted line directly b/w application and control service; if it's not going through SCION, no need to complicate matters. For inter-AS I can summarize grpc http and quic into a single box. I think it is important to mention that there is middleware there, but details are not so relevant indeed. Let me try again.

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

How's that?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
9 changes: 9 additions & 0 deletions doc/protocols/stack.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,9 @@
********************
SCION Protocol Stack
********************

.. _stack:

This document provides a visual summary of the SCION overall protocol stack.

.. figure:: fig/stack.excalidraw.png
Loading