From 7ade38fb40fe3ee7c79483e3b837f16dac68c5e1 Mon Sep 17 00:00:00 2001 From: shreyasiddhartha Date: Mon, 24 Feb 2025 16:34:42 +0530 Subject: [PATCH] OSSM-8296 --- _topic_maps/_topic_map.yml | 2 + install/ossm-enabling-mtls.adoc | 31 +++++++++++++++ modules/ossm-about-mtls.adoc | 26 +++++++++++++ .../ossm-enabling-strict-mtls-namespace.adoc | 39 +++++++++++++++++++ ...abling-strict-mtls-whole-service-mesh.adoc | 39 +++++++++++++++++++ 5 files changed, 137 insertions(+) create mode 100644 install/ossm-enabling-mtls.adoc create mode 100644 modules/ossm-about-mtls.adoc create mode 100644 modules/ossm-enabling-strict-mtls-namespace.adoc create mode 100644 modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc diff --git a/_topic_maps/_topic_map.yml b/_topic_maps/_topic_map.yml index 27f5cdb06df6..fe41e1bb6e33 100644 --- a/_topic_maps/_topic_map.yml +++ b/_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 diff --git a/install/ossm-enabling-mtls.adoc b/install/ossm-enabling-mtls.adoc new file mode 100644 index 000000000000..f6ea92f36670 --- /dev/null +++ b/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) \ No newline at end of file diff --git a/modules/ossm-about-mtls.adoc b/modules/ossm-about-mtls.adoc new file mode 100644 index 000000000000..b9a4ac403f36 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/modules/ossm-enabling-strict-mtls-namespace.adoc b/modules/ossm-enabling-strict-mtls-namespace.adoc new file mode 100644 index 000000000000..78b6e1aef5ec --- /dev/null +++ b/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: +spec: + mtls: + mode: STRICT +---- + +You can enable mTLS for all destination hosts in the `` 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: +spec: + host: "*..svc.cluster.local" + trafficPolicy: + tls: + mode: ISTIO_MUTUAL +---- diff --git a/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc b/modules/ossm-enabling-strict-mtls-whole-service-mesh.adoc new file mode 100644 index 000000000000..69f4a7ed3076 --- /dev/null +++ b/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 +---- \ No newline at end of file