diff --git a/docs/user/00-10-overview-istio-controller.md b/docs/user/00-10-overview-istio-controller.md index 46200b9b0e..16aed59734 100644 --- a/docs/user/00-10-overview-istio-controller.md +++ b/docs/user/00-10-overview-istio-controller.md @@ -1,9 +1,19 @@ # Istio Controller +- [Overview](#overview) +- [Istio Version](#istio-version) +- [Upgrades and Downgrades](#upgrades-and-downgrades) +- [Compatibility Mode](#compatibility-mode) +- [Restart of Workloads with Enabled Sidecar Injection](#restart-of-workloads-with-enabled-sidecar-injection) +- [X-Forwarded-For HTTP Header](#x-forwarded-for-http-header) +- [TLS termination](#tls-termination) +- [Labeling Resources](#labeling-resources) + + ## Overview Istio Controller is part of Kyma Istio Operator. Its role is to manage the installation of Istio as defined by the Istio custom resource (CR). The controller is responsible for: -- Installing, upgrading, and uninstalling Istio +- Installing, upgrading, and uninstalling Istio. - Restarting workloads that have a proxy sidecar to ensure that these workloads are using the correct Istio version. ## Istio Version @@ -12,14 +22,32 @@ The version of Istio is dependent on the version of Istio Controller that you us ## Upgrades and Downgrades -You can only skip a version of Kyma Istio Operator if the difference between the minor version of Istio it contains and the minor version of Istio you're using is not greater than one (for example, 1.2.3 -> 1.3.0). +You can only skip a version of the Istio module if the difference between the minor version of Istio it contains and the minor version of Istio you're using is not greater than one (for example, 1.2.3 -> 1.3.0). If the difference is greater than one minor version (for example, 1.2.3 -> 1.4.0), the reconciliation fails. The same happens if you try to update the major version (for example, 1.2.3 -> 2.0.0) or downgrade the version. Such scenarios are not supported and cause the Istio CR to be in the `Warning` state with the `Ready` condition set to `false` and the reason being `IstioVersionUpdateNotAllowed`. -## Istio Custom Resource +## Compatibility Mode + +To enable compatibility mode in the Istio module, you can set the **spec.compatibilityMode** field in the Istio CR. This allows you to mitigate breaking changes when a new release introduces an Istio upgrade. The Istio module applies an opinionated subset of Istio compatibilityVersion, and supports compatibility with the previous minor version of Istio. For example, the Istio module with Istio 1.21.0 applies a compatibility version of Istio 1.20. For more information, see [Compatibility Versions](https://istio.io/latest/docs/setup/additional-setup/compatibility-versions/). + + +The following Istio Pilot environment variables are applied when you set `spec.compatibilityMode: true` in Istio CR: -The `istios.operator.kyma-project.io` CustomResourceDefinition (CRD) describes the Istio CR that is used to manage the Istio installation. To learn more, read the [Istio CR documentation](04-00-istio-custom-resource.md). +Name | Value +---------------------------------------|-------- +**ENABLE_ENHANCED_RESOURCE_SCOPING** | `false` +**ENABLE_RESOLUTION_NONE_TARGET_PORT** | `false` + +The following Istio Proxy environment variables are applied when you set `spec.compatibilityMode: true` in Istio CR: + +Name | Value +--------------------|-------- +**ISTIO_DELTA_XDS** | `false` + + +> [!WARNING] +> You can use the compatibility mode to retain the behavior of the current Istio version when a new version of the Istio module with a higher version of Istio is released. Then, the compatibility will be 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. ## Restart of Workloads with Enabled Sidecar Injection @@ -27,39 +55,6 @@ When the Istio version is updated or the configuration of the proxies is changed 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. Istio Operator 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). -## Status Codes - -| Code | Description | -|:------------:|:---------------------------------------------| -| `Ready` | Controller finished reconciliation. | -| `Processing` | Controller is installing or upgrading Istio. | -| `Deleting` | Controller is uninstalling Istio. | -| `Error` | An error occurred during reconciliation. | -| `Warning` | Controller is misconfigured. | - -Conditions: - -| CR state | Type | Status | Reason | Message | -|------------|------------------------------|--------|------------------------------------|------------------------------------------------------------------------------------------| -| Ready | Ready | True | ReconcileSucceeded | Reconciliation succeeded | -| Error | Ready | False | ReconcileFailed | Reconciliation failed | -| Warning | Ready | False | OlderCRExists | This Istio custom resource is not the oldest one and does not represent the module state | -| Processing | Ready | False | IstioInstallNotNeeded | Istio installation is not needed | -| Processing | Ready | False | IstioInstallSucceeded | Istio installation succeeded | -| Processing | Ready | False | IstioUninstallSucceeded | Istio uninstallation succeded | -| Error | Ready | False | IstioInstallUninstallFailed | Istio install or uninstall failed | -| Error | Ready | False | IstioCustomResourceMisconfigured | Istio custom resource has invalid configuration | -| Warning | Ready | False | IstioCustomResourcesDangling | Istio deletion blocked because of existing Istio custom resources | -| Processing | Ready | False | CustomResourcesReconcileSucceeded | Custom resources reconciliation succeeded | -| Error | Ready | False | CustomResourcesReconcileFailed | Custom resources reconciliation failed | -| Processing | ProxySidecarRestartSucceeded | True | ProxySidecarRestartSucceeded | Proxy sidecar restart succeeded | -| Error | ProxySidecarRestartSucceeded | False | ProxySidecarRestartFailed | Proxy sidecar restart failed | -| Processing | ProxySidecarRestartSucceeded | False | ProxySidecarPartiallySucceeded | Proxy sidecar restart partially succeeded | -| Warning | ProxySidecarRestartSucceeded | False | ProxySidecarManualRestartRequired | Proxy sidecar manual restart is required for some workloads | -| Processing | Ready | False | IngressGatewayReconcileSucceeded | Istio Ingress Gateway reconciliation succeeded | -| Error | Ready | False | IngressGatewayReconcileFailed | Istio Ingress Gateway reconciliation failed | -| Warning | Ready | False | IstioVersionUpdateNotAllowed | Update to the new Istio version is not allowed | - ## X-Forwarded-For HTTP Header The XFF header conveys the client IP address and the chain of intermediary proxies that the request traversed to reach the Istio service mesh. @@ -73,7 +68,7 @@ the TLS termination process is handled by the Ingress Gateway Envoy proxy, which ## Labeling Resources -In accordance with the decision [Consistent Labeling of Kyma Modules](https://github.com/kyma-project/community/issues/864), the Istio Operator resources use the standard Kubernetes labels: +In accordance with the decision [Consistent Labeling of Kyma Modules](https://github.com/kyma-project/community/issues/864), the Istio Operator's resources use the standard Kubernetes labels: ```yaml @@ -96,25 +91,3 @@ Run this command to get all resources created by the Istio module: ```bash kubectl get all| -A -l kyma-project.io/module=istio ``` - -## Compatibility Mode - -To enable compatibility mode in the Istio module, you can set the **spec.compatibilityMode** field in the Istio CR. This allows you to mitigate breaking changes when a new release introduces an Istio upgrade. The Istio module applies an opinionated subset of Istio compatibilityVersion, and supports compatibility with the previous minor version of Istio. For example, the Istio module with Istio 1.21.0 applies a compatibility version of Istio 1.20. For more information, see [Compatibility Versions](https://istio.io/latest/docs/setup/additional-setup/compatibility-versions/). - - -The following Istio Pilot environment variables are applied when you set `spec.compatibilityMode: true` in Istio CR: - - Name | Value - ----------------------------------------|--------- - **ENABLE_ENHANCED_RESOURCE_SCOPING** | `false` - **ENABLE_RESOLUTION_NONE_TARGET_PORT** | `false` - -The following Istio Proxy environment variables are applied when you set `spec.compatibilityMode: true` in Istio CR: - - Name | Value - ---------------------|--------- - **ISTIO_DELTA_XDS** | `false` - - -> [!WARNING] -> You can use the compatibility mode to retain the behavior of the current Istio version when a new version of the Istio module with a higher version of Istio is released. Then, the compatibility will be 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. diff --git a/docs/user/00-15-overview-istio-setup.md b/docs/user/00-15-overview-istio-setup.md new file mode 100644 index 0000000000..ad29da3636 --- /dev/null +++ b/docs/user/00-15-overview-istio-setup.md @@ -0,0 +1,49 @@ +# Default Istio Configuration + +Kyma Istio Operator provides baseline values for the Istio installation, which you can override in the Istio custom resource (CR). Istio Operator applies the following changes to customize Istio: + +- Within Kyma Istio Operator, components like Istiod (Pilot) and Ingress Gateway are enabled by default. +- For security and performance, both [Istio control plane and data plane](https://istio.io/latest/docs/ops/deployment/architecture/) use distroless version of Istio images. Those images are not Debian-based and are slimmed down to reduce any potential attack surface and increase startup time. To learn more, see [Harden Docker Container Images](https://istio.io/latest/docs/ops/configuration/security/harden-docker-images/). +- Automatic sidecar injection is disabled by default. +- Resource requests and limits for Istio sidecars are modified to best suit the needs of the evaluation and production profiles. +- [Mutual TLS (mTLS)](https://istio.io/docs/concepts/security/#mutual-tls-authentication) is enabled cluster-wide in the `STRICT` mode. +- Ingress Gateway is expanded to handle HTTPS requests on port `443`. It redirects HTTP requests to HTTPS on port `80`. +- The use of HTTP 1.0 is enabled in the outbound HTTP listeners by the **PILOT_HTTP10** flag set in the Istiod component environment variables. +- No Egress limitations are implemented - all applications deployed in the Kyma cluster can access outside resources without limitations. +- The CNI component is provided as a DaemonSet, meaning that one replica is present on every node of the target cluster. + +## Configuration Based on the Cluster Size + +The configuration of Istio resources depends on the cluster capabilities. If your cluster has less than 5 total virtual CPU cores or its total memory capacity is less than 10 Gigabytes, the default setup for resources and autoscaling is lighter. If your cluster exceeds both of these thresholds, Istio is installed with the higher resource configuration. + +### Default Resource Configuration for Larger Clusters + +| Component | CPU Requests | CPU Limits | Memory Requests | Memory Limits | +|-----------------|--------------|------------|-----------------|---------------| +| Proxy | 10m | 1000m | 192Mi | 1024Mi | +| Ingress Gateway | 100m | 2000m | 128Mi | 1024Mi | +| Pilot | 100m | 4000m | 512Mi | 2Gi | +| CNI | 100m | 500m | 512Mi | 1024Mi | + +### Default Resource Configuration for Smaller Clusters + +| Component | CPU Requests | CPU Limits | Memory Requests | Memory Limits | +|-----------------|--------------|------------|-----------------|---------------| +| Proxy | 10m | 250m | 32Mi | 254Mi | +| Ingress Gateway | 10m | 1000m | 32Mi | 1024Mi | +| Pilot | 50m | 1000m | 128Mi | 1024Mi | +| CNI | 10m | 250m | 128Mi | 384Mi | + +### Default Autoscaling Configuration for Larger Clusters + +| Component | Min replicas | Max replicas | +|-----------------|--------------|--------------| +| Pilot | 2 | 5 | +| Ingress Gateway | 3 | 10 | + +### Default Autoscaling Configuration for Smaller Clusters + +| Component | Min replicas | Max replicas | +|-----------------|--------------|--------------| +| Pilot | 1 | 1 | +| Ingress Gateway | 1 | 1 | \ No newline at end of file diff --git a/docs/user/00-20-overview-service-mesh.md b/docs/user/00-20-overview-service-mesh.md index 8bbd99d178..c666910382 100644 --- a/docs/user/00-20-overview-service-mesh.md +++ b/docs/user/00-20-overview-service-mesh.md @@ -1,10 +1,36 @@ # Istio 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, Kyma uses the [Istio](https://istio.io/docs/concepts/what-is-istio/) service mesh that is customized for the specific needs of the implementation. +## What is the Istio 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](https://istio.io/docs/concepts/what-is-istio/) service mesh that is customized for the specific needs of the implementation. The main principle of the Istio service mesh is to inject Pods of every service with the Envoy sidecar proxy. Envoy intercepts the communication between the services and regulates it by applying and enforcing the rules you create. -By default, Istio installed by Kyma Istio Operator has [mutual TLS (mTLS)](https://istio.io/docs/concepts/security/#mutual-tls-authentication) disabled. See how to [enable sidecar proxy injection](./operation-guides/02-20-enable-sidecar-injection.md). You can manage mTLS traffic in services or at a namespace level by creating [DestinationRules](https://istio.io/docs/reference/config/networking/destination-rule/) and [Peer Authentications](https://istio.io/docs/tasks/security/authentication/authn-policy/). If you disable sidecar injection for a service or for a namespace, you must manage their traffic configuration by creating appropriate DestinationRules and Peer Authentications. +## Purpose and Benefits of Istio Sidecars + +By default, Istio installed by Istio Operator is configured with automatic Istio sidecar proxy injection disabled. This means that none of the Pods of your workloads, except any workloads in the `kyma-system` namespace, get their own sidecar proxy container running next to your application. You can manage 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. If you disable sidecar injection for a service or for a namespace, you must manage their traffic configuration by creating appropriate DestinationRule and PeerAuthentication resources. + +With an Istio sidecar, the resource becomes part of the Istio service mesh, which brings the following benefits that would be complex to manage otherwise. + +### Secure Communication + +In Kyma's [default Istio configuration](./00-40-overview-istio-setup.md), [peer authentication](https://istio.io/latest/docs/concepts/security/#peer-authentication) is set to cluster-wide `STRICT` mode. This ensures that your workload only accepts [mutual TLS 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. + +Another security benefit of having a sidecar proxy is that 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 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/). By being part of the Istio service mesh, you can access advanced observability features that would otherwise require complex instrumentation code within your application. + +### Traffic Management + +[Traffic management](https://istio.io/latest/docs/concepts/traffic-management/) is an important feature of service mesh. If you have the sidecar injected into every workload, you can use Istio’s traffic routing rules without additional configuration. + +With [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/), developers can use techniques like canary releases and A/B testing to make their 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, resiliency features like timeouts, retries, and circuit breakers were implemented by application libraries. However, with service mesh, you can delegate such tasks to the mesh, and the same configuration options will 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). -> [!NOTE] ->For security and performance, we use the [distroless](https://istio.io/docs/ops/configuration/security/harden-docker-images/) version of Istio images. Those images are not Debian-based and are slimmed down to reduce any potential attack surface and increase startup time. diff --git a/docs/user/00-30-overview-istio-sidecars.md b/docs/user/00-30-overview-istio-sidecars.md deleted file mode 100644 index 4edac6e6da..0000000000 --- a/docs/user/00-30-overview-istio-sidecars.md +++ /dev/null @@ -1,38 +0,0 @@ -# Purpose and Benefits of Istio Sidecars - -## Purpose of Istio Sidecars - -By default, Istio installed by Kyma Istio Operator is configured with automatic [Istio proxy sidecar injection](https://istio.io/docs/setup/kubernetes/additional-setup/sidecar-injection/) disabled. This means that none of the Pods of your workloads (such as deployments and StatefulSets, except any workloads in the `kyma-system` namespace) get their own sidecar proxy container running next to your application. - -With an Istio sidecar, the resource becomes part of the Istio service mesh, which brings the following benefits that would be complex to manage otherwise. - -## Secure Communication - -In Kyma's [default Istio configuration](./00-40-overview-istio-setup.md), [peer authentication](https://istio.io/latest/docs/concepts/security/#peer-authentication) is set to cluster-wide `STRICT` mode. This ensures that your workload only accepts [mutual TLS 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. - -Another security benefit of having a sidecar proxy is that 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 - -Furthermore, Istio 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/). - -Kiali is another tool that allows you to monitor the service mesh. You can configure Istio to export metrics necessary to support Kiali features that facilitate managing, visualizing, and troubleshooting your service mesh. Follow the [Kiali example](https://github.com/kyma-project/examples/tree/main/kiali) to learn how to deploy Kiali to your Kyma cluster. - -By being part of the Istio service mesh, you can access advanced observability features that would otherwise require complex instrumentation code within your application. - -## Traffic Management - -[Traffic management](https://istio.io/latest/docs/concepts/traffic-management/) is an important feature of service mesh. If you have the sidecar injected into every workload, you can use this traffic management without additional configuration. - -With [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/), developers can use techniques like canary releases and A/B testing to make their 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, resiliency features like timeouts, retries, and circuit breakers were implemented by application libraries. However, with service mesh, you can delegate such tasks to the mesh, and the same configuration options will work regardless of the programming language of your application. You can read more about it in [Network resilience and testing](https://istio.io/latest/docs/concepts/traffic-management/#network-resilience-and-testing). - -## Operation Guides and Troubleshooting - -[Check if you have automatic Istio sidecar proxy injection enabled](./operation-guides/02-10-check-if-sidecar-injection-is-enabled.md) and learn how to [enable automatic Istio sidecar proxy injection](./operation-guides/02-20-enable-sidecar-injection.md). -Follow the troubleshooting guides if you experience [issues with Istio sidecar injection](./troubleshooting/03-30-istio-no-sidecar.md) or have [incompatible Istio sidecar version after Kyma Istio Operator's upgrade](./troubleshooting/03-40-incompatible-istio-sidecar-version.md). diff --git a/docs/user/00-40-overview-istio-setup.md b/docs/user/00-40-overview-istio-setup.md deleted file mode 100644 index 7b8139ffdf..0000000000 --- a/docs/user/00-40-overview-istio-setup.md +++ /dev/null @@ -1,18 +0,0 @@ -# Default Istio Setup - -This document provides an overview of the default setup for Istio. Kyma Istio Operator uses the [Istio library](https://github.com/istio/istio/tree/master/operator) for installing Istio. Within Kyma Istio Operator, components like Istiod (Pilot) and Ingress Gateway are enabled by default. - - -## Istio Module-Specific Configuration - -These configuration changes are applied to customize Istio: - -- Both [Istio control plane and data plane](https://istio.io/latest/docs/ops/deployment/architecture/) use distroless images. To learn more, read about [Harden Docker Container Images](https://istio.io/latest/docs/ops/configuration/security/harden-docker-images/). -- Automatic sidecar injection is disabled by default. See how to [enable sidecar proxy injection](./operation-guides/02-20-enable-sidecar-injection.md). -- Resource requests and limits for Istio sidecars are modified to best suit the needs of the evaluation and production profiles. -- [Mutual TLS (mTLS)](https://istio.io/docs/concepts/security/#mutual-tls-authentication) is enabled cluster-wide in the `STRICT` mode. -- Ingress Gateway is expanded to handle HTTPS requests on port `443`. It redirects HTTP requests to HTTPS on port `80`. -- The use of HTTP 1.0 is enabled in the outbound HTTP listeners by the `PILOT_HTTP10` flag set in the Istiod component environment variables. -- The [Istio custom resource (CR)](./04-00-istio-custom-resource.md) defines the kind of data used to manage Istio. -- No Egress limitations are implemented - all applications deployed in the Kyma cluster can access outside resources without limitations. -- The self-signed CA certificate's bit length is set to `4096` instead of the default `2048`. \ No newline at end of file diff --git a/docs/user/00-50-resource-configuration.md b/docs/user/00-50-resource-configuration.md deleted file mode 100644 index 322cae06cb..0000000000 --- a/docs/user/00-50-resource-configuration.md +++ /dev/null @@ -1,51 +0,0 @@ -# Default Resources and Autoscaling Configuration for Kyma Istio Operator - -Kyma Istio Operator provides baseline values for the Istio installation. Those values can be overridden with configuration in the Istio custom resource (CR). - -## Cluster-Based Default Configuration - -Istio Controller installs Istio with a configuration that depends in the cluster capabilities. If your cluster has less than 5 total virtual CPU cores or its total memory capacity is less than 10 Gigabytes, the default setup for resources and autoscaling is lighter. If your cluster exceeds both of these thresholds, Istio is installed with the higher resource configuration. - -### Default Resource Configuration for Larger Clusters - -| Component | | CPU | Memory | -|-----------------|----------|-------|--------| -| Proxy | Limits | 1000m | 1024Mi | -| Proxy | Requests | 10m | 192Mi | -| Ingress Gateway | Limits | 2000m | 1024Mi | -| Ingress Gateway | Requests | 100m | 128Mi | -| Pilot | Limits | 4000m | 2Gi | -| Pilot | Requests | 100m | 512Mi | -| CNI | Limits | 500m | 1024Mi | -| CNI | Requests | 100m | 512Mi | - -### Default Autoscaling Configuration for Larger Clusters - -| Component | Min replicas | Max replicas | -|-----------------|--------------|--------------| -| Pilot | 2 | 5 | -| Ingress Gateway | 3 | 10 | - -### Default Resource Configuration for Smaller Clusters - -| Component | | CPU | Memory | -|-----------------|----------|-------|--------| -| Proxy | Limits | 250m | 254Mi | -| Proxy | Requests | 10m | 32Mi | -| Ingress Gateway | Limits | 1000m | 1024Mi | -| Ingress Gateway | Requests | 10m | 32Mi | -| Pilot | Limits | 1000m | 1024Mi | -| Pilot | Requests | 50m | 128Mi | -| CNI | Limits | 250m | 384Mi | -| CNI | Requests | 10m | 128Mi | - -### Default Autoscaling Configuration for Smaller Clusters - -| Component | Min replicas | Max replicas | -|-----------------|--------------|--------------| -| Pilot | 1 | 1 | -| Ingress Gateway | 1 | 1 | - -### CNI Autoscaling - -The CNI component is provided as a DaemonSet, meaning that one replica is present on every node of the target cluster. diff --git a/docs/user/04-00-istio-custom-resource.md b/docs/user/04-00-istio-custom-resource.md index c7781a4d59..17db1622c0 100644 --- a/docs/user/04-00-istio-custom-resource.md +++ b/docs/user/04-00-istio-custom-resource.md @@ -10,15 +10,16 @@ kubectl get crd istios.operator.kyma-project.io -o yaml You are only allowed to use one Istio CR, which you must create in the `kyma-system` namespace. If the namespace contains multiple Istio CRs, the oldest one reconciles the module. Any additional Istio CR is placed in the `Warning` state. -## Specification -This table lists all the possible parameters of the given resource together with their descriptions: +## Custom Resource Parameters + +This table lists all the possible parameters of Istio CR together with their descriptions: ### Spec | Parameter | Type | Description | |-------------------------------------------------------------|----------------|---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -| **compatibilityMode** | bool | Enables compatibility mode in Istio. | +| **compatibilityMode** | bool | Enables compatibility mode in Istio. See [Compatibility Mode](./00-10-overview-istio-controller.md#compatibility-mode). | | **components.cni** | object | Defines component configuration for Istio CNI DaemonSet. | | **components.cni.k8s.affinity** | object | Affinity is a group of affinity scheduling rules. To learn more, read about affininty in the [Istio documentation](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#Affinity). | | **components.cni.k8s.resources** | object | Defines [Kubernetes resources requests and limits configuration](https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/). For more information, read about Resources in the [Istio documentation](https://istio.io/latest/docs/reference/config/istio.operator.v1alpha1/#Resources ). | @@ -45,7 +46,7 @@ This table lists all the possible parameters of the given resource together with | **experimental.pilot.enableAlphaGatewayAPI** | bool | Enables support for alpha Kubernetes Gateway API. | | **experimental.pilot.enableMultiNetworkDiscoverGatewayAPI** | bool | Enables support for multi-network discovery in Kubernetes Gateway API. | -**Authorizer** +### Authorizer | Parameter | Type | Description | |------------------------|---------|-----------------------------------------------------------------------------------------------------------------------------------------------| @@ -54,7 +55,8 @@ This table lists all the possible parameters of the given resource together with | **port** (required) | integer | Specifies the port number of the external authorizer used to make the authorization request. | | **headers** | headers | Specifies headers to be included, added, or forwarded during authorization. | -**Headers** + +### Headers | Parameter | Type | Description | |--------------------------|------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| @@ -79,7 +81,44 @@ This table lists all the possible parameters of the given resource together with | **conditions.​status** (required) | string | Represents the status of the condition. The value is either `True`, `False`, or `Unknown`. | | **conditions.​type** | string | Provides a short description of the condition. | -### Annotations +## Istio CR's State + +See the possible values of the **status.state** field: + +| Code | Description | +|:------------:|:---------------------------------------------------| +| `Ready` | Istio Controller finished reconciliation. | +| `Processing` | Istio Controller is installing or upgrading Istio. | +| `Deleting` | Istio Controller is uninstalling Istio. | +| `Error` | An error occurred during reconciliation. | +| `Warning` | Istio Controller is misconfigured. | + +## Istio CR's Status Conditions + +See the possible values of the **status.conditions** fields: + +| Istio CR's State | Type | Status | Reason | Message | +|--------------|--------------------------------|---------|-------------------------------------|------------------------------------------------------------------------------------------| +| `Ready` | `Ready` | `True` | `ReconcileSucceeded` | Reconciliation succeeded | +| `Error` | `Ready` | `False` | `ReconcileFailed` | Reconciliation failed | +| `Warning` | `Ready` | `False` | `OlderCRExists` | This Istio custom resource is not the oldest one and does not represent the module state | +| `Processing` | `Ready` | `False` | `IstioInstallNotNeeded` | Istio installation is not needed | +| `Processing` | `Ready` | `False` | `IstioInstallSucceeded` | Istio installation succeeded | +| `Processing` | `Ready` | `False` | `IstioUninstallSucceeded` | Istio uninstallation succeded | +| `Error` | `Ready` | `False` | `IstioInstallUninstallFailed` | Istio install or uninstall failed | +| `Error` | `Ready` | `False` | `IstioCustomResourceMisconfigured` | Istio custom resource has invalid configuration | +| `Warning` | `Ready` | `False` | `IstioCustomResourcesDangling` | Istio deletion blocked because of existing Istio custom resources | +| `Processing` | `Ready` | `False` | `CustomResourcesReconcileSucceeded` | Custom resources reconciliation succeeded | +| `Error` | `Ready` | `False` | `CustomResourcesReconcileFailed` | Custom resources reconciliation failed | +| `Processing` | `ProxySidecarRestartSucceeded` | `True` | `ProxySidecarRestartSucceeded` | Proxy sidecar restart succeeded | +| `Error` | `ProxySidecarRestartSucceeded` | `False` | `ProxySidecarRestartFailed` | Proxy sidecar restart failed | +| `Processing` | `ProxySidecarRestartSucceeded` | `False` | `ProxySidecarPartiallySucceeded` | Proxy sidecar restart partially succeeded | +| `Warning` | `ProxySidecarRestartSucceeded` | `False` | `ProxySidecarManualRestartRequired` | Proxy sidecar manual restart is required for some workloads | +| `Processing` | `Ready` | `False` | `IngressGatewayReconcileSucceeded` | Istio Ingress Gateway reconciliation succeeded | +| `Error` | `Ready` | `False` | `IngressGatewayReconcileFailed` | Istio Ingress Gateway reconciliation failed | +| `Warning` | `Ready` | `False` | `IstioVersionUpdateNotAllowed` | Update to the new Istio version is not allowed | + +## External Name Annotation To retain the behavior of `EXTERNAL_NAME` that was present in versions of Istio prior to 1.21, you can configure the `ENABLE_EXTERNAL_NAME_ALIAS` environment variable in the Istio pilot. To do this, add the following annotation to the Istio CR: diff --git a/docs/user/README.md b/docs/user/README.md index b6a44a69ce..badd1871d9 100644 --- a/docs/user/README.md +++ b/docs/user/README.md @@ -17,7 +17,7 @@ The latest release includes the following versions of Istio and Envoy: ## Architecture -[Istio Operator Architecture](../assets/istio-controller-overview-user.svg) +![Istio Operator Architecture](../assets/istio-controller-overview-user.svg) ### Istio Operator @@ -29,16 +29,9 @@ Istio Controller manages the installation of Istio as defined by the Istio custo For more information, see [Istio Controller](./00-10-overview-istio-controller.md). -## Upgrades and Downgrades - -You can only skip a version of Kyma Istio Operator if the difference between the minor version of Istio it contains and the minor version of Istio you're using is not greater than one (for example, 1.2.3 -> 1.3.0). -If the difference is greater than one minor version (for example, 1.2.3 -> 1.4.0), the reconciliation fails. -The same happens if you try to update the major version (for example, 1.2.3 -> 2.0.0) or downgrade the version. -Such scenarios are not supported and cause the Istio CR to be in the `Warning` state with the `Ready` condition set to `false` and the reason being `IstioVersionUpdateNotAllowed`. - ## API / Custom Resource Definitions -The `istios.operator.kyma-project.io` CustomResourceDefinition (CRD) describes the Istio CR that is used to manage the Istio installation. See [Istio Custom Resource](https://kyma-project.io/#/istio/user/04-00-istio-custom-resource?id=istio-custom-resource). +The `istios.operator.kyma-project.io` CustomResourceDefinition (CRD) describes the Istio CR that Istio Controller uses to manage the installation of Istio. See [Istio Custom Resource](https://kyma-project.io/#/istio/user/04-00-istio-custom-resource?id=istio-custom-resource). ## Resource Consumption diff --git a/docs/user/technical-reference/05-00-istio-controller-parameters.md b/docs/user/technical-reference/05-00-istio-controller-parameters.md index 35ec615d4b..a4ab456538 100644 --- a/docs/user/technical-reference/05-00-istio-controller-parameters.md +++ b/docs/user/technical-reference/05-00-istio-controller-parameters.md @@ -2,10 +2,6 @@ You can configure [Istio Controller](../00-10-overview-istio-controller.md) using various parameters. All options are listed in this document. -## Reconciliation Interval - -By default, Kyma Istio Operator is reconciled every 10 hours or whenever the custom resource is changed. You can adjust this interval by modifying the operator's parameters. For example, you can set the **-reconciliation-interval** parameter to `120s`. - ## All Configuration Parameters | Parameter | Description | Default | @@ -18,7 +14,7 @@ By default, Kyma Istio Operator is reconciled every 10 hours or whenever the cus | **-metrics-bind-address** | Specifies the address the metric endpoint binds to. | `:8090` | | **-rate-limiter-burst** | Indicates the burst value for the bucket rate limiter. | `200` | | **-rate-limiter-frequency** | Indicates the bucket rate limiter frequency, which signifies the number of events per second. | `30` | -| **-reconciliation-interval** | Indicates the time-based reconciliation interval. | `10h0m0s` | +| **-reconciliation-interval** | Indicates the time-based reconciliation interval of Istio Operator. By default, Istio Operator is reconciled every 10 hours or whenever the custom resource changes. You can adjust this interval by modifying this parameter. | `10h0m0s` | | **-zap-devel** | Allows for switching between development mode and production mode. In development mode, the default parameter values are: `(encoder=consoleEncoder,logLevel=Debug,stackTraceLevel=Warn)`. In production mode, the default parameter values are: `(encoder=jsonEncoder,logLevel=Info,stackTraceLevel=Error)`. | `true` | | **-zap-encoder** | Indicates the way of Zap log encoding. The value is either `json` or `console`. | None | | **-zap-log-level** | Indicates Zap Level used to configure the verbosity of logging. The value is either `debug`, `info`, `error`, or any integer value greater than 0, corresponding to custom debug levels of increasing verbosity. | None | diff --git a/docs/user/troubleshooting/03-00-istio-basic-diagnostics.md b/docs/user/troubleshooting/03-00-istio-basic-diagnostics.md index c3af342690..f321febb72 100644 --- a/docs/user/troubleshooting/03-00-istio-basic-diagnostics.md +++ b/docs/user/troubleshooting/03-00-istio-basic-diagnostics.md @@ -1,10 +1,10 @@ # Istio Basic Diagnostics -If you are experiencing issues with the cluster, follow the steps below to troubleshoot the problem before you contact us. This guide is designed to help you identify the root cause of the problem, which might not necessarily be related to Istio itself but rather to the misconfiguration of Istio custom resources (CRs) or other cluster resources. +If you are experiencing issues with the cluster, follow the steps below to troubleshoot the problem before you report it. This guide is designed to help you identify the root cause of the problem, which might not necessarily be related to Istio itself but rather to the misconfiguration of Istio custom resources (CRs) or other cluster resources. ## Network Connectivity -1. Verify if Istio CR is in the `Warning` state. If it is, check the warning message and conditions. This might be helpful at the beginning of the investigation. +1. Verify the state of Istio CR. If it is in the `Warning` state, check the warning message and conditions. This might be helpful at the beginning of the investigation. 2. Verify that no [NetworkPolicies](https://kubernetes.io/docs/concepts/services-networking/network-policies/) are affecting the connectivity by blocking traffic between Pods in the service mesh. To find all NetworkPolicies, run the command `kubectl get networkpolicies -A`. 3. The configuration of the following kinds of resources can affect the connectivity in the service mesh. Verify that those resources are configured as intended: - [`DestinationRule`](https://istio.io/latest/docs/reference/config/networking/destination-rule/) @@ -13,7 +13,7 @@ If you are experiencing issues with the cluster, follow the steps below to troub - [`AuthorizationPolicy`](https://istio.io/latest/docs/reference/config/security/authorization-policy/) - [`RequestAuthentication`](https://istio.io/latest/docs/reference/config/security/request_authentication/) 4. Use the command `istioctl analyze -A` to check for potential issues in the Istio configuration and see suggestions on how to fix them. -5. To enable the access logs of the Envoy proxy, follow the guide [Envoy Access Logs](https://istio.io/latest/docs/tasks/observability/logs/access-log/). In the access logs, you can find the field **response_flags**. The response flags DC (Downstream client terminated connection) and UC (Upstream terminated connection) are not within the scope of the Istio module team, as they relate to the behavior of the client (DC) or the workload application (UC). +5. To enable the access logs of the Envoy proxy, follow the guide [Envoy Access Logs](https://istio.io/latest/docs/tasks/observability/logs/access-log/). In the access logs, you can find the field **response_flags**. The response flags DC (Downstream client terminated connection) and UC (Upstream terminated connection) are not within the scope of the Istio module, as they relate to the behavior of the client (DC) or the workload application (UC). ## Sidecar Injection @@ -21,6 +21,6 @@ If you are experiencing issues with the cluster, follow the steps below to troub 2. Check if you correctly enabled sidecar injection. See the guide [Check If You Have Istio Sidecar Proxy Injection Enabled](https://kyma-project.io/#/istio/user/operation-guides/02-10-check-if-sidecar-injection-is-enabled?id=check-if-you-have-istio-sidecar-proxy-injection-enabled) for more information. 3. Make sure the Pod does not have `hostNetwork: true` in the spec. If it does, the sidecar will not be injected. -## Still Something Does Not Work? +## Still Something Doesn't Work? 1. Check the [Official Istio Troubleshooting Guide](https://github.com/istio/istio/wiki/Troubleshooting-Istio). 2. Look for already existing issues in the [Istio module repository](https://github.com/kyma-project/istio/issues). If none of them is related to your problem, create a new issue. \ No newline at end of file diff --git a/docs/user/tutorials/01-00-x-forwarded-for-header.md b/docs/user/tutorials/01-00-x-forwarded-for-header.md index e06dce01db..0aee59c1a8 100644 --- a/docs/user/tutorials/01-00-x-forwarded-for-header.md +++ b/docs/user/tutorials/01-00-x-forwarded-for-header.md @@ -1,7 +1,7 @@ # Forward a Client IP in the X-Forwarded-For Header -Many applications need to know the client IP address of an originating request to behave properly. Usual use cases include workloads that require the client IP address to restrict their access. The ability to provide client attributes to services has long been a staple of reverse proxies, which use the X-Forwarded-For (XFF) header to forward client attributes to destination workloads. For more information on XFF, see -the [IETF’s RFC documentation](https://datatracker.ietf.org/doc/html/rfc7239) and [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-for). +Many applications must know the client IP address of an originating request to behave properly. Usual use cases include workloads that require the client IP address to restrict their access. The ability to provide client attributes to services has long been a staple of reverse proxies, which use the X-Forwarded-For (XFF) header to forward client attributes to destination workloads. For more information on XFF, see +the [IETF’s RFC documentation](https://datatracker.ietf.org/doc/html/rfc7239) and [Envoy documentation](https://www.envoyproxy.io/docs/envoy/latest/configuration/http/http_conn_man/headers#x-forwarded-for). ## Prerequisites @@ -13,8 +13,7 @@ the [IETF’s RFC documentation](https://datatracker.ietf.org/doc/html/rfc7239) ### Configure the Number of Trusted Proxies in the Istio Custom Resource Applications rely on reverse proxies to forward the client IP address in a request using the XFF header. However, due to -the variety of network topologies, you must specify the configuration property **numTrustedProxies**, so that the client address can be extracted correctly. This property indicates the number of trusted proxies deployed -in front of the Istio Gateway proxy. +the variety of network topologies, you must specify the configuration property **numTrustedProxies**, so that the client address can be extracted correctly. This property indicates the number of trusted proxies deployed in front of the Istio Gateway proxy. Add **numTrustedProxies** to the Istio custom resource: @@ -33,7 +32,7 @@ Run the following command: 4. Select **Save**. -### Configure Gateway External Traffic Policy in the Istio Custom Resource (GCP and Azure only) +### Configure Gateway External Traffic Policy in the Istio CR (Only Required for GCP and Azure) If you are using a GCP or Azure cluster, you must also set the **gatewayExternalTrafficPolicy** to `Local` in order to include the client's IP address in the XFF header. Skip this step if you're using a different cloud service provider. @@ -60,7 +59,7 @@ Run the following command: #### **Kyma Dashboard** -1. Navigate to **Cluster Details** and select **Modify Modules**. +1. Go to **Cluster Details** and select **Modify Modules**. 2. Choose the Istio module and select **Edit**. 3. In the `General` section, set the Gateway external traffic policy to `Local`. 4. Select **Save**. @@ -68,13 +67,28 @@ Run the following command: ### Create a Workload for Verification -1. [Create an HttpBin workload](https://kyma-project.io/#/api-gateway/user/tutorials/01-00-create-workload). -2. Export the following values as environment variables. +1. Export the name of the namespace in which you want to deploy the HTTPBin Service: + + ```bash + export NAMESPACE={NAMESPACE_NAME} + ``` + +2. Create a namespace with Istio injection enabled and deploy the HTTPBin Service: + + ```bash + kubectl create ns $NAMESPACE + kubectl label namespace $NAMESPACE istio-injection=enabled --overwrite + kubectl create -n $NAMESPACE -f https://raw.githubusercontent.com/istio/istio/release-1.22/samples/tcp-echo/tcp-echo.yaml + ``` + +3. Export the following values as environment variables. + ```bash export DOMAIN_TO_EXPOSE_WORKLOADS={GATEWAY_DOMAIN} export GATEWAY={GATEWAY_NAMESPACE}/GATEWAY_NAME} - ``` -3. Expose the HttpBin workload using a VirtualService. + ``` + +4. Expose the HttpBin workload using a VirtualService. ```bash cat <