Add comprehensive custom certificates documentation#293
Conversation
pwright
commented
Jun 10, 2026
pwright
commented
- Add detailed custom certificates section to kube-yaml/site-linking.md
- Explains default Skupper CA and certificate behavior
- Documents custom server certificate setup
- Provides kubectl/yq and manual methods for Link generation
- Includes client certificate generation workflows
- Add cross-reference in kube-cli/site-linking.md directing to YAML approach
| ``` | ||
| Apply the secret: | ||
| ```shell | ||
| kubectl delete secret skupper-site-server # delete existing secret |
There was a problem hiding this comment.
If we recommend using the skupper-site-server secret (the default one used when link-access is enabled), then better to also recommend creating it before the site is created, as it needs to exist on the namespace before the skupper.io.Certificate (CR) exists, to avoid racing with the controller.
An alternative would be to suggest a custom RouterAccess CR, instead of using --enable-link-access. Then we could also explain how to define the RouterAccess CR manuall, which has the .spec.generateTlsCredentials=false and has the .spec.tlsCredentials set to a user provided Secret.
There was a problem hiding this comment.
I've updated doc with two alternative approaches.
BTW Would deleting routeraccess when user disables linkaccess automatically be a good idea?
(then user could disable linkaccess, apply secret and re-enable linkaccess)
| spec: | ||
| ca: skupper-site-ca | ||
| client: true | ||
| subject: skupper.public.host |
There was a problem hiding this comment.
Subject here is not related to the server, so we can use something else to avoid confusion.
There was a problem hiding this comment.
change to subject: skupper-client
but i dunno if that makes sense?
|
|
||
| 3. 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`. Since Skupper always creates the `skupper-site-ca` signing `Certificate` resource on Kubernetes sites, you can use it to generate client credentials automatically. If you have replaced `skupper-site-ca` with a custom CA that Skupper cannot use for signing, you will need to provide the client `Secret` yourself. |
There was a problem hiding this comment.
If you have provided the skupper-site-ca before creating your site, then you can use it to sign your certificates, as long as both client and server certificates have been signed by it.
In this second approach you're providing the skupper-site-server yourself so in this case you must use the same CA used to sign the server certificate, to sign the client certificate.
So for the Certificate CR to be used, the respective CA must have been also used to sign the server cert.
- Add detailed custom certificates section to kube-yaml/site-linking.md - Explains default Skupper CA and certificate behavior - Documents custom server certificate setup - Provides kubectl/yq and manual methods for Link generation - Includes client certificate generation workflows - Add cross-reference in kube-cli/site-linking.md directing to YAML approach - Update overview/security.md with certificate trust explanation - Fix terminology: 'Issuer' → 'signing Certificate resource' - Fix certificate description: clarify CA hierarchy (not self-signed server cert) - Fix kubectl commands: remove incorrect .items[] path for named resources
|
|
||
| 3. 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`. If your custom server Secret's `ca.crt` field contains `skupper-site-ca`, you can use the Certificate CR to generate client credentials automatically (Skupper will sign them with `skupper-site-ca`). If your custom server Secret's `ca.crt` contains a different CA, you must provide the client `Secret` yourself, signed by that CA. |
There was a problem hiding this comment.
I believe that this sentence is a bit misleading: "If your custom server Secret's ca.crt field contains skupper-site-ca".
Maybe clearer to say something like: "If your custom server certificate was signed by the skupper-site-ca issuer or by a CA whose secret is on the listening site's namespace, you can use the Certificate CR to generate client credentials automatically".
I'd use something similar on the rest of the sentence: "If your custom server certificate was signed by a different CA, ...".
|
|
||
| 5. On the listening site, create client credentials for the connecting site. | ||
|
|
||
| Since Skupper still creates the `skupper-site-ca` signing `Certificate` resource, you can use it to generate a client secret automatically. Create a `Certificate` resource: |
There was a problem hiding this comment.
..., you can use it to generate a client secret automatically.
I'd add a note here saying something like:
..., you can use it to generate a client secret automatically **(if your server certificate was also signed by skupper-site-ca)**.
There was a problem hiding this comment.
Or maybe split step 5 into a and b approaches.
A if skupper-site-ca was used to sign the server certificate and B otherwise.
|
|
||
| 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`. | ||
|
|
||
| 6. On the listening site, create a `Link` resource YAML file. |
There was a problem hiding this comment.
On the listening site or From the listening site ?
There was a problem hiding this comment.
From the context of the listening site?
fgiorgetti
left a comment
fgiorgetti
left a comment
There was a problem hiding this comment.
Few comments, but looking better now.
2 participants
