Merge pull request #31490 from bergerhoffer/OSDOCS-2028

OSDOCS-2028: Adding note about additional subject for headless services

Author: bergerhoffer

modules/customize-certificates-add-service-serving.adoc

@@ -5,15 +5,16 @@
 [id="add-service-certificate_{context}"]
 = Add a service certificate
 
-To secure communication to your service, generate a
-signed serving certificate and key pair into a secret in the same
-namespace as the service.
+To secure communication to your service, generate a signed serving certificate and key pair into a secret in the same namespace as the service.
+
+The generated certificate is only valid for the internal service DNS name `<service.name>.<service.namespace>.svc`, and is only valid for internal communications. If your service is a headless service (no `clusterIP` value set), the generated certificate also contains a wildcard subject in the format of `*.<service.name>.<service.namespace>.svc`.
 
 [IMPORTANT]
 ====
-The generated certificate is only valid for the internal service DNS name
-`<service.name>.<service.namespace>.svc`, and are only valid for
-internal communications.
+Because the generated certificates contain wildcard subjects for headless services, you must not use the service CA if your client must differentiate between individual pods. In this case:
+
+* Generate individual TLS certificates by using a different CA.
+* Do not accept the service CA as a trusted CA for connections that are directed to individual pods and must not be impersonated by other pods. These connections must be configured to trust the CA that was used to generate the individual TLS certificates.
 ====
 
 .Prerequisites: