Document Eventing istio integration

Signed-off-by: Pierangelo Di Pilato <[email protected]>
knative · Feb 26, 2024 · 132497b · 132497b
1 parent 71b2d6f
commit 132497b
Show file tree

Hide file tree

Showing 2 changed files with 79 additions and 5 deletions.
diff --git a/docs/eventing/experimental-features/README.md b/docs/eventing/experimental-features/README.md
@@ -67,12 +67,13 @@ data:
 The following table gives an overview of the available experimental features in
 Knative Eventing:
 
-| Feature                                                    | Flag                   | Description                                                                                                                                                                                                        | Maturity |
-|------------------------------------------------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------| -------- |
+| Feature                                                    | Flag                   | Description                                                                                                                                                                                                        | Maturity                   |
+|------------------------------------------------------------|------------------------|--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------------------|
 | [DeliverySpec.RetryAfterMax field](delivery-retryafter.md) | `delivery-retryafter`  | Specify a maximum retry duration that overrides HTTP [Retry-After](https://datatracker.ietf.org/doc/html/rfc7231#section-7.1.3) headers when calculating backoff times for retrying **429** and **503** responses. | Alpha, disabled by default |
-| [DeliverySpec.Timeout field](delivery-timeout.md)          | `delivery-timeout`     | When using the `delivery` spec to configure event delivery parameters, you can use  the`timeout` field to specify the timeout for each sent HTTP request.                                                          | Beta, enabled by default |
+| [DeliverySpec.Timeout field](delivery-timeout.md)          | `delivery-timeout`     | When using the `delivery` spec to configure event delivery parameters, you can use  the`timeout` field to specify the timeout for each sent HTTP request.                                                          | Beta, enabled by default   |
 | [KReference.Group field](kreference-group.md)              | `kreference-group`     | Specify the API `group` of `KReference` resources without the API version.                                                                                                                                         | Alpha, disabled by default |
 | [Knative reference mapping](kreference-mapping.md)         | `kreference-mapping`   | Provide mappings from a [Knative reference](https://github.com/knative/specs/blob/main/specs/eventing/overview.md#destination) to a templated URI.                                                                 | Alpha, disabled by default |
-| [New trigger filters](new-trigger-filters.md)              | `new-trigger-filters`  | Enables a new Trigger `filters` field that supports a set of powerful filter expressions.                                                                                                                          | Beta, enabled by default |
+| [New trigger filters](new-trigger-filters.md)              | `new-trigger-filters`  | Enables a new Trigger `filters` field that supports a set of powerful filter expressions.                                                                                                                          | Beta, enabled by default   |
 | [Transport encryption](transport-encryption.md)            | `transport-encryption` | Enables components to encrypt traffic using TLS by exposing HTTPS URL.                                                                                                                                             | Alpha, disabled by default |
-| [Sender Identity](sender-identity.md)            | `authentication-oidc` | Enables Eventing sources to send authenticated requests and addressables to require authenticated requests. | Alpha, disabled by default |
+| [Sender Identity](sender-identity.md)                      | `authentication-oidc`  | Enables Eventing sources to send authenticated requests and addressables to require authenticated requests.                                                                                                        | Alpha, disabled by default |
+| [Eventing with Istio](istio-integration.md)                | `istio`                | Enables Eventing components to communicate with workloads in an Istio mesh.                                                                                                                                        | Beta, disabled by default  |
diff --git a/docs/eventing/experimental-features/istio-integration.md b/docs/eventing/experimental-features/istio-integration.md
@@ -0,0 +1,73 @@
+# Eventing integration with Istio service mesh
+
+**Flag name**: `istio`
+
+**Stage**: Beta, disabled by default
+
+**Tracking issue**: [#6596](https://github.com/knative/eventing/issues/6596)
+
+## Overview
+
+Administrators can use Istio with Eventing to encrypt, authenticate and authorize requests to
+Eventing components.
+
+## Prerequisites
+
+- In order to enable the istio integration, you will need to install Istio by
+  following [the Istio installation guides](https://istio.io/latest/docs/setup/install/).
+
+## Installation
+
+Some Eventing components use services of type `ExternalName` and with such services, Istio need to
+be manually configured to connect to such services using mutual TLS.
+
+Eventing releases a controller that automatically configures Istio so that any pod that is part of
+an Istio mesh can communicate with Eventing components that are also part of the same Istio mesh.
+
+1. Create the Eventing namespace and enable Istio injection:
+   ```shell
+    kubectl create namespace knative-eventing --dry-run=client -oyaml | kubectl apply -f -
+    kubectl label namespace knative-eventing istio-injection=enabled
+    ```
+2. [Follow Eventing installation](./../../install)
+
+3. Install `eventing-istio-controller`:
+    ```shell
+    kubectl apply -f {{ artifact(org="knative-extensions", repo="eventing-istio",file="eventing-istio.yaml")}}
+    ```
+4. Verify `eventing-istio-controller` is ready:
+    ```shell
+    kubectl get deployment -n knative-eventing
+    ```
+   Example output:
+    ```shell
+    NAME                        ...   READY
+    eventing-istio-controller   ...   True 
+    # other deployments omitted ...
+    ```
+
+## Enable istio integration
+
+The `istio` feature flag is an enum configuration that configures the `eventing-istio-controller` to
+create Istio resources for Eventing resources.
+
+The possible values for `istio` are:
+
+- `disabled`
+    - Disable Eventing integration with Istio
+- `enabled`
+    - Enabled Eventing integration with Istio
+
+For example, to enable `istio` integration, the `config-features` ConfigMap will look like
+the following:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: config-features
+  namespace: knative-eventing
+data:
+  istio: "enabled"
+```
+