Add multicast documents #4339

ceclinux · 2022-10-26T06:56:41Z

Signed-off-by: ceclinux src655@gmail.com

docs/antctl.md

docs/multicast-guide.md

luolanzone · 2022-10-26T08:30:01Z

docs/multicast-guide.md

+1. IGMP egress rules: IGMP membership report and IGMP leave group messages.
+2. IGMP ingress rules: IGMP query, which includes IGMPv1, IGMPv2, and IGMPv3.
+3. Multicast egress rules: non-IGMP multicast traffic from Pod to other Pods or external hosts.
+Multicast ingress rules are currently not supported.


Add a new line before this.

Suggested change

Multicast ingress rules are currently not supported.

Note: multicast ingress rules are currently not supported.

docs/multicast-guide.md

luolanzone · 2022-10-26T08:31:11Z

docs/multicast-guide.md

+
+## Debugging and Collecting Multicast Statistics
+
+Users could use these tools to get the current status of the multicast application running in the cluster.


Suggested change

Users could use these tools to get the current status of the multicast application running in the cluster.

Users could check following guides and corresponding tools to get the current status of the multicast application running in the cluster.

luolanzone · 2022-10-26T08:38:12Z

docs/multicast-guide.md

+### Traffic in Local Network Control Block
+Multicast IP that in [Local Network Control Block](https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml#multicast-addresses-1)(224.0.0.0/24) should work only in encap mode. Multicast traffic destined for that IPs are not expected to be forward, therefore, no multicast route will be configured, and external hosts are not working either.
+
+### Linux kernel


new line missing

luolanzone · 2022-10-26T08:38:36Z

docs/multicast-guide.md

+Multicast IP that in [Local Network Control Block](https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml#multicast-addresses-1)(224.0.0.0/24) should work only in encap mode. Multicast traffic destined for that IPs are not expected to be forward, therefore, no multicast route will be configured, and external hosts are not working either.
+
+### Linux kernel
+You may find some traffic is not routed if the Node environment meets the following specifications:


luolanzone · 2022-10-26T08:38:53Z

docs/multicast-guide.md

+You may find some traffic is not routed if the Node environment meets the following specifications:
+1. Node kernel version under 5.4
+2. Node network doesn't support IGMP snooping
+3. Lots of multicast traffic with group IPs that won't be received by the Node(not Pod has not joined that group in that Node)


Suggested change

3. Lots of multicast traffic with group IPs that won't be received by the Node(not Pod has not joined that group in that Node)

3. Lots of multicast traffic with group IPs that won't be received by the Node (not Pod has not joined that group in that Node)

luolanzone · 2022-10-26T08:39:00Z

docs/multicast-guide.md

+2. Node network doesn't support IGMP snooping
+3. Lots of multicast traffic with group IPs that won't be received by the Node(not Pod has not joined that group in that Node)
+
+### Encap mode


luolanzone · 2022-10-26T08:39:19Z

docs/multicast-guide.md

+3. Lots of multicast traffic with group IPs that won't be received by the Node(not Pod has not joined that group in that Node)
+
+### Encap mode
+In encap mode, Multicast packets sent from Pod cannot be forwarded to more than one network interface on the host. Therefore Pods to external hosts multicast is not supported in encap mode.


Multicast -> multicast

docs/antctl.md

jianjuns · 2022-10-27T00:54:29Z

docs/antctl.md

+
+### Multicast commands
+
+The `antctl get podmulticaststats [NAME] [-n NAMESPACE]` command can print inbound and outbound multicast statistics for each Pod. Note that IGMP packets are not counted.


NAME -> POD_NAME

docs/multicast-guide.md

jianjuns · 2022-10-27T22:36:23Z

docs/multicast-guide.md

+## Use case example
+
+In this section, we will show how multicast video steaming works in
+Antrea using [VLC](https://www.videolan.org/vlc/).


Probably introduce VLC in a separate sentence. "[VLC] is used for the video streaming server.".

jianjuns · 2022-10-27T22:37:16Z

docs/multicast-guide.md

+
+## Prerequisites
+
+`Multicast` is introduced in v1.5 as an alpha feature. The feature gate


in Antrea v1.5.0.

docs/multicast-guide.md

jianjuns · 2022-10-27T23:31:14Z

docs/multicast-guide.md

+
+1. Node kernel version under 5.4
+2. Node network doesn't support IGMP snooping
+3. Lots of multicast traffic with group IPs that won't be received by the Node


I do not understand this sentence. Could you rephrase?

updated. This limitation can be detailed described by

busy networks with lots of unresolved multicast routing entries, the creation of new multicast group routes can be extremely slow and unreliable.

and resolved in this commit in Linux kernel torvalds/linux@0079ad8

jianjuns · 2022-10-27T23:31:44Z

docs/multicast-guide.md

+
+### Encap mode
+
+In encap mode, multicast packets sent from Pod cannot be forwarded to more than one


from a local Pod

jianjuns · 2022-10-27T23:31:56Z

docs/multicast-guide.md

+### Encap mode
+
+In encap mode, multicast packets sent from Pod cannot be forwarded to more than one
+network interface on the host. Therefore Pods to external hosts multicast is not supported


interfaces

on the Node

We should talk about the issue first. So, move "Multicast traffic from Pods to external hosts is not supported in encap mode" to be the first sentence.

I feel we can remove the reason sentence, but if you want to keep it" "This is because ..."

updated. Reason sentence removed.

wenyingd · 2022-11-01T09:07:34Z

docs/multicast-guide.md

+
+## Use case example
+
+[VLC](https://www.videolan.org/vlc/) is an open source multimedia player, it can be used for video streaming.


I think we can remove the company information if Antrea is not officially claimed to being or used to be used by the peer?

I would not talk about VLC in the first paragraph, which is just a minor thing as a tool we used in the example.

How about:

This section will take multicast video streaming as an example to demonstrate how multicast works with Antrea. In this example, VLC multimedia tools are used to generate and consume multicast video streams.

wenyingd · 2022-11-01T09:11:05Z

docs/multicast-guide.md

+
+### Encap mode
+
+Multicast traffic from Pods to external hosts is not supported in encap mode.


We should support Pod-to-external multicast traffic in encap mode. The only limitation is we do not support multiple multicast interfaces on the Node, and the packet is SNATed with Node's IP after it leaves the Node with encap mode.

@wenyingd : please provide a correct description in your mind.

I would like to use this description with encap mode,

The Pod-to-external multicast traffic leaves Node from the network interface which the default route is configured on, and the packet is SNATed. Configuration `multicastInterfaces` is not supported with encap mode.

How about

Configuration `multicastInterfaces` is not supported with encap mode. Multicast packets in encap mode are SNATed and forwarded to transport interface only.

jianjuns · 2022-11-01T21:03:51Z

docs/multicast-guide.md

+
+## Use case example
+
+[VLC](https://www.videolan.org/vlc/) is an open source multimedia player, it can be used for video streaming.


I would not talk about VLC in the first paragraph, which is just a minor thing as a tool we used in the example.

How about:

This section will take multicast video streaming as an example to demonstrate how multicast works with Antrea. In this example, VLC multimedia tools are used to generate and consume multicast video streams.

docs/multicast-guide.md

jianjuns · 2022-11-01T21:08:25Z

docs/multicast-guide.md

+2. IGMP ingress rules: applied to IGMP query, which includes IGMPv1, IGMPv2, and IGMPv3.
+3. Multicast egress rules: applied to non-IGMP multicast traffic from the selected Pods to other Pods or external hosts.
+
+Note: multicast ingress rules are currently not supported.


"are not supported at the moment"

Maybe Note: -> Note,

jianjuns · 2022-11-01T21:11:38Z

docs/multicast-guide.md

+
+### Multicast NetworkPolicy statistics
+
+[The Antrea NetworkPolicyStats feature](feature-gates.md#networkpolicystats) also applies to multicast NetworkPolices.


applies to -> supports

jianjuns · 2022-11-01T21:12:18Z

docs/multicast-guide.md

+
+### Multicast NetworkPolicy statistics
+
+[The Antrea NetworkPolicyStats feature](feature-gates.md#networkpolicystats) also applies to multicast NetworkPolices.


Nit: maybe move The out of the link.

The Antrea NetworkPolicyStats feature

jianjuns · 2022-11-01T21:18:12Z

docs/multicast-guide.md

+
+Multicast IPs in [Local Network Control Block](https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml#multicast-addresses-1) (224.0.0.0/24)
+should work only in Antrea encap mode. Multicast traffic destined for those addresses
+are not expected to be forwarded, therefore, no multicast route will be configured for them.


jianjuns · 2022-11-01T21:19:13Z

docs/multicast-guide.md

+### Linux kernel
+
+If the following situations apply to your Nodes, you may observe multicast traffic
+not routed correctly:


docs/multicast-guide.md

jianjuns · 2022-11-01T21:24:16Z

docs/multicast-guide.md

+
+1. Node kernel version under 5.4
+2. Node network doesn't support IGMP snooping
+3. Lots of inbound multicast traffic with groups that are not joined by the Pods on the local Node


busy networks with lots of unresolved
multicast routing entries, the creation of new multicast group routes
can be extremely slow and unreliable.

Here, routing entries are on the K8s Nodes, or some underlay switch/router? In any case, I feel no need to mention this one. It is a general issue with multicast. Listing it here without enough context can be misleading.

Updated.I mean on the k8s Nodes. Remove this line.

jianjuns · 2022-11-01T21:25:11Z

docs/multicast-guide.md

+
+### Encap mode
+
+Multicast traffic from Pods to external hosts is not supported in encap mode.


@wenyingd : please provide a correct description in your mind.

jianjuns

LGTM.

Two more nits.

jianjuns · 2022-11-03T19:06:38Z

docs/multicast-guide.md

+### Encap mode
+
+Configuration `multicastInterfaces` is not supported with encap mode.
+Multicast packets in encap mode are SNATed and forwarded to transport interface only.


to the transport interface

jianjuns · 2022-11-03T19:06:46Z

docs/multicast-guide.md

+
+### Encap mode
+
+Configuration `multicastInterfaces` is not supported with encap mode.


Configuration option

ceclinux · 2022-11-06T09:29:52Z

I tested and changed the vlc command in the example a bit

Give the specific url of the video to avoid possible encoding/decoding problems for the user-provided sample video. The video is in public domain, which should be free to be used.https://commons.wikimedia.org/wiki/File:Bees_on_flowers.webm
full command is not needed. Only params need to passed. https://github.com/galexrt/container-vlc

tnqn · 2022-11-25T13:54:23Z

docs/antctl.md

+antctl get podmulticaststats
+


Prepend $ to command to differentiate command and output like other examples:

Suggested change

antctl get podmulticaststats

$ antctl get podmulticaststats

docs/feature-gates.md

tnqn · 2022-11-25T14:06:31Z

docs/multicast-guide.md

+Example output of the command:
+
+```bash
+kubectl get multicastgroups


Suggested change

kubectl get multicastgroups

$ kubectl get multicastgroups

tnqn · 2022-11-25T14:12:05Z

docs/multicast-guide.md

+
+```bash
+ip mroute
+(pod-ip, 239.255.12.42)     Iif: antrea-gw0 Oifs: transport interfaces State: resolved


Suggested change

(pod-ip, 239.255.12.42) Iif: antrea-gw0 Oifs: transport interfaces State: resolved

(<POD IP>, 239.255.12.42) Iif: antrea-gw0 Oifs: <TRANSPORT INTERFACES> State: resolved

tnqn · 2022-11-25T14:12:24Z

docs/multicast-guide.md

+the Antrea gateway interface to the transport interface.
+
+```bash
+ip mroute


Suggested change

ip mroute

$ ip mroute

tnqn · 2022-11-25T14:18:33Z

docs/multicast-guide.md

+### Traffic in local network control block
+
+Multicast IPs in [Local Network Control Block](https://www.iana.org/assignments/multicast-addresses/multicast-addresses.xhtml#multicast-addresses-1) (224.0.0.0/24)
+should work only in Antrea encap mode. Multicast traffic destined for those addresses


should work only in Antrea encap mode? I feel it's "can only work in encap mode". @jianjuns

I don't understand your point here. Could you explain more?

Basically we has tested some simple cases for MDNS(224.0.0.251) and it works as expected in encap mode. The other multicast service running in 224.0.0.0/24 are not tested comprehensively, therefore may not work as expected.

@tnqn means changing "should" to "can". I agree "can" sounds better here.

updated. Thanks

Signed-off-by: ceclinux <src655@gmail.com>

tnqn

LGTM

tnqn · 2022-12-06T03:38:57Z

/skip-all

Signed-off-by: ceclinux <src655@gmail.com>

ceclinux force-pushed the multicast_docs branch from a3ece2e to 83a7665 Compare October 26, 2022 07:24

luolanzone reviewed Oct 26, 2022

View reviewed changes

luolanzone requested review from wenyingd and jianjuns October 26, 2022 08:39

jianjuns reviewed Oct 27, 2022

View reviewed changes

ceclinux force-pushed the multicast_docs branch 2 times, most recently from 942b96a to e7ce5f9 Compare October 27, 2022 06:38

jianjuns reviewed Oct 27, 2022

View reviewed changes

ceclinux force-pushed the multicast_docs branch 4 times, most recently from cae1411 to a34661d Compare November 1, 2022 08:53

wenyingd reviewed Nov 1, 2022

View reviewed changes

jianjuns reviewed Nov 1, 2022

View reviewed changes

ceclinux force-pushed the multicast_docs branch 3 times, most recently from 17deb8b to 8912a71 Compare November 3, 2022 07:20

jianjuns reviewed Nov 3, 2022

View reviewed changes

ceclinux force-pushed the multicast_docs branch from 8912a71 to 4cf0c3b Compare November 6, 2022 09:08

jianjuns previously approved these changes Nov 7, 2022

View reviewed changes

tnqn reviewed Nov 25, 2022

View reviewed changes

ceclinux dismissed jianjuns’s stale review via 9f5d704 December 6, 2022 00:06

ceclinux force-pushed the multicast_docs branch from 4cf0c3b to 9f5d704 Compare December 6, 2022 00:06

add multicast documents

47c1353

Signed-off-by: ceclinux <src655@gmail.com>

ceclinux force-pushed the multicast_docs branch from 9f5d704 to 47c1353 Compare December 6, 2022 00:12

tnqn approved these changes Dec 6, 2022

View reviewed changes

tnqn added this to the Antrea v1.10 release milestone Dec 6, 2022

tnqn added the kind/documentation Categorizes issue or PR as related to a documentation. label Dec 6, 2022

tnqn merged commit b0e9636 into antrea-io:main Dec 6, 2022

GraysonWu pushed a commit to GraysonWu/antrea that referenced this pull request Jan 27, 2023

add multicast documents (antrea-io#4339)

3aaa32f

Signed-off-by: ceclinux <src655@gmail.com>

	Multicast ingress rules are currently not supported.
	Note: multicast ingress rules are currently not supported.


		## Debugging and Collecting Multicast Statistics

		Users could use these tools to get the current status of the multicast application running in the cluster.

	Users could use these tools to get the current status of the multicast application running in the cluster.
	Users could check following guides and corresponding tools to get the current status of the multicast application running in the cluster.

	3. Lots of multicast traffic with group IPs that won't be received by the Node(not Pod has not joined that group in that Node)
	3. Lots of multicast traffic with group IPs that won't be received by the Node (not Pod has not joined that group in that Node)


		### Multicast commands

		The `antctl get podmulticaststats [NAME] [-n NAMESPACE]` command can print inbound and outbound multicast statistics for each Pod. Note that IGMP packets are not counted.


		## Prerequisites

		`Multicast` is introduced in v1.5 as an alpha feature. The feature gate


		### Encap mode

		In encap mode, multicast packets sent from Pod cannot be forwarded to more than one


		## Use case example

		[VLC](https://www.videolan.org/vlc/) is an open source multimedia player, it can be used for video streaming.


		### Encap mode

		Multicast traffic from Pods to external hosts is not supported in encap mode.


		### Multicast NetworkPolicy statistics

		[The Antrea NetworkPolicyStats feature](feature-gates.md#networkpolicystats) also applies to multicast NetworkPolices.


		### Encap mode

		Configuration `multicastInterfaces` is not supported with encap mode.

	(pod-ip, 239.255.12.42) Iif: antrea-gw0 Oifs: transport interfaces State: resolved
	(<POD IP>, 239.255.12.42) Iif: antrea-gw0 Oifs: <TRANSPORT INTERFACES> State: resolved

Add multicast documents #4339

Add multicast documents #4339

Conversation

ceclinux commented Oct 26, 2022

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ceclinux Nov 3, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

jianjuns left a comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

ceclinux commented Nov 6, 2022 • edited Loading

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

Choose a reason for hiding this comment

tnqn left a comment

Choose a reason for hiding this comment

tnqn commented Dec 6, 2022

ceclinux Nov 3, 2022 •

edited

Loading

ceclinux commented Nov 6, 2022 •

edited

Loading