From fbcd8a89cfe15aef07faa232bb778a1228d82338 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Wed, 20 May 2026 14:30:27 +0100 Subject: [PATCH 1/4] proxy init --- input/kube-cli/site-linking.md | 108 +++++++++++++++++++++++++++++++++ 1 file changed, 108 insertions(+) diff --git a/input/kube-cli/site-linking.md b/input/kube-cli/site-linking.md index b352ff02..17650ea2 100644 --- a/input/kube-cli/site-linking.md +++ b/input/kube-cli/site-linking.md @@ -137,3 +137,111 @@ 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. + + +## 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. + +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. Make sure the proxy allows CONNECT to the listening site's router ports, typically 55671 and 45671. For example Squid configuration: + ``` + acl skupper_ports port 55671 45671 + http_access allow CONNECT skupper_ports + ``` + +2. On the site where you want to create a link through a proxy, create a Secret with the proxy configuration: + ```yaml + apiVersion: v1 + kind: Secret + metadata: + name: my-proxy-config + type: Opaque + stringData: + host: proxy.example.com + port: "3128" + ``` + Apply the Secret: + ```bash + kubectl apply -f proxy-secret.yaml + ``` + + **📌 NOTE** + If your proxy requires authentication, add the username to the Secret: + ```yaml + ... + stringData: + host: proxy.example.com + port: "3128" + username: myuser + ``` + The password is stored separately in a credentials file that is automatically mounted into the router pod. + +3. On the listening site, make sure link access is enabled: + ```bash + skupper site update --enable-link-access + ``` + +4. On the listening site, create a `link` resource YAML file: + ```bash + skupper link generate > link.yaml + ``` + +5. Edit the generated `link.yaml` file to add the proxy configuration in the settings section: + ```yaml + 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 2. + +6. Apply the `link` resource YAML file to create the link: + ```bash + kubectl apply -f link.yaml + ``` + +7. Check the status of the link: + ```bash + skupper link status + ``` + + **📌 NOTE** + The proxy must allow HTTP CONNECT requests to the ports used by Skupper (typically 55671 for inter-router and 45671 for edge connections). + 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 + +8. To troubleshoot connection issues, check the router logs to see the HTTP CONNECT proxy exchange: + ```bash + kubectl logs deployment/skupper-router -f + ``` + +All inter-site traffic is protected by mutual TLS and routed through the HTTP CONNECT proxy tunnel. + +There are many options to consider when linking sites using the CLI, see [CLI Reference][cli-ref], including *frequently used* options. From c634719229e2b7bb66f30802082d57a74666cf5e Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Wed, 20 May 2026 14:32:29 +0100 Subject: [PATCH 2/4] update --- input/kube-cli/site-linking.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/input/kube-cli/site-linking.md b/input/kube-cli/site-linking.md index 17650ea2..ca626e20 100644 --- a/input/kube-cli/site-linking.md +++ b/input/kube-cli/site-linking.md @@ -243,5 +243,3 @@ To link sites through a proxy, you create a Secret containing the proxy configur ``` All inter-site traffic is protected by mutual TLS and routed through the HTTP CONNECT proxy tunnel. - -There are many options to consider when linking sites using the CLI, see [CLI Reference][cli-ref], including *frequently used* options. From 8dbc686e1f7ab3f15d64605b076ebb36b5a94107 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Wed, 20 May 2026 15:57:40 +0100 Subject: [PATCH 3/4] force update --- input/kube-cli/site-linking.md | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/input/kube-cli/site-linking.md b/input/kube-cli/site-linking.md index ca626e20..c33bb3d6 100644 --- a/input/kube-cli/site-linking.md +++ b/input/kube-cli/site-linking.md @@ -187,7 +187,6 @@ To link sites through a proxy, you create a Secret containing the proxy configur port: "3128" username: myuser ``` - The password is stored separately in a credentials file that is automatically mounted into the router pod. 3. On the listening site, make sure link access is enabled: ```bash @@ -241,5 +240,9 @@ To link sites through a proxy, you create a Secret containing the proxy configur ```bash kubectl logs deployment/skupper-router -f ``` + If you update the `my-proxy-config` secret, you must update the link resource to force the controller to update the configuration, for example: + ```bash + kubectl annotate link link-to-remote-site -n east reconcile=$(date +%s) --overwrite + ``` All inter-site traffic is protected by mutual TLS and routed through the HTTP CONNECT proxy tunnel. From a4beaa2330e2feef24c2875bb19515ea7db95f23 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Mon, 25 May 2026 15:11:55 +0100 Subject: [PATCH 4/4] update based on feedback --- input/kube-cli/site-linking.md | 64 +++++++++++++++++++--------------- 1 file changed, 35 insertions(+), 29 deletions(-) diff --git a/input/kube-cli/site-linking.md b/input/kube-cli/site-linking.md index c33bb3d6..bd74771c 100644 --- a/input/kube-cli/site-linking.md +++ b/input/kube-cli/site-linking.md @@ -149,20 +149,31 @@ This feature is only available when using `link` resources, not tokens. * 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. +* 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. Make sure the proxy allows CONNECT to the listening site's router ports, typically 55671 and 45671. For example Squid configuration: +1. On the listening site, make sure link access is enabled: + ```bash + skupper site update --enable-link-access ``` - acl skupper_ports port 55671 45671 - http_access allow CONNECT skupper_ports + +2. On the listening site, create a `link` resource YAML file: + ```bash + skupper link generate > link.yaml ``` -2. On the site where you want to create a link through a proxy, create a Secret with the proxy configuration: +3. Copy the generated `link.yaml` file to the linking site. + +4. On the linking site, create a Secret with the proxy configuration: ```yaml apiVersion: v1 kind: Secret @@ -179,26 +190,21 @@ To link sites through a proxy, you create a Secret containing the proxy configur ``` **📌 NOTE** - If your proxy requires authentication, add the username to the Secret: + If your proxy requires authentication, add the username and password to the Secret: ```yaml - ... + 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 ``` -3. On the listening site, make sure link access is enabled: - ```bash - skupper site update --enable-link-access - ``` - -4. On the listening site, create a `link` resource YAML file: - ```bash - skupper link generate > link.yaml - ``` - -5. Edit the generated `link.yaml` file to add the proxy configuration in the settings section: +5. On the linking site, edit the `link.yaml` file to add the proxy configuration in the settings section: ```yaml apiVersion: skupper.io/v2alpha1 kind: Link @@ -217,9 +223,9 @@ To link sites through a proxy, you create a Secret containing the proxy configur settings: proxy-configuration: my-proxy-config ``` - where `my-proxy-config` is the name of the Secret created in step 2. + where `my-proxy-config` is the name of the Secret created in step 4. -6. Apply the `link` resource YAML file to create the link: +6. On the linking site, apply the `link` resource YAML file to create the link: ```bash kubectl apply -f link.yaml ``` @@ -228,21 +234,21 @@ To link sites through a proxy, you create a Secret containing the proxy configur ```bash skupper link status ``` + You might need to issue the command multiple times before the link is ready. - **📌 NOTE** - The proxy must allow HTTP CONNECT requests to the ports used by Skupper (typically 55671 for inter-router and 45671 for edge connections). 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` -8. To troubleshoot connection issues, check the router logs to see the HTTP CONNECT proxy exchange: - ```bash - kubectl logs deployment/skupper-router -f - ``` - If you update the `my-proxy-config` secret, you must update the link resource to force the controller to update the configuration, for example: + **📌 NOTE** + If you update the proxy Secret, you must trigger a reconciliation to apply the changes: ```bash - kubectl annotate link link-to-remote-site -n east reconcile=$(date +%s) --overwrite + kubectl annotate link 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.