Linking sites on Kubernetes using the Skupper CLI

Create links between sites on Kubernetes by using the CLI.

Using the Skupper command-line interface (CLI) allows you to create links between sites. The link direction is not significant, and is typically determined by ease of connectivity. For example, if east is behind a firewall, linking from east to west is the easiest option.

Once sites are linked, services can be exposed and consumed across the application network without the need to open ports or manage inter-site connectivity.

Linking sites using a token

A token provides a secure method to link sites. By default, a token can only be used once and must be used within 15 minutes to link sites. This procedure describes how to issue a token from one site and redeem that token on another site to create a link.

Prerequisites

• Two sites
• At least one site with enable-link-access enabled.

To link sites, you create a token on one site and redeem that token on the other site to create the link.

Procedure

1. On the site where you want to issue the token, make sure link access is enabled:

   skupper site update --enable-link-access
   

2. Create a token:

   skupper token issue <filename>
   

   where <filename> is the name of a YAML file that is saved on your local filesystem.

This file contains a key and the location of the site that created it.

📌 NOTE Access to this file provides access to the application network. Protect it appropriately. A token can be restricted by any combination of:

• Time - prevents token reuse after a specified period.

  For example, to allow a token to be used for 1 hour after it is issued:

  skupper token issue build/west.yaml --expiration-window 60m
  

  * Usage - prevents creating multiple links from a single token.

  For example, to allow a token to be used 3 times:

  skupper token issue output/west.yaml --redemptions-allowed 3
  

All inter-site traffic is protected by mutual TLS using a private, dedicated certificate authority (CA). A token is not a certificate, but is securely exchanged for a certificate during the linking process.

1. Redeem the token on a different site to create a link:

   skupper token redeem <filename>
   

   where <filename> is the name of a YAML file that is saved on your local filesystem.

2. Check the status of the link:

   skupper link status
   

   You might need to issue the command multiple times before the link is ready:

   skupper link status
   

   Example output:

   NAME                                            STATUS  COST    MESSAGE
   west-12f75bc8-5dda-4256-88f8-9df48150281a       Pending 1       Not Operational
   

   skupper link status
   

   Example output:

   NAME                                            STATUS  COST    MESSAGE
   west-12f75bc8-5dda-4256-88f8-9df48150281a       Ready   1       OK
   

   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.

Linking sites using a link resource

An alternative approach to linking sites using tokens is to create a link resource YAML file using the CLI, and to apply that resource to another site.

Prerequisites

• Two sites
• At least one site with enable-link-access enabled.

To link sites, you create a link resource YAML file on one site and apply that resource on the other site to create the link.

Procedure

1. On the site where you want to create a link, make sure link access is enabled:

   skupper site update --enable-link-access
   

2. Create a link resource YAML file:

   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:
3. The name of the link
4. The certificate used to authenticate the link
5. 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.

1. Apply the link resource YAML file on a different site to create a link:

   kubectl apply -f <filename>
   

   where <filename> is the name of a YAML file that is saved on your local filesystem.

2. Check the status of the link:

   skupper link status
   

   You might need to issue the command multiple times before the link is ready:

   skupper link status
   

   Example output:

   NAME                                            STATUS  COST    MESSAGE
   west-12f75bc8-5dda-4256-88f8-9df48150281a       Pending 1       Not Operational
   

   skupper link status
   

   Example output:

   NAME                                            STATUS  COST    MESSAGE
   west-12f75bc8-5dda-4256-88f8-9df48150281a       Ready   1       OK
   

   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.

Linking sites through an HTTP proxy

If your network requires routing through an HTTP CONNECT proxy to reach remote sites, you can configure Skupper links to use a proxy. This feature is only available when using link resources, not tokens.

Prerequisites

• Two sites
• At least one site with enable-link-access enabled.
• An HTTP CONNECT proxy accessible from the linking site
• Network connectivity from the proxy to the listening site's router endpoints
• The proxy must allow HTTP CONNECT requests to ports 55671 (inter-router) and 45671 (edge). For example, Squid requires:

  acl skupper_ports port 55671 45671  
  http_access allow CONNECT skupper_ports
  

To link sites through a proxy, you create a Secret containing the proxy configuration, generate a link resource YAML file, reference the proxy Secret in the link settings, and apply that resource to create the link.

Procedure

1. On the listening site, make sure link access is enabled:

   skupper site update --enable-link-access
   

2. On the listening site, create a link resource YAML file:

   skupper link generate > link.yaml
   

3. Copy the generated link.yaml file to the linking site.

4. On the linking site, create a Secret with the proxy configuration:

   apiVersion: v1
   kind: Secret
   metadata:
     name: my-proxy-config
   type: kubernetes.io/basic-auth
   stringData:
     host: proxy.example.com
     port: "3128"
     username: myuser
     password: mypassword
   

📌 NOTE If your proxy does not require authentication, remove the username and password.

1. On the linking site, edit the link.yaml file to add the proxy configuration in the settings section:

   apiVersion: skupper.io/v2alpha1
   kind: Link
   metadata:
     name: link-to-remote-site
   spec:
     cost: 1
     endpoints:
     - host: remote-site.example.com
       name: inter-router
       port: "55671"
     - host: remote-site.example.com
       name: edge
       port: "45671"
     tlsCredentials: link-to-remote-site
     settings:
       proxy-configuration: my-proxy-config
   

   where my-proxy-config is the name of the Secret created in step 4.

2. On the linking site, apply the link resource YAML file to create the link:

   kubectl apply -f link.yaml
   

3. Check the status of the link:

   skupper link status
   

   You might need to issue the command multiple times before the link is ready.

If the link remains in "Pending" or "Not Operational" status, check:

• The proxy Secret exists and contains the correct host and port
• The proxy is accessible from the router pod
• Router logs for connection errors: kubectl logs deployment/skupper-router

📌 NOTE If you update the proxy Secret, you must trigger a reconciliation to apply the changes:

kubectl annotate link <link-name> reconcile=$(date +%s) --overwrite

All inter-site traffic is protected by mutual TLS and routed through the HTTP CONNECT proxy tunnel. 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.

Specifying link cost

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 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:

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

1. 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.

1. 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 instead.