Chapter 13. Linking sites using custom certificates

On the listening site, create a Site CR without spec.linkAccess (or with spec.linkAccess: none):

apiVersion: skupper.io/v2alpha1
kind: Site
metadata:
  name: my-site
spec: {}

Apply it:

kubectl apply -f site.yaml

Because spec.linkAccess is not set, the controller will not auto-create any RouterAccess.

On the listening site, create a Secret containing your custom server certificate. You can name it anything — this example uses my-server-cert:

apiVersion: v1
kind: Secret
type: "kubernetes.io/tls"
metadata:
  name: my-server-cert
data:
  ca.crt: LS0tLS1C...redacted
  tls.crt: LS0tLS1C...redacted
  tls.key: LS0tLS1C...redacted

Apply it:

kubectl apply -f my-server-cert.yaml

Make sure the certificate in tls.crt is valid for the hostname or IP address that will be referenced in your Link resource. In this example, consider it valid for skupper.public.host.

On the listening site, create a RouterAccess CR that references your Secret and sets generateTlsCredentials: false:

apiVersion: skupper.io/v2alpha1
kind: RouterAccess
metadata:
  name: my-router-access
spec:
  generateTlsCredentials: false
  tlsCredentials: my-server-cert
  accessType: loadbalancer   # or "route", "ingress", etc.
  roles:
    - name: inter-router
      port: 55671
    - name: edge
      port: 45671

Apply it:

kubectl apply -f my-router-access.yaml

Because generateTlsCredentials: false, Skupper will use your Secret as-is and will never overwrite it.

Determine the hostname or IP address for the listening site.

Check the RouterAccess status for the resolved endpoints:

kubectl get routeraccess my-router-access -o json | jq -r '.status.endpoints[0].host'

You should see something like:

skupper.public.host

On the listening site, create client credentials for the connecting site.

a) If your server certificate was signed by skupper-site-ca:

Since Skupper creates the skupper-site-ca signing Certificate resource, you can use it to generate a client secret automatically. Create a Certificate resource:

apiVersion: skupper.io/v2alpha1
kind: Certificate
metadata:
  name: skupper-link
spec:
  ca: skupper-site-ca
  client: true
  subject: skupper-client

Apply it:

kubectl apply -f skupper-link-certificate.yaml

Save the generated Secret for use in the next step:

kubectl get secret skupper-link -o yaml | yq eval -o=yaml 'del(.metadata.namespace, .metadata.creationTimestamp, .metadata.resourceVersion, .metadata.uid, .metadata.managedFields)' - > client-secret.yaml

b) If your server certificate was signed by a different CA:

You must issue a client certificate yourself and create a Secret named skupper-link directly. The client certificate must be signed by the same CA that signed your custom server certificate. Create the Secret similarly to how you created the server certificate earlier, ensuring the ca.crt field contains the same CA certificate. Save it as client-secret.yaml.

From the listening site, create a Link resource YAML file.

Option A: Using kubectl with jq and yq

kubectl get routeraccess my-router-access -o json | jq '{
  apiVersion: "skupper.io/v2alpha1",
  kind: "Link",
  metadata: {name: "skupper-link"},
  spec: {
    cost: 1,
    tlsCredentials: "skupper-link",
    endpoints: .status.endpoints
  }
}' | yq -P > skupper-link.yaml
echo "---" >> skupper-link.yaml
cat client-secret.yaml >> skupper-link.yaml

Option B: Manual generation

Retrieve the endpoints:

kubectl get routeraccess my-router-access -o yaml | yq '.status.endpoints'

Then compose the file manually:

---
apiVersion: skupper.io/v2alpha1
kind: Link
metadata:
  name: skupper-link
spec:
  cost: 1
  tlsCredentials: skupper-link
  endpoints:
    - group: skupper-router
      host: skupper.public.host
      name: inter-router
      port: '55671'
    - group: skupper-router
      host: skupper.public.host
      name: edge
      port: '45671'
---
apiVersion: v1
kind: Secret
type: "kubernetes.io/tls"
metadata:
  name: skupper-link
data:
  ca.crt: LS0tLS1C...redacted
  tls.crt: LS0tLS1C...redacted
  tls.key: LS0tLS1C...redacted

Securely transfer the Link resource YAML file to the connecting site.

📌 NOTE Access to this file provides access to the application network. Protect it appropriately.

On the connecting site, apply the YAML file and check status:

kubectl apply -f skupper-link.yaml
kubectl get link
NAME            STATUS   REMOTE SITE   MESSAGE
skupper-link    Ready    my-site       OK

On the listening site, create a secret named skupper-site-server, for example:

apiVersion: v1
kind: Secret
type: "kubernetes.io/tls"
metadata:
  name: skupper-site-server
data:
  ca.crt: LS0tLS1C...redacted
  tls.crt: LS0tLS1C...redacted
  tls.key: LS0tLS1C...redacted

Apply the secret while deleting and recreating the site:

kubectl delete site <site-name> # delete the site
kubectl apply -f skupper-site-server.yaml
kubectl apply -f site.yaml # recreate the site

