Add documentation for secondary network IPAM #3634

jianjuns · 2022-04-13T16:36:35Z

Add a document for secondary network IPAM, and add the Antrea IPAM
option to the Multus cookbook.

Signed-off-by: Jianjun Shen shenj@vmware.com

codecov-commenter · 2022-04-13T16:45:09Z

Codecov Report

Merging #3634 (393740c) into main (ce0de59) will decrease coverage by 0.40%.
The diff coverage is n/a.

@@            Coverage Diff             @@
##             main    #3634      +/-   ##
==========================================
- Coverage   63.94%   63.54%   -0.41%     
==========================================
  Files         278      278              
  Lines       27838    39360   +11522     
==========================================
+ Hits        17802    25010    +7208     
- Misses       8110    12420    +4310     
- Partials     1926     1930       +4

Flag	Coverage Δ
kind-e2e-tests	`50.68% <ø> (-0.30%)`	⬇️
unit-tests	`43.83% <ø> (+0.47%)`	⬆️

Flags with carried forward coverage won't be shown. Click here to find out more.

Impacted Files	Coverage Δ
pkg/features/antrea_features.go	`11.11% <ø> (+2.02%)`	⬆️
...g/agent/apiserver/handlers/featuregates/handler.go	`4.54% <0.00%> (-77.81%)`	⬇️
...kg/apiserver/registry/system/supportbundle/rest.go	`22.17% <0.00%> (-52.83%)`	⬇️
pkg/support/dump.go	`7.90% <0.00%> (-49.47%)`	⬇️
pkg/support/dump_others.go	`0.00% <0.00%> (-44.00%)`	⬇️
...egator/apiserver/handlers/recordmetrics/handler.go	`4.00% <0.00%> (-40.45%)`	⬇️
pkg/agent/cniserver/pod_configuration_linux.go	`26.31% <0.00%> (-40.36%)`	⬇️
...gregator/apiserver/handlers/flowrecords/handler.go	`1.44% <0.00%> (-38.56%)`	⬇️
...g/agent/apiserver/handlers/addressgroup/handler.go	`5.00% <0.00%> (-35.00%)`	⬇️
...agent/apiserver/handlers/appliedtogroup/handler.go	`5.00% <0.00%> (-35.00%)`	⬇️
... and 269 more

antoninbas · 2022-04-13T18:41:31Z

build/yamls/base/conf/antrea-agent.conf

+# bridging mode and allocates IPs to Pods in bridging mode. It is also required by secondary network
+# network IPAM.


It is also required by secondary network IPAM

If I interpret this correctly, we should stop shipping the Whereabouts binary altogether in the Antrea Docker image, as AntreaIPAM is the only supported option now?

The current implementation supports only Multus managed network, not Antrea native secondary network. I plan to wait for the SR-IOV CI ready to add Antrea IPAM support for native secondary network.

build/yamls/base/conf/antrea-agent.conf

build/yamls/base/conf/antrea-controller.conf

docs/cookbooks/multus/README.md

antoninbas · 2022-04-13T18:48:59Z

docs/secondary-network-ipam.md

