Update AGENTS.md and domain knowledge files

.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

.github/ai_agents/knowledge/domain-knowledge-api-types.md → .agents/knowledge/domain-knowledge-api-types.md

@@ -8,10 +8,13 @@ This document provides AI agents with detailed knowledge about the Sail Operator
 The primary resource for managing Istio control plane deployments.
 
 **Key Fields:**
-- `spec.version` - Istio version to install (defaults to operator's supported version)
-- `spec.namespace` - Target namespace for control plane (typically `istio-system`)
+- `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` - Controls how updates are performed (`InPlace` or `RevisionBased`)
+- `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.
@@ -34,27 +37,48 @@ Represents a specific deployment of Istio control plane components.
 Manages the Istio CNI plugin (required for OpenShift and Ambient mesh).
 
 **Key Fields:**
-- `spec.version` - CNI plugin version
-- `spec.namespace` - CNI installation namespace (typically `istio-cni`)
+- `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
 
-### ZTunnel Resource (Alpha)
+**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
-- `spec.namespace` - ZTunnel namespace (typically `ztunnel`)
+- `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.
+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` - Reference to target IstioRevision
-- `spec.tag` - Tag name (e.g., `canary`, `stable`)
+- `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:
 
@@ -153,13 +177,14 @@ spec:
 
 ### Ambient Mesh Setup
 ```yaml
-# 1. CNI
-apiVersion: sailoperator.io/v1alpha1
+# 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
@@ -168,10 +193,7 @@ metadata:
   name: default
 spec:
   namespace: istio-system
-  values:
-    pilot:
-      env:
-        PILOT_ENABLE_AMBIENT: true
+  profile: ambient
 
 # 3. ZTunnel
 apiVersion: sailoperator.io/v1
@@ -184,21 +206,21 @@ spec:
 
 ### Revision-Based Canary Deployment
 ```yaml
-# Main revision
+# Main Istio resource with RevisionBased strategy
 apiVersion: sailoperator.io/v1
 kind: Istio
 metadata:
-  name: stable
+  name: default
 spec:
   namespace: istio-system
   updateStrategy:
     type: RevisionBased
 
-# Canary revision tag
+# Revision tag pointing to the Istio resource
 apiVersion: sailoperator.io/v1
 kind: IstioRevisionTag
 metadata:
-  name: canary
+  name: stable
 spec:
   targetRef:
     kind: Istio

.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

.github/ai_agents/AGENTS.md → AGENTS.md

@@ -4,7 +4,7 @@ This document provides AI coding agents with project-specific context for the Sa
 
 ## Project Overview
 
-The Sail Operator is a Kubernetes operator built to manage Istio service mesh deployments. It provides custom resources (`Istio`, `IstioRevision`, `IstioCNI`, `ZTunnel`) to deploy and manage control plane components.
+The Sail Operator is a Kubernetes operator built to manage Istio service mesh deployments. It provides custom resources (`Istio`, `IstioRevision`, `IstioRevisionTag`, `IstioCNI`, `ZTunnel`) to deploy and manage control plane components.
 
 ## Setup Commands
 
@@ -83,8 +83,8 @@ CONTAINER_CLI=podman DOCKER_GID=0 make deploy
 
 ### Resource Relationships
 - `Istio` creates and manages `IstioRevision`
-- `IstioRevisionTag` points to a `Istio` resource
-- Ambient mode requires `Istio` + `ZTunnel` (+ `IstioCNI` on OpenShift)
+- `IstioRevisionTag` points to an `Istio` or `IstioRevision` resource
+- Ambient mode requires `Istio` + `IstioCNI` + `ZTunnel`
 - Sidecar mode requires `Istio` (+ `IstioCNI` on OpenShift)
 
 ## Key Configuration Files
@@ -124,8 +124,10 @@ The project supports downstream vendors with custom configurations:
 ## Versioning Policy
 
 - Sail Operator versions follow Istio versioning
-- Supports n-2 Istio releases (e.g., Sail 1.27 supports Istio 1.25-1.27)
+- Supports n-2 Istio releases (the operator supports the current and two previous minor Istio versions)
 - Not all Istio patch versions are included in Sail releases
+- EOL versions remain valid inputs but are not installable
+- Check `pkg/istioversion/versions.yaml` for the current list of supported versions
 
 ## Security
 
@@ -156,15 +158,15 @@ The operator deploys Istio using Helm charts and follows Istio's configuration p
 For detailed technical knowledge about specific areas of the Sail Operator, refer to these domain-specific documents:
 
 ### API and Resource Management
-- **[API Types and CRDs](.github/ai_agents/knowledge/domain-knowledge-api-types.md)** - Detailed knowledge about Custom Resource Definitions, API types, validation rules, and resource relationships
-- **[Controllers Architecture](.github/ai_agents/knowledge/domain-knowledge-controllers.md)** - Controller reconciliation patterns, error handling, debugging, and inter-controller communication
+- **[API Types and CRDs](.agents/knowledge/domain-knowledge-api-types.md)** - Detailed knowledge about Custom Resource Definitions, API types, validation rules, and resource relationships
+- **[Controllers Architecture](.agents/knowledge/domain-knowledge-controllers.md)** - Controller reconciliation patterns, error handling, debugging, and inter-controller communication
 
 ### Development and Operations
-- **[Helm Integration](.github/ai_agents/knowledge/domain-knowledge-helm-integration.md)** - Chart management, values processing, platform customization, and troubleshooting
-- **[Testing Framework](.github/ai_agents/knowledge/domain-knowledge-testing-framework.md)** - Unit/integration/E2E testing methodologies, utilities, and best practices
-- **[Version Management](.github/ai_agents/knowledge/domain-knowledge-version-management.md)** - Version compatibility, upgrade strategies, chart management, and troubleshooting
+- **[Helm Integration](.agents/knowledge/domain-knowledge-helm-integration.md)** - Chart management, values processing, platform customization, and troubleshooting
+- **[Testing Framework](.agents/knowledge/domain-knowledge-testing-framework.md)** - Unit/integration/E2E testing methodologies, utilities, and best practices
+- **[Version Management](.agents/knowledge/domain-knowledge-version-management.md)** - Version compatibility, upgrade strategies, chart management, and troubleshooting
 
 ### Creating New Domain Knowledge
-- **[Domain Knowledge Creation Guide](.github/ai_agents/domain_knowledge_prompt.md)** - Template and guidelines for creating new domain knowledge files
+- **[Domain Knowledge Creation Guide](.agents/domain_knowledge_prompt.md)** - Template and guidelines for creating new domain knowledge files
 
 Each domain knowledge file provides deep, technical details that complement the high-level guidance in this document. Use them for specific implementation questions and detailed understanding of system behavior.