|
| 1 | +# Migration Plan: Istio Operator → Envoy Gateway |
| 2 | + |
| 3 | +## Overview |
| 4 | + |
| 5 | +This document outlines the complete migration plan to replace the Istio-based ingress controller with [Envoy Gateway](https://gateway.envoyproxy.io/) for Kafka external access in Koperator. |
| 6 | + |
| 7 | +**Migration Date**: 2025-11-03 |
| 8 | +**Last Commit**: 37d9feba - "Add e2e tests" |
| 9 | +**Branch**: istio |
| 10 | + |
| 11 | +## Rationale |
| 12 | + |
| 13 | +- **Standardization**: Envoy Gateway uses Kubernetes Gateway API (standard) |
| 14 | +- **Simplification**: Remove dependency on Istio operator and custom client library |
| 15 | +- **Community Support**: Envoy Gateway is actively maintained by the Envoy community |
| 16 | +- **Reduced Complexity**: Eliminate custom mesh gateway deployments |
| 17 | + |
| 18 | +## Current State |
| 19 | + |
| 20 | +### Istio Components to Remove |
| 21 | +- `pkg/resources/istioingress/` - Complete Istio ingress implementation |
| 22 | +- `third_party/github.com/banzaicloud/istio-client-go` - Custom Istio client |
| 23 | +- `tests/e2e/test_istio_kafka_cluster.go` - Istio e2e tests |
| 24 | +- `config/samples/kraft/kafkacluster-kraft-with-istio.yaml` - Sample config |
| 25 | +- API types: `IstioIngressConfig` struct and related fields |
| 26 | + |
| 27 | +### Existing Envoy Support |
| 28 | +The codebase already has `pkg/resources/envoy/` which creates custom Envoy deployments. This will remain as-is for now (users can still use `ingressController: "envoy"`). |
| 29 | + |
| 30 | +--- |
| 31 | + |
| 32 | +## Phase 1: Code Changes |
| 33 | + |
| 34 | +### 1.1 API Changes |
| 35 | + |
| 36 | +**File**: `api/v1beta1/kafkacluster_types.go` |
| 37 | + |
| 38 | +- [ ] Remove `IstioIngressConfig` struct (lines ~511-531) |
| 39 | +- [ ] Remove `IstioIngressConfig` field from `KafkaClusterSpec` (line ~205) |
| 40 | +- [ ] Remove `IstioIngressConfig` field from `IngressConfig` struct (line ~742) |
| 41 | +- [ ] Update `IngressController` enum validation to remove `istioingress` (line ~188) |
| 42 | +- [ ] Remove Istio-related constants: |
| 43 | + - `defaultIstioIngressRequestResourceCpu` |
| 44 | + - `defaultIstioIngressRequestResourceMemory` |
| 45 | + - `defaultIstioIngressLimitResourceCpu` |
| 46 | + - `defaultIstioIngressLimitResourceMemory` |
| 47 | + - `DefaultIstioProxyImage` |
| 48 | +- [ ] Remove methods: |
| 49 | + - `GetResources()` for IstioIngressConfig |
| 50 | + - `GetReplicas()` for IstioIngressConfig |
| 51 | + - `GetAnnotations()` for IstioIngressConfig |
| 52 | + - `GetVirtualServiceAnnotations()` for IstioIngressConfig |
| 53 | + - `GetLoadBalancerSourceRanges()` for IstioIngressConfig |
| 54 | +- [ ] Remove import: `github.com/banzaicloud/istio-client-go/pkg/networking/v1beta1` |
| 55 | + |
| 56 | +**File**: `api/v1beta1/zz_generated.deepcopy.go` |
| 57 | +- [ ] Regenerate after API changes |
| 58 | + |
| 59 | +### 1.2 Remove Istio Client Dependency |
| 60 | + |
| 61 | +**File**: `go.mod` |
| 62 | +- [ ] Remove `github.com/banzaicloud/istio-client-go v0.0.17` dependency |
| 63 | +- [ ] Remove replace directive: `github.com/banzaicloud/istio-client-go => ./third_party/github.com/banzaicloud/istio-client-go` |
| 64 | +- [ ] Run `go mod tidy` |
| 65 | + |
| 66 | +**Directory**: `third_party/github.com/banzaicloud/istio-client-go` |
| 67 | +- [ ] Delete entire directory |
| 68 | + |
| 69 | +### 1.3 Remove Istio Ingress Implementation |
| 70 | + |
| 71 | +**Directory**: `pkg/resources/istioingress/` |
| 72 | +- [ ] Delete entire directory containing: |
| 73 | + - `istioingress.go` - Main reconciler |
| 74 | + - `gateway.go` - Istio Gateway resources |
| 75 | + - `virtualservice.go` - Istio VirtualService resources |
| 76 | + - `meshgateway.go` - Custom mesh gateway deployment |
| 77 | + - `istioingress_test.go` - Unit tests |
| 78 | + - `meshgateway_test.go` - Unit tests |
| 79 | + |
| 80 | +**Directory**: `pkg/util/istioingress/` |
| 81 | +- [ ] Check if exists and delete if present |
| 82 | + |
| 83 | +### 1.4 Update Controller |
| 84 | + |
| 85 | +**File**: `controllers/kafkacluster_controller.go` |
| 86 | +- [ ] Remove import: `istioingress "github.com/banzaicloud/koperator/pkg/resources/istioingress"` |
| 87 | +- [ ] Remove from reconcilers list (line ~124): `istioingress.New(r.Client, instance),` |
| 88 | +- [ ] Remove any Istio-specific watches (check `SetupKafkaClusterWithManager`) |
| 89 | + |
| 90 | +### 1.5 Update Utility Functions |
| 91 | + |
| 92 | +**File**: `pkg/util/` (various files) |
| 93 | +- [ ] Search for Istio references: `grep -r "istio" pkg/util/` |
| 94 | +- [ ] Update or remove Istio-specific utility functions |
| 95 | +- [ ] Check `pkg/util/kafka/` for any Istio-related code |
| 96 | + |
| 97 | +--- |
| 98 | + |
| 99 | +## Phase 2: Unit Tests |
| 100 | + |
| 101 | +### 2.1 Remove Istio Unit Tests |
| 102 | + |
| 103 | +**Files to Delete**: |
| 104 | +- [ ] `pkg/resources/istioingress/istioingress_test.go` |
| 105 | +- [ ] `pkg/resources/istioingress/meshgateway_test.go` |
| 106 | +- [ ] `controllers/tests/kafkacluster_controller_istioingress_test.go` |
| 107 | + |
| 108 | +### 2.2 Update Existing Tests |
| 109 | + |
| 110 | +**File**: `pkg/k8sutil/resource_test.go` |
| 111 | +- [ ] Remove Istio-related test cases (check for 278 new lines from last commit) |
| 112 | + |
| 113 | +**File**: `pkg/resources/envoy/envoy_test.go` |
| 114 | +- [ ] Review and ensure no Istio dependencies (303 new lines from last commit) |
| 115 | + |
| 116 | +**File**: `pkg/scale/scale_test.go` |
| 117 | +- [ ] Remove Istio scenarios if any |
| 118 | + |
| 119 | +**File**: `pkg/resources/nodeportexternalaccess/nodeportExternalAccess_test.go` |
| 120 | +- [ ] Review for Istio references (233 new lines from last commit) |
| 121 | + |
| 122 | +### 2.3 Run Unit Tests |
| 123 | + |
| 124 | +- [ ] Run: `make test` |
| 125 | +- [ ] Fix any compilation errors |
| 126 | +- [ ] Ensure all tests pass |
| 127 | + |
| 128 | +--- |
| 129 | + |
| 130 | +## Phase 3: E2E Tests |
| 131 | + |
| 132 | +### 3.1 Remove Istio E2E Tests |
| 133 | + |
| 134 | +**Files to Delete**: |
| 135 | +- [ ] `tests/e2e/test_istio_kafka_cluster.go` (202 lines) |
| 136 | +- [ ] `config/samples/kraft/kafkacluster-kraft-with-istio.yaml` (245 lines) |
| 137 | + |
| 138 | +**File**: `tests/e2e/koperator_suite_test.go` |
| 139 | +- [ ] Remove Istio test invocations |
| 140 | + |
| 141 | +### 3.2 Update E2E Test Infrastructure |
| 142 | + |
| 143 | +**File**: `tests/e2e/const.go` |
| 144 | +- [ ] Remove Istio CRD kinds from `koperatorRelatedResourceKinds()` (lines 130-142): |
| 145 | + - `virtualservices.networking.istio.io` |
| 146 | + - `gateways.networking.istio.io` |
| 147 | + - `destinationrules.networking.istio.io` |
| 148 | + - `serviceentries.networking.istio.io` |
| 149 | + - `workloadentries.networking.istio.io` |
| 150 | + - `workloadgroups.networking.istio.io` |
| 151 | + - `envoyfilters.networking.istio.io` |
| 152 | + - `sidecars.networking.istio.io` |
| 153 | + - `authorizationpolicies.security.istio.io` |
| 154 | + - `peerauthentications.security.istio.io` |
| 155 | + - `requestauthentications.security.istio.io` |
| 156 | + - `telemetries.telemetry.istio.io` |
| 157 | + - `wasmplugins.extensions.istio.io` |
| 158 | + |
| 159 | +**File**: `.github/workflows/e2e-test.yaml` |
| 160 | +- [ ] Remove Istio installation steps if any |
| 161 | + |
| 162 | +**File**: `.github/actions/kind-create/action.yaml` |
| 163 | +- [ ] Remove Istio setup if present |
| 164 | + |
| 165 | +### 3.3 Run E2E Tests |
| 166 | + |
| 167 | +- [ ] Run: `make e2e-test` or equivalent |
| 168 | +- [ ] Ensure tests pass without Istio |
| 169 | + |
| 170 | +--- |
| 171 | + |
| 172 | +## Phase 4: Documentation & Cleanup |
| 173 | + |
| 174 | +### 4.1 Update CRDs |
| 175 | + |
| 176 | +**Files**: |
| 177 | +- [ ] `charts/kafka-operator/crds/kafkaclusters.yaml` - Regenerate |
| 178 | +- [ ] `config/base/crds/kafka.banzaicloud.io_kafkaclusters.yaml` - Regenerate |
| 179 | +- [ ] Run: `make generate manifests` |
| 180 | + |
| 181 | +### 4.2 Update Documentation |
| 182 | + |
| 183 | +**File**: `README.md` |
| 184 | +- [ ] Remove Istio references |
| 185 | +- [ ] Update ingress controller options (only `envoy` and `contour`) |
| 186 | + |
| 187 | +**File**: `docs/developer.md` |
| 188 | +- [ ] Update development setup (remove Istio) |
| 189 | + |
| 190 | +**File**: `ADOPTERS.md` |
| 191 | +- [ ] Review and update if needed |
| 192 | + |
| 193 | +### 4.3 Final Cleanup |
| 194 | + |
| 195 | +- [ ] Search for remaining "istio" references: |
| 196 | + ```bash |
| 197 | + grep -ri "istio" --exclude-dir=vendor --exclude-dir=.git --exclude="*.sum" --exclude="MIGRATION_PLAN.md" |
| 198 | + ``` |
| 199 | +- [ ] Update any remaining references |
| 200 | +- [ ] Run full test suite: `make test` |
| 201 | +- [ ] Run linting: `make lint` |
| 202 | +- [ ] Update CHANGELOG or release notes |
| 203 | + |
| 204 | +### 4.4 Verify Build |
| 205 | + |
| 206 | +- [ ] Run: `make build` |
| 207 | +- [ ] Run: `make docker-build` |
| 208 | +- [ ] Ensure no compilation errors |
| 209 | + |
| 210 | +--- |
| 211 | + |
| 212 | +## Breaking Changes |
| 213 | + |
| 214 | +⚠️ **This is a BREAKING CHANGE for users** |
| 215 | + |
| 216 | +### Impact |
| 217 | +Users currently using `ingressController: "istioingress"` will need to migrate. |
| 218 | + |
| 219 | +### Migration Path for Users |
| 220 | + |
| 221 | +**Option 1: Use existing Envoy support** |
| 222 | +```yaml |
| 223 | +spec: |
| 224 | + ingressController: "envoy" |
| 225 | + envoyConfig: |
| 226 | + # ... existing envoy config |
| 227 | +``` |
| 228 | + |
| 229 | +**Option 2: Use Contour** |
| 230 | +```yaml |
| 231 | +spec: |
| 232 | + ingressController: "contour" |
| 233 | + contourIngressConfig: |
| 234 | + # ... contour config |
| 235 | +``` |
| 236 | + |
| 237 | +**Option 3: Future - Envoy Gateway** (not in this migration) |
| 238 | +Users who want Envoy Gateway will need to wait for future implementation or use the existing `envoy` option. |
| 239 | + |
| 240 | +--- |
| 241 | + |
| 242 | +## Testing Checklist |
| 243 | + |
| 244 | +- [ ] Unit tests pass: `make test` |
| 245 | +- [ ] E2E tests pass: `make e2e-test` |
| 246 | +- [ ] Linting passes: `make lint` |
| 247 | +- [ ] Build succeeds: `make build` |
| 248 | +- [ ] Docker build succeeds: `make docker-build` |
| 249 | +- [ ] CRDs generated correctly: `make manifests` |
| 250 | +- [ ] No Istio references remain in codebase |
| 251 | + |
| 252 | +--- |
| 253 | + |
| 254 | +## Rollback Plan |
| 255 | + |
| 256 | +If issues arise: |
| 257 | +1. Revert to commit `37d9feba` (before migration) |
| 258 | +2. Cherry-pick any critical fixes |
| 259 | +3. Re-evaluate migration approach |
| 260 | + |
| 261 | +--- |
| 262 | + |
| 263 | +## Timeline |
| 264 | + |
| 265 | +- **Phase 1**: Code Changes - 2-3 hours |
| 266 | +- **Phase 2**: Unit Tests - 1-2 hours |
| 267 | +- **Phase 3**: E2E Tests - 1-2 hours |
| 268 | +- **Phase 4**: Documentation & Cleanup - 1 hour |
| 269 | + |
| 270 | +**Total Estimated Time**: 5-8 hours |
| 271 | + |
| 272 | +--- |
| 273 | + |
| 274 | +## Notes |
| 275 | + |
| 276 | +- The existing `pkg/resources/envoy/` implementation remains unchanged |
| 277 | +- This migration only removes Istio support |
| 278 | +- Future work could add Envoy Gateway support as a new ingress controller type |
| 279 | +- Users have `envoy` and `contour` as alternatives |
| 280 | + |
0 commit comments