Improve kube-proxy config / CLI documentation

cmd/kube-proxy/app/server.go

@@ -143,12 +143,11 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) {
 	fs.StringVar(&o.ConfigFile, "config", o.ConfigFile, "The path to the configuration file.")
 	fs.StringVar(&o.WriteConfigTo, "write-config-to", o.WriteConfigTo, "If set, write the default configuration values to this file and exit.")
 	fs.StringVar(&o.config.ClientConnection.Kubeconfig, "kubeconfig", o.config.ClientConnection.Kubeconfig, "Path to kubeconfig file with authorization information (the master location can be overridden by the master flag).")
-	fs.StringVar(&o.config.ClusterCIDR, "cluster-cidr", o.config.ClusterCIDR, "The CIDR range of pods in the cluster. When configured, traffic sent to a Service cluster IP from outside this range will be masqueraded and traffic sent from pods to an external LoadBalancer IP will be directed to the respective cluster IP instead. "+
+	fs.StringVar(&o.config.ClusterCIDR, "cluster-cidr", o.config.ClusterCIDR, "The CIDR range of the pods in the cluster. (For dual-stack clusters, this can be a comma-separated dual-stack pair of CIDR ranges.). When --detect-local-mode is set to ClusterCIDR, kube-proxy will consider traffic to be local if its source IP is in this range. (Otherwise it is not used.) "+
-		"For dual-stack clusters, a comma-separated list is accepted with at least one CIDR per IP family (IPv4 and IPv6). "+
 		"This parameter is ignored if a config file is specified by --config.")
 	fs.StringVar(&o.config.ClientConnection.ContentType, "kube-api-content-type", o.config.ClientConnection.ContentType, "Content type of requests sent to apiserver.")
 	fs.StringVar(&o.master, "master", o.master, "The address of the Kubernetes API server (overrides any value in kubeconfig)")
-	fs.StringVar(&o.hostnameOverride, "hostname-override", o.hostnameOverride, "If non-empty, will use this string as identification instead of the actual hostname.")
+	fs.StringVar(&o.hostnameOverride, "hostname-override", o.hostnameOverride, "If non-empty, will be used as the name of the Node that kube-proxy is running on. If unset, the node name is assumed to be the same as the node's hostname.")
 	fs.StringVar(&o.config.IPVS.Scheduler, "ipvs-scheduler", o.config.IPVS.Scheduler, "The ipvs scheduler type when proxy mode is ipvs")
 	fs.StringVar(&o.config.ShowHiddenMetricsForVersion, "show-hidden-metrics-for-version", o.config.ShowHiddenMetricsForVersion,
 		"The previous version for which you want to show hidden metrics. "+
@@ -158,17 +157,17 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) {
 			"rather than being surprised when they are permanently removed in the release after that. "+
 			"This parameter is ignored if a config file is specified by --config.")
 
-	fs.StringSliceVar(&o.config.IPVS.ExcludeCIDRs, "ipvs-exclude-cidrs", o.config.IPVS.ExcludeCIDRs, "A comma-separated list of CIDR's which the ipvs proxier should not touch when cleaning up IPVS rules.")
+	fs.StringSliceVar(&o.config.IPVS.ExcludeCIDRs, "ipvs-exclude-cidrs", o.config.IPVS.ExcludeCIDRs, "A comma-separated list of CIDRs which the ipvs proxier should not touch when cleaning up IPVS rules.")
 	fs.StringSliceVar(&o.config.NodePortAddresses, "nodeport-addresses", o.config.NodePortAddresses,
-		"A string slice of values which specify the addresses to use for NodePorts. Values may be valid IP blocks (e.g. 1.2.3.0/24, 1.2.3.4/32). The default empty string slice ([]) means to use all local addresses. This parameter is ignored if a config file is specified by --config.")
+		"A list of CIDR ranges that contain valid node IPs. If set, connections to NodePort services will only be accepted on node IPs in one of the indicated ranges. If unset, NodePort connections will be accepted on all local IPs. This parameter is ignored if a config file is specified by --config.")
 
 	fs.BoolVar(&o.CleanupAndExit, "cleanup", o.CleanupAndExit, "If true cleanup iptables and ipvs rules and exit.")
 
-	fs.Var(&utilflag.IPVar{Val: &o.config.BindAddress}, "bind-address", "The IP address for the proxy server to serve on (set to '0.0.0.0' for all IPv4 interfaces and '::' for all IPv6 interfaces). This parameter is ignored if a config file is specified by --config.")
+	fs.Var(&utilflag.IPVar{Val: &o.config.BindAddress}, "bind-address", "Overrides kube-proxy's idea of what its node's primary IP is. Note that the name is a historical artifact, and kube-proxy does not actually bind any sockets to this IP. This parameter is ignored if a config file is specified by --config.")
-	fs.Var(&utilflag.IPPortVar{Val: &o.config.HealthzBindAddress}, "healthz-bind-address", "The IP address with port for the health check server to serve on (set to '0.0.0.0:10256' for all IPv4 interfaces and '[::]:10256' for all IPv6 interfaces). Set empty to disable. This parameter is ignored if a config file is specified by --config.")
+	fs.Var(&utilflag.IPPortVar{Val: &o.config.HealthzBindAddress}, "healthz-bind-address", "The IP address and port for the health check server to serve on, defaulting to \"0.0.0.0:10256\" (if --bind-address is unset or IPv4), or \"[::]:10256\" (if --bind-address is IPv6). Set empty to disable. This parameter is ignored if a config file is specified by --config.")
-	fs.Var(&utilflag.IPPortVar{Val: &o.config.MetricsBindAddress}, "metrics-bind-address", "The IP address with port for the metrics server to serve on (set to '0.0.0.0:10249' for all IPv4 interfaces and '[::]:10249' for all IPv6 interfaces). Set empty to disable. This parameter is ignored if a config file is specified by --config.")
+	fs.Var(&utilflag.IPPortVar{Val: &o.config.MetricsBindAddress}, "metrics-bind-address", "The IP address and port for the metrics server to serve on, defaulting to \"127.0.0.1:10249\" (if --bind-address is unset or IPv4), or \"[::1]:10249\" (if --bind-address is IPv6). (Set to \"0.0.0.0:10249\" / \"[::]:10249\" to bind on all interfaces.) Set empty to disable. This parameter is ignored if a config file is specified by --config.")
 	fs.BoolVar(&o.config.BindAddressHardFail, "bind-address-hard-fail", o.config.BindAddressHardFail, "If true kube-proxy will treat failure to bind to a port as fatal and exit")
-	fs.Var(utilflag.PortRangeVar{Val: &o.config.PortRange}, "proxy-port-range", "Range of host ports (beginPort-endPort, single port or beginPort+offset, inclusive) that may be consumed in order to proxy service traffic. If (unspecified, 0, or 0-0) then ports will be randomly chosen.")
+	fs.Var(utilflag.PortRangeVar{Val: &o.config.PortRange}, "proxy-port-range", "This was previously used to configure the userspace proxy, but is now unused.")
 	fs.Var(&o.config.Mode, "proxy-mode", "Which proxy mode to use: on Linux this can be 'iptables' (default) or 'ipvs'. On Windows the only supported value is 'kernelspace'."+
 		"This parameter is ignored if a config file is specified by --config.")
 	fs.Var(cliflag.NewMapStringBool(&o.config.FeatureGates), "feature-gates", "A set of key=value pairs that describe feature gates for alpha/experimental features. "+
@@ -180,17 +179,17 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) {
 	fs.Int32Var(&o.metricsPort, "metrics-port", o.metricsPort, "The port to bind the metrics server. Use 0 to disable.")
 	fs.MarkDeprecated("metrics-port", "This flag is deprecated and will be removed in a future release. Please use --metrics-bind-address instead.")
 	fs.Int32Var(o.config.OOMScoreAdj, "oom-score-adj", ptr.Deref(o.config.OOMScoreAdj, int32(qos.KubeProxyOOMScoreAdj)), "The oom-score-adj value for kube-proxy process. Values must be within the range [-1000, 1000]. This parameter is ignored if a config file is specified by --config.")
-	fs.Int32Var(o.config.IPTables.MasqueradeBit, "iptables-masquerade-bit", ptr.Deref(o.config.IPTables.MasqueradeBit, 14), "If using the pure iptables proxy, the bit of the fwmark space to mark packets requiring SNAT with.  Must be within the range [0, 31].")
+	fs.Int32Var(o.config.IPTables.MasqueradeBit, "iptables-masquerade-bit", ptr.Deref(o.config.IPTables.MasqueradeBit, 14), "If using the iptables or ipvs proxy mode, the bit of the fwmark space to mark packets requiring SNAT with.  Must be within the range [0, 31].")
 	fs.Int32Var(o.config.Conntrack.MaxPerCore, "conntrack-max-per-core", *o.config.Conntrack.MaxPerCore,
 		"Maximum number of NAT connections to track per CPU core (0 to leave the limit as-is and ignore conntrack-min).")
 	fs.Int32Var(o.config.Conntrack.Min, "conntrack-min", *o.config.Conntrack.Min,
 		"Minimum number of conntrack entries to allocate, regardless of conntrack-max-per-core (set conntrack-max-per-core=0 to leave the limit as-is).")
 	fs.Int32Var(&o.config.ClientConnection.Burst, "kube-api-burst", o.config.ClientConnection.Burst, "Burst to use while talking with kubernetes apiserver")
 
-	fs.DurationVar(&o.config.IPTables.SyncPeriod.Duration, "iptables-sync-period", o.config.IPTables.SyncPeriod.Duration, "The maximum interval of how often iptables rules are refreshed (e.g. '5s', '1m', '2h22m').  Must be greater than 0.")
+	fs.DurationVar(&o.config.IPTables.SyncPeriod.Duration, "iptables-sync-period", o.config.IPTables.SyncPeriod.Duration, "An interval (e.g. '5s', '1m', '2h22m') indicating how frequently various re-synchronizing and cleanup operations are performed. Must be greater than 0.")
-	fs.DurationVar(&o.config.IPTables.MinSyncPeriod.Duration, "iptables-min-sync-period", o.config.IPTables.MinSyncPeriod.Duration, "The minimum interval of how often the iptables rules can be refreshed as endpoints and services change (e.g. '5s', '1m', '2h22m').")
+	fs.DurationVar(&o.config.IPTables.MinSyncPeriod.Duration, "iptables-min-sync-period", o.config.IPTables.MinSyncPeriod.Duration, "The minimum period between iptables rule resyncs (e.g. '5s', '1m', '2h22m'). A value of 0 means every Service or EndpointSlice change will result in an immediate iptables resync.")
-	fs.DurationVar(&o.config.IPVS.SyncPeriod.Duration, "ipvs-sync-period", o.config.IPVS.SyncPeriod.Duration, "The maximum interval of how often ipvs rules are refreshed (e.g. '5s', '1m', '2h22m').  Must be greater than 0.")
+	fs.DurationVar(&o.config.IPVS.SyncPeriod.Duration, "ipvs-sync-period", o.config.IPVS.SyncPeriod.Duration, "An interval (e.g. '5s', '1m', '2h22m') indicating how frequently various re-synchronizing and cleanup operations are performed. Must be greater than 0.")
-	fs.DurationVar(&o.config.IPVS.MinSyncPeriod.Duration, "ipvs-min-sync-period", o.config.IPVS.MinSyncPeriod.Duration, "The minimum interval of how often the ipvs rules can be refreshed as endpoints and services change (e.g. '5s', '1m', '2h22m').")
+	fs.DurationVar(&o.config.IPVS.MinSyncPeriod.Duration, "ipvs-min-sync-period", o.config.IPVS.MinSyncPeriod.Duration, "The minimum period between IPVS rule resyncs (e.g. '5s', '1m', '2h22m'). A value of 0 means every Service or EndpointSlice change will result in an immediate IPVS resync.")
 	fs.DurationVar(&o.config.IPVS.TCPTimeout.Duration, "ipvs-tcp-timeout", o.config.IPVS.TCPTimeout.Duration, "The timeout for idle IPVS TCP connections, 0 to leave as-is. (e.g. '5s', '1m', '2h22m').")
 	fs.DurationVar(&o.config.IPVS.TCPFinTimeout.Duration, "ipvs-tcpfin-timeout", o.config.IPVS.TCPFinTimeout.Duration, "The timeout for IPVS TCP connections after receiving a FIN packet, 0 to leave as-is. (e.g. '5s', '1m', '2h22m').")
 	fs.DurationVar(&o.config.IPVS.UDPTimeout.Duration, "ipvs-udp-timeout", o.config.IPVS.UDPTimeout.Duration, "The timeout for IPVS UDP packets, 0 to leave as-is. (e.g. '5s', '1m', '2h22m').")
@@ -202,14 +201,14 @@ func (o *Options) AddFlags(fs *pflag.FlagSet) {
 	fs.DurationVar(&o.config.ConfigSyncPeriod.Duration, "config-sync-period", o.config.ConfigSyncPeriod.Duration, "How often configuration from the apiserver is refreshed.  Must be greater than 0.")
 
 	fs.BoolVar(&o.config.IPVS.StrictARP, "ipvs-strict-arp", o.config.IPVS.StrictARP, "Enable strict ARP by setting arp_ignore to 1 and arp_announce to 2")
-	fs.BoolVar(&o.config.IPTables.MasqueradeAll, "masquerade-all", o.config.IPTables.MasqueradeAll, "If using the pure iptables proxy, SNAT all traffic sent via Service cluster IPs (this not commonly needed)")
+	fs.BoolVar(&o.config.IPTables.MasqueradeAll, "masquerade-all", o.config.IPTables.MasqueradeAll, "If using the iptables or ipvs proxy mode, SNAT all traffic sent via Service cluster IPs. This may be required with some CNI plugins.")
-	fs.BoolVar(o.config.IPTables.LocalhostNodePorts, "iptables-localhost-nodeports", ptr.Deref(o.config.IPTables.LocalhostNodePorts, true), "If false Kube-proxy will disable the legacy behavior of allowing NodePort services to be accessed via localhost, This only applies to iptables mode and ipv4.")
+	fs.BoolVar(o.config.IPTables.LocalhostNodePorts, "iptables-localhost-nodeports", ptr.Deref(o.config.IPTables.LocalhostNodePorts, true), "If false, kube-proxy will disable the legacy behavior of allowing NodePort services to be accessed via localhost. (Applies only to iptables mode and IPv4; localhost NodePorts are never allowed with other proxy modes or with IPv6.)")
 	fs.BoolVar(&o.config.EnableProfiling, "profiling", o.config.EnableProfiling, "If true enables profiling via web interface on /debug/pprof handler. This parameter is ignored if a config file is specified by --config.")
 
 	fs.Float32Var(&o.config.ClientConnection.QPS, "kube-api-qps", o.config.ClientConnection.QPS, "QPS to use while talking with kubernetes apiserver")
 	fs.Var(&o.config.DetectLocalMode, "detect-local-mode", "Mode to use to detect local traffic. This parameter is ignored if a config file is specified by --config.")
-	fs.StringVar(&o.config.DetectLocal.BridgeInterface, "pod-bridge-interface", o.config.DetectLocal.BridgeInterface, "A bridge interface name in the cluster. Kube-proxy considers traffic as local if originating from an interface which matches the value. This argument should be set if DetectLocalMode is set to BridgeInterface.")
+	fs.StringVar(&o.config.DetectLocal.BridgeInterface, "pod-bridge-interface", o.config.DetectLocal.BridgeInterface, "A bridge interface name. When --detect-local-mode is set to BridgeInterface, kube-proxy will consider traffic to be local if it originates from this bridge.")
-	fs.StringVar(&o.config.DetectLocal.InterfaceNamePrefix, "pod-interface-name-prefix", o.config.DetectLocal.InterfaceNamePrefix, "An interface prefix in the cluster. Kube-proxy considers traffic as local if originating from interfaces that match the given prefix. This argument should be set if DetectLocalMode is set to InterfaceNamePrefix.")
+	fs.StringVar(&o.config.DetectLocal.InterfaceNamePrefix, "pod-interface-name-prefix", o.config.DetectLocal.InterfaceNamePrefix, "An interface name prefix. When --detect-local-mode is set to InterfaceNamePrefix, kube-proxy will consider traffic to be local if it originates from any interface whose name begins with this prefix.")
 	logsapi.AddFlags(&o.config.Logging, fs)
 }
 

pkg/proxy/apis/config/types.go

@@ -30,36 +30,44 @@ import (
 // details for the Kubernetes proxy server.
 type KubeProxyIPTablesConfiguration struct {
 	// masqueradeBit is the bit of the iptables fwmark space to use for SNAT if using
-	// the pure iptables proxy mode. Values must be within the range [0, 31].
+	// the iptables or ipvs proxy mode. Values must be within the range [0, 31].
 	MasqueradeBit *int32
-	// masqueradeAll tells kube-proxy to SNAT everything if using the pure iptables proxy mode.
+	// masqueradeAll tells kube-proxy to SNAT all traffic sent to Service cluster IPs,
+	// when using the iptables or ipvs proxy mode. This may be required with some CNI
+	// plugins.
 	MasqueradeAll bool
-	// LocalhostNodePorts tells kube-proxy to allow service NodePorts to be accessed via
+	// localhostNodePorts, if false, tells kube-proxy to disable the legacy behavior
-	// localhost (iptables mode only)
+	// of allowing NodePort services to be accessed via localhost. (Applies only to
+	// iptables mode and IPv4; localhost NodePorts are never allowed with other proxy
+	// modes or with IPv6.)
 	LocalhostNodePorts *bool
-	// syncPeriod is the period that iptables rules are refreshed (e.g. '5s', '1m',
+	// syncPeriod is an interval (e.g. '5s', '1m', '2h22m') indicating how frequently
-	// '2h22m').  Must be greater than 0.
+	// various re-synchronizing and cleanup operations are performed. Must be greater
+	// than 0.
 	SyncPeriod metav1.Duration
-	// minSyncPeriod is the minimum period that iptables rules are refreshed (e.g. '5s', '1m',
+	// minSyncPeriod is the minimum period between iptables rule resyncs (e.g. '5s',
-	// '2h22m').
+	// '1m', '2h22m'). A value of 0 means every Service or EndpointSlice change will
+	// result in an immediate iptables resync.
 	MinSyncPeriod metav1.Duration
 }
 
 // KubeProxyIPVSConfiguration contains ipvs-related configuration
 // details for the Kubernetes proxy server.
 type KubeProxyIPVSConfiguration struct {
-	// syncPeriod is the period that ipvs rules are refreshed (e.g. '5s', '1m',
+	// syncPeriod is an interval (e.g. '5s', '1m', '2h22m') indicating how frequently
-	// '2h22m').  Must be greater than 0.
+	// various re-synchronizing and cleanup operations are performed. Must be greater
+	// than 0.
 	SyncPeriod metav1.Duration
-	// minSyncPeriod is the minimum period that ipvs rules are refreshed (e.g. '5s', '1m',
+	// minSyncPeriod is the minimum period between IPVS rule resyncs (e.g. '5s', '1m',
-	// '2h22m').
+	// '2h22m'). A value of 0 means every Service or EndpointSlice change will result
+	// in an immediate IPVS resync.
 	MinSyncPeriod metav1.Duration
-	// ipvs scheduler
+	// scheduler is the IPVS scheduler to use
 	Scheduler string
-	// excludeCIDRs is a list of CIDR's which the ipvs proxier should not touch
+	// excludeCIDRs is a list of CIDRs which the ipvs proxier should not touch
 	// when cleaning up ipvs services.
 	ExcludeCIDRs []string
-	// strict ARP configure arp_ignore and arp_announce to avoid answering ARP queries
+	// strictARP configures arp_ignore and arp_announce to avoid answering ARP queries
 	// from kube-ipvs0 interface
 	StrictARP bool
 	// tcpTimeout is the timeout value used for idle IPVS TCP sessions.
@@ -103,23 +111,23 @@ type KubeProxyWinkernelConfiguration struct {
 	// enableDSR tells kube-proxy whether HNS policies should be created
 	// with DSR
 	EnableDSR bool
-	// RootHnsEndpointName is the name of hnsendpoint that is attached to
+	// rootHnsEndpointName is the name of hnsendpoint that is attached to
 	// l2bridge for root network namespace
 	RootHnsEndpointName string
-	// ForwardHealthCheckVip forwards service VIP for health check port on
+	// forwardHealthCheckVip forwards service VIP for health check port on
 	// Windows
 	ForwardHealthCheckVip bool
 }
 
 // DetectLocalConfiguration contains optional settings related to DetectLocalMode option
 type DetectLocalConfiguration struct {
-	// BridgeInterface is a string argument which represents a single bridge interface name.
+	// bridgeInterface is a bridge interface name. When DetectLocalMode is set to
-	// Kube-proxy considers traffic as local if originating from this given bridge.
+	// LocalModeBridgeInterface, kube-proxy will consider traffic to be local if
-	// This argument should be set if DetectLocalMode is set to BridgeInterface.
+	// it originates from this bridge.
 	BridgeInterface string
-	// InterfaceNamePrefix is a string argument which represents a single interface prefix name.
+	// interfaceNamePrefix is an interface name prefix. When DetectLocalMode is set to
-	// Kube-proxy considers traffic as local if originating from one or more interfaces which match
+	// LocalModeInterfaceNamePrefix, kube-proxy will consider traffic to be local if
-	// the given prefix. This argument should be set if DetectLocalMode is set to InterfaceNamePrefix.
+	// it originates from any interface whose name begins with this prefix.
 	InterfaceNamePrefix string
 }
 
@@ -133,25 +141,34 @@ type KubeProxyConfiguration struct {
 	// featureGates is a map of feature names to bools that enable or disable alpha/experimental features.
 	FeatureGates map[string]bool
 
-	// bindAddress is the IP address for the proxy server to serve on (set to 0.0.0.0
+	// bindAddress can be used to override kube-proxy's idea of what its node's
-	// for all interfaces)
+	// primary IP is. Note that the name is a historical artifact, and kube-proxy does
+	// not actually bind any sockets to this IP.
 	BindAddress string
-	// healthzBindAddress is the IP address and port for the health check server to serve on,
+	// healthzBindAddress is the IP address and port for the health check server to
-	// defaulting to 0.0.0.0:10256
+	// serve on, defaulting to "0.0.0.0:10256" (if bindAddress is unset or IPv4), or
+	// "[::]:10256" (if bindAddress is IPv6).
 	HealthzBindAddress string
-	// metricsBindAddress is the IP address and port for the metrics server to serve on,
+	// metricsBindAddress is the IP address and port for the metrics server to serve
-	// defaulting to 127.0.0.1:10249 (set to 0.0.0.0 for all interfaces)
+	// on, defaulting to "127.0.0.1:10249" (if bindAddress is unset or IPv4), or
+	// "[::1]:10249" (if bindAddress is IPv6). (Set to "0.0.0.0:10249" / "[::]:10249"
+	// to bind on all interfaces.)
 	MetricsBindAddress string
-	// BindAddressHardFail, if true, kube-proxy will treat failure to bind to a port as fatal and exit
+	// bindAddressHardFail, if true, tells kube-proxy to treat failure to bind to a
+	// port as fatal and exit
 	BindAddressHardFail bool
 	// enableProfiling enables profiling via web interface on /debug/pprof handler.
 	// Profiling handlers will be handled by metrics server.
 	EnableProfiling bool
-	// clusterCIDR is the CIDR range of the pods in the cluster. It is used to
+	// clusterCIDR is the CIDR range of the pods in the cluster. (For dual-stack
-	// bridge traffic coming from outside of the cluster. If not provided,
+	// clusters, this can be a comma-separated dual-stack pair of CIDR ranges.). When
-	// no off-cluster bridging will be performed.
+	// DetectLocalMode is set to LocalModeClusterCIDR, kube-proxy will consider
+	// traffic to be local if its source IP is in this range. (Otherwise it is not
+	// used.)
 	ClusterCIDR string
-	// hostnameOverride, if non-empty, will be used as the identity instead of the actual hostname.
+	// hostnameOverride, if non-empty, will be used as the name of the Node that
+	// kube-proxy is running on. If unset, the node name is assumed to be the same as
+	// the node's hostname.
 	HostnameOverride string
 	// clientConnection specifies the kubeconfig file and client connection settings for the proxy
 	// server to use when communicating with the apiserver.
@@ -165,32 +182,30 @@ type KubeProxyConfiguration struct {
 	OOMScoreAdj *int32
 	// mode specifies which proxy mode to use.
 	Mode ProxyMode
-	// portRange is the range of host ports (beginPort-endPort, inclusive) that may be consumed
+	// portRange was previously used to configure the userspace proxy, but is now unused.
-	// in order to proxy service traffic. If unspecified (0-0) then ports will be randomly chosen.
 	PortRange string
 	// conntrack contains conntrack-related configuration options.
 	Conntrack KubeProxyConntrackConfiguration
 	// configSyncPeriod is how often configuration from the apiserver is refreshed. Must be greater
 	// than 0.
 	ConfigSyncPeriod metav1.Duration
-	// nodePortAddresses is the --nodeport-addresses value for kube-proxy process. Values must be valid
+	// nodePortAddresses is a list of CIDR ranges that contain valid node IPs. If set,
-	// IP blocks. These values are as a parameter to select the interfaces where nodeport works.
+	// connections to NodePort services will only be accepted on node IPs in one of
-	// In case someone would like to expose a service on localhost for local visit and some other interfaces for
+	// the indicated ranges. If unset, NodePort connections will be accepted on all
-	// particular purpose, a list of IP blocks would do that.
+	// local IPs.
-	// If set it to "127.0.0.0/8", kube-proxy will only select the loopback interface for NodePort.
-	// If set it to a non-zero IP block, kube-proxy will filter that down to just the IPs that applied to the node.
-	// An empty string slice is meant to select all network interfaces.
 	NodePortAddresses []string
 	// winkernel contains winkernel-related configuration options.
 	Winkernel KubeProxyWinkernelConfiguration
-	// ShowHiddenMetricsForVersion is the version for which you want to show hidden metrics.
+	// showHiddenMetricsForVersion is the version for which you want to show hidden metrics.
 	ShowHiddenMetricsForVersion string
-	// DetectLocalMode determines mode to use for detecting local traffic, defaults to LocalModeClusterCIDR
+
+	// detectLocalMode determines mode to use for detecting local traffic, defaults to LocalModeClusterCIDR
 	DetectLocalMode LocalMode
-	// DetectLocal contains optional configuration settings related to DetectLocalMode.
+	// detectLocal contains optional configuration settings related to DetectLocalMode.
 	DetectLocal DetectLocalConfiguration
-	// Logging specifies the options of logging.
+	// logging specifies the options of logging.
-	// Refer to [Logs Options](https://github.com/kubernetes/component-base/blob/master/logs/options.go) for more information.
+	// Refer to [Logs Options](https://github.com/kubernetes/component-base/blob/master/logs/options.go)
+	// for more information.
 	Logging logsapi.LoggingConfiguration
 }
 

staging/src/k8s.io/kube-proxy/config/v1alpha1/types.go

@@ -26,36 +26,44 @@ import (
 // details for the Kubernetes proxy server.
 type KubeProxyIPTablesConfiguration struct {
 	// masqueradeBit is the bit of the iptables fwmark space to use for SNAT if using
-	// the pure iptables proxy mode. Values must be within the range [0, 31].
+	// the iptables or ipvs proxy mode. Values must be within the range [0, 31].
 	MasqueradeBit *int32 `json:"masqueradeBit"`
-	// masqueradeAll tells kube-proxy to SNAT everything if using the pure iptables proxy mode.
+	// masqueradeAll tells kube-proxy to SNAT all traffic sent to Service cluster IPs,
+	// when using the iptables or ipvs proxy mode. This may be required with some CNI
+	// plugins.
 	MasqueradeAll bool `json:"masqueradeAll"`
-	// LocalhostNodePorts tells kube-proxy to allow service NodePorts to be accessed via
+	// localhostNodePorts, if false, tells kube-proxy to disable the legacy behavior
-	// localhost (iptables mode only)
+	// of allowing NodePort services to be accessed via localhost. (Applies only to
+	// iptables mode and IPv4; localhost NodePorts are never allowed with other proxy
+	// modes or with IPv6.)
 	LocalhostNodePorts *bool `json:"localhostNodePorts"`
-	// syncPeriod is the period that iptables rules are refreshed (e.g. '5s', '1m',
+	// syncPeriod is an interval (e.g. '5s', '1m', '2h22m') indicating how frequently
-	// '2h22m').  Must be greater than 0.
+	// various re-synchronizing and cleanup operations are performed. Must be greater
+	// than 0.
 	SyncPeriod metav1.Duration `json:"syncPeriod"`
-	// minSyncPeriod is the minimum period that iptables rules are refreshed (e.g. '5s', '1m',
+	// minSyncPeriod is the minimum period between iptables rule resyncs (e.g. '5s',
-	// '2h22m').
+	// '1m', '2h22m'). A value of 0 means every Service or EndpointSlice change will
+	// result in an immediate iptables resync.
 	MinSyncPeriod metav1.Duration `json:"minSyncPeriod"`
 }
 
 // KubeProxyIPVSConfiguration contains ipvs-related configuration
 // details for the Kubernetes proxy server.
 type KubeProxyIPVSConfiguration struct {
-	// syncPeriod is the period that ipvs rules are refreshed (e.g. '5s', '1m',
+	// syncPeriod is an interval (e.g. '5s', '1m', '2h22m') indicating how frequently
-	// '2h22m').  Must be greater than 0.
+	// various re-synchronizing and cleanup operations are performed. Must be greater
+	// than 0.
 	SyncPeriod metav1.Duration `json:"syncPeriod"`
-	// minSyncPeriod is the minimum period that ipvs rules are refreshed (e.g. '5s', '1m',
+	// minSyncPeriod is the minimum period between IPVS rule resyncs (e.g. '5s', '1m',
-	// '2h22m').
+	// '2h22m'). A value of 0 means every Service or EndpointSlice change will result
+	// in an immediate IPVS resync.
 	MinSyncPeriod metav1.Duration `json:"minSyncPeriod"`
-	// ipvs scheduler
+	// scheduler is the IPVS scheduler to use
 	Scheduler string `json:"scheduler"`
-	// excludeCIDRs is a list of CIDR's which the ipvs proxier should not touch
+	// excludeCIDRs is a list of CIDRs which the ipvs proxier should not touch
 	// when cleaning up ipvs services.
 	ExcludeCIDRs []string `json:"excludeCIDRs"`
-	// strict ARP configure arp_ignore and arp_announce to avoid answering ARP queries
+	// strictARP configures arp_ignore and arp_announce to avoid answering ARP queries
 	// from kube-ipvs0 interface
 	StrictARP bool `json:"strictARP"`
 	// tcpTimeout is the timeout value used for idle IPVS TCP sessions.
@@ -76,7 +84,7 @@ type KubeProxyConntrackConfiguration struct {
 	// per CPU core (0 to leave the limit as-is and ignore min).
 	MaxPerCore *int32 `json:"maxPerCore"`
 	// min is the minimum value of connect-tracking records to allocate,
-	// regardless of conntrackMaxPerCore (set maxPerCore=0 to leave the limit as-is).
+	// regardless of maxPerCore (set maxPerCore=0 to leave the limit as-is).
 	Min *int32 `json:"min"`
 	// tcpEstablishedTimeout is how long an idle TCP connection will be kept open
 	// (e.g. '2s').  Must be greater than 0 to set.
@@ -93,29 +101,29 @@ type KubeProxyWinkernelConfiguration struct {
 	// networkName is the name of the network kube-proxy will use
 	// to create endpoints and policies
 	NetworkName string `json:"networkName"`
-	// sourceVip is the IP address of the source VIP endoint used for
+	// sourceVip is the IP address of the source VIP endpoint used for
 	// NAT when loadbalancing
 	SourceVip string `json:"sourceVip"`
 	// enableDSR tells kube-proxy whether HNS policies should be created
 	// with DSR
 	EnableDSR bool `json:"enableDSR"`
-	// RootHnsEndpointName is the name of hnsendpoint that is attached to
+	// rootHnsEndpointName is the name of hnsendpoint that is attached to
 	// l2bridge for root network namespace
 	RootHnsEndpointName string `json:"rootHnsEndpointName"`
-	// ForwardHealthCheckVip forwards service VIP for health check port on
+	// forwardHealthCheckVip forwards service VIP for health check port on
 	// Windows
 	ForwardHealthCheckVip bool `json:"forwardHealthCheckVip"`
 }
 
 // DetectLocalConfiguration contains optional settings related to DetectLocalMode option
 type DetectLocalConfiguration struct {
-	// BridgeInterface is a string argument which represents a single bridge interface name.
+	// bridgeInterface is a bridge interface name. When DetectLocalMode is set to
-	// Kube-proxy considers traffic as local if originating from this given bridge.
+	// LocalModeBridgeInterface, kube-proxy will consider traffic to be local if
-	// This argument should be set if DetectLocalMode is set to LocalModeBridgeInterface.
+	// it originates from this bridge.
 	BridgeInterface string `json:"bridgeInterface"`
-	// InterfaceNamePrefix is a string argument which represents a single interface prefix name.
+	// interfaceNamePrefix is an interface name prefix. When DetectLocalMode is set to
-	// Kube-proxy considers traffic as local if originating from one or more interfaces which match
+	// LocalModeInterfaceNamePrefix, kube-proxy will consider traffic to be local if
-	// the given prefix. This argument should be set if DetectLocalMode is set to LocalModeInterfaceNamePrefix.
+	// it originates from any interface whose name begins with this prefix.
 	InterfaceNamePrefix string `json:"interfaceNamePrefix"`
 }
 
@@ -129,25 +137,34 @@ type KubeProxyConfiguration struct {
 	// featureGates is a map of feature names to bools that enable or disable alpha/experimental features.
 	FeatureGates map[string]bool `json:"featureGates,omitempty"`
 
-	// bindAddress is the IP address for the proxy server to serve on (set to 0.0.0.0
+	// bindAddress can be used to override kube-proxy's idea of what its node's
-	// for all interfaces)
+	// primary IP is. Note that the name is a historical artifact, and kube-proxy does
+	// not actually bind any sockets to this IP.
 	BindAddress string `json:"bindAddress"`
-	// healthzBindAddress is the IP address and port for the health check server to serve on,
+	// healthzBindAddress is the IP address and port for the health check server to
-	// defaulting to 0.0.0.0:10256
+	// serve on, defaulting to "0.0.0.0:10256" (if bindAddress is unset or IPv4), or
+	// "[::]:10256" (if bindAddress is IPv6).
 	HealthzBindAddress string `json:"healthzBindAddress"`
-	// metricsBindAddress is the IP address and port for the metrics server to serve on,
+	// metricsBindAddress is the IP address and port for the metrics server to serve
-	// defaulting to 127.0.0.1:10249 (set to 0.0.0.0 for all interfaces)
+	// on, defaulting to "127.0.0.1:10249" (if bindAddress is unset or IPv4), or
+	// "[::1]:10249" (if bindAddress is IPv6). (Set to "0.0.0.0:10249" / "[::]:10249"
+	// to bind on all interfaces.)
 	MetricsBindAddress string `json:"metricsBindAddress"`
-	// bindAddressHardFail, if true, kube-proxy will treat failure to bind to a port as fatal and exit
+	// bindAddressHardFail, if true, tells kube-proxy to treat failure to bind to a
+	// port as fatal and exit
 	BindAddressHardFail bool `json:"bindAddressHardFail"`
 	// enableProfiling enables profiling via web interface on /debug/pprof handler.
 	// Profiling handlers will be handled by metrics server.
 	EnableProfiling bool `json:"enableProfiling"`
-	// clusterCIDR is the CIDR range of the pods in the cluster. It is used to
+	// clusterCIDR is the CIDR range of the pods in the cluster. (For dual-stack
-	// bridge traffic coming from outside of the cluster. If not provided,
+	// clusters, this can be a comma-separated dual-stack pair of CIDR ranges.). When
-	// no off-cluster bridging will be performed.
+	// DetectLocalMode is set to LocalModeClusterCIDR, kube-proxy will consider
+	// traffic to be local if its source IP is in this range. (Otherwise it is not
+	// used.)
 	ClusterCIDR string `json:"clusterCIDR"`
-	// hostnameOverride, if non-empty, will be used as the identity instead of the actual hostname.
+	// hostnameOverride, if non-empty, will be used as the name of the Node that
+	// kube-proxy is running on. If unset, the node name is assumed to be the same as
+	// the node's hostname.
 	HostnameOverride string `json:"hostnameOverride"`
 	// clientConnection specifies the kubeconfig file and client connection settings for the proxy
 	// server to use when communicating with the apiserver.
@@ -161,29 +178,26 @@ type KubeProxyConfiguration struct {
 	OOMScoreAdj *int32 `json:"oomScoreAdj"`
 	// mode specifies which proxy mode to use.
 	Mode ProxyMode `json:"mode"`
-	// portRange is the range of host ports (beginPort-endPort, inclusive) that may be consumed
+	// portRange was previously used to configure the userspace proxy, but is now unused.
-	// in order to proxy service traffic. If unspecified (0-0) then ports will be randomly chosen.
 	PortRange string `json:"portRange"`
 	// conntrack contains conntrack-related configuration options.
 	Conntrack KubeProxyConntrackConfiguration `json:"conntrack"`
 	// configSyncPeriod is how often configuration from the apiserver is refreshed. Must be greater
 	// than 0.
 	ConfigSyncPeriod metav1.Duration `json:"configSyncPeriod"`
-	// nodePortAddresses is the --nodeport-addresses value for kube-proxy process. Values must be valid
+	// nodePortAddresses is a list of CIDR ranges that contain valid node IPs. If set,
-	// IP blocks. These values are as a parameter to select the interfaces where nodeport works.
+	// connections to NodePort services will only be accepted on node IPs in one of
-	// In case someone would like to expose a service on localhost for local visit and some other interfaces for
+	// the indicated ranges. If unset, NodePort connections will be accepted on all
-	// particular purpose, a list of IP blocks would do that.
+	// local IPs.
-	// If set it to "127.0.0.0/8", kube-proxy will only select the loopback interface for NodePort.
-	// If set it to a non-zero IP block, kube-proxy will filter that down to just the IPs that applied to the node.
-	// An empty string slice is meant to select all network interfaces.
 	NodePortAddresses []string `json:"nodePortAddresses"`
 	// winkernel contains winkernel-related configuration options.
 	Winkernel KubeProxyWinkernelConfiguration `json:"winkernel"`
-	// ShowHiddenMetricsForVersion is the version for which you want to show hidden metrics.
+	// showHiddenMetricsForVersion is the version for which you want to show hidden metrics.
 	ShowHiddenMetricsForVersion string `json:"showHiddenMetricsForVersion"`
-	// DetectLocalMode determines mode to use for detecting local traffic, defaults to LocalModeClusterCIDR
+
+	// detectLocalMode determines mode to use for detecting local traffic, defaults to LocalModeClusterCIDR
 	DetectLocalMode LocalMode `json:"detectLocalMode"`
-	// DetectLocal contains optional configuration settings related to DetectLocalMode.
+	// detectLocal contains optional configuration settings related to DetectLocalMode.
 	DetectLocal DetectLocalConfiguration `json:"detectLocal"`
 	// logging specifies the options of logging.
 	// Refer to [Logs Options](https://github.com/kubernetes/component-base/blob/master/logs/options.go)