Custom certs and service tls

input/advanced-deployments/custom-certs.md

@@ -0,0 +1,116 @@
+## Using custom certificates for incoming links on Kubernetes
+
+This section describes how to replace the default certificates for Kubernetes sites.
+
+By default, the Skupper controller creates its own Certificate Authority (CA) and self-signed server certificates. 
+For example, it generates certificates to authenticate incoming links from other Skupper sites.
+
+The default CA is named `skupper-site-ca`. 
+The default server certificate is named `skupper-site-server` and is issued for the public hostname or IP address of the `skupper-router` service, based on the ingress type (for example, OpenShift Route or LoadBalancer).
+
+You can replace these defaults with your own CA or server certificate.
+
+## About mutual TLS between sites
+
+When two Skupper sites are linked, the routers use mutual TLS (mTLS) for authentication. 
+
+![Application traffic encrypted](../images/app-traffic.png)
+
+For information on TLS within sites, see [Encrypting service traffic](./encrypting-service-traffic.html)
+
+The certificates and keys for traffic between sites are stored in Kubernetes Secrets:
+
+- **`skupper-site-server`**  
+  Contains the key, certificate, and CA certificate used by the `skupper-router` when accepting incoming links from other sites.
+- **Client credential Secret**  
+  Contains the key, certificate, and CA certificate used by the `skupper-router` when creating outgoing links to other sites. The Secret name is user-defined and referenced in the `Link` resource’s `spec.tlsCredentials` field.
+
+Both routers must trust the peer’s CA and verify that the certificate’s hostname or IP matches the link’s address.
+
+If `skupper-site-server` or the client credential Secret are not provided, Skupper generates them using a self-signed CA stored in the `skupper-site-ca` Secret.
+
+> **Note:** Skupper uses the `skupper-site-ca` Secret only if a custom `skupper-site-server` or client credential Secret is not already present.
+
+## Using a custom server certificate
+
+To use your own server certificate, create a secret named `skupper-site-server` in the namespace of your Skupper site:
+
+```yaml
+apiVersion: v1
+kind: Secret
+metadata:
+  name: skupper-site-server
+data:
+  ca.crt: <base64-ca-cert>
+  tls.crt: <base64-server-cert>
+  tls.key: <base64-server-key>
+```
+
+The certificate in `tls.crt` must be valid for the hostname or IP address used in your `Link` resource. To find this value for an existing site:
+
+```bash
+kubectl get site -o json | jq -r .items[].status.endpoints[0].host
+```
+
+If the site exists, Skupper detects the secret and stops managing the server certificate. Verify with:
+
+```bash
+kubectl get certificate skupper-site-server -o json | jq -r .status.conditions[].message
+```
+
+Expected output:
+```
+Secret exists but is not controlled by skupper
+```
+
+---
+
+## Generating a Link
+
+A **Link** lets a remote Skupper site connect securely to your site (incoming link). A link requires:
+
+- A `Link` resource with your site’s connection details.
+- A client certificate secret (`skupper-link`) that the remote site uses for authentication.
+
+1. Provide `skupper-site-ca` to Skupper, it can create the client certificate secret for you. Example:
+
+    ```bash
+    kubectl create -f - <<EOF
+    apiVersion: skupper.io/v2alpha1
+    kind: Certificate
+    metadata:
+      name: skupper-link
+    spec:
+      ca: skupper-site-ca
+      client: true
+      subject: skupper.public.host
+    EOF
+    ```
+
+2. Create a Link resource:
+You can create a link in three ways:
+
+    **1. Skupper CLI**
+    - Auto-generate (when CA is available):
+      ```bash
+      skupper link generate
+      ```
+    - Use existing secret:
+      ```bash
+      skupper link generate --tls-credentials skupper-link
+      ```
+    - Provide your own secret:
+      ```bash
+      skupper link generate --generate-credential=false --tls-credentials=skupper-link
+      ```
+
+    **2. kubectl**
+    Extract endpoints and create the `Link` YAML, then append the client secret.
+
+    **3. Manual**
+    Get endpoints:
+    ```bash
+    kubectl get site -o yaml | yq -y .items[].status.endpoints
+    ```
+    Write a YAML file containing both the `Link` resource and the client secret.
+

