Release 1.28

.github/ai_agents/domain_knowledge_prompt.md → .agents/domain_knowledge_prompt.md

@@ -1,6 +1,6 @@
 # Create Domain Knowledge File
 
-This guide outlines best practices for creating domain knowledge files in the `.github/ai_agents/knowledge/` folder. These files serve as a source of truth for understanding the Sail Operator architecture, patterns, and implementation details.
+This guide outlines best practices for creating domain knowledge files in the `.agents/knowledge/` folder. These files serve as a source of truth for understanding the Sail Operator architecture, patterns, and implementation details.
 
 ## Naming Convention
 
@@ -232,10 +232,10 @@ Common issues and solutions:
 ## Related Components
 
 Links to related Sail Operator domain knowledge files:
-- [API Types](domain-knowledge-api-types.md)
-- [Controllers](domain-knowledge-controllers.md)
-- [Testing Framework](domain-knowledge-testing-framework.md)
-- [Version Management](domain-knowledge-version-management.md)
+- [API Types](knowledge/domain-knowledge-api-types.md)
+- [Controllers](knowledge/domain-knowledge-controllers.md)
+- [Testing Framework](knowledge/domain-knowledge-testing-framework.md)
+- [Version Management](knowledge/domain-knowledge-version-management.md)
 ```
 
 ## Maintenance

.agents/knowledge/domain-knowledge-api-types.md

@@ -0,0 +1,228 @@
+# Sail Operator API Types Domain Knowledge
+
+This document provides AI agents with detailed knowledge about the Sail Operator's Custom Resource Definitions (CRDs) and API types.
+
+## Core Custom Resources
+
+### Istio Resource
+The primary resource for managing Istio control plane deployments.
+
+**Key Fields:**
+- `spec.version` - Istio version to install (defaults to operator's default version)
+- `spec.namespace` - Target namespace for control plane (default: `istio-system`, immutable)
+- `spec.profile` - Built-in installation profile (e.g., `default`, `ambient`, `openshift`)
+- `spec.values` - Helm values for customizing Istio installation
+- `spec.updateStrategy.type` - Update strategy: `InPlace` (default) or `RevisionBased`
+- `spec.updateStrategy.inactiveRevisionDeletionGracePeriodSeconds` - Seconds before removing inactive revision (default: 30)
+- `spec.updateStrategy.updateWorkloads` - Automatically move workloads to new revision (default: false)
+
+**Status Fields:**
+- `status.state` - Current state: `Healthy`, `Installing`, `Updating`, `Error`, etc.
+- `status.activeRevisionName` - Name of the active IstioRevision
+- `status.revisions` - Summary of all managed revisions
+
+### IstioRevision Resource
+Represents a specific deployment of Istio control plane components.
+
+**Key Fields:**
+- `spec.version` - Exact Istio version for this revision
+- `spec.namespace` - Installation namespace
+- `spec.values` - Helm configuration values
+
+**Status Fields:**
+- `status.state` - Revision state: `Installing`, `Healthy`, `Failed`, etc.
+- `status.conditions` - Detailed condition information
+
+### IstioCNI Resource
+Manages the Istio CNI plugin (required for OpenShift and Ambient mesh).
+
+**Key Fields:**
+- `spec.version` - CNI plugin version (must match Istio version)
+- `spec.namespace` - CNI installation namespace (default: `istio-cni`, immutable)
+- `spec.profile` - Built-in installation profile
+- `spec.values` - CNI-specific Helm values
+
+**Note:** The resource name must be `default` (validated by CRD).
+
+### ZTunnel Resource
+Manages ZTunnel workloads for Istio Ambient mesh mode.
+
+**Key Fields:**
+- `spec.version` - ZTunnel version (must match Istio version)
+- `spec.namespace` - ZTunnel namespace (default: `ztunnel`)
+- `spec.values` - ZTunnel configuration values
+
+**Note:** The resource name must be `default` (validated by CRD). ZTunnel was promoted to v1 API; a v1alpha1 version still exists for backwards compatibility.
+
+### IstioRevisionTag Resource
+Creates revision tags for canary deployments and traffic shifting. References an Istio or IstioRevision object and serves as an alias for sidecar injection.
+
+**Key Fields:**
+- `spec.targetRef.kind` - Kind of target resource (`Istio` or `IstioRevision`)
+- `spec.targetRef.name` - Name of the target resource
+
+**Status Fields:**
+- `status.istioRevision` - Name of the referenced IstioRevision
+- `status.istiodNamespace` - Namespace of the corresponding Istiod instance
+
+## Common Patterns
+
+### Profile Configuration
+Istio and IstioCNI resources support profiles for predefined configuration sets:
+- `ambient` - Ambient mesh configuration
+- `default` - Default Istio configuration (always applied)
+- `demo` - Demo configuration with additional features
+- `empty` - Empty profile
+- `openshift` - OpenShift-specific configuration (auto-applied on OpenShift)
+- `openshift-ambient` - OpenShift with Ambient mesh
+- `preview` - Preview features
+- `remote` - Remote cluster configuration
+- `stable` - Stable production configuration
+
+### Values Configuration
+All resources support Helm values via the `values` field:
+
+```yaml
+spec:
+  values:
+    global:
+      variant: distroless
+      logging:
+        level: "all:info"
+    meshConfig:
+      trustDomain: cluster.local
+      defaultConfig:
+        proxyStatsMatcher:
+          inclusionRegexps:
+            - ".*outlier_detection.*"
+```
+
+### Version Management
+- Versions are specified as semantic versions (e.g., `1.25.0`)
+- If no version specified, uses operator's default supported version
+- Version compatibility is enforced by the operator
+
+### Resource Relationships
+1. `Istio` → creates/manages → `IstioRevision`
+2. `IstioRevisionTag` → references → `Istio`
+3. Ambient mode requires: `Istio` + `IstioCNI` + `ZTunnel`
+4. Sidecar mode requires: `Istio` (+ `IstioCNI` on OpenShift)
+
+## Status Conditions
+
+All resources use standard Kubernetes condition patterns:
+
+**Common Condition Types:**
+- `Ready` - Resource is ready and operational
+- `Reconciled` - Last reconciliation was successful
+- `ReconcileError` - Reconciliation encountered errors
+
+**Condition Status Values:**
+- `True` - Condition is active/successful
+- `False` - Condition is inactive/failed
+- `Unknown` - Condition state is uncertain
+
+## Update Strategies
+
+### InPlace Strategy
+- Updates existing revision in-place
+- Faster but with brief control plane downtime
+- Default strategy
+
+### RevisionBased Strategy
+- Creates new revision alongside existing one
+- Enables canary deployments and zero-downtime updates
+- Requires manual traffic shifting via IstioRevisionTag
+
+## Validation Rules
+
+### Version Constraints
+- Must use supported Istio versions (defined in `versions.yaml`)
+- CNI and ZTunnel versions must be compatible with Istio version
+- Revision names must be unique within namespace
+
+### Namespace Requirements
+- Control plane namespace must exist before creating Istio resource
+- CNI deployed to `istio-cni` namespace
+- ZTunnel deployed to `ztunnel` namespace
+
+### Resource Dependencies
+- IstioCNI must be deployed before Istio in Ambient mode
+- ZTunnel requires both Istio and IstioCNI to be ready
+- Removing Istio resource removes all associated IstioRevisions
+
+## Generated Types
+
+The `api/v1/values_types.gen.go` file contains auto-generated types from Istio's Helm values schema:
+
+- **Values** - Root Helm values structure
+- **GlobalConfig** - Global Istio configuration
+- **PilotConfig** - Istiod (Pilot) specific configuration
+- **ProxyConfig** - Sidecar proxy configuration
+- **MeshConfig** - Service mesh configuration
+
+These types ensure type-safe access to all Istio configuration options.
+
+## Common Configuration Examples
+
+### Basic Istio Installation
+```yaml
+apiVersion: sailoperator.io/v1
+kind: Istio
+metadata:
+  name: default
+spec:
+  namespace: istio-system
+```
+
+### Ambient Mesh Setup
+```yaml
+# 1. CNI (required for Ambient)
+apiVersion: sailoperator.io/v1
+kind: IstioCNI
+metadata:
+  name: default
+spec:
+  namespace: istio-cni
+  profile: ambient
+
+# 2. Control Plane
+apiVersion: sailoperator.io/v1
+kind: Istio
+metadata:
+  name: default
+spec:
+  namespace: istio-system
+  profile: ambient
+
+# 3. ZTunnel
+apiVersion: sailoperator.io/v1
+kind: ZTunnel
+metadata:
+  name: default
+spec:
+  namespace: ztunnel
+```
+
+### Revision-Based Canary Deployment
+```yaml
+# Main Istio resource with RevisionBased strategy
+apiVersion: sailoperator.io/v1
+kind: Istio
+metadata:
+  name: default
+spec:
+  namespace: istio-system
+  updateStrategy:
+    type: RevisionBased
+
+# Revision tag pointing to the Istio resource
+apiVersion: sailoperator.io/v1
+kind: IstioRevisionTag
+metadata:
+  name: stable
+spec:
+  targetRef:
+    kind: Istio
+    name: default
+```

.github/ai_agents/knowledge/domain-knowledge-controllers.md → .agents/knowledge/domain-knowledge-controllers.md

@@ -4,14 +4,14 @@ This document provides AI agents with detailed knowledge about the Sail Operator
 
 ## Controller Architecture
 
-The Sail Operator uses the controller-runtime framework with separate controllers for each Custom Resource:
-
-- **IstioController** - Manages `Istio` resources and their lifecycle
-- **IstioRevisionController** - Manages `IstioRevision` resources and Helm deployments
-- **IstioCNIController** - Manages `IstioCNI` resources for CNI plugin
-- **ZTunnelController** - Manages `ZTunnel` resources for Ambient mesh
-- **IstioRevisionTagController** - Manages `IstioRevisionTag` resources for canary deployments
-- **WebhookController** - Manages ValidatingAdmissionWebhook for Istio resources
+The Sail Operator uses the controller-runtime framework with separate controllers for each Custom Resource. Controllers are located in `controllers/<resource>/` directories:
+
+- **IstioController** (`controllers/istio/`) - Manages `Istio` resources and their lifecycle
+- **IstioRevisionController** (`controllers/istiorevision/`) - Manages `IstioRevision` resources and Helm deployments
+- **IstioCNIController** (`controllers/istiocni/`) - Manages `IstioCNI` resources for CNI plugin
+- **ZTunnelController** (`controllers/ztunnel/`) - Manages `ZTunnel` resources for Ambient mesh
+- **IstioRevisionTagController** (`controllers/istiorevisiontag/`) - Manages `IstioRevisionTag` resources for canary deployments
+- **WebhookController** (`controllers/webhook/`) - Manages MutatingWebhookConfiguration for Istio resources
 
 ## Controller Reconciliation Patterns
 

.github/ai_agents/knowledge/domain-knowledge-testing-framework.md → .agents/knowledge/domain-knowledge-testing-framework.md

@@ -87,12 +87,15 @@ E2E tests are organized by functionality:
 
 ```
 tests/e2e/
