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)
|
|
||
| 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.
If you provided your own certificate, without using skupper-site-ca to sign it, then you must issue a client certificate yourself and just create a secret, similarly to what you've done earlier with the server cert. The client secret needs to be signed by the same CA (ca.crt) that signed the server certificate.
This approach is valid only if the server certificate was also signed by skupper-site-ca.
| 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
| | Site delete/recreate needed | Yes, to prevent overwrite | No | | ||
| | Skupper overwrites your cert | Yes, unless pre-created | Never | | ||
|
|
||
| **Site-specific context** |
There was a problem hiding this comment.
@fgiorgetti After rereading, I added this section to help orient users, wdyt?
There was a problem hiding this comment.
Certificate CR can also be a listening site concern, if a CA is provided, as the Certificate CR can reference the respective CA secret to sign the server certificate.
For a connecting site to use a Certificate CR, the CA that will be used to sign the public certificate must also be present on the respective namespace. If a RouterAccess has a reference to a custom secret signed by some external CA (no secret on the namespace), then client Certificates won't be used.
| | Site delete/recreate needed | Yes, to prevent overwrite | No | | ||
| | Skupper overwrites your cert | Yes, unless pre-created | Never | | ||
|
|
||
| **Site-specific context** |
There was a problem hiding this comment.
Certificate CR can also be a listening site concern, if a CA is provided, as the Certificate CR can reference the respective CA secret to sign the server certificate.
For a connecting site to use a Certificate CR, the CA that will be used to sign the public certificate must also be present on the respective namespace. If a RouterAccess has a reference to a custom secret signed by some external CA (no secret on the namespace), then client Certificates won't be used.
|
|
||
| 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, ...".
2 participants
