feat(library): Add pkg/install library for embedding Istio installation in external operators

bundle/bundle.go

@@ -0,0 +1,20 @@
+// Copyright Istio Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+package bundle
+
+import _ "embed"
+
+//go:embed manifests/servicemeshoperator3.clusterserviceversion.yaml
+var CSV []byte

chart/crds/crds.go

@@ -0,0 +1,27 @@
+// Copyright Istio Authors
+//
+// Licensed under the Apache License, Version 2.0 (the "License");
+// you may not use this file except in compliance with the License.
+// You may obtain a copy of the License at
+//
+//     http://www.apache.org/licenses/LICENSE-2.0
+//
+// Unless required by applicable law or agreed to in writing, software
+// distributed under the License is distributed on an "AS IS" BASIS,
+// WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+// See the License for the specific language governing permissions and
+// limitations under the License.
+
+// Package crds provides embedded CRD YAML files for Istio and Sail resources.
+package crds
+
+import "embed"
+
+// FS contains all CRD YAML files from the chart/crds directory.
+// This allows programmatic access to CRDs for installation.
+//
+// CRD files follow the naming convention: {group}_{plural}.yaml
+// Example: extensions.istio.io_wasmplugins.yaml
+//
+//go:embed *.yaml
+var FS embed.FS

go.mod

