OSS Istio migration docs

amuraru · amuraru · commit b196e7fa3034 · 2025-09-27T12:00:21.000+02:00
diff --git a/content/docs/_index.md b/content/docs/_index.md
@@ -126,9 +126,14 @@ a dynamic reconfiguration.
 
 ### Seamless Istio mesh support
 
-- Operator allows to use ClusterIP services instead of Headless, which still works better in case of Service meshes.
-- To avoid too early Kafka initialization, which might lead to unready sidecar container. The operator uses a small script to mitigate this behavior. Any Kafka image can be used with the only requirement of an available **curl** command.
-- To access a Kafka cluster which runs inside the mesh. Operator supports creating Istio ingress gateways.
+- **Standard Istio Integration**: Koperator now uses standard Istio resources (Gateway, VirtualService) instead of deprecated banzaicloud istio-operator
+- **Flexible Deployment**: Works with any Istio installation method (operator, Helm, or manual)
+- **Service Mesh Ready**: Operator allows to use ClusterIP services instead of Headless, which works better with Service meshes
+- **Sidecar Compatibility**: To avoid too early Kafka initialization, the operator uses a small script to mitigate sidecar container readiness issues
+- **Istio Ingress Gateways**: Operator supports creating Istio ingress gateways for external access to Kafka clusters running inside the mesh
+- **No Control Plane Dependency**: Works with any Istio installation without requiring specific control plane configuration
+
+For detailed Istio integration configuration, troubleshooting, and migration guides, see the [Istio Integration Guide]({{< relref "istio-integration.md" >}}).
 
 ---
 Apache Kafka, Kafka, and the Kafka logo are either registered trademarks or trademarks of The Apache Software Foundation in the United States and other countries.
diff --git a/content/docs/configurations/examples/_index.md b/content/docs/configurations/examples/_index.md
@@ -54,7 +54,7 @@ You can create a broker-ingress mapping to eliminate traffic across availability
 
 ## Kafka cluster with Istio
 
