update usage

Signed-off-by: terassyi <[email protected]>
terassyi · Dec 19, 2023 · c52bce2 · c52bce2
1 parent f659d96
commit c52bce2
Show file tree

Hide file tree

Showing 7 changed files with 1,038 additions and 2 deletions.
diff --git a/docs/bgp.md b/docs/bgp.md
@@ -0,0 +1,126 @@
+# How to Use
+
+Sart has two CLI interfaces, sartd is for daemon and sart-cli is for controlling sartd.
+
+### sartd bgp
+
+We can run the BGP daemon with `sartd bgp` command.
+And we can specify some parameters such as AS number and router id.
+To integrate Fib manager, we have to give the path to the gRPC endpoint for fib manager.
+
+```console
+Usage: sartd bgp [OPTIONS]
+
+Options:
+  -f, --file <FILE>              Config file path for BGP daemon
+  -a, --as <AS>                  Local AS Number
+  -d, --format <FORMAT>          Log display format [default: plain] [possible values: plain, json]
+  -r, --router-id <ROUTER_ID>    Local router id(must be ipv4 format)
+      --fib <FIB_ENDPOINT>       Fib endpoint url(gRPC) exp) localhost:5001
+      --table-id <FIB_TABLE_ID>  Target fib table id(default is main(254))
+      --exporter <EXPORTER>      Exporter endpoint url
+  -l, --level <LEVEL>            Log level(trace, debug, info, warn, error) [default: info]
+  -h, --help                     Print help
+```
+
+We also can configure BGP with a configuration file written by Yaml.
+This is the example of config files.
+
+```yaml
+asn: 65000
+router_id: 10.0.0.2
+multi_path: true
+neighbors:
+  - asn: 65010
+    router_id: 10.0.0.3
+    address: 10.0.0.3
+  - asn: 65020
+    router_id: 10.0.1.3
+    address: 10.0.1.3
+```
+
+
+## sart Commands
+
+To control running daemons, we can use sart-cli commands.
+Now we support following subcommands
+
+- bgp
+
+### sart bgp
+
+`sart bgp` command accepts `global` level and `neighbor` level subcommands.
+
+`global` level can get and set AS number or router id of the local daemon.
+And it also can configure RIB(Loc-RIB) information.
+
+```console
+root@233eff855e37:/# sart bgp global rib -h
+Usage: sart bgp global rib [OPTIONS] <COMMAND>
+
+Commands:
+  get
+  add
+  del
+  help  Print this message or the help of the given subcommand(s)
+
+Options:
+  -d, --format <FORMAT>      Display format [default: plain] [possible values: plain, json]
+  -e, --endpoint <ENDPOINT>  Endpoint to API server [default: localhost:5000]
+  -a, --afi <AFI>            Address Family Information [default: ipv4] [possible values: ipv4, ipv6]
+  -s, --safi <SAFI>          Sub Address Family Information [default: unicast] [possible values: unicast, multicast]
+  -h, --help                 Print help
+```
+
+For example, to add a prefix to running BGP daemon, run this command.
+```console
+root@233eff855e37:/# sart bgp global rib add 10.0.10.0/24 -a ipv4 -t origin=igp
+```
+
+`neighbor` level can get and set neighbor information.
+
+**Some commands are not implemented yet.**
+
+```console
+root@233eff855e37:/# sart bgp neighbor -h
+Usage: sart bgp neighbor [OPTIONS] <COMMAND>
+
+Commands:
+  get
+  list
+  add
+  del
+  rib
+  policy
+  help    Print this message or the help of the given subcommand(s)
+```
+
+For example, to add a neighbor, run this.
+
+```console
+root@233eff855e37:/# sart bgp neighbor add 10.10.0.1 65000
+```
+
+## gRPC Interfaces
+
+Sartd has gRPC interfaces.
+Sart-cli calls this interface internally.
+
+For detail, please see [proto/](https://github.com/teassyi/sart/blob/main/proto).
+
+## Integrate with FIB Manager
+
+To install paths received from other peers, we need to a FIB manager.
+For example, [FRR](https://frrouting.org/) needs to run [zebrad](https://docs.frrouting.org/en/latest/zebra.html) to install paths bgpd gets.
+
+For `sartd-bgp`, we can run `sartd-fib` as the FIB manager.
+`Sartd-fib` has gRPC interface to interact with other component.
+
+> [!NOTE]
+>`Sartd-fib` is in the PoC phase.
+
+To integrate with `sartd-fib`, we have to specify the gRPC endpoint to FIB manager as a parameter like below.
+
+```console
+$ sartd bgp --fib localhost:5010
+```
diff --git a/docs/design.md b/docs/design.md
@@ -146,6 +146,10 @@ This interact with the node local BGP speaker to announce load-balancer addresse
 
 These CRD's API group and version is `sart.terassyi.net`, `v1alpha2`
 
+This figure shows the relationships between CRDs.
+
+![kubernetes-model](./img/kubernetes-model.drawio.svg)
+
 #### AddressPool
 
 `AddressPool` defines a CIDR usable in itself.
@@ -168,6 +172,7 @@ spec:
 #### AddressBlock
 
 `AddressBlock` defines a subset of the `AddressPool` and its CIDR must be contained by AddressPool's CIDR.
+The allocator entity is tied to `AddressBlock`.
 
 This is automatically generated by `AddressPool`.
 
@@ -305,16 +310,58 @@ spec:
 
 ##### AddressPool
 
-To allocate IP addresses to LoadBalancer,
+To allocate IP addresses to LoadBalancers, we can create pools of IP addresses.
+To create pools for LoadBalancer, we have to apply `AddressPool` resource with `type: service`.
+
+We can create multiple pools.
 
 ##### Choosing pools
 
+We create multiple pools in one cluster.
+If there are multiple pools, we can choose the pool from which the controller allocates to the LoadBalancer.
+Choosing the pool, we have to add the annotation.
+
+When we specify multiple pools in the annotation, we can assign multiple addresses from specified pools.
+
+We also define a default assignable pool to specify `autoAssign: true` in the spec.
+If we want to use the pool its `autoAssign` is true, we can omit to specify its pool name in the annotation.
+We cannot create multiple default assignable pools.
+
+When we specify multiple pools, and one of specified pools is default assignable, we must specify its name.
+
 ##### Requesting specific addresses
 
+We can assign specific addresses to the LoadBalancer.
+To specify it, we also use the annotation.
+
+We can give multiple addresses from one pool or multiple pools.
+
 ##### AddressBlock
 
-##### Allocating LoadBalancer addresses
+`AddressBlock` is automatically generated by `AddressPool` and is a subset of a pool.
+In case of a pool for LoadBalancer(`type: service`), `AddressBlock` is created only one by the pool.
+Therefore, CIDR field of `AddressBlock` must be equal to `AddressPool`'s CIDR.
+
+And its allocator is managed by the `controller`.
+
+##### Allocating and Releasing LoadBalancer addresses
+
+Sartd-kubernetes's `controller` watches `Service` and `EndpointSlice` resources.
+When it detects the event for LoadBalancer, it triggers the reconciliation logic.
+
+First, when the LoadBalancer is created, the controller picks addresses from desired pools if addresses are requested, it picks its addresses or if not, automatically.
+If its addresses are valid, the controller allocates these.
+And it updates the status(`status.loadBalancer.ingress[].ip`) of given `Service` resource.
 
 ### Announcing addresses
 
+The controller creates `BGPAdvertisement` resources depending on allocated addresses and the `externalTrafficPolicy` of the LoadBalancer.
+
+When `externalTrafficPolicy` is `Cluster`, advertisements must have all peers which matches group label.
+If group label is not specified, all existing peers are picked.
+
+When `externalTrafficPolicy` is `Local`, advertisements must have peers on the node where backend pods exist.
+And target peers must be changed depending on the change of backend pods scheduling.
+
+
 ## CNI for Kubernetes
diff --git a/docs/fib.md b/docs/fib.md
@@ -0,0 +1,18 @@
+# How to Use 
+
+Sart has two CLI interfaces, sartd is for daemon and sart-cli is for controlling sartd.
+
+### sartd fib
+
+We can run the Fib manager to install or uninstall routing information in kernel with `sartd fib`.
+
+```console
+root@233eff855e37:/# sartd fib -h
+Usage: sartd fib [OPTIONS]
+
+Options:
+  -e, --endpoint <ENDPOINT>  Fib manager running endpoint url [default: 127.0.0.1:5001]
+  -l, --level <LEVEL>        Log level(trace, debug, info, warn, error) [default: info]
+  -d, --format <FORMAT>      Log display format [default: plain] [possible values: plain, json]
+  -h, --help                 Print help
+```