SKUPPER-2883: High availability (#281)

ha explanation

Author: pwright

input/kube-cli/site-configuration.md

@@ -76,6 +76,40 @@ For example
   To configure site resources, see [Setting site resources](../kube-yaml/site-configuration.html#kube-site-resources-yaml).
 
 
+<a id="kube-ha-cli"></a>
+## Creating a high availability site using the CLI on Kubernetes
+
+You can create a site that is highly available by using the `ha` option.
+High availability mode is intended to maintain service continuity during router restarts or pod rescheduling, but it does not provide failover if network connectivity between sites is lost.
+High availability mode deploys two router pods with anti-affinity rules to ensure service continuity during node failures.
+
+**Prerequisites**
+
+* The `skupper` CLI is installed.
+* The Skupper controller is running on the Kubernetes cluster.
+
+**Procedure**
+
+1. Create a high availability site on Kubernetes:
+
+   ```bash
+   skupper site create <site-name> --enable-ha
+   ```
+   If the site already exists, you can use the `update` command to enable high availability:
+   ```bash
+   skupper site update --enable-ha
+   ```
+2. To verify that the site is running in high availability mode, run the following command:
+   ```bash
+   kubectl get site -o yaml | grep ha
+   ```
+   The output should be similar to the following:
+   ```
+   ha: true
+   ```
+   When high availability mode is enabled, two router pods are created so that traffic can continue if one pod restarts or is rescheduled.
+   High availability can also help during a node failure.
+
 <a id="kube-deleting-site-cli"></a>
 ## Deleting a site using the CLI on Kubernetes
 

input/kube-cli/site-linking.md

@@ -101,14 +101,20 @@ To link sites, you create a `link` resource YAML file on one site and apply that
    skupper link generate > <filename>
    ```
    where `<filename>` is the name of a YAML file that is saved on your local filesystem.
+   The `link` YAML file contains the following information:
+   * The name of the link
+   * The certificate used to authenticate the link
+   * Two host and port entries for the listening site are included for each link.
+   
+   If the listening site uses high availability mode, two link resources are created.
 
-3. Apply the `link` resource YAML file on a different site to create a link:
+1. Apply the `link` resource YAML file on a different site to create a link:
    ```bash
    kubectl apply -f <filename>
    ```
    where `<filename>` is the name of a YAML file that is saved on your local filesystem.
 
-4. Check the status of the link:
+2. Check the status of the link:
    ```bash
    skupper link status
    ```
@@ -124,4 +130,3 @@ To link sites, you create a `link` resource YAML file on one site and apply that
    You can now expose services on the application network.
 
 There are many options to consider when linking sites using the CLI, see [CLI Reference][cli-ref], including *frequently used* options.
-

input/kube-yaml/site-configuration.md

@@ -68,6 +68,42 @@ There are many options to consider when creating sites using YAML, see the [YAML
 [yaml-ref]: https://skupperproject.github.io/refdog/resources/index.html
 
 
+<a id="kube-ha-yaml"></a>
+## Creating a high availability site using YAML
+
+You can create a site that is highly available by using the `ha` option.
+High availability mode is intended to maintain service continuity during router restarts or pod rescheduling, but it does not provide failover if network connectivity between sites is lost.
+High availability mode deploys two router pods with anti-affinity rules to ensure service continuity during node failures.
+
+**Prerequisites**
+
+* The Skupper controller is running on the Kubernetes cluster you are running
+
+
+Procedure
+
+1. Create a site CR YAML file named `ha-site.yaml`, for example:
+
+   ```yaml
+   apiVersion: skupper.io/v2alpha1
+   kind: Site
+   metadata:
+     name: ha-site
+     namespace: west
+   spec:
+     ha: true
+     linkAccess: default  # Optional: configure external access
+   ```
+   This YAML creates a high availability site named `ha-site` in the `west` namespace.
+
+   See [Setting site resources](#kube-site-resources-yaml) for more information about sizing the site.
+
+2. Apply the YAML to create the site:
+
+   ```bash
+   kubectl apply -f ha-site.yaml
+   ```
+
 <a id="kube-site-resources-yaml"></a>
 ## Setting site resources
 

input/kube-yaml/site-linking.md

@@ -113,4 +113,4 @@ A connecting site redeems this token for a `Link` resource to establish a link t
    kubectl get link
    NAME            STATUS   REMOTE SITE   MESSAGE
    token-to-west   Ready    my-site       OK
-   ```
+   ```