Add documentation for feature gates

Includes a quick description of each feature, links to appropriate
documentation, feature stage, etc.

Fixes antrea-io#892

docs/feature-gates.md

@@ -0,0 +1,83 @@
+# Antrea Feature Gates
+
+This page contains an overview of the various feature gates an administrator can
+specify for Antrea components. We follow the same convention as the [Kubernetes
+feature
+gates](https://kubernetes.io/docs/reference/command-line-tools-reference/feature-gates/).
+
+In particular:
+ * a feature in the Alpha stage will be disabled by default but can be enabled
+ by editing the appropriate `.conf` entry in the Antrea manifest.
+ * a feature in the Beta stage will be enabled by default but can be disabled
+ by editing the appropriate `.conf` entry in the Antrea manifest.
+ * a feature in the GA stage will be enabled by default and cannot be disabled.
+
+Some feature gates are specific to the Agent, others are specific to the
+Controller, and some apply to both and should be enabled / disabled consistently
+in both `.conf` entries.
+
+To enable / disable a feature, edit the Antrea manifest appropriately. For
+example, to enable `AntreaProxy` on Linux, edit the Agent configuration in the
+`antrea` ConfigMap as follows:
+```yaml
+  antrea-agent.conf: |
+    # FeatureGates is a map of feature names to bools that enable or disable experimental features.
+    featureGates:
+    # Enable antrea proxy which provides ServiceLB for in-cluster services in antrea agent.
+    # It should be enabled on Windows, otherwise NetworkPolicy will not take effect on
+    # Service traffic.
+      AntreaProxy: true
+```
+
+## Stages for all Feature Gates
+
+| Feature Name            | Component          | Default | Stage | Alpha Release | Beta Release | GA Release | Extra Requirements | Notes |
+| ----------------------- | ------------------ | ------- | ----- | ------------- | ------------ | ---------- | ------------------ | ----- |
+| `AntreaProxy`           | Agent              | `false` | Alpha | v0.8.0        | N/A          | N/A        | Yes                | Must be enabled for Windows. |
+| `ClusterNetworkPolicy`  | Controller         | `false` | Alpha | v0.8.0        | N/A          | N/A        | No                 |       |
+| `Traceflow`             | Agent + Controller | `false` | Alpha | v0.8.0        | N/A          | N/A        | Yes                |       |
+
+## Description and Requirements of Feature Gates
+
+### AntreaProxy
+
+`AntreaProxy` implements Service load-balancing for ClusterIP Services as part
+of the OVS pipeline, as opposed to relying on kube-proxy. This only applies to
+traffic originating from Pods, and destined to ClusterIP Services. In
+particular, it does not apply to NodePort Services.
+
+Note that this feature must be enabled for Windows. The Antrea Windows YAML
+manifest provided as part of releases enables this feature by default. If you
+edit the manifest, make sure you do not disable it, as it is needed for correct
+NetworkPolicy implementation for Pod-to-Service traffic.
+
+#### Requirements for this Feature
+
+When using the OVS built-in kernel module (which is the most common case), your
+kernel version must be >= 4.6 (as opposed to >= 4.4 without this feature).
+
+### ClusterNetworkPolicy
+
+`ClusterNetworkPolicy` is an Antrea-specific extension to K8s NetworkPolicies,
+which enables cluster admins to define security policies which apply to the
+entire cluster. Refer to this [document](network-policy.md) for more
+information.
+
+#### Requirements for this Feature
+
+None
+
+### Traceflow
+
+`Traceflow` enables a CRD API for Antrea that supports generating tracing
+requests for traffic going through the Antrea-managed Pod network. This is
+useful for troubleshooting connectivity issues, e.g. determining if a
+NetworkPolicy is responsible for traffic drops between two Pods.
+
+We are currently working on adding documentation for this feature.
+
+#### Requirements for this Feature
+
+This feature can only be used in "encap" mode when the Geneve tunnel type is
+being used. Note that this is the default configuration for both Linux and
+Windows.

docs/getting-started.md

@@ -41,6 +41,10 @@ In case a node does not have a supported OVS module installed,
 you can install it following the instructions at:
 [Installing Open vSwitch](https://docs.openvswitch.org/en/latest/intro/install).
 
+Some experimental features disabled by default may have additional requirements,
+please refer to the [Feature Gates documentation](feature-gates.md) to determine
+whether it applies to you.
+
 Antrea will work out-of-the-box on most popular Operating Systems. Known issues
 encountered when running Antrea on specific OSes are documented
 [here](os-issues.md).
@@ -63,6 +67,10 @@ kubectl apply -f https://raw.githubusercontent.com/vmware-tanzu/antrea/master/bu
 If you want to add Windows Nodes to your cluster, please refer to the
 installation instructions in [windows.md](/docs/windows.md).
 
+Antrea supports some experimental features that can be enabled or disabled,
+please refer to the [Feature Gates documentation](feature-gates.md) for more
+information.
+
 ### Deploying Antrea on a Cluster with Existing CNI
 
 The instructions above only apply when deploying Antrea in a new cluster. If you

pkg/features/antrea_features.go

@@ -19,6 +19,9 @@ import (
 	"k8s.io/component-base/featuregate"
 )
 
+// When editing this file, make sure you edit the documentation as well to keep
+// it consistent: /docs/feature-gates.md
+
 const (
 	// Every feature gate should add constant here following this template:
 	//