@@ -31,7 +31,9 @@ require (
 	k8s.io/apimachinery v0.35.1
 	k8s.io/cli-runtime v0.35.0
 	k8s.io/client-go v0.35.1
+	k8s.io/utils v0.0.0-20260108192941-914a6e750570
 	sigs.k8s.io/controller-runtime v0.23.3
+	sigs.k8s.io/yaml v1.6.0
 )
 
 require (
@@ -175,7 +177,6 @@ require (
 	k8s.io/klog/v2 v2.130.1 // indirect
 	k8s.io/kube-openapi v0.0.0-20251125145642-4e65d59e963e // indirect
 	k8s.io/kubectl v0.35.0 // indirect
-	k8s.io/utils v0.0.0-20260108192941-914a6e750570 // indirect
 	oras.land/oras-go/v2 v2.6.0 // indirect
 	sigs.k8s.io/apiserver-network-proxy/konnectivity-client v0.32.1 // indirect
 	sigs.k8s.io/controller-tools v0.14.0 // indirect
@@ -184,5 +185,4 @@ require (
 	sigs.k8s.io/kustomize/kyaml v0.20.1 // indirect
 	sigs.k8s.io/randfill v1.0.0 // indirect
 	sigs.k8s.io/structured-merge-diff/v6 v6.3.2 // indirect
-	sigs.k8s.io/yaml v1.6.0 // indirect
 )

pkg/install/README.md

@@ -0,0 +1,109 @@
+# pkg/install
+
+Library for managing istiod installations without running the Sail Operator.
+Designed for embedding in other operators (e.g. OpenShift Ingress) that need
+to install and maintain Istio as an internal dependency.
+
+## Usage
+
+```go
+lib, err := install.New(kubeConfig, resourceFS)
+notifyCh := lib.Start(ctx)
+
+// In controller reconcile:
+lib.Apply(install.Options{
+    Namespace: "istio-system",
+    Values:    install.GatewayAPIDefaults(),
+})
+
+// Read result after notification:
+for range notifyCh {
+    status := lib.Status()
+    // update conditions from status
+}
+
+// Teardown:
+lib.Uninstall(ctx, "istio-system", "default")
+```
+
+## How it works
+
+The Library runs as an independent actor with a simple state model:
+
+1. **Apply** -- consumer sends desired state (version, namespace, values)
+2. **Reconcile** -- Library installs/upgrades CRDs and istiod via Helm
+3. **Drift detection** -- dynamic informers watch owned resources and CRDs, re-enqueuing reconciliation on changes
+4. **Status** -- consumer reads the reconciliation result
+
+The reconciliation loop sits idle until the first `Apply()` call. After that,
+it stays active with informers running until `Uninstall()` clears the desired
+state and stops the loop.
+
+## Public API
+
+### Constructor
+
+- `New(kubeConfig, resourceFS)` -- creates a Library with Kubernetes clients, Helm chart manager, and CRD manager
+- `FromDirectory(path)` -- creates an `fs.FS` from a filesystem path (alternative to embedded resources)
+
+### Library methods
+
+| Method | Description |
+|---|---|
+| `Start(ctx)` | Starts the reconciliation loop; returns a notification channel |
+| `Apply(opts)` | Sets desired state; enqueues reconciliation if changed |
+| `Enqueue()` | Forces re-reconciliation without changing desired state |
+| `Status()` | Returns the latest reconciliation result |
+| `Uninstall(ctx, ns, rev)` | Stops informers, waits for processing, then Helm-uninstalls |
+
+### Types
+
+- **Options** -- install options: `Namespace`, `Version`, `Revision`, `Values`, `ManageCRDs`, `IncludeAllCRDs`, `OverwriteOLMManagedCRD`
+- **Status** -- reconciliation result: `CRDState`, `CRDMessage`, `CRDs`, `Installed`, `Version`, `Error`
+- **CRDManagementState** -- aggregate CRD ownership: `ManagedByCIO`, `ManagedByOLM`, `UnknownManagement`, `MixedOwnership`, `NoneExist`
+- **CRDInfo** -- per-CRD state: `Name`, `State`, `Found`
+- **ImageNames** -- image names for each component: `Istiod`, `Proxy`, `CNI`, `ZTunnel`
+
+### Helper functions
+
+- `GatewayAPIDefaults()` -- pre-configured values for Gateway API mode on OpenShift
+- `MergeValues(base, overlay)` -- deep-merge two Values structs (overlay wins)
+- `DefaultVersion(resourceFS)` -- highest stable semver version from the resource FS
+- `NormalizeVersion(version)` -- ensures a `v` prefix
+- `ValidateVersion(resourceFS, version)` -- checks that a version directory exists
+- `SetImageDefaults(resourceFS, registry, images)` -- populates image refs from version directories
+- `LibraryRBACRules()` -- returns RBAC PolicyRules for a consumer's ClusterRole
+
+## CRD management
+
+The Library classifies existing CRDs by ownership labels before deciding what to do:
+
+| State | Meaning | Action |
+|---|---|---|
+| `NoneExist` | No target CRDs on cluster | Install with CIO labels |
+| `ManagedByCIO` | All owned by Cluster Ingress Operator | Update as needed |
+| `ManagedByOLM` | All owned by OLM (OSSM subscription) | Leave alone; Helm install proceeds |
+| `UnknownManagement` | CRDs exist without recognized labels | Leave alone; set Status.Error |
+| `MixedOwnership` | Inconsistent labels across CRDs | Leave alone; set Status.Error |
+
+The `OverwriteOLMManagedCRD` callback in Options lets the consumer decide
+whether to take over OLM-managed CRDs (e.g. after an OSSM subscription is deleted).
+
+Which CRDs are targeted depends on `IncludeAllCRDs`: when false (default), only
+CRDs matching `PILOT_INCLUDE_RESOURCES` / `PILOT_IGNORE_RESOURCES` are managed.
+
+## Files
+
+| File | Purpose |
+|---|---|
+| `library.go` | Public API, types (`Library`, `Status`, `Options`), constructor |
+| `lifecycle.go` | Reconciliation loop, workqueue, `Start`/`Apply`/`Uninstall` |
+| `installer.go` | Core install/uninstall logic, Helm values resolution, watch spec extraction |
+| `crds.go` | CRD ownership classification, install, update |
+| `crds_filter.go` | CRD selection based on `PILOT_INCLUDE_RESOURCES` / `PILOT_IGNORE_RESOURCES` |
+| `values.go` | `GatewayAPIDefaults()`, `MergeValues()` |
+| `predicates.go` | Event filtering for informers (ownership checks, status-only changes) |
+| `informers.go` | Dynamic informer setup for drift detection |
+| `version.go` | Version resolution and validation |
+| `images.go` | Image configuration from resource FS |
+| `rbac.go` | RBAC rules for library consumers |