input/advanced-deployments/encrypting-service-traffic.md

@@ -0,0 +1,54 @@
+# Encrypting service traffic on Kubernetes
+
+When the backend workload you want to expose into your Virtual Application Network (VAN) is protected with TLS, creating a simple pair of `Connector` and `Listener` (without specifying TLS credentials) will result in **TLS passthrough**.
+In passthrough mode, Skupper forwards encrypted traffic from client to server without terminating or inspecting it.
+
+However, in many cases, the TLS certificate presented by the backend server is not valid for the hostname used by the remote client.
+To solve this, you can configure Skupper to **terminate TLS on the Listener** and **re-encrypt TLS on the Connector**, ensuring trusted connections on both ends using certificates that are appropriate for each hop as described in this section.
+
+
+# TLS Termination and Re-encryption with Skupper
+
+![traffic encrypted](../images/tls-traffic.png)
+
+For information on TLS between sites, see [Using custom certificates for incoming links](./custom-certs.html)
+
+* An HTTP application that receives requests from a client in a remote site. The connection between the client and the router and the connection between the remote router and the server are unencrypted. The communication between routers is always encrypted.
+* An HTTPS application where the traffic is encrypted by the client and unencrypted by the remote server. This scenario might not work due to hostname mismatch or untrusted CA
+* An HTTPS application where traffic is encrypted at every stage: encrypted between the client and the router, re-encrypted between the routers, and re-encrypted between the router and the server at the remote site.
+This section describes that third scenario, and the Secrets required to have TLS between the application and the router.
+
+When a TLS connection from a client of a service is terminated and re-encrypted at the router, or when the router establishes a TLS connection to a pod implementing the service, additional Secrets are required.
+
+To set up hop-by-hop encryption requires:
+
+- The **trusted CA certificate** for the `Connector`
+- A **valid server certificate** for the `Listener`
+
+
+# Configuring the Connector with a server certificate
+
+To connect securely to a TLS-protected backend, the `Connector` must present the CA certificate trusted by the backend service.
+
+Generate a Kubernetes `Secret` containing the following data:
+
+- `ca.crt`: the server's trusted CA certificate
+
+Then configure the `Connector` to use your Kubernetes `Secret` through the `spec.tlsCredentials` field.
+
+# Configuring the Listener with a server certificate
+
+If the traffic is not required to be decrypted at the listener, you can skip this step. 
+For example if the traffic is decrypted by a device connected to the cluster.
+
+The `Listener` can be configured to terminate TLS by specifying a Kubernetes `Secret` through the `spec.tlsCredentials` field of the Listener CR.
+The server certificate must be valid for the `host` value your client applications will connect to.
+
+For example, if your `Listener` uses `host: my-service`, then the certificate's Common Name (CN) or Subject Alternative Name (SAN) must include `my-service`.
+
+Here are the data needed as part of your Kubernetes `Secret`:
+
+- `tls.crt`: the server certificate (valid for the `my-service` hostname)
+- `tls.key`: the corresponding private key
+- `ca.crt`: the issuing CA certificate
+

input/index.html.in

@@ -96,6 +96,15 @@ body_template: config/wide-body.html
     <nav>
       <li><a href="./console/index.html">Using the Skupper console</a></li>
 
+    </nav>
+  </div>
+ <div>
+    <h2 id="observability">Advanced deployments</h2>
+    <p>While Skupper provides many options, you may have specific requirements that fall outside the standard configurations.</p>
+    <nav>
+      <li><a href="./advanced-deployments/custom-certs.html">Using custom certificates</a></li>
+
+
     </nav>
   </div>