Update mkl (#294)

* mkl and link cost updates

Author: pwright

input/kube-cli/index.md

@@ -8,8 +8,10 @@ The Skupper CLI is designed to generate and consume standard resources, ensuring
 
 * [Create sites][site-configuration]
 * [Link sites][site-linking] (requires that one site has link access enabled)
+* [Configure link cost][link-cost]
 * [Expose and consume services][service-exposure]
 
 [site-configuration]: ./site-configuration.html
 [site-linking]: ./site-linking.html
+[link-cost]: ./site-linking.html#kube-link-cost-cli
 [service-exposure]: ./service-exposure.html

input/kube-cli/site-linking.md

@@ -252,3 +252,97 @@ All inter-site traffic is protected by mutual TLS and routed through the HTTP CO
 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.
+
+<a id="kube-link-cost-cli"></a>
+## Specifying link cost
+<!--PROCEDURE-->
+
+Link cost is a configurable integer value that influences how Skupper routes
+traffic across links between sites.
+The routing algorithm favors paths with the lowest total cost from client to
+target server.
+
+**📌 NOTE**
+For most load-balancing and failover use cases, a [multi-key listener][mkl]
+provides per-service control.
+Link cost applies to **all services** that traverse a link; it is not
+possible to set different costs for distinct services on the same link.
+
+Understanding link cost behavior:
+
+* The default link cost is `1`. Local workloads have an implicit cost of `0`.
+* If a connection traverses more than one link, the path cost is the sum of
+  all link costs along the path.
+* Cost acts as a threshold. When only one path exists, traffic flows on that
+  path regardless of cost. If a target becomes unavailable, traffic moves to
+  the remaining path regardless of cost.
+* When multiple paths exist, traffic flows on the lowest-cost path until the
+  number of open connections exceeds the cost of an alternative path. After
+  that threshold is reached, new connections are spread across both paths.
+* Traffic distribution is statistical, not round robin.
+
+The following procedure describes how to set link cost in various scenarios:
+
+**Procedure**
+
+1. To issue a token and specify the cost:
+
+   ```bash
+   skupper token issue <filename> --cost <integer-cost>
+   ```
+   where `<integer-cost>` is a positive integer (minimum `1`) and traffic favors
+   lower-cost links.
+
+   For example, to issue a token and set the link cost to `2`:
+   ```
+   skupper token issue token.yaml --cost 2
+   ```
+
+
+2. To update the cost on an existing link:
+
+   ```
+   skupper link update <link-name> --cost <integer-cost>
+   ```
+   For example:
+   ```
+   skupper link update west-6bfn6 --cost 2
+   Waiting for status...
+   Link "west-6bfn6" is ready.
+   ```
+
+3. To check the cost of a specific link:
+
+   ```
+   skupper link status <link-name>
+   ```
+   Example output:
+   ```
+   Name:     west-6bfn6
+   Status:   Ready
+   Cost:     2
+   Message:  <none>
+   ```
+
+**Additional information**
+
+A common use case for link cost is automatic failover.
+You can configure a primary site with an effective cost of `0` (local) and a
+backup site with a high link cost, for example `99999`:
+
+- local server — effective cost `0`
+- remote backup server — link cost `99999`
+
+In this configuration, all connections are routed to the local server.
+If the local server becomes unavailable, traffic fails over to the remote
+server regardless of the high cost.
+
+**📌 NOTE**
+Skupper does not provide orchestrated failover for stateful applications that
+require control over the order in which traffic is redirected.
+You must implement that orchestration separately.
+
+For per-service failover or weighted traffic distribution, use a
+[multi-key listener][mkl] instead.
+
+[mkl]: ../kube-yaml/service-exposure.html#kube-creating-multikeylistener-yaml

input/kube-yaml/index.md

@@ -6,8 +6,10 @@ You can use YAML on Kubernetes after installing the Skupper controller to create
 
 * [Create sites][site-configuration]
 * [Link sites][site-linking] (requires that one site has link access enabled)
+* [Configure link cost][link-cost]
 * [Expose and consume services][service-exposure]
 
 [site-configuration]: ./site-configuration.html
 [site-linking]: ./site-linking.html
+[link-cost]: ./site-linking.html#kube-link-cost-yaml
 [service-exposure]: ./service-exposure.html

input/kube-yaml/service-exposure.md

@@ -40,7 +40,7 @@ There are many options to consider when creating connectors using YAML, see [Con
    ```
    This creates a connector in the `east` site and exposes the `backend` deployment on the network on port 8080.
    You can create a listener on a different site using the matching routing key `backend` to address this service.
-
+   
    To create the connector resource:
 
    ```bash
@@ -95,7 +95,7 @@ For configuration details, see [Listener resource][listener-resource].
    ```
    This creates a listener in the `west` site and matches with the connector that uses the routing key `backend`. 
    It also creates a service named  `east-backend` exposed on port 8080 in the current namespace.
-
+   
    To create the listener resource:
 
    ```bash
@@ -128,10 +128,11 @@ Use a multi-key listener when you want one service endpoint to aggregate traffic
 
 With multi-key listeners, you must choose a strategy which determines how the traffic is distributed:
 
-* priority - Uses the first routing key in list that is available for traffic. If the connector becomes unavailable, the listener matches with the next available routing key in list.
+* priority - Uses the first routing key in list that is available for traffic. If the connectors for that routing key become unavailable, the listener matches with the next routing key in list.
 * weighted - Uses the routing keys in proportion to the assigned weights. For example, if `backend1` is assigned 25 and `backend2` is assigned 75, then only a quarter of the TCP connections are directed to `backend1`.
 
-Multi-key listeners provide predictable traffic distribution from the client side and typically are not influenced by link costs.
+**📌 NOTE**
+Multi-key listeners select between routing keys using the configured strategy. Each routing key may have multiple connectors, and link cost determines which connector is used within each routing key. The two mechanisms are independent.
 
 For configuration details, see [MultiKeyListener resource][multikeylistener-resource].
 
@@ -146,7 +147,6 @@ For configuration details, see [MultiKeyListener resource][multikeylistener-reso
 
 2. Determine which strategy is best for your use case. For example, failover is best achieved using the `priority` strategy.
 
-
 3. Create a multi-key listener resource YAML file.
    For example:
    ```yaml
@@ -163,8 +163,8 @@ For configuration details, see [MultiKeyListener resource][multikeylistener-reso
            east-backend: 1
            west-backend: 1
    ```
-   This creates a listener named `mkl-backend` that exposes a single endpoint on port 9092 and distributes traffic evenly across the `east-backend` and `west-backend` routing keys.
-
+   This creates a listener named `mkl-backend` that exposes a single endpoint on port 9092 and distributes traffic evenly between the `east-backend` and `west-backend` routing keys. Each routing key may have multiple connectors; link cost determines which connector is used within each routing key.
+   
    To prefer one routing key first and fall back to another, use the `priority` strategy:
    ```yaml
    apiVersion: skupper.io/v2alpha1
@@ -180,13 +180,10 @@ For configuration details, see [MultiKeyListener resource][multikeylistener-reso
            - east-backend-http
            - west-backend-http
    ```
-
    To create the multi-key listener resource:
-
    ```bash
    kubectl apply -f <filename>
    ```
-
    where `<filename>` is the name of a YAML file that is saved on your local filesystem.
 
 4. Check the multi-key listener status:

input/kube-yaml/site-linking.md

@@ -122,3 +122,147 @@ A connecting site redeems this token for a `Link` resource to establish a link t
    NAME            STATUS   REMOTE SITE   MESSAGE
    token-to-west   Ready    my-site       OK
    ```
+
+<a id="kube-link-cost-yaml"></a>
+## Specifying link cost using YAML
+<!--PROCEDURE-->
+
+Link cost is a configurable integer value that influences how Skupper routes
+traffic across links between sites.
+The routing algorithm favors paths with the lowest total cost from client to
+target server.
+
+**📌 NOTE**
+For most load-balancing and failover use cases, a [multi-key listener][mkl]
+provides more predictable, per-service control than link cost.
+Link cost applies to **all services** that traverse a link; it is not
+possible to set different costs for distinct services on the same link.
+
+Understanding link cost behavior:
+
+* The default link cost is `1`. Local workloads have an implicit cost of `0`.
+* If a connection traverses more than one link, the path cost is the sum of
+  all link costs along the path.
+* Cost acts as a threshold. When only one path exists, traffic flows on that
+  path regardless of cost. If a target becomes unavailable, traffic moves to
+  the remaining path regardless of cost.
+* When multiple paths exist, traffic flows on the lowest-cost path until the
+  number of open connections exceeds the cost of an alternative path. After
+  that threshold is reached, new connections are spread across both paths.
+* Traffic distribution is statistical, not round robin.
+
+Link cost is set on the `Link` custom resource via `spec.cost`.
+The `AccessToken` resource also exposes `spec.linkCost`, which is applied to the `Link` created when the token is redeemed.
+
+**Prerequisites**
+
+* Two or more linked sites.
+* The name of the `Link` resource whose cost you want to set.
+
+**Procedure**
+
+**Option A — Set cost when redeeming a token**
+
+Add `linkCost` to the `AccessToken` resource before applying it. When the token is redeemed, the resulting `Link` is created with that cost.
+
+```yaml
+apiVersion: skupper.io/v2alpha1
+kind: AccessToken
+metadata:
+  name: my-token
+spec:
+  url: <grant-url>
+  code: <secret-code>
+  ca: <ca-cert>
+  linkCost: 2
+```
+
+Apply it:
+
+```bash
+kubectl apply -f token.yaml
+```
+
+**Option B — Update cost on an existing link**
+
+1. Find the link name:
+
+   ```bash
+   kubectl get links
+   ```
+   Example output:
+   ```
+   NAME          STATUS   REMOTE SITE   MESSAGE
+   west-6bfn6    Ready    west
+   ```
+
+2. Patch the cost on the link:
+
+   ```bash
+   kubectl patch link west-6bfn6 --type merge -p '{"spec":{"cost":2}}'
+   ```
+   
+   Or edit the resource directly:
+   
+   ```bash
+   kubectl edit link west-6bfn6
+   ```
+   
+   Set the `cost` field in `spec`:
+   
+   ```yaml
+   apiVersion: skupper.io/v2alpha1
+   kind: Link
+   metadata:
+     name: west-6bfn6
+   spec:
+     cost: 2
+     endpoints:
+       - host: <remote-host>
+         name: inter-router
+         port: "55671"
+       - host: <remote-host>
+         name: edge
+         port: "45671"
+     tlsCredentials: west-6bfn6
+   ```
+
+**Verifying link cost**
+
+Check the cost of a specific link:
+
+```bash
+kubectl get link west-6bfn6 -o yaml
+```
+
+Look for `spec.cost` in the output. Alternatively, for a summary:
+
+```bash
+kubectl get links
+```
+
+**Additional information**
+
+* The minimum enforced cost is `1`. If `spec.cost` is set to `0` or omitted, the router treats it as `1`.
+* For the failover pattern (primary cost `0`/local, backup cost `99999`), set `spec.cost: 99999` on the backup site's `Link` resource.
+
+A common use case for link cost is automatic failover.
+You can configure a primary site with an effective cost of `0` (local) and a
+backup site with a high link cost, for example `99999`:
+
+- local server — effective cost `0`
+- remote backup server — link cost `99999`
+
+In this configuration, all connections are routed to the local server.
+If the local server becomes unavailable, traffic fails over to the remote
+server regardless of the high cost.
+
+**📌 NOTE**
+Skupper does not provide orchestrated failover for stateful applications that
+require control over the order in which traffic is redirected.
+You must implement that orchestration separately.
+
+For per-service failover or weighted traffic distribution, use a
+[multi-key listener][mkl] instead.
+
+[mkl]: ./service-exposure.html#kube-creating-multikeylistener-yaml