draft of tls concepts

kubernetes/con-tls.adoc

@@ -0,0 +1,105 @@
+include::../partials/attributes.adoc[]
+// Type: concept
+[id="understanding-tls"] 
+= Understanding TLS certificates for Kubernetes sites
+
+By default, the traffic between sites is encrypted using mutual TLS providing secure communication between Kubernetes clusters.
+The traffic between internal components is also encrypted using mutual TLS.
+Optionally, the communication between an application and the {skupper-name} router can be encrypted using TLS.
+
+This section describes the Kubernetes secrets involved and when the certificates can be replaced with user-provided certificates.
+
+== Overview
+
+By default, {skupper-name} creates Certificate Authority certificates to support TLS for the following:
+
+(1)Within a site:: traffic flowing between the router and the service controller (and optionally the flow collector).
+
+(2)Between sites:: traffic flowing between a router in one site and a router in another site.
+
+(3)Between an application and a router:: traffic flowing between an application and a router.
+
+When running in Kubernetes, {skupper-name} expects specific Secrets to exist in each namespace where it is installed. 
+These Secrets, which contain TLS keys and certificates for each of the scenarios above, are located in predefined locations. 
+
+When you create a site using the CLI or create a site declaratively using YAML, {skupper-name} creates the required Secrets if they do not already exist.
+That gives you the ability to use your certificates to populate the Secrets before the site is created. 
+
+== (1) Mutual TLS with a site
+
+Within a Skupper site, both the skupper-service-controller and the skupper-flow-collector (optional, but required for the console) need to connect to the skupper router. 
+These connections are secured using mutual TLS, and the required keys and certificates are stored in specific Secrets, all sharing the prefix skupper-local-:
+
+skupper-local-client:: Contains the key, and the certificate used by the skupper-service-controller and the skupper-flow-collector.
+skupper-local-server:: Contains the key, and the certificate used by the skupper router.
+
+If these Secrets do not exist, Skupper creates them using a certificate authority (CA) to sign the certificates. 
+
+For this purpose, Skupper generates another secret:
+
+skupper-local-ca:: Contains a key and a self-signed certificate. 
+
+NOTE: Skupper will only use this secret if skupper-local-server and skupper-local-client are not populated.
+
+If skupper-local-client and skupper-local-server Secrets are provided by the user, there is no requirement for the skupper-local-ca Secret.
+
+== (2) Mutual TLS between sites
+
+== (3) TLS between a router and applications
+
+== Summary of TLS related secrets
+
+[cols=5*]
+|===
+
+| Scenario | Secret Name | Components | Category | Notes 
+
+| (1) Mutual TLS within a site 
+| skupper-local-ca 
+| core 
+| Certificate authority for signing skupper-local-client and skupper-local-server secrets. 
+| Created by default. Not used if user provides other secrets. 
+
+|  
+| skupper-local-client 
+| skupper-service-controller, skupper-flow-collector 
+| Secures connections to the skupper-router using mutual TLS. 
+| The flow collector is an optional component, required for console.
+
+|  
+| skupper-local-server 
+| skupper-router 
+| Secures incoming connections from skupper-service-controller and skupper-flow-collector. 
+| The flow collector is an optional component, required for console 
+
+
+| (2) Mutual TLS between Skupper Sites 
+| skupper-site-ca 
+| core 
+| CA for signing certificates in skupper-site-server and client certificates for links. 
+|  Created by default. Not used if user provides other secrets. 
+
+|  
+| skupper-site-server 
+| skupper-router 
+| Secures incoming connections from other Skupper sites. | Contains key, certificate, and CA certificate. 
+
+|
+| <link-specific-secret> 
+| skupper-router 
+| Used by the initiating site's router to establish a link with another Skupper site. 
+| Labeled with `skupper.io/type=connection-token`
+
+| (3) TLS between Skupper Router and Applications | skupper-service-ca 
+| Skupper router, external services 
+| Manages CA certificates for TLS termination and connections. 
+| Created by default. Not used if user provides other secrets. 
+|
+
+|  
+| skupper-service-client 
+| Skupper router, external services 
+| Secures TLS termination at the router and TLS connections to services. 
+| Users can provide their own secrets via \--tls-cert and annotations.
+
+|===