From 3a474bf4a10acb32a6fdeec0262917bb644d404b Mon Sep 17 00:00:00 2001
From: Hongliang Liu <lhongliang@vmware.com>
Date: Fri, 12 Jul 2024 18:04:04 +0800
Subject: [PATCH] Add document for BGPPolicy

Signed-off-by: Hongliang Liu <lhongliang@vmware.com>
---
 docs/bgp-policy.md | 164 +++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 164 insertions(+)
 create mode 100644 docs/bgp-policy.md

diff --git a/docs/bgp-policy.md b/docs/bgp-policy.md
new file mode 100644
index 00000000000..08c08652dc6
--- /dev/null
+++ b/docs/bgp-policy.md
@@ -0,0 +1,164 @@
+# BGPPolicy
+
+## Table of Contents
+
+## What is BGPPolicy?
+
+`BGPPolicy` is a CRD API that allows users to initialize BGP service on selected Kubernetes Nodes and advertise Service
+IPs, Pod IPs and Egress IPs to remote BGP peers.
+
+## Prerequisites
+
+BGPPolicy was introduced in v2.1as an alpha feature. A feature gate, `BGPPolicy` must be enabled on the antrea-agent in
+the `antrea-config` ConfigMap for the feature to work, like the following:
+
+```yaml
+kind: ConfigMap
+apiVersion: v1
+metadata:
+  name: antrea-config
+  namespace: kube-system
+data:
+  antrea-agent.conf: |
+    featureGates:
+      BGPPolicy: true
+```
+
+## The BGPPolicy resource
+
+A BGPPolicy in Kubernetes is a Custom Resource Definition (CRD) object. Like all CRD objects, you can POST a BGPPolicy
+definition to the API server to create a new instance. This CRD allows users to initiate the BGP service on selected
+Kubernetes Nodes and advertise various IPs (Service IPs, Pod IPs, and Egress IPs) to remote BGP peers, facilitating
+the integration of Kubernetes clusters with external BGP-enabled networks.
+
+Below is an example BGPPolicy object configuration:
+
+```yaml
+apiVersion: crd.antrea.io/v1alpha1
+kind: BGPPolicy
+metadata:
+  name: example-bgp-policy
+spec:
+  nodeSelector:
+    matchLabels:
+      bgp: enabled
+  localASN: 64512
+  listenPort: 179
+  advertisements:
+    service:
+      ipTypes:
+        - ClusterIP
+        - ExternalIP
+        - LoadBalancerIP
+    pod: {}
+    egress: {}
+  bgpPeers:
+    - address: 192.168.77.200
+      asn: 65001
+      port: 179
+```
+
+### NodeSelector
+
+The `nodeSelector` field specifies which Kubernetes Nodes the BGPPolicy applies to. Nodes are selected based on the
+labels specified. If multiple BGPPolicy objects select the same Node, only one will be selected randomly to take effect
+while the others will serve as alternatives.
+
+### LocalASN
+
+The `localASN` field defines the Autonomous System Number (ASN) used by the local BGP process. The available private ASN
+range is 64512-65535.
+
+### ListenPort
+
+The `listenPort` field specifies the port on which the BGP process listens. The default value is 179.
+
+### Advertisements
+
+The `advertisements` field configures which IPs or CIDRs are advertised to BGP peers.
+
+- `Service`: Specifies how to advertise Service IPs. The `ipTypes` field lists the types of Service IPs to be advertised,
+  including `ClusterIP`, `ExternalIP`, and `LoadBalancerIP`.
+- `Pod`: Specifies how to advertise Pod IPs. Currently, the Node IPAM Pod CIDR is advertised instead of specific Pod IPs.
+- `Egress`: Specifies how to advertise Egress IPs. Currently, all Egress IPs are advertised.
+
+### BGPPeers
+
+The `bgpPeers` field lists the BGP peers to which the advertisements are sent.
+
+- `Address`: The IP address on which the BGP peer listens.
+- `ASN`: The Autonomous System Number of the BGP peer.
+- `Port`: The port number on which the BGP peer listens. Default is 179.
+- `MultihopTTL`: The Time To Live (TTL) value used in BGP packets sent to the BGP peer, with a range of 1 to 255.
+  Default is 1.
+- `GracefulRestartTimeSeconds`: Specifies how long the BGP peer waits for the BGP session to re-establish after a
+  restart before deleting stale routes, with a range of 1 to 3600 seconds. Default is 120 seconds.
+
+## Usage examples
+
+### Combined Advertisements of Service, Pod, and Egress IPs
+
+In this example, we will advertise ClusterIP and LoadBalancerIP types of Service IPs, Pod CIDR, and Egress IPs from the
+selected Nodes to remote BGP peers.
+
+```yaml
+apiVersion: crd.antrea.io/v1alpha1
+kind: BGPPolicy
+metadata:
+  name: advertise-all-ips
+spec:
+  nodeSelector:
+    matchLabels:
+      bgp: enabled
+  localASN: 64515
+  listenPort: 179
+  advertisements:
+    service:
+      ipTypes:
+        - ClusterIP
+        - LoadBalancerIP
+    pod: {}
+    egress: {}
+  bgpPeers:
+    - address: 192.168.77.200
+      asn: 65001
+      port: 179
+    - address: 192.168.77.201
+      asn: 65001
+      port: 179
+```
+
+### Advertise Egress IPs to external BGP peers more than one hop
+
+In this example, we configure the BGPPolicy to advertise Egress IPs from selected Nodes to a remote BGP peer that is
+more than one hop away from the cluster. It's crucial to set the multihopTTL to a value greater than 1, which allows BGP
+packets to traverse multiple hops to reach the peer.
+
+```yaml
+apiVersion: crd.antrea.io/v1alpha1
+kind: BGPPolicy
+metadata:
+  name: advertise-all-ips
+spec:
+  nodeSelector:
+    matchLabels:
+      bgp: enabled
+  localASN: 64515
+  listenPort: 179
+  advertisements:
+    service:
+      ipTypes:
+        - ClusterIP
+        - LoadBalancerIP
+    pod: {}
+    egress: {}
+  bgpPeers:
+    - address: 192.168.78.201
+      asn: 65001
+      port: 179
+      multihopTTL: 2
+```
+
+## Limitations
+
+## What's next
\ No newline at end of file