Make sure the certificate specified in tls.crt is valid for the hostname or IP address that will be referenced in your Link resource. In this example, consider the server certificate as being valid for the hostname: skupper.public.host.

Determine the hostname or IP address for the listening site.

In case your Skupper Site is already created, you can find the appropriate Hostname or IP by looking at the Endpoint element of a Site status:

kubectl get site <site-name> -o json | jq -r '.status.endpoints[0].host'

And you will see something like:

skupper.public.host

Note: Make sure you specify the appropriate namespace when running the commands from this example.

Again, if your Site has already been created, Skupper will recognize your custom secret. You can confirm this with the following command:

kubectl get certificate.skupper.io skupper-site-server -o json | jq -r '.status.conditions[].message'

You should see a message like:

Secret exists but is not controlled by skupper

This confirms that Skupper has detected your certificate but is not managing it.

On the listening site, create client credentials for the connecting site.

Once your Skupper site is configured to use your custom server certificate, you can create a Link resource and an associated client Secret.

To use the automatically created skupper-site-ca issuer, create a Certificate resource so that Skupper generates a client secret named skupper-link:

+

apiVersion: skupper.io/v2alpha1
kind: Certificate
metadata:
  name: skupper-link
spec:
  ca: skupper-site-ca
  client: true
  subject: skupper-client

+ Apply the resource:

+

kubectl apply -f skupper-link-certificate.yaml

+ You should see an output like:

+

certificate.skupper.io/skupper-link created

+ Then a Secret named skupper-link should be created and it can be used to compose your link file.

+ Save the generated secret to a local file for use in the next step:

+

kubectl get secret skupper-link -o yaml | yq eval -o=yaml 'del(.metadata.namespace, .metadata.creationTimestamp, .metadata.resourceVersion, .metadata.uid, .metadata.managedFields)' - > client-secret.yaml

+ If you are providing the client certificate yourself, create a secret named skupper-link, for example:

+

apiVersion: v1
kind: Secret
type: "kubernetes.io/tls"
metadata:
  name: skupper-link
data:
  ca.crt: LS0tLS1C...redacted
  tls.crt: LS0tLS1C...redacted
  tls.key: LS0tLS1C...redacted

+ Save this resource locally as client-secret.yaml if you want to combine it with a Link resource in a single file.

On the listening site, create a Link resource YAML file.

Now, regardless of whether Skupper generated your client certificate Secret or if you generated it yourself, to define a Skupper Link, that can be shared with remote sites allowing them to initiate a secure outgoing link to your site, you will need to write a YAML file that contains both documents: a Link, and a Client Secret.

You can generate a Link using kubectl or manually (as long as retrieve the list of endpoints). Here are these two methods:

Option A: Using kubectl with jq and yq

The following command uses kubectl, jq, and yq to extract and compose the information needed to define a Link, storing the Link document into skupper-link.yaml:

kubectl get site <site-name> -o json | jq '{
  apiVersion: "skupper.io/v2alpha1",
  kind: "Link",
  metadata: {name: "skupper-link"},
  spec: {
    cost: 1,
    tlsCredentials: "skupper-link",
    endpoints: .status.endpoints
  }
}' | yq -P > skupper-link.yaml

Then you need to combine it in a YAML file that contains both the Link above and the client Secret. Suppose your client Secret is stored in a file named client-secret.yaml, you could run:

echo "---" >> skupper-link.yaml
cat client-secret.yaml >> skupper-link.yaml

Option B: Manual generation

You can retrieve the list of endpoints from the Site definition, using:

kubectl get site <site-name> -o yaml | yq '.status.endpoints'

The command above uses both kubectl and yq. And the output should be something like:

- group: skupper-router
  host: skupper.public.host
  name: inter-router
  port: '55671'
- group: skupper-router
  host: skupper.public.host
  name: edge
  port: '45671'

Then you can create your Link file with:

---
apiVersion: skupper.io/v2alpha1
kind: Link
metadata:
  name: skupper-link
spec:
  cost: 1
  tlsCredentials: skupper-link
  endpoints:
    - group: skupper-router
      host: skupper.public.host  # The hostname or IP specified in your custom certificate
      name: inter-router
      port: '55671'
    - group: skupper-router
      host: skupper.public.host  # The same hostname or IP
      name: edge
      port: '45671'
---
apiVersion: v1
kind: Secret
type: "kubernetes.io/tls"
metadata:
  name: skupper-link
data:
  ca.crt: LS0tLS1C...redacted        # The trusted CA certificate
  tls.crt: LS0tLS1C...redacted       # The client certificate
  tls.key: LS0tLS1C...redacted       # The corresponding private key

Securely transfer the Link resource YAML file to the context of the connecting site. If you have both sites available from your terminal session, this step is not required.

📌 NOTE Access to this file provides access to the application network. Protect it appropriately.

On the connecting site, apply the YAML file and check status:

kubectl apply -f skupper-link.yaml
kubectl get link
NAME            STATUS   REMOTE SITE   MESSAGE
skupper-link    Ready    my-site       OK