Add docs for clusterset IP feature

User guide and subctl commands.

Signed-off-by: Tom Pantelis <[email protected]>

src/content/operations/deployment/subctl/_index.en.md

@@ -73,16 +73,18 @@ contains the following details:
 #### `deploy-broker` flags
 
 <!-- markdownlint-disable line-length -->
-| Flag                                  | Description
-|:--------------------------------------|:---------------------------------------------------------------------------------------------------|
-| `--repository` `<string>`             | The repository from where the various Submariner images will be sourced (default `quay.io/submariner`)
-| `--version` `<string>`                | Image version (defaults to the subctl version)
-| `--components <strings>`              | Comma-separated list of components to be installed - any of `service-discovery`,`connectivity`. The default is: `service-discovery`,`connectivity`
-| `--globalnet`                         | Enable support for overlapping Cluster/Service CIDRs in connecting clusters (default disabled)
-| `--globalnet-cidr-range` `<string>`   | Global CIDR supernet range for allocating GlobalCIDRs to each cluster (default "242.0.0.0/8")
-| `--globalnet-cluster-size` `<value>`  | Default cluster size for GlobalCIDR allocated to each cluster (amount of global IPs) (default 65536)
-| `--ipsec-psk-from` `<string>`         | Import IPsec PSK from existing Submariner broker file, like broker-info.subm (default `broker-info.subm`)
-| `--broker-namespace` `<string>`       | Namespace on the Broker used for synchronizing resources between clusters (default `submariner-k8s-broker`)
+| Flag                                 | Description
+|:-------------------------------------|:---------------------------------------------------------------------------------------------------|
+| `--repository` `<string>`            | The repository from where the various Submariner images will be sourced (default `quay.io/submariner`)
+| `--version` `<string>`               | Image version (defaults to the subctl version)
+| `--components <strings>`             | Comma-separated list of components to be installed - any of `service-discovery`,`connectivity`. The default is: `service-discovery`,`connectivity`
+| `--globalnet`                        | Enable support for overlapping Cluster/Service CIDRs in connecting clusters (default disabled)
+| `--globalnet-cidr-range` `<string>`  | Global CIDR supernet range for allocating GlobalCIDRs to each cluster (default "242.0.0.0/8")
+| `--globalnet-cluster-size` `<value>` | Default cluster size for GlobalCIDR allocated to each cluster (amount of global IPs) (default 65536)
+| `--ipsec-psk-from` `<string>`        | Import IPsec PSK from existing Submariner broker file, like broker-info.subm (default `broker-info.subm`)
+| `--broker-namespace` `<string>`      | Namespace on the Broker used for synchronizing resources between clusters (default `submariner-k8s-broker`)
+| `--enable-clusterset-ip`             | Set default support for use of cluster set IP for exported services in connecting clusters (default disabled)
+| `--clusterset-ip-cidr-range` `<string>`      | Cluster set IP CIDR supernet range for allocating cluster set IP CIDRs to each cluster
 <!-- markdownlint-enable line-length -->
 
 ### `export`
@@ -97,6 +99,7 @@ discoverable from other clusters in the Submariner deployment.
 | Flag                     | Description
 |:-------------------------|:-------------------|
 | `--namespace` `<string>` | Namespace to use
+| `--use-clusterset-ip` `<string>`   | Use cluster set IP for this service (true or false)
 
 If no `namespace` flag is specified, it uses the default namespace from the current context, if present, otherwise it uses `default`.
 
@@ -142,6 +145,8 @@ deployment.
 | `--preferred-server`               | Enable this cluster as a preferred IPsec server for dataplane connections (only available with libreswan cable driver)
 | `--pod-debug`                      | Enable Submariner pod debugging (verbose logging in the deployed pods)
 | `--servicecidr`                    | Specifies the cluster's CIDR used to generate Service IP addresses. If not specified, `subctl` will try to discover it and if unable to do so, it will prompt the user
+| `--enable-clusterset-ip`             | Set default support for use of cluster set IP for exported services in connecting clusters (default disabled)
+| `--clusterset-ip-cidr` `<string>`      | Cluster set IP CIDR to be allocated to the cluster
 <!-- markdownlint-enable line-length -->
 
 #### `join` flags (Globalnet)

src/content/operations/usage/_index.en.md

@@ -684,6 +684,17 @@ are ignored.
 always returns the ClusterIP Service on **cluster2**. Similarly, `cluster3.nginx.nginx-test.svc.clusterset.local` always returns the
 ClusterIP Service on **cluster3**.
 
+##### Cluster Set Virtual IP
+
+Submariner can also allocate a cluster set virtual IP for an exported service that is stored in the `ServiceImport` resource. This is
+an opt-in feature that can be enabled per service via the `lighthouse.submariner.io/use-clusterset-ip` annotation on the `ServiceExport`
+or automatically for all services via the `enable-clusterset-ip` option on `subctl deploy-broker`. Submariner will allocate a virtual IP
+from a pool of IP addresses based on a configurable CIDR assigned to the cluster from a global CIDR range. The first cluster to export
+a service will allocate and assign the virtual IP.
+
+Lighthouse DNS will return the cluster set virtual IP from queries instead of a constituent cluster IP address. However, Submariner
+does not route this virtual IP and relies on some external component to do so.
+
 #### Test StatefulSet and Headless Service
 
 Submariner also supports Headless Services with StatefulSets, making it possible to access individual Pods via their stable DNS name.