-├── operator/           # Operator deployment tests
-├── ambient/           # Ambient mesh functionality
-├── sidecar/           # Sidecar injection tests
-├── multicluster/      # Multi-cluster scenarios
-├── upgrade/           # Version upgrade tests
-└── util/              # Shared utilities
+├── ambient/              # Ambient mesh functionality tests
+├── controlplane/         # Control plane installation and update tests
+├── dualstack/            # Dual-stack networking tests
+├── multicluster/         # Multi-cluster scenarios (primary-remote, multi-primary, external control plane)
+├── multicontrolplane/    # Multiple control plane tests
+├── operator/             # Operator deployment and installation tests
+├── samples/              # Sample application tests
+├── setup/                # Test setup utilities
+└── util/                 # Shared utilities (cleaner, kubectl, helm, etc.)
 ```
 
 ### Cluster Management
@@ -131,8 +134,8 @@ BUILD_WITH_CONTAINER=0 make test.e2e.kind
 - `SKIP_BUILD=false` - Skip operator image build
 - `SKIP_DEPLOY=false` - Skip operator deployment
 - `IMAGE=quay.io/sail-dev/sail-operator:latest` - Operator image
-- `OCP=false` - Use OpenShift cluster
-- `OLM=false` - Deploy via OLM instead of Helm
+- `OCP=true` - Use OpenShift cluster
+- `OLM=true` - Deploy via OLM instead of Helm
 
 #### Test Behavior
 - `GINKGO_FLAGS` - Pass flags to Ginkgo runner

.github/ai_agents/knowledge/domain-knowledge-version-management.md → .agents/knowledge/domain-knowledge-version-management.md

@@ -15,26 +15,41 @@ This file defines all supported Istio versions:
 
 ```yaml
 versions:
-  - name: v1.26-latest
-    ref: v1.26.0
-  - name: v1.26.0
-    version: 1.26.0
+  # Alias pointing to a specific version (the first entry is the default)
+  - name: v1.X-latest
+    ref: v1.X.Y
+
+  # Full version definition
+  - name: v1.X.Y
+    version: 1.X.Y
     repo: https://github.com/istio/istio
-    commit: 1.26.0
+    commit: 1.X.Y
     charts:
-      - https://istio-release.storage.googleapis.com/charts/base-1.26.0.tgz
-      - https://istio-release.storage.googleapis.com/charts/istiod-1.26.0.tgz
-      - https://istio-release.storage.googleapis.com/charts/gateway-1.26.0.tgz
-      - https://istio-release.storage.googleapis.com/charts/cni-1.26.0.tgz
-      - https://istio-release.storage.googleapis.com/charts/ztunnel-1.26.0.tgz
+      - https://istio-release.storage.googleapis.com/charts/base-1.X.Y.tgz
+      - https://istio-release.storage.googleapis.com/charts/istiod-1.X.Y.tgz
+      - https://istio-release.storage.googleapis.com/charts/gateway-1.X.Y.tgz
+      - https://istio-release.storage.googleapis.com/charts/cni-1.X.Y.tgz
+      - https://istio-release.storage.googleapis.com/charts/ztunnel-1.X.Y.tgz
+
+  # End-of-life version (still valid input, but not installable)
+  - name: v1.W-latest
+    ref: v1.W.Z
+    eol: true
+  - name: v1.W.Z
+    eol: true
 ```
 
+**Note:** Check `pkg/istioversion/versions.yaml` in the repository for the current list of supported versions.
+
 ### Version Entry Structure
-- **name** - Human-readable version identifier
+- **name** - Human-readable version identifier (e.g., `v1.X.Y`, `v1.X-latest`)
+- **ref** - Reference to another version (for alias entries like `v1.X-latest`)
 - **version** - Semantic version (x.y.z)
 - **repo** - Source repository URL
 - **commit** - Git commit/tag reference
+- **branch** - Git branch (for development versions like `master`)
 - **charts** - List of Helm chart URLs for this version
+- **eol** - Boolean indicating end-of-life (version remains valid but not installable)
 
 ### Vendor Customization
 The version file can be customized using the `VERSIONS_YAML_FILE` environment variable:
@@ -51,9 +66,10 @@ This allows downstream vendors to:
 ## Versioning Policy
 
 ### Supported Version Range
-- **Current policy**: n-2 versions (e.g., Operator 1.26 supports Istio 1.24-1.26)
+- **Current policy**: n-2 versions (the operator supports the current and two previous minor Istio versions)
 - **Version alignment**: Operator version matches latest supported Istio version
 - **Patch version handling**: Not all Istio patch versions are included
+- **EOL versions**: Versions can be marked with `eol: true` to keep them as valid input but not installable
 
 ### Version Lifecycle
 1. **New Istio release** - Add to versions.yaml with charts