OSSM-8296 [DOC] Istio mTLS Configuration Doc

_topic_maps/_topic_map.yml

@@ -80,6 +80,8 @@ Topics:
   File: ossm-deploying-multiple-service-meshes-on-single-cluster
 - Name: Installing the Istio command line utility
   File: ossm-istioctl-tool
+- Name: Enabling mutual Transport Layer Security
+  File: ossm-enabling-mtls
 ---
 Name: Updating
 Dir: update

install/ossm-enabling-mtls.adoc

@@ -0,0 +1,31 @@
+:_content-type: ASSEMBLY
+[id="ossm-enabling-mtls_{context}"]
+= Enabling mutual Transport Layer Security
+include::_attributes/common-attributes.adoc[]
+:context: ossm-enabling-mtls
+
+
+toc::[]
+
+
+You can use {SMProductName}  for your application to customize the communication security between the complex array of microservices. Mutual Transport Layer Security (mTLS) is a protocol that enables two parties to authenticate each other.
+
+include::modules/ossm-about-mtls.adoc[leveloffset=+1]
+
+include::modules/ossm-enabling-strict-mtls-namespace.adoc[leveloffset=+1]
+
+include::modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc[leveloffset=+1]
+
+[id="ossm-validating-encrytions-kiali_{context}"]
+== Validating encrytions with Kiali
+
+The Kiali console offers several ways to validate whether or not your applications, services, and workloads have mTLS encryption enabled.
+
+The *Services Detail Overview* page displays a *Security* icon on the graph edges where at least one request with mTLS enabled is present. Also note that Kiali displays a lock icon in the *Network* section next to ports that are configured for mTLS.
+
+[role="_additional-resources"]
+[id="additional-resources-enabling-mtls"]
+== Additional resources
+* link:https://istio.io/latest/docs/tasks/security/tls-configuration/workload-min-tls-version/[Istio workload minimum TLS version configuration] (Istio documentation)
+* link:https://istio.io/latest/docs/ops/configuration/traffic-management/tls-configuration/[Understanding TLS configuration] (Istio documentation)
+* link:https://istio.io/latest/docs/concepts/security/#permissive-mode[Permissive mode] (Istio documentation)

modules/ossm-about-mtls.adoc

@@ -0,0 +1,26 @@
+// Module included in the following assemblies:
+// install/ossm-enabling-mtls.adoc
+
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-about-mtls_{context}"]
+= About mutual Transport Layer Security (mTLS)
+
+
+In {SMProduct} 3, you use the `Istio` resource instead of the `ServiceMeshControlPlane` resource to configure mTLS settings. 
+
+
+In {SMProduct} 3, you configure `STRICT` mTLS mode by using the `PeerAuthentication` and `DestinationRule` resources. You set TLS protocol versions through Istio Workload Minimum TLS Version Configuration.
+
+Review the following `Istio` resources and concepts to configure mTLS settings properly:
+
+
+`PeerAuthentication`:: defines the type of mTLS traffic a sidecar accepts. In `PERMISSIVE` mode, both plaintext and mTLS traffic are accepted. In `STRICT` mode, only mTLS traffic is allowed.
+
+
+`DestinationRule`:: configures the type of TLS traffic a sidecar sends. In `DISABLE` mode, the sidecar sends plaintext. In `SIMPLE`, `MUTUAL`, and `ISTIO_MUTUAL` modes, the sidecar establishes a TLS connection.
+
+
+`Auto mTLS`:: ensures that all inter-mesh traffic is encrypted with mTLS by default, regardless of the `PeerAuthentication` mode configuration. `Auto mTLS` is controlled by the global mesh configuration field `enableAutoMtls`, which is enabled by default in {SMProduct} 2 and 3. The mTLS setting operates entirely between sidecar proxies, requiring no changes to application or service code.
+
+By default, `PeerAuthentication` is set to `PERMISSIVE` mode, allowing sidecars in the {SMProductShortName} to accept both plain-text and mTLS-encrypted traffic.

modules/ossm-enabling-strict-mtls-namespace.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+// install/ossm-enabling-mtls.adoc
+
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-enabling-strict-mtls-namespace_{context}"]
+= Enabling strict mTLS mode by using the namespace
+
+You can restrict workloads to accept only encrypted mTLS traffic by enabling the `STRICT` mode in `PeerAuthentication`.
+
+.Example `PeerAuthentication` policy for a namespace
+[source,yaml,subs="attributes,verbatim"]
+----
+apiVersion: security.istio.io/v1
+kind: PeerAuthentication
+metadata:
+  name: default
+  namespace: <namespace>
+spec:
+  mtls:
+    mode: STRICT
+----
+
+You can enable mTLS for all destination hosts in the `<namespace>` by creating a `DestinationRule` resource with `MUTUAL` or `ISTIO_MUTUAL` mode when `auto mTLS` is disabled and `PeerAuthentication` is set to `STRICT` mode.
+
+.Example `DestinationRule` policy for a namespace
+[source,yaml,subs="attributes,verbatim"]
+----
+apiVersion: networking.istio.io/v1
+kind: DestinationRule
+metadata:
+  name: enable-mtls
+  namespace: <namespace>
+spec:
+  host: "*.<namespace>.svc.cluster.local"
+  trafficPolicy:
+   tls:
+    mode: ISTIO_MUTUAL
+----

modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc

@@ -0,0 +1,39 @@
+// Module included in the following assemblies:
+// install/ossm-enabling-mtls.adoc
+
+
+:_mod-docs-content-type: CONCEPT
+[id="ossm-enabling-strict-mtls-whole-service-mesh_{context}"]
+= Enabling strict mTLS across the whole service mesh
+
+You can configure mTLS across the entire mesh by applying the `PeerAuthentication` policy to the `istiod` namespace, such as `istio-system`. The `istiod` namespace name must match to the `spec.namespace` field of your `Istio` resource.
+
+.Example `PeerAuthentication` policy for the whole mesh
+[source,yaml,subs="attributes,verbatim"]
+----
+apiVersion: security.istio.io/v1
+kind: PeerAuthentication
+metadata:
+  name: default
+  namespace: istio-system
+spec:
+  mtls:
+    mode: STRICT
+----
+
+Additionally, create a `DestinationRule` resource to disable mTLS for communication with the API server, as it does not have a sidecar. Apply similar `DestinationRule` configurations for other services without sidecars.
+
+.Example `DestinationRule` policy for the whole mesh
+[source,yaml,subs="attributes,verbatim"]
+----
+apiVersion: networking.istio.io/v1
+kind: DestinationRule
+metadata:
+  name: api-server
+  namespace: istio-system
+spec:
+  host: kubernetes.default.svc.cluster.local
+  trafficPolicy:
+    tls:
+      mode: DISABLE
+----