+With the [AntreaIPM feature](antrea-ipam.md#antrea-flexible-ipam), Antrea can
+allocate IPs for Pod secondary networks. At the moment, AntreaIPAM supports
+secondary networks managed by [Multus](https://github.com/k8snetworkplumbingwg/multus-cni),
+we will add support for secondary networks managed by Antrea in future.


I may be missing something, but that seems in direct contradiction with what you added to the config comments:

It is also required by secondary network IPAM

I feel like it is quite confusing to use the "secondary network" terminology in both cases, as this is the name of the Antrea feature.

What is your suggestion then? But at least when we finally support IPAM for Antrea native secondary network, then it will not be problem any more?

I guess most of my confusion comes from the "It is also required by secondary network IPAM." statement in other places. That doesn't seem to apply to either case:

For the Multus case, any IPAM solution can be used, so AntreaIPAM is not required

For the Antrea SecondaryNetwork feature, only Whereabouts is supported at the moment

I think I see what you are trying to say, but maybe something like this would help clarify (in config comments):

To use Antrea for IPAM when configuring secondary network interfaces with Multus, this feature gate needs to be enabled.

For this documentation, the current version sounds good to me. In the last sentence I would just add a reference to the Antrea feature name (SecondaryNetwork) for clarification.

BTW, I am not sure why we need a new document and cannot place this information in https://github.com/antrea-io/antrea/blob/main/docs/antrea-ipam.md?

Ok. Let me rephrase the comments on feature gate. I can merge the doc to antrea-ipam.md as well. Earlier thought secondary network IPAM is not interested by most people, so created a separate doc.

antoninbas · 2022-04-13T19:59:16Z

docs/secondary-network-ipam.md

+With the [AntreaIPM feature](antrea-ipam.md#antrea-flexible-ipam), Antrea can
+allocate IPs for Pod secondary networks. At the moment, AntreaIPAM supports
+secondary networks managed by [Multus](https://github.com/k8snetworkplumbingwg/multus-cni),
+we will add support for secondary networks managed by Antrea in future.


I guess most of my confusion comes from the "It is also required by secondary network IPAM." statement in other places. That doesn't seem to apply to either case:

For the Multus case, any IPAM solution can be used, so AntreaIPAM is not required

For the Antrea SecondaryNetwork feature, only Whereabouts is supported at the moment

I think I see what you are trying to say, but maybe something like this would help clarify (in config comments):

To use Antrea for IPAM when configuring secondary network interfaces with Multus, this feature gate needs to be enabled.

For this documentation, the current version sounds good to me. In the last sentence I would just add a reference to the Antrea feature name (SecondaryNetwork) for clarification.

BTW, I am not sure why we need a new document and cannot place this information in https://github.com/antrea-io/antrea/blob/main/docs/antrea-ipam.md?

docs/secondary-network-ipam.md

gran-vmv · 2022-04-14T01:37:31Z

build/yamls/base/conf/antrea-agent.conf

@@ -32,7 +32,10 @@ featureGates:
 #  Egress: true

 # Enable AntreaIPAM, which can allocate IP addresses from IPPools. AntreaIPAM is required by the
-# bridging mode and allocates IPs to Pods in bridging mode.
+# bridging mode and allocates IPs to Pods in bridging mode. It is also required to use Antrea for


Do you think that a new line for each case (bridgingMode and secondaryNetwork) is more clear?

I feel one paragraph is ok. I do not like short paragraphs.

gran-vmv · 2022-04-14T01:37:50Z

build/yamls/base/conf/antrea-controller.conf

-# Enable flexible IPAM mode for Antrea. This mode allows to assign IP Ranges to Namespaces,
-# Deployments and StatefulSets via IP Pool annotation.
+# Enable AntreaIPAM, which can allocate IP addresses from IPPools. AntreaIPAM is required by the
+# bridging mode and allocates IPs to Pods in bridging mode. It is also required to use Antrea for


antoninbas

some small comments, otherwise LGTM

antoninbas · 2022-04-14T20:12:07Z

docs/antrea-ipam.md

+With the AntreaIPAM feature, Antrea can allocate IPs for Pod secondary networks. At the
+moment, AntreaIPAM supports secondary networks managed by [Multus](https://github.com/k8snetworkplumbingwg/multus-cni),
+we will add support for [secondary networks managed by Antrea](feature-gates.md#secondarynetwork)
+in future.


in the future

antoninbas · 2022-04-14T20:12:48Z

docs/antrea-ipam.md

+
+To configure Antrea IPAM, `antrea` should be specified as the IPAM plugin in the
+the CNI IPAM configuration, and at least one Antrea IPPool should be specified
+in the `ippools` field. IPs will be allcoated from the specified IPPool(s) for


s/allcoated/allocated

antoninbas · 2022-04-14T20:16:35Z

docs/antrea-ipam.md

+Additionally, Antrea IPAM also supports configuration of static IP addresses,
+static routes, and DNS settings, as what are supported by the [static IPAM
+plugin](https://www.cni.dev/plugins/current/ipam/static). The following example


That sentence is not correct. Maybe you mean:

Additionally, Antrea IPAM also supports the same configuration of static IP addresses, static routes, and DNS settings as what is supported by the ...

antoninbas · 2022-04-14T20:17:31Z

docs/antrea-ipam.md

+
+## `IPPool` CRD
+
+Antrea IP pools are defined with `IPPool` CRD. The following two examples define


with the IPPool CRD

antoninbas · 2022-04-14T20:18:43Z

docs/feature-gates.md

+by the underlay network. For more information, please refer to the
+[Antrea IPAM document](antrea-ipam.md#antrea-flexible-ipam).
+
+This feature gate also needs to be enabled, to use Antrea for IPAM when


Suggested change

This feature gate also needs to be enabled, to use Antrea for IPAM when

This feature gate also needs to be enabled to use Antrea for IPAM when

antoninbas · 2022-04-14T20:18:52Z

docs/feature-gates.md

+[Antrea IPAM document](antrea-ipam.md#antrea-flexible-ipam).
+
+This feature gate also needs to be enabled, to use Antrea for IPAM when
+configuring secondary network interfaces with Multus, in which Antrea works


in which case

antoninbas · 2022-04-14T20:19:26Z

docs/feature-gates.md

-be included in the Namespace annotation. In the future, annotation of up to two pools for
-IPv4 and IPv6 respectively will be supported.
+The bridging mode works only with `system` OVS datapath type; and `noEncap`,
+`noSNAT` traffic mode. At this moment, it supports only IPv4. The IPs in an IP


At the moment

Add a document for secondary network IPAM, and add the Antrea IPAM option to the Multus cookbook. Signed-off-by: Jianjun Shen <shenj@vmware.com>

antoninbas

LGTM

jianjuns · 2022-04-14T22:25:10Z

/skip-all

jianjuns added area/ipam Issues or PRs related to IP address management (IPAM). kind/documentation Categorizes issue or PR as related to a documentation. labels Apr 13, 2022

jianjuns added this to the Antrea v1.7 release milestone Apr 13, 2022

jianjuns requested review from antoninbas, annakhm and gran-vmv April 13, 2022 16:36

jianjuns force-pushed the ipam-doc branch 2 times, most recently from 3892d55 to bdcf497 Compare April 13, 2022 17:43

antoninbas reviewed Apr 13, 2022

View reviewed changes

jianjuns force-pushed the ipam-doc branch 2 times, most recently from b7aeee5 to f4f6609 Compare April 13, 2022 19:01

antoninbas reviewed Apr 13, 2022

View reviewed changes

jianjuns force-pushed the ipam-doc branch 3 times, most recently from fa31969 to 98f1e98 Compare April 13, 2022 21:33

gran-vmv reviewed Apr 14, 2022

View reviewed changes

jianjuns force-pushed the ipam-doc branch 2 times, most recently from b140a2d to 3958eab Compare April 14, 2022 01:45

jianjuns mentioned this pull request Apr 14, 2022

Support static addresses in secondary network IPAM #3633

Merged

antoninbas reviewed Apr 14, 2022

View reviewed changes

Add documentation for secondary network IPAM

393740c

Add a document for secondary network IPAM, and add the Antrea IPAM option to the Multus cookbook. Signed-off-by: Jianjun Shen <shenj@vmware.com>

jianjuns force-pushed the ipam-doc branch 2 times, most recently from e20b5ef to 393740c Compare April 14, 2022 20:31

antoninbas approved these changes Apr 14, 2022

View reviewed changes

jianjuns merged commit 2ab80d0 into antrea-io:main Apr 14, 2022

Provide feedback

Saved searches

Use saved searches to filter your results more quickly

Add documentation for secondary network IPAM #3634

Add documentation for secondary network IPAM #3634

jianjuns commented Apr 13, 2022

codecov-commenter commented Apr 13, 2022 •

edited

Loading

antoninbas Apr 13, 2022

jianjuns Apr 13, 2022

antoninbas Apr 13, 2022

jianjuns Apr 13, 2022

antoninbas Apr 13, 2022

jianjuns Apr 13, 2022

jianjuns Apr 13, 2022

antoninbas Apr 13, 2022

gran-vmv Apr 14, 2022

jianjuns Apr 14, 2022

gran-vmv Apr 14, 2022

antoninbas left a comment

antoninbas Apr 14, 2022

jianjuns Apr 14, 2022

antoninbas Apr 14, 2022

jianjuns Apr 14, 2022

antoninbas Apr 14, 2022

jianjuns Apr 14, 2022

antoninbas Apr 14, 2022

jianjuns Apr 14, 2022

antoninbas Apr 14, 2022

jianjuns Apr 14, 2022

antoninbas Apr 14, 2022

jianjuns Apr 14, 2022

antoninbas Apr 14, 2022

jianjuns Apr 14, 2022

antoninbas left a comment

jianjuns commented Apr 14, 2022

		# bridging mode and allocates IPs to Pods in bridging mode. It is also required by secondary network
		# network IPAM.


		## `IPPool` CRD

		Antrea IP pools are defined with `IPPool` CRD. The following two examples define

	This feature gate also needs to be enabled, to use Antrea for IPAM when
	This feature gate also needs to be enabled to use Antrea for IPAM when

Add documentation for secondary network IPAM #3634

Add documentation for secondary network IPAM #3634

Conversation

jianjuns commented Apr 13, 2022

codecov-commenter commented Apr 13, 2022 • edited Loading

Codecov Report

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

antoninbas 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

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

antoninbas left a comment

Choose a reason for hiding this comment

jianjuns commented Apr 14, 2022

codecov-commenter commented Apr 13, 2022 •

edited

Loading