Skip to content

Commit

Permalink
add docu
Browse files Browse the repository at this point in the history
  • Loading branch information
@nataliasitko
nataliasitko committed Sep 11, 2024
1 parent 31c6141 commit 706492d
Show file tree
Hide file tree
Showing 11 changed files with 190 additions and 206 deletions.
93 changes: 33 additions & 60 deletions docs/user/00-10-overview-istio-controller.md
View file
Original file line number Diff line number Diff line change
@@ -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
Expand All @@ -12,54 +22,39 @@ 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

When the Istio version is updated or the configuration of the proxies is changed, the Pods that have Istio 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 sidecars.
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.
Expand All @@ -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
Expand All @@ -96,25 +91,3 @@ Run this command to get all resources created by the Istio module:
```bash
kubectl get all|<resources-kind> -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.
49 changes: 49 additions & 0 deletions docs/user/00-15-overview-istio-setup.md
View file
Original file line number Diff line number Diff line change
@@ -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 |
Loading

0 comments on commit 706492d

Please sign in to comment.