From 492eb929b4df55f8c24dc78ef74f90d391ffab96 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Wed, 15 Oct 2025 12:26:57 +0100 Subject: [PATCH 1/3] using env vars --- input/kube-yaml/site-configuration.md | 12 ++ input/kube-yaml/site-linking.md | 153 ++++++++++++++++++++++++++ 2 files changed, 165 insertions(+) diff --git a/input/kube-yaml/site-configuration.md b/input/kube-yaml/site-configuration.md index f3057cb9..7c06c01d 100644 --- a/input/kube-yaml/site-configuration.md +++ b/input/kube-yaml/site-configuration.md @@ -28,6 +28,18 @@ Procedure This YAML creates a site named `my-site` in the `west` namespace. Specifying the namespace is not required if the context is set to the namespace where you want to create the site. + If you need to link to this site, enable link access: + ```yaml + apiVersion: skupper.io/v2alpha1 + kind: Site + metadata: + name: my-site + namespace: west + spec: + linkAccess: default + ``` + + 2. Create the site: ```bash kubectl apply -f my-site.yaml diff --git a/input/kube-yaml/site-linking.md b/input/kube-yaml/site-linking.md index e69de29b..bdd0f486 100644 --- a/input/kube-yaml/site-linking.md +++ b/input/kube-yaml/site-linking.md @@ -0,0 +1,153 @@ + +# Linking sites on Kubernetes using YAML + +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. + +Terminology: + +* Connecting site: The site that initiates the link connection. +* Listening site: The site receives the the link connection. + +The link direction is not significant, and is typically determined by ease of connectivity. For example, if `east` is behind a firewall and `west` is a cluster on the public cloud, linking from `east` to `west` is the easiest option. + +There are two ways of linking sites on Kubernetes using YAML: + +* Using `AccessGrant` and `AccessToken` resources to produce a token on the listening site. The link is created when the `AccessToken` is applied to the connecting site. + +* Using a `Link` resource on the listening site. The link is created when the `Link` is applied to the connecting site. + +The advantage of using `AccessGrant` and `AccessToken` resources is that you can limit token usage. By default, a token can only be used once and must be used within 15 minutes to link sites. + +The procedures below describe linking an existing site. +Typically, it is easier to configure a site, links and services in a set of files and then create a configured site by placing all the YAML files in a directory, for example `local` and then using the following command to + + +## Linking sites using `AccessGrant` and `AccessToken` resources + +**Prerequisites** + +* Two sites +* The listening site must have `link-access` enabled. For example: + ```yaml + apiVersion: skupper.io/v2alpha1 + kind: Site + metadata: + name: west + namespace: west + spec: + linkAccess: default + ``` +To link sites, you create `AccessGrant` and `AccessToken` resources on the listening site and apply the `AccessToken` resource on the connecting site to create the link. + + +**AccessGrant** is a server-side permission on a listening site that allows redemption of access tokens to create links. It exposes a URL, a secret code, and a CA for issuing certificates. The number of redemptions and the length of the redemption window is configurable. + +**AccessToken** is short-lived, usually single-use credential that contains the AccessGrant URL and secret code. A connecting site redeems this token to establish a link to the listening site. + +**Procedure** + +1. On the listening site, for example `west` namespace, create an `AccessGrant` resource: + ```yaml + apiVersion: skupper.io/v2alpha1 + kind: AccessGrant + metadata: + name: grant-west + spec: + redemptionsAllowed: 2 # default 1 + expirationWindow: 25m # default 15m + ``` + For example, if you created `accessgrant.yaml`: + ```bash + kubectl apply -f accessgrant.yaml + ``` +3. Populate environment variables to allow token generation: + + ```bash + NS="west" + GRANT="grant-west" + + CODE=$(kubectl -n "$NS" get accessgrant "$GRANT" -o jsonpath='{.status.code}') + CA_RAW=$(kubectl -n "$NS" get accessgrant "$GRANT" -o jsonpath='{.status.ca}') + # Use bash's %q to escape safely for a single-line YAML string + CA_ESCAPED=$(printf '%q' "$CA_RAW") + + URL=$(kubectl -n "$NS" get accessgrant "$GRANT" -o jsonpath='{.status.url}') + ``` + These environment variable settings support the next step of generating the token. + +4. Create a token YAML file: + ```bash + cat > token.yaml < +## 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** + +* A local kube site +* A Kubernetes 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: + ```bash + skupper site update --enable-link-access + ``` +2. Create a `link` resource YAML file: + ```bash + skupper link generate > + ``` + where `` is the name of a YAML file that is saved on your local filekube. + +3. Apply the `link` resource YAML file on a local kube site to create a link: + ```bash + mv ~/.local/share/skupper/namespaces/default/input/resources/ + skupper kube setup --force + ``` + where `` is the name of a YAML file that is saved on your local filekube. + + The path shown is specific to the `default` namespace. + If you are configuring a different namespace, use that name instead. + + The site is recreated and you see some of the internal resources that are not affected, for example: + ``` + Sources will be consumed from namespace "default" + 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-local-ca/tls.crt + 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-local-ca/tls.key + 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-local-ca/ca.crt + 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-site-ca/tls.crt + 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-site-ca/tls.key + 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-site-ca/ca.crt + 2025/03/09 22:43:15 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-service-ca/tls.crt + 2025/03/09 22:43:15 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-service-ca/tls.key + 2025/03/09 22:43:15 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-service-ca/ca.crt + + ``` + +4. Check the status of the link: + ```bash + skupper link status + ``` + The output shows the link name: + ``` + $ skupper link status + NAME STATUS + link-west Ok + ``` + You can now expose services on the application network. From edf637814de13272fbf22fffae26234865a77ffa Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Wed, 15 Oct 2025 12:56:12 +0100 Subject: [PATCH 2/3] update and correct --- input/kube-yaml/site-linking.md | 111 ++++++++------------------------ 1 file changed, 27 insertions(+), 84 deletions(-) diff --git a/input/kube-yaml/site-linking.md b/input/kube-yaml/site-linking.md index bdd0f486..5ba2a333 100644 --- a/input/kube-yaml/site-linking.md +++ b/input/kube-yaml/site-linking.md @@ -6,20 +6,10 @@ Once sites are linked, services can be exposed and consumed across the applicati Terminology: * Connecting site: The site that initiates the link connection. -* Listening site: The site receives the the link connection. +* Listening site: The site receives the link connection. The link direction is not significant, and is typically determined by ease of connectivity. For example, if `east` is behind a firewall and `west` is a cluster on the public cloud, linking from `east` to `west` is the easiest option. -There are two ways of linking sites on Kubernetes using YAML: - -* Using `AccessGrant` and `AccessToken` resources to produce a token on the listening site. The link is created when the `AccessToken` is applied to the connecting site. - -* Using a `Link` resource on the listening site. The link is created when the `Link` is applied to the connecting site. - -The advantage of using `AccessGrant` and `AccessToken` resources is that you can limit token usage. By default, a token can only be used once and must be used within 15 minutes to link sites. - -The procedures below describe linking an existing site. -Typically, it is easier to configure a site, links and services in a set of files and then create a configured site by placing all the YAML files in a directory, for example `local` and then using the following command to ## Linking sites using `AccessGrant` and `AccessToken` resources @@ -56,98 +46,51 @@ To link sites, you create `AccessGrant` and `AccessToken` resources on the liste redemptionsAllowed: 2 # default 1 expirationWindow: 25m # default 15m ``` - For example, if you created `accessgrant.yaml`: + For example, if you created `accessgrant.yaml`, apply and check status: ```bash kubectl apply -f accessgrant.yaml + + kubectl get accessgrants + + NAME REDEMPTIONS ALLOWED REDEMPTIONS MADE EXPIRATION STATUS MESSAGE + grant-west 20 20 2025-10-15T12:33:04Z Ready OK ``` -3. Populate environment variables to allow token generation: +2. On the listening site, populate environment variables to allow token generation: ```bash - NS="west" - GRANT="grant-west" - - CODE=$(kubectl -n "$NS" get accessgrant "$GRANT" -o jsonpath='{.status.code}') - CA_RAW=$(kubectl -n "$NS" get accessgrant "$GRANT" -o jsonpath='{.status.ca}') - # Use bash's %q to escape safely for a single-line YAML string - CA_ESCAPED=$(printf '%q' "$CA_RAW") + CODE="$(kubectl get accessgrant grant-west -o template --template '{{ .status.code }}')" + URL="$(kubectl get accessgrant grant-west -o template --template '{{ .status.url }}')" + CA_RAW="$(kubectl get accessgrant grant-west -o template --template '{{ .status.ca }}')" - URL=$(kubectl -n "$NS" get accessgrant "$GRANT" -o jsonpath='{.status.url}') ``` These environment variable settings support the next step of generating the token. -4. Create a token YAML file: +3. On the listening site, create a token YAML file: ```bash cat > token.yaml < -## 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** - -* A local kube site -* A Kubernetes 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: - ```bash - skupper site update --enable-link-access - ``` -2. Create a `link` resource YAML file: +4. On the connecting site, apply the token and check status: ```bash - skupper link generate > + kubectl apply -f token.yaml + kubectl get accesstokens + NAME URL REDEEMED STATUS MESSAGE + token-to-west https://10.110.160.132:9090/87426fa9-5623-49af-a612-47d33b7a4200 true Ready OK ``` - where `` is the name of a YAML file that is saved on your local filekube. - -3. Apply the `link` resource YAML file on a local kube site to create a link: +5. On the connecting site, check link status: ```bash - mv ~/.local/share/skupper/namespaces/default/input/resources/ - skupper kube setup --force - ``` - where `` is the name of a YAML file that is saved on your local filekube. - - The path shown is specific to the `default` namespace. - If you are configuring a different namespace, use that name instead. - - The site is recreated and you see some of the internal resources that are not affected, for example: - ``` - Sources will be consumed from namespace "default" - 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-local-ca/tls.crt - 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-local-ca/tls.key - 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-local-ca/ca.crt - 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-site-ca/tls.crt - 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-site-ca/tls.key - 2025/03/09 22:43:14 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-site-ca/ca.crt - 2025/03/09 22:43:15 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-service-ca/tls.crt - 2025/03/09 22:43:15 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-service-ca/tls.key - 2025/03/09 22:43:15 WARN certificate will not be overwritten path=~/.local/share/skupper/namespaces/default/runtime/issuers/skupper-service-ca/ca.crt - - ``` - -4. Check the status of the link: - ```bash - skupper link status - ``` - The output shows the link name: - ``` - $ skupper link status - NAME STATUS - link-west Ok - ``` - You can now expose services on the application network. + kubectl get link + NAME STATUS REMOTE SITE MESSAGE + token-to-west Ready my-site OK + ``` \ No newline at end of file From 1bc4f3371c15abb7a0e3c9615032f203b29867a5 Mon Sep 17 00:00:00 2001 From: Paul Wright Date: Wed, 15 Oct 2025 17:23:19 +0100 Subject: [PATCH 3/3] update based on feedback --- input/kube-yaml/site-linking.md | 29 ++++++++++++++++++++++++----- 1 file changed, 24 insertions(+), 5 deletions(-) diff --git a/input/kube-yaml/site-linking.md b/input/kube-yaml/site-linking.md index 5ba2a333..3487c9c9 100644 --- a/input/kube-yaml/site-linking.md +++ b/input/kube-yaml/site-linking.md @@ -29,10 +29,15 @@ The link direction is not significant, and is typically determined by ease of co ``` To link sites, you create `AccessGrant` and `AccessToken` resources on the listening site and apply the `AccessToken` resource on the connecting site to create the link. +**AccessGrant** is a permission on a listening site that allows redemption of access tokens to create links. +The component it gives permission to is the **GrantServer** which is a HTTPS server that ultimately sets up the link. -**AccessGrant** is a server-side permission on a listening site that allows redemption of access tokens to create links. It exposes a URL, a secret code, and a CA for issuing certificates. The number of redemptions and the length of the redemption window is configurable. +The GrantServer provides a URL, a secret code, and a cert that are bundled together to form an AccessToken. +The number of times an AccessToken can be redeemed and how long it remains active are both configurable. +On OpenShift, the GrantServer is exposed by a Route, while other systems use a LoadBalancer to make it accessible. -**AccessToken** is short-lived, usually single-use credential that contains the AccessGrant URL and secret code. A connecting site redeems this token to establish a link to the listening site. +**AccessToken** is short-lived, usually single-use credential that contains the AccessGrant URL, secret code and a cert to establish a secure connection to the GrantServer. +A connecting site redeems this token for a `Link` resource to establish a link to the listening site. **Procedure** @@ -58,13 +63,17 @@ To link sites, you create `AccessGrant` and `AccessToken` resources on the liste 2. On the listening site, populate environment variables to allow token generation: ```bash - CODE="$(kubectl get accessgrant grant-west -o template --template '{{ .status.code }}')" URL="$(kubectl get accessgrant grant-west -o template --template '{{ .status.url }}')" + CODE="$(kubectl get accessgrant grant-west -o template --template '{{ .status.code }}')" CA_RAW="$(kubectl get accessgrant grant-west -o template --template '{{ .status.ca }}')" ``` These environment variable settings support the next step of generating the token. + * URL is the URL of the GrantServer + * CODE is the secret code to access the GrantServer + * CA_RAW is the cert required to establish a HTTPS connection to the GrantServer + 3. On the listening site, create a token YAML file: ```bash cat > token.yaml <