Skip to content

Commit

Permalink
update docu
Browse files Browse the repository at this point in the history
  • Loading branch information
@nataliasitko
nataliasitko committed Sep 11, 2024
1 parent 706492d commit 0325501
Show file tree
Hide file tree
Showing 23 changed files with 128 additions and 97 deletions.
4 changes: 0 additions & 4 deletions docs/assets/istio-controller-overview-user.svg
View file

This file was deleted.

4 changes: 4 additions & 0 deletions docs/assets/istio-module-architecture.svg
View file
Loading
Sorry, something went wrong. Reload?
Sorry, we cannot display this file.
Sorry, this file is invalid so it cannot be displayed.
18 changes: 6 additions & 12 deletions docs/user/00-10-overview-istio-controller.md
View file
Original file line number Diff line number Diff line change
Expand Up @@ -18,7 +18,7 @@ Istio Controller is part of Kyma Istio Operator. Its role is to manage the insta

## Istio Version

The version of Istio is dependent on the version of Istio Controller that you use. This means that if a new version of Istio Controller introduces a new version of Istio, deploying the controller will automatically trigger an upgrade of Istio.
The version of Istio depends on the version of Istio module that you use. This means that if a new version of Istio module introduces a new version of Istio, deploying the controller automatically triggers an upgrade of Istio.

## Upgrades and Downgrades

Expand Down Expand Up @@ -52,7 +52,7 @@ Name | Value
## 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.
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).

## X-Forwarded-For HTTP Header
Expand All @@ -63,13 +63,11 @@ Due to [technical limitations of AWS Classic ELBs](https://docs.aws.amazon.com/e
Moreover, Istio Ingress Gateway Envoy does not append the private IP address of the load balancer to the XFF header, effectively removing this information from the request.

## TLS termination
The `istio-ingressgateway` Service creates a Layer 4 load balancer, that does not terminate TLS connections. Within the Istio service mesh,
the TLS termination process is handled by the Ingress Gateway Envoy proxy, which serves as a middleman between the incoming traffic and the backend services.
The `istio-ingressgateway` Service creates a Layer 4 load balancer, that does not terminate TLS connections. Within the Istio service mesh, the TLS termination process is handled by the Ingress Gateway Envoy proxy, which serves as a middleman between the incoming traffic and the backend services.

## Labeling Resources

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:

The Istio Operator's resources use the standard Kubernetes labels:

```yaml
kyma-project.io/module: istio
Expand All @@ -80,13 +78,9 @@ app.kubernetes.io/component: operator
app.kubernetes.io/part-of: istio
```
All other resources, such as the external `istio` component and its respective resources, use only the Kyma module label:

```yaml
kyma-project.io/module: istio
```
All other resources, such as the external `istio` component and its respective resources, use only the `kyma-project.io/module: istio` label.

Run this command to get all resources created by the Istio module:
To get all resources created by the Istio module, run the command:

```bash
kubectl get all|<resources-kind> -A -l kyma-project.io/module=istio
Expand Down
42 changes: 21 additions & 21 deletions docs/user/00-15-overview-istio-setup.md
View file
Original file line number Diff line number Diff line change
@@ -1,13 +1,13 @@
# 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:
Istio Operator provides baseline values for the Istio installation, which you can override in the Istio custom resource (CR). It 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/).
- Istiod (Pilot) and Ingress Gateway components are enabled by default.
- 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.
- To enhance 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/).
- Resource requests and limits for Istio sidecars are modified to best suit the needs of the evaluation and production profiles. // czy to w czymś pomaga
- [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`.
- Ingress Gateway is expanded to handle HTTPS requests on port `443`. It redirects HTTP requests to HTTPS on port `80`. //do api gateway
- 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.
Expand All @@ -16,6 +16,15 @@ Kyma Istio Operator provides baseline values for the Istio installation, which y

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 Smaller Clusters

| Component | CPU Requests | CPU Limits | Memory Requests | Memory Limits |
|-----------------|--------------|------------|-----------------|---------------|
| Proxy | 10 m | 250 m | 32 Mi | 254 Mi |
| Ingress Gateway | 10 m | 1000 m | 32 Mi | 1024 Mi |
| Pilot | 50 m | 1000 m | 128 Mi | 1024 Mi |
| CNI | 10 m | 250 m | 128 Mi | 384 Mi |

### Default Resource Configuration for Larger Clusters

| Component | CPU Requests | CPU Limits | Memory Requests | Memory Limits |
Expand All @@ -25,25 +34,16 @@ The configuration of Istio resources depends on the cluster capabilities. If you
| Pilot | 100m | 4000m | 512Mi | 2Gi |
| CNI | 100m | 500m | 512Mi | 1024Mi |

### Default Resource Configuration for Smaller Clusters
### Default Autoscaling 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 |
| Component | minReplicas | maxReplicas |
|-----------------|-------------|-------------|
| Ingress Gateway | 1 | 1 |
| Pilot | 1 | 1 |

### Default Autoscaling Configuration for Larger Clusters

| Component | Min replicas | Max replicas |
| Component | minReplicas | maxReplicas |
|-----------------|--------------|--------------|
| 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 |
| Pilot | 2 | 5 |
41 changes: 41 additions & 0 deletions docs/user/00-18-istio-version.md
View file
Original file line number Diff line number Diff line change
@@ -0,0 +1,41 @@
# Istio Version

The version of Istio depends on the version of the Istio module that you use. If a new version of Istio module introduces a new version of Istio, an upgrade of the module automatically (triggers) an upgrade of Istio.

The latest release includes the following versions of Istio and Envoy:

**Istio version:** 1.22.3

**Envoy version:** 1.30.5

## Upgrades and Downgrades
//czy to się nadaje na hp? przeciez skr nie ma wyboru jaką wersję Istio instaluje i upgrades dzieją się automatycznie, nie?

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`.

## Compatibility Mode

The Istio module applies an opinionated subset of Istio compatibilityVersion variables, 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. See [Compatibility Versions](https://istio.io/latest/docs/setup/additional-setup/compatibility-versions/).

To enable compatibility mode in the Istio module, you can set the **spec.compatibilityMode** field in the Istio CR to `true`. This allows you to mitigate breaking changes when a new release introduces an Istio upgrade.


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 variable is 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.
13 changes: 8 additions & 5 deletions docs/user/00-20-overview-service-mesh.md → docs/user/00-20-istio-sidecar-proxies.md
View file
Original file line number Diff line number Diff line change
@@ -1,20 +1,18 @@
# Istio Service Mesh

## What is the Istio service mesh?
# Istio Sidecar Proxies

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.

## 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.
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 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
<!-- markdown-link-check-disable-next-line -->
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.
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 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.

Expand All @@ -34,3 +32,8 @@ To improve the resiliency of your applications, you can use [mirroring](https://

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).

## 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).
Loading

0 comments on commit 0325501

Please sign in to comment.