Prepare Istio documentation for migration to Help Portal (#999)

* readme update

* add diagram

* add docu

* update docu

* update docs

* adjust to HP structure

* update sidear analysis scrypt

* update dita changes

* add hp changes

* update the sidebar

* update sidecar proxies doc

* update sidebar

* remove a duplicated diagram

* fix links

* remove assets

* Apply suggestions from code review

Co-authored-by: Iwona Langer <[email protected]>

* Apply suggestions from code review

* add Iwona's suggestions

* add periods

* update notes in gateway api tutorials

* fix indentation

* fix prerequisites

* replace remedy with solution

* fix the tip

* add loadbalancer link

---------

Co-authored-by: Iwona Langer <[email protected]>

docs/assets/sidecar-analysis.sh

@@ -26,9 +26,9 @@ log_pods_with () {
 }
 
 if [ -z "$target_namespace" ]; then
-    echo "Pods out of istio mesh:"
+    echo "See all Pods that are not part of the Istio service mesh:"
 
-    echo "  In namespace labeled with \"istio-injection=disabled\":"
+    echo "  Pods in namespaces labeled with \"istio-injection=disabled\":"
     disabled_namespaces=$(kubectl get ns -l "istio-injection=disabled" -o jsonpath='{.items[*].metadata.name}')
 
     for ns in $disabled_namespaces
@@ -38,7 +38,7 @@ if [ -z "$target_namespace" ]; then
         fi
     done
 
-    echo "  In namespace labeled with \"istio-injection=enabled\" with pod labeled with \"sidecar.istio.io/inject=false\":"
+    echo "  Pods labeled with \"sidecar.istio.io/inject=false\" in namespaces labeled with \"istio-injection=enabled\":"
     enabled_ns=$(kubectl get ns -l "istio-injection=enabled" -o jsonpath='{.items[*].metadata.name}')
     for ns in $enabled_ns
     do
@@ -47,7 +47,7 @@ if [ -z "$target_namespace" ]; then
         fi
     done
 
-    echo "  In not labeled ns with pod not labeled with \"sidecar.istio.io/inject=true\":"
+    echo "  Pods not labeled with \"sidecar.istio.io/inject=true\" in unlabeled namespaces:"
     not_labeled_ns=$(kubectl get ns -l "istio-injection!=disabled, istio-injection!=enabled" -o jsonpath='{.items[*].metadata.name}')
     for ns in $not_labeled_ns
     do
@@ -57,12 +57,15 @@ if [ -z "$target_namespace" ]; then
     done
 else 
     ns_label=$(kubectl get ns $target_namespace -o jsonpath='{.metadata.labels.istio-injection}')
-    echo "Pods out of istio mesh in namespace $target_namespace:"
+    echo "In the namespace $target_namespace, the following Pods are not part of the Istio service mesh:"
     if [ "$ns_label" == "enabled" ]; then
         log_pods_with $target_namespace "sidecar.istio.io/inject=false"
+        echo -e "Reason: The namespace $target_namespace has Istio sidecar proxy injection enabled, but the above Pods are labeled with \"sidecar.istio.io/inject=false\"."
     elif [ "$ns_label" == "disabled" ]; then
         log_pods_with $target_namespace
+        echo -e "Reason: The namespace $target_namespace has Istio sidecar proxy injection disabled, so none of its Pods have been injected with an Istio sidecar proxy."
     else
         log_pods_with $target_namespace "sidecar.istio.io/inject!=true"
+        echo -e "Reason: The namespace $target_namespace is not labeled and the above Pods are not labeled with "sidecar.istio.io/inject!=true"."
     fi
 fi

docs/user/00-00-istio-sidecar-proxies.md

@@ -0,0 +1,35 @@
+# Istio Sidecar Proxies
+
+Learn more about Istio sidecar proxies: what they are, what benefits they bring, how and when the Istio module restarts workloads with Istio sidecar proxy injection enabled.
+
+## What Is a Service Mesh?
+
+A service mesh is an infrastructure layer that handles service-to-service communication, proxying, service discovery, traceability, and security, independently of the code of the services. To deliver this functionality, the Istio module uses the [Istio service mesh](https://istio.io/docs/concepts/what-is-istio/) that is customized for the specific needs of an implementation. The main principle of the Istio service mesh is to inject Pods of every service with Istio sidecar proxy, which is an extended version of the Envoy proxy. Envoy intercepts the communication between the services and regulates it by applying and enforcing the rules you create.
+
+## Purpose and Benefits of Istio Sidecar Proxies
+
+By default, Istio installed as part of the Istio module is configured with automatic Istio sidecar proxy injection disabled. This means that none of your workloads' Pods, except those in the `kyma-system` namespace, get their own sidecar proxy container running next to the application. When Istio sidecar proxy injection is disabled for a service or for a namespace, you must manage mutual TLS (mTLS) traffic in services or at a namespace level by creating [DestinationRule](https://istio.io/docs/reference/config/networking/destination-rule/) and [PeerAuthentication](https://istio.io/docs/tasks/security/authentication/authn-policy/) resources. With an Istio sidecar proxy injected, a resource becomes part of the Istio service mesh, which brings the following benefits that would be complex to manage otherwise.
+
+### Secure Communication
+<!-- markdown-link-check-disable-next-line -->
+The Istio module sets [peer authentication](https://istio.io/latest/docs/concepts/security/#peer-authentication) to cluster-wide `STRICT` mode. This ensures that your workload only accepts [mutual TLS (mTLS) traffic](https://www.cloudflare.com/learning/access-management/what-is-mutual-tls/) where both client and server certificates are validated to ensure that all traffic is encrypted. This provides each service with a strong identity and a reliable system for managing keys and certificates.
+
+Also, with Istio sidecar proxy injected, you can perform [request authentication](https://istio.io/latest/docs/reference/config/security/request_authentication/) for your service. Istio enables request authentication with JSON Web Token (JWT) validation using a custom authentication provider.
+
+### Observability
+
+Istio sidecar proxies enhance tracing capabilities by performing global tracing and forwarding the data to a tracing backend using the [OTLP protocol](https://opentelemetry.io/docs/reference/specification/protocol/). When you integrate your application into the Istio service mesh, you can easily access advanced observability features without needing to implement complex instrumentation within the application.
+
+### Traffic Management
+
+If you have an Istio sidecar proxy injected into every workload, you can use Istio’s traffic routing rules without additional configuration. See [Traffic management](https://istio.io/latest/docs/concepts/traffic-management/).
+
+[Traffic shifting](https://istio.io/latest/docs/tasks/traffic-management/traffic-shifting/) and [request routing](https://istio.io/latest/docs/tasks/traffic-management/request-routing/) allows you to use techniques like canary releases and A/B testing to make your software release process faster and more reliable. To improve the resiliency of your applications, you can use [mirroring](https://istio.io/latest/docs/tasks/traffic-management/mirroring/) and [fault injection](https://istio.io/latest/docs/tasks/traffic-management/fault-injection/) for testing and audit purposes.
+
+### Resiliency
+
+Application resiliency is an important topic within traffic management. Traditionally, application libraries implemented resiliency features like timeouts, retries, and circuit breakers. However, with service mesh, you can delegate such tasks to the mesh, and the same configuration options work regardless of the programming language of your application. See [Network Resilience and Testing](https://istio.io/latest/docs/concepts/traffic-management/#network-resilience-and-testing).
+
+## Restart of Workloads with Enabled Istio Sidecar Injection
+
+When the Istio version is updated or the configuration of Istio sidecar proxies changes, the Pods that have Istio sidecar proxy injection enabled are automatically restarted. This is possible for all resources that allow for a rolling restart. If Istio is uninstalled, the workloads are restarted again to remove the Istio sidecar proxies. However, if a resource is a Job, a ReplicaSet that is not managed by any Deployment, or a Pod that is not managed by any other resource, the restart cannot be performed automatically. In such cases, a warning is logged, and you must manually restart the resources. The Istio module does not restart an Istio sidecar proxy if it has a custom image set. See [Resource Annotations](https://istio.io/latest/docs/reference/config/annotations/#SidecarProxyImage).

docs/user/00-10-istio-version.md

@@ -0,0 +1,29 @@
+# Istio Version
+Learn which version of Istio the Istio module contains and how to enable compatibility mode with the previous minor version of Istio.
+
+The version of Istio depends on the version of the Istio module that you use. If a new version of the Istio module introduces a new version of Istio, an upgrade of the module causes an automatic upgrade of Istio.
+
+The latest release includes the following versions of Istio and Envoy:  
+
+**Istio version:** 1.22.3
+
+**Envoy version:** 1.30.5
+
+## Compatibility Mode
+
+Compatibility mode allows you to revert certain changes in Istio's behavior, and it is recommended only when you encounter compatibility issues with the new version of Istio. The Istio module supports compatibility with the previous minor version of Istio. For example, for the version of the Istio module that contains Istio 1.21, you can apply a compatibility version of Istio 1.20. See [Compatibility Versions](https://istio.io/latest/docs/setup/additional-setup/compatibility-versions/).
+
+> [!WARNING]
+> You can use the compatibility mode to retain the behavior of the current Istio version before a new version of the Istio module with a higher version of Istio is released. Then, the compatibility is first set to a minor version lower than the one you are currently using. If this lower version’s behavior is not compatible with your current mesh setup, some configurations may be broken until the new release of the Istio module is rolled out.
+
+To enable compatibility mode, set the **spec.compatibilityMode** field in the Istio CR to `true`.
+
+When you set `spec.compatibilityMode: true`, the Istio module applies an opinionated subset of Istio **compatibilityVersion** variables. The compatibility version of Istio 1.22 includes the following Istio Pilot and Istio Proxy environment variables:
+
+| Istio Component | Name                                 | Value   |
+|-----------------|--------------------------------------|---------|
+| Istio Pilot     | **ENABLE_DELIMITED_STATS_TAG_REGEX** | `false` |
+| Istio Proxy     | **ENABLE_DEFERRED_CLUSTER_CREATION** | `false` |
+| Istio Proxy     | **ENABLE_DELIMITED_STATS_TAG_REGEX** | `false` |
+
+To learn more about the changes that specific compatibility versions revert, follow the [Istio release notes](https://github.com/kyma-project/istio/releases).