# russelltao/protocol-2day-training architecture

> Architecture diagram of the GitHub repository russelltao/protocol-2day-training, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2025-05-19). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/russelltao/protocol-2day-training
- Repository: https://github.com/russelltao/protocol-2day-training

## Overview

##### Project type and purpose
- This repo is not a typical application but a set of training materials and packet‐capture artifacts for a “2-day network protocol” workshop.
- It collects PCAP/PKT files for various layers (ARP, TCP, HTTP1/2/3, TLS, QUIC, Kubernetes vxlan overlay), plus a PDF on software architecture and a simple Python script.

##### File structure
- Top-level artifacts: dozens of `.pcapng` / `.pkt` capture files named by lesson (`l2-…`, `l10-…`, `l15-…`), a `flannel.yaml` (CNI config), one Python example script (`l14-broadcast_send.py`), and a `.pdf` on architecture styles.
- No traditional “src” or “lib,” but the presence of `flannel.yaml` and detailed capture instructions in the README point at a Kubernetes + flannel overlay testbed.

##### README
- Describes how to install capture tools (Wireshark, tcpdump), gives pointers to network / HTTP / TLS / QUIC / ASCII reference materials, and shows a “k8s capture environment” using veth pairs, bridges (`cni0`), vxlan (flannel.1) overlay atop an L3 underlay.
- Clearly defines Underlay vs. Overlay addresses, show how to find the right veth interface for a given pod.

##### Main components
a. Physical Hosts (could be VMs) running Linux
b. Underlay Network (eth0 on each host, IP range 172.27.0.0/20)
c. Linux Bridge “cni0” (and docker0) on each host
d. Flannel VXLAN Overlay (`flannel.1`) on each host, carrying Pod CIDR (10.244.0.0/16)
e. Kubernetes Master & Worker Nodes
f. Pods / Containers with their eth0 interfaces, each linked via a veth pair into `cni0`
g. Tools (tcpdump/Wireshark) tapping at selected veth or flannel interfaces
h. Data artifacts: lesson PCAP files, Python script, flannel config, architecture PDF

##### Relationships & interactions
- Pod-to-Pod traffic on the same host: container eth0 → veth pair → cni0 → flannel.1 (via VXLAN) → cni0 → veth → target container.
- Cross-host Pod traffic: container → veth → cni0 → flannel.1 encapsulate in VXLAN → eth0 → network switch → eth0 on other host → flannel.1 de-encapsulate → cni0 → target container.
- Points: annotate tcpdump on `vethXXXXX` and `flannel.1` to illustrate Underlay vs. Overlay captures.

##### Architectural patterns & design principles
- Layered network architecture: separate Underlay (physical IP/MAC) from Overlay (VXLAN, Pod IP/MAC).
- Control plane vs. data plane: Kubernetes API & etcd on master vs. packet forwarding in flannel agent on each node.
- Use of CNI plugin for container networking, micro-segmentation by Pod CIDRs.

##### Relevant technologies & files
- Linux bridging (`bridge-utils`), veth pairs
- Flannel CNI (config in `flannel.yaml`) over VXLAN
- Kubernetes Pods (represented by IPs in captures)
- Tools: tcpdump, Wireshark, Python (for small broadcast script)
- PCAP/PKT lesson recordings as evidence / test vectors

##### Essential details
- Clear component labels (Host A / Node1, Host B / Node2, Master Node, Worker Node)
- Interface names + IP/MAC examples

## Diagram (Mermaid)

```mermaid
flowchart TD
    %% Subgraphs for Hosts and Network Layers
    subgraph "Physical Host A / Node1"
        style Node1 fill:#e0f7fa,stroke:#006064
        Node1["Host A / Node1"]:::host
        Node1_eth0["eth0\n(172.27.0.10)"]:::underlay
        Node1_bridge["cni0"]:::bridge
        Node1_veth["vethXXX@ifY"]:::veth
        Node1_pod["Pod eth0\n(10.244.0.5)"]:::pod
        Node1_flannel["flannel.1"]:::overlay
    end

    subgraph "Physical Host B / Node2"
        style Node2 fill:#e0f7fa,stroke:#006064
        Node2["Host B / Node2"]:::host
        Node2_eth0["eth0\n(172.27.0.11)"]:::underlay
        Node2_bridge["cni0"]:::bridge
        Node2_veth["vethYYY@ifZ"]:::veth
        Node2_pod["Pod eth0\n(10.244.0.6)"]:::pod
        Node2_flannel["flannel.1"]:::overlay
    end

    subgraph "Kubernetes Control Plane"
        style ControlPlane fill:#fff3e0,stroke:#e65100
        Master["Master Node"]:::control
        Master_api["kube-apiserver"]:::control
        etcd["etcd"]:::control
    end

    subgraph "Underlay Network"
        style Underlay fill:#e3f2fd,stroke:#0d47a1
        Switch["Layer2/3 Switch"]:::underlay
    end

    %% Connections Host A
    Node1_pod -->|"veth" | Node1_veth
    Node1_veth -->|"bridge" | Node1_bridge
    Node1_bridge -->|"vxlan encapsulate"| Node1_flannel
    Node1_flannel -->|"UDP VXLAN\nport 8472"| Node1_eth0
    Node1_eth0 -->|"underlay"| Switch

    %% Connections Host B
    Switch -->|"underlay"| Node2_eth0
    Node2_eth0 -->|"UDP VXLAN\nport 8472"| Node2_flannel
    Node2_flannel -->|"vxlan decapsulate"| Node2_bridge
    Node2_bridge -->|"veth"| Node2_veth
    Node2_veth -->|"container"| Node2_pod

    %% Pod-to-Pod same host path example on A
    Node1_pod -->|"veth"| Node1_veth
    Node1_veth -->|"bridge"| Node1_bridge
    Node1_bridge -->|"veth"| Node1_veth
    Node1_veth -->|"container"| Node1_pod

    %% Control Plane connections
    Master_api -->|“sync”| etcd
    Master_api -->|“provision”| Node1
    Master_api -->|“provision”| Node2

    %% Capture Points
    capture1["tcpdump on vethXXX"]:::capture
    capture2["tcpdump on flannel.1"]:::capture
    Node1_veth -->|tap| capture1
    Node1_flannel -->|tap| capture2

    %% Artifacts Repository
    subgraph "Training Artifacts"
        style Artifacts fill:#f1f8e9,stroke:#33691e
        README["README & Docs"]:::doc
        flannelYAML["Flannel CNI config"]:::config
        archPDF["Architecture PDF"]:::doc
        l2gzip["l2-baidu-index-gzip.pcapng"]:::artifact
        l2raw["l2-baidu-index-raw.pcapng"]:::artifact
        l3webdav["l3-webdav协议抓包.pcapng"]:::artifact
        l7grpc["l7-grpc-data_transmission_compress.pkt"]:::artifact
        l9log["l9-sina_sslkeylogfile.log"]:::artifact
        l9tls["l9-sina_tls.pkt"]:::artifact
        l10ocsp["l10-ocsp.pcapng"]:::artifact
        l10psk["l10-tls1.2_psk.pcapng"]:::artifact
        l1013["l10-tls1_3.pcapng"]:::artifact
        l12a["l12-tcp_fastopen_initial_connection.pcapng"]:::artifact
        l12b["l12-tcp_fastopen_second_connection.pcapng"]:::artifact
        l14py["l14-broadcast_send.py"]:::artifact
        l14dns["l14-dns.pkt"]:::artifact
        l14udp["l14-udp_broadcast.pkt.pcapng"]:::artifact
        arpstorm["arp-storm.pcapng"]:::artifact
        arpbasic["l15-arp_pcap.pcapng"]:::artifact
        rarp["l15-rarp_req_reply.pcap.pcapng"]:::artifact
        masterUL["l15-master.pcapng"]:::artifact
        masterVLAN["l15-master_8472.pcapng"]:::artifact
        workerUL["l15-worker.pcapng"]:::artifact
        flannelCap["l15-m_flannel1.pcapng"]:::artifact
        cni0http["l15-worker_cni0_http_mysql.pcapng"]:::artifact
        cni080["l15m_cni0_80_local.pcapng"]:::artifact
        eth08472["l15-w_eth0_8472.pcapng"]:::artifact
    end

    %% Click Events
    click README "https://github.com/russelltao/protocol-2day-training/blob/main/README.md"
    click flannelYAML "https://github.com/russelltao/protocol-2day-training/blob/main/flannel.yaml"
    click archPDF "https://github.com/russelltao/protocol-2day-training/blob/main/架构风格与基于网络的软件架构设计.pdf"
    click l2gzip "https://github.com/russelltao/protocol-2day-training/blob/main/l2-baidu-index-gzip.pcapng"
    click l2raw "https://github.com/russelltao/protocol-2day-training/blob/main/l2-baidu-index-raw.pcapng"
    click l3webdav "https://github.com/russelltao/protocol-2day-training/blob/main/l3-webdav协议抓包.pcapng"
    click l7grpc "https://github.com/russelltao/protocol-2day-training/blob/main/l7-grpc-data_transmission_compress.pkt"
    click l9log "https://github.com/russelltao/protocol-2day-training/blob/main/l9-sina_sslkeylogfile.log"
    click l9tls "https://github.com/russelltao/protocol-2day-training/blob/main/l9-sina_tls.pkt"
    click l10ocsp "https://github.com/russelltao/protocol-2day-training/blob/main/l10-ocsp.pcapng"
    click l10psk "https://github.com/russelltao/protocol-2day-training/blob/main/l10-tls1.2_psk.pcapng"
    click l1013 "https://github.com/russelltao/protocol-2day-training/blob/main/l10-tls1_3.pcapng"
    click l12a "https://github.com/russelltao/protocol-2day-training/blob/main/l12-tcp_fastopen_initial_connection.pcapng"
    click l12b "https://github.com/russelltao/protocol-2day-training/blob/main/l12-tcp_fastopen_second_connection.pcapng"
    click l14py "https://github.com/russelltao/protocol-2day-training/blob/main/l14-broadcast_send.py"
    click l14dns "https://github.com/russelltao/protocol-2day-training/blob/main/l14-dns.pkt"
    click l14udp "https://github.com/russelltao/protocol-2day-training/blob/main/l14-udp_broadcast.pkt.pcapng"
    click arpstorm "https://github.com/russelltao/protocol-2day-training/blob/main/arp-storm.pcapng"
    click arpbasic "https://github.com/russelltao/protocol-2day-training/blob/main/l15-arp_pcap.pcapng"
    click rarp "https://github.com/russelltao/protocol-2day-training/blob/main/l15-rarp_req_reply.pcap.pcapng"
    click masterUL "https://github.com/russelltao/protocol-2day-training/blob/main/l15-master.pcapng"
    click masterVLAN "https://github.com/russelltao/protocol-2day-training/blob/main/l15-master_8472.pcapng"
    click workerUL "https://github.com/russelltao/protocol-2day-training/blob/main/l15-worker.pcapng"
    click flannelCap "https://github.com/russelltao/protocol-2day-training/blob/main/l15-m_flannel1.pcapng"
    click cni0http "https://github.com/russelltao/protocol-2day-training/blob/main/l15-worker_cni0_http_mysql.pcapng"
    click cni080 "https://github.com/russelltao/protocol-2day-training/blob/main/l15m_cni0_80_local.pcapng"
    click eth08472 "https://github.com/russelltao/protocol-2day-training/blob/main/l15-w_eth0_8472.pcapng"

    %% Styles
    classDef underlay fill:#e3f2fd,color:#0d47a1,stroke:#0d47a1
    classDef overlay fill:#e8f5e9,color:#1b5e20,stroke:#1b5e20
    classDef bridge fill:#bbdefb,color:#0d47a1,stroke:#0d47a1
    classDef veth fill:#c5cae9,color:#283593,stroke:#283593
    classDef pod fill:#dcedc8,color:#33691e,stroke:#33691e
    classDef host fill:#e0f7fa,color:#006064,stroke:#006064
    classDef control fill:#fff3e0,color:#e65100,stroke:#e65100
    classDef capture fill:#eceff1,color:#455a64,stroke:#455a64,stroke-dasharray: 5 5
    classDef doc fill:#fff8e1,color:#f57f17,stroke:#f57f17
    classDef config fill:#e1f5fe,color:#0277bd,stroke:#0277bd
    classDef artifact fill:#f1f8e9,color:#33691e,stroke:#33691e
```