-You can use Istio as the ingress controller for your external listeners. It requires using our [Istio operator](https://github.com/banzaicloud/istio-operator) in the Kubernetes cluster.  
+You can use Istio as the ingress controller for your external listeners. Koperator now uses standard Istio resources (Gateway, VirtualService) instead of the deprecated banzaicloud istio-operator, providing better compatibility and working with any Istio installation.
 
 - [Kafka cluster with Istio as ingress controller](https://github.com/adobe/koperator/blob/master/config/samples/kafkacluster-with-istio.yaml)
 
diff --git a/content/docs/developer.md b/content/docs/developer.md
@@ -45,6 +45,35 @@ Create CR and let the operator set up Kafka in your cluster (you can change the
 
 `kubectl create -n kafka -f config/samples/simplekafkacluster.yaml`
 
+## Istio Integration
+
+Koperator now supports Istio integration using standard Istio resources instead of the deprecated banzaicloud istio-operator. This provides better compatibility and works with any Istio installation.
+
+### Prerequisites for Istio Integration
+
+1. Install Istio in your cluster (any method - operator, Helm, or manual)
+2. Ensure Istio CRDs are available
+3. Configure the `istioIngressConfig` section in your KafkaCluster spec
+
+### Example Istio Configuration
+
+```yaml
+apiVersion: kafka.banzaicloud.io/v1beta1
+kind: KafkaCluster
+metadata:
+  name: kafka
+spec:
+  ingressController: "istioingress"
+  istioIngressConfig:
+    gatewayConfig:
+      mode: ISTIO_MUTUAL
+  # ... rest of your configuration
+```
+
+**Note**: The `istioControlPlane` configuration is no longer required. Koperator creates standard Kubernetes Deployment and Service resources along with Istio Gateway and VirtualService resources.
+
+For comprehensive Istio integration documentation including advanced configuration, troubleshooting, and migration guides, see the [Istio Integration Guide]({{< relref "istio-integration.md" >}}).
+
 ## Limitations on minikube
 
 Minikube does not have a load balancer implementation, thus our envoy service will not get an external IP and the operator will get stuck at this point.
diff --git a/content/docs/external-listener/index.md b/content/docs/external-listener/index.md
@@ -107,16 +107,18 @@ To configure an external listener that uses the LoadBalancer access method, comp
         ingressController: "envoy"
       ```
 
-    - To use Istio ingress controller set the `ingressController` field to `istioingress`. [Istio operator](https://github.com/banzaicloud/istio-operator) v2 is supported from Koperator version 0.21.0+. Istio operator v2 supports multiple Istio control plane on the same cluster, that is why the corresponding control plane to the gateway must be specified. The `istioControlPlane` field in the `KafkaCluster` custom resource is a reference to that IstioControlPlane resource. For an example, [see](https://github.com/adobe/koperator/blob/672b19d49e5c0a22f9658181003beddb56f17d33/config/samples/kafkacluster-with-istio.yaml#L10).
+    - To use Istio ingress controller set the `ingressController` field to `istioingress`. Koperator now uses standard Istio resources (Gateway, VirtualService) instead of the deprecated banzaicloud istio-operator. This provides better compatibility and works with any Istio installation. The `istioControlPlane` configuration is no longer required.
 
       ```yaml
       spec:
         ingressController: "istioingress"
-        istioControlPlane:
-          name: <name of the IstioControlPlane custom resource>
-          namespace: <namespace of the IstioControlPlane custom resource>
+        istioIngressConfig:
+          gatewayConfig:
+            mode: ISTIO_MUTUAL  # or SIMPLE for non-mTLS
       ```
 
+      For detailed Istio integration configuration and advanced features, see the [Istio Integration Guide]({{< relref "../istio-integration.md" >}}).
+
 1. Configure additional parameters for the ingress controller as needed for your environment, for example, number of replicas, resource requirements and resource limits. You can be configure such parameters using the *envoyConfig* and *istioIngressConfig* fields, respectively.
 1. (Optional) For external access through a static URL instead of the load balancer's public IP, specify the URL in the `hostnameOverride` field of the external listener that resolves to the public IP of the load balancer. The broker address will be advertised as, `advertised.listeners=EXTERNAL1://kafka-1.dev.my.domain:<broker port number>`.
 
diff --git a/content/docs/istio-integration.md b/content/docs/istio-integration.md
@@ -0,0 +1,312 @@
+---
+title: Istio Integration
+weight: 200
+---
+
+# Istio Integration with Koperator
+
+Koperator now supports Istio integration using standard Istio resources, providing advanced service mesh capabilities for Kafka clusters. This integration replaces the deprecated banzaicloud istio-operator with a more robust approach using standard Kubernetes and Istio resources.
+
+## Overview
+
+The Istio integration in Koperator provides:
+
+- **Service Mesh Capabilities**: Full Istio service mesh integration for Kafka clusters
+- **Traffic Management**: Advanced traffic routing and load balancing
+- **Security**: mTLS encryption and authentication
+- **Observability**: Enhanced monitoring and tracing capabilities
+- **Gateway Management**: Automatic Istio Gateway and VirtualService creation
+- **No Control Plane Dependency**: Works with any Istio installation
+
+## Prerequisites
+
+Before using Istio integration with Koperator, ensure you have:
+
+1. **Istio Installation**: Any Istio installation (operator-based or manual)
+2. **Kubernetes Cluster**: Version 1.19+ with sufficient resources
+3. **Istio CRDs**: Istio Custom Resource Definitions installed
+
+## Installation
+
+### 1. Install Istio (Optional)
+
+If you don't have Istio installed, you can install it using any method:
+
+```bash
+# Option 1: Using Istio operator
+kubectl apply -f https://github.com/istio/istio/releases/download/1.19.0/istio-1.19.0-linux-amd64.tar.gz
+istioctl install --set values.defaultRevision=default
+
+# Option 2: Using Helm
+helm repo add istio https://istio-release.storage.googleapis.com/charts
+helm repo update
+helm install istio-base istio/base -n istio-system --create-namespace
+helm install istiod istio/istiod -n istio-system --wait
+```
+
+### 2. Verify Istio Installation
+
+```bash
+# Check Istio control plane status (if installed)
+kubectl get pods -n istio-system
+
+# Verify Istio CRDs are available
+kubectl get crd | grep istio
+```
+
+## Configuration
+
+### Basic Istio Configuration
+
+Configure your KafkaCluster to use Istio ingress:
+
+```yaml
+apiVersion: kafka.banzaicloud.io/v1beta1
+kind: KafkaCluster
+metadata:
+  name: kafka
+  namespace: kafka
+spec:
+  ingressController: "istioingress"
+  istioIngressConfig:
+    gatewayConfig:
+      mode: ISTIO_MUTUAL
+  # ... rest of your Kafka configuration
+```
+
+**Note**: The `istioControlPlane` configuration is no longer required as Koperator now creates standard Kubernetes resources that work with any Istio installation.
+
+### Advanced Configuration Options
+
+#### Istio Ingress Configuration
+
+```yaml
+spec:
+  istioIngressConfig:
+    # Gateway configuration
+    gatewayConfig:
+      mode: ISTIO_MUTUAL  # or SIMPLE for non-mTLS
+    
+    # Resource limits and requests
+    resources:
+      requests:
+        cpu: "100m"
+        memory: "128Mi"
+      limits:
+        cpu: "2000m"
+        memory: "1024Mi"
+    
+    # Replica configuration
+    replicas: 2
+    
+    # Node selector for gateway placement
+    nodeSelector:
+      kubernetes.io/os: linux
+    
+    # Tolerations for gateway scheduling
+    tolerations:
+    - key: "istio"
+      operator: "Equal"
+      value: "true"
+      effect: "NoSchedule"
+    
+    # Environment variables
+    envs:
+    - name: CUSTOM_VAR
+      value: "custom-value"
+    
+    # Annotations for the gateway
+    annotations:
+      custom.annotation: "value"
+    
+    # Service annotations
+    serviceAnnotations:
+      service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
+```
+
+## Architecture Changes
+
+### Previous Architecture (banzaicloud istio-operator)
+
+The previous implementation used:
+- `IstioMeshGateway` custom resources
+- banzaicloud istio-operator dependencies
+- Custom Istio operator APIs
+
+### New Architecture (Standard Istio Resources)
+
+The new implementation uses:
+- Standard Kubernetes `Deployment` and `Service` resources
+- Native Istio `Gateway` and `VirtualService` resources
+- No dependency on specific Istio control plane or operator
+
+### Resource Creation
+
+When you create a KafkaCluster with Istio integration, Koperator automatically creates:
+
+1. **Kubernetes Deployment**: Istio proxy deployment with `docker.io/istio/proxyv2:latest` image
+2. **Kubernetes Service**: Load balancer service for external access
+3. **Istio Gateway**: Routes external traffic to Kafka brokers
+4. **VirtualService**: Defines routing rules for the gateway
+
+The implementation creates standard Kubernetes resources that work with any Istio installation, making it more flexible and compatible.
+
+## Security Features
+
+### mTLS Configuration
+
+The Istio integration supports mutual TLS (mTLS) for secure communication:
+
+```yaml
+spec:
+  istioIngressConfig:
+    gatewayConfig:
+      mode: ISTIO_MUTUAL  # Enables mTLS
+```
+
+### Authentication and Authorization
+
+Istio provides additional security features:
+- **PeerAuthentication**: Configure mTLS policies
+- **AuthorizationPolicy**: Define access control rules
+- **RequestAuthentication**: JWT token validation
+
+## Monitoring and Observability
+
+### Metrics
+
+Istio integration provides enhanced metrics:
+- **Traffic Metrics**: Request rates, latency, error rates
+- **Gateway Metrics**: Istio gateway performance
+- **Service Mesh Metrics**: End-to-end observability
+
+### Tracing
+
+Distributed tracing is automatically enabled:
+- **Jaeger Integration**: Automatic trace collection
+- **Zipkin Support**: Alternative tracing backend
+- **Custom Trace Sampling**: Configurable sampling rates
+
+## Troubleshooting
+
+### Common Issues
+
+1. **Istio Control Plane Not Found**
+   ```bash
+   # Verify Istio control plane is running
+   kubectl get pods -n istio-system
+   ```
+
+2. **Gateway Not Receiving Traffic**
+   ```bash
+   # Check gateway status
+   kubectl get gateway -n kafka
+   kubectl describe gateway kafka-gateway -n kafka
+   ```
+
+3. **mTLS Configuration Issues**
+   ```bash
+   # Verify peer authentication
+   kubectl get peerauthentication -n kafka
+   ```
+
+### Debugging Commands
+
+```bash
+# Check Istio proxy status
+istioctl proxy-status
+
+# Verify configuration
+istioctl analyze
+
+# Check gateway configuration
+kubectl get gateway,virtualservice -n kafka
+
+# View Istio logs
+kubectl logs -n kafka -l app=istio-ingressgateway
+```
+
+## Migration from banzaicloud istio-operator
+
+If you're migrating from the deprecated banzaicloud istio-operator:
+
+1. **Remove old dependencies**: Uninstall banzaicloud istio-operator
+2. **Install upstream Istio**: Follow the installation steps above
+3. **Update configurations**: Update your KafkaCluster specs
+4. **Test thoroughly**: Verify all functionality works as expected
+
+## Best Practices
+
+1. **Resource Planning**: Allocate sufficient resources for Istio components
+2. **Security**: Always use mTLS in production environments
+3. **Monitoring**: Set up comprehensive monitoring and alerting
+4. **Testing**: Thoroughly test Istio configurations in non-production environments
+5. **Updates**: Keep Istio and Koperator versions compatible
+
+## Examples
+
+### Complete KafkaCluster with Istio
+
+```yaml
+apiVersion: kafka.banzaicloud.io/v1beta1
+kind: KafkaCluster
+metadata:
+  name: kafka
+  namespace: kafka
+spec:
+  headlessServiceEnabled: false
+  ingressController: "istioingress"
+  istioIngressConfig:
+    gatewayConfig:
+      mode: ISTIO_MUTUAL
+    resources:
+      requests:
+        cpu: "100m"
+        memory: "128Mi"
+      limits:
+        cpu: "2000m"
+        memory: "1024Mi"
+    replicas: 2
+    annotations:
+      sidecar.istio.io/inject: "true"
+  zkAddresses:
+    - "zookeeper-server-client.zookeeper:2181"
+  clusterImage: "ghcr.io/adobe/koperator/kafka:2.13-3.9.1"
+  brokers:
+    - id: 0
+      brokerConfigGroup: "default"
+    - id: 1
+      brokerConfigGroup: "default"
+    - id: 2
+      brokerConfigGroup: "default"
+  brokerConfigGroups:
+    default:
+      storageConfigs:
+        - mountPath: "/kafka-logs"
+          pvcSpec:
+            accessModes:
+              - ReadWriteOnce
+            resources:
+              requests:
+                storage: 10Gi
+  listenersConfig:
+    internalListeners:
+      - type: "plaintext"
+        name: "internal"
+        containerPort: 29092
+        usedForInnerBrokerCommunication: true
+    externalListeners:
+      - type: "plaintext"
+        name: "external"
+        externalStartingPort: 19090
+        containerPort: 9094
+```
+
+## Support
+
+For issues related to Istio integration:
+
+1. **Koperator Issues**: Report to the Koperator GitHub repository
+2. **Istio Issues**: Report to the Istio GitHub repository
+3. **Documentation**: Check the official Istio documentation
+4. **Community**: Join the Istio and Koperator community discussions
