docs(Kong/kong-operator): update Kong/kong-operator docs

.github/styles/base/Dictionary.txt

@@ -192,6 +192,7 @@ db_import
 db-ip
 dbless
 dcr
+debounce
 DECK_
 deck_files
 declaratively
@@ -501,6 +502,7 @@ M_Link
 M_Resource
 maglev
 major_version
+malforming
 managedfields
 matchers
 max_args
@@ -661,6 +663,7 @@ proxy_listen
 proxy_ssl
 proxying
 public_key
+pushable
 Qdrant
 qubit
 querystring
@@ -698,6 +701,8 @@ reportingComponent
 reportingInstance
 requery
 requeue
+requeued
+requeues
 requeuing
 request_counts
 requestable
@@ -745,6 +750,7 @@ Scriptable
 SDKs
 search_by_username
 secret_id
+semver
 sequenceDiagram
 serializer
 serverless
@@ -901,6 +907,7 @@ unicode
 unix
 unlinking
 unmanaged
+unmarshal
 unmarshalled
 unnamespaced
 unnormalized

app/operator/changelog.md

@@ -14,6 +14,115 @@ breadcrumbs:
 
 Changelog for supported {{ site.operator_product_name }} versions.
 
+## 2.4.0-rapid.2.0
+
+**Release date**: 2026-09-30
+
+### Added
+
+- `DataPlane`: added `ipFamilies` and `ipFamilyPolicy` to
+  `spec.network.services.ingress`. The requested setting to these fields must be
+  supported by the cluster. When the operator's IP family is dual and both fields
+  are unset, the ingress Service defaults to `PreferDualStack`.
+  [#5797](https://github.com/Kong/kong-operator/pull/5797)
+- `KongLicense` is now handled for the on-prem {{site.ai_gateway}}: the operator picks
+  the newest enabled `KongLicense` and propagates it to `AIGatewayDataPlane`
+  gateway pods via the `KONG_LICENSE_DATA` environment variable. License
+  availability is reported on the `AIGatewayDataPlane` and `OnPremAIGateway`
+  status via a new `LicenseValid` condition, which does not gate `Ready`.
+  [#5912](https://github.com/Kong/kong-operator/issues/5912)
+- The on-prem {{site.ai_gateway}} control plane instances now dynamically discover the
+  Admin API endpoints of all `AIGatewayDataPlane`s that reference the gateway
+  via `spec.controlPlaneRef.type: onpremNamespacedRef` (through their Admin
+  API Services' EndpointSlices) and re-render the configuration when the
+  discovered endpoint set changes. Multiple `AIGatewayDataPlane`s can now
+  reference the same `OnPremAIGateway`.
+  [#5740](https://github.com/Kong/kong-operator/issues/5740)
+- The on-prem {{site.ai_gateway}} control plane instances now push the rendered
+  configuration to the Admin API of every discovered `AIGatewayDataPlane`
+  endpoint over mTLS, using a cluster-CA-signed client certificate Secret
+  provisioned per `OnPremAIGateway`. Push failures are reported on the
+  gateway's `DataPlanesConfigured` condition and as Warning events, and the
+  failed pushes are retried.
+  [#5401](https://github.com/Kong/kong-operator/issues/5401)
+- Added the `KonnectConfigStoreSync` controller to continuously sync selected
+  data from a Kubernetes `Secret` into a Konnect Config Store. It supports
+  combined certificate/key and split-entry modes, validates data before
+  writing, resolves contested store keys deterministically, and provides
+  `Orphan` and `Delete` lifecycle policies without exposing Secret plaintext in
+  status, logs, or events.
+  [#5773](https://github.com/Kong/kong-operator/pull/5773),
+  [#5779](https://github.com/Kong/kong-operator/pull/5779),
+  [#5785](https://github.com/Kong/kong-operator/pull/5785)
+- `PortalPage`: `spec.apiSpec.parentPageIDRef` can now reference another
+  `PortalPage` (by `namespacedRef` or `konnectID`) to build page hierarchies;
+  the operator resolves the reference to the parent's Konnect ID and watches
+  referenced pages for changes.
+  [#5701](https://github.com/Kong/kong-operator/pull/5701)
+- Added `AIGatewayCustomPolicy` CRD: manage Konnect {{site.ai_gateway}} custom policies
+  (`aiconfiguration.konghq.com/v1alpha1`), parented to `KonnectAIGateway`,
+  supporting both `installed` and `streaming` (Lua `schema` and `handler`)
+  custom policy types. `OnPremAIGateway` references are not supported yet
+  and are rejected at admission.
+  [#5896](https://github.com/Kong/kong-operator/pull/5896)
+- `AIGatewayCustomPolicy`: `labels` and `managedBy` can now be set on both the
+  `installed` and `streaming` custom policy types and are propagated to Konnect.
+  The operator now labels custom policies with the owning object's Kubernetes
+  metadata and, on a create conflict, only adopts a Konnect custom policy
+  carrying the object's UID label (previously it matched by type and name).
+  This prevents two objects declaring the same policy name from sharing, and
+  overwriting or deleting, the same Konnect custom policy. The custom policy
+  `type` is now immutable, as Konnect rejects switching between `installed`
+  and `streaming`.
+  [#5901](https://github.com/Kong/kong-operator/pull/5901)
+- `AIGatewayCustomPolicy`: the Lua `schema` and `handler` sources can be
+  provided inline (`type: inline` with `value`) or read from a key of a
+  `ConfigMap` in the same namespace (`type: configMapRef` with
+  `configMapRef.name` and `configMapRef.key`). The `ConfigMap` must match the
+  operator's `--config-map-label-selector` (`konghq.com/configmap: "true"` by
+  default). The `ConfigMapRefValid` condition reports missing `ConfigMap`s or
+  keys. Changes to a referenced `ConfigMap` are applied to Konnect on the next
+  sync (`--konnect-sync-period`).
+  [#5907](https://github.com/Kong/kong-operator/pull/5907)
+- `AIGatewayPolicy`: added `spec.apiSpec.customPolicyRef` to use an
+  `AIGatewayCustomPolicy` from the cluster instead of setting `spec.apiSpec.type`
+  to the custom policy's Konnect name. The operator waits until the referenced
+  custom policy exists in Konnect and is not being deleted, and sends its
+  Konnect name as the policy type. Exactly one of `type` and `customPolicyRef`
+  must be set; `type` keeps accepting built-in and custom policy names.
+  [#5904](https://github.com/Kong/kong-operator/pull/5904)
+- `AIGatewayCustomPolicy`: deleting a custom policy that policies still use is
+  blocked (`Programmed=False`, reason `DeletionBlocked`, naming the
+  `AIGatewayPolicy` objects using it and any Konnect policies not managed from
+  the cluster) and proceeds once they are gone.
+  [#5904](https://github.com/Kong/kong-operator/pull/5904)
+
+### Fixes
+
+- Resolving `Secret`-sourced fields no longer writes the resolved values into
+  the cached object when they sit under a union variant or in a list.
+  [#5907](https://github.com/Kong/kong-operator/pull/5907)
+- Gateway: when more than one `ControlPlane` is found for a `Gateway`, the
+  extra ones are now deleted and the oldest is kept. Previously, two
+  reconciliations running close together could each create a `ControlPlane`.
+  The `Gateway` then stayed stuck with `Programmed=False`, while two control
+  plane instances served the same ingress class and sent configuration to the
+  same `DataPlane`.
+  [#5855](https://github.com/Kong/kong-operator/pull/5855)
+- Konnect: labels set in an entity's spec can no longer override the labels
+  the operator adds to Konnect entities (`k8s-name`, `k8s-namespace`, `k8s-uid`,
+  `k8s-generation`, `k8s-kind`, `k8s-group`, `k8s-version` and `managed-by`).
+  Previously, a spec label such as `k8s-uid` replaced the operator's value. The
+  operator then could not find the entity it owns in Konnect, so it could not
+  recover a lost entity ID or delete the entity when the object was deleted.
+  [#5917](https://github.com/Kong/kong-operator/pull/5917)
+- {{site.ai_gateway}} configuration entities: free-form `config` (e.g. of an
+  `AIGatewayPolicy`) is now sent to Konnect verbatim. Previously, config whose
+  data looked like a discriminated union (such as a headroom compressor config
+  with `provider: headroom` next to a `headroom` block) was flattened, and
+  Konnect rejected it with "unknown field" errors.
+  [#5888](https://github.com/Kong/kong-operator/pull/5888)
+
 ## 2.4.0-rapid.1
 
 **Release date**: 2026-09-23
@@ -147,7 +256,7 @@ by the operator's semver:
   previous shape could only hold scalar strings, so `paths`/`hosts`/`methods`
   could never be expressed as the arrays Kong's route matching actually requires,
   and every `AIGatewayMCPServer` with a non-empty `route` failed to reconcile
-  (`Programmed=False`/`FailedToCreate`) with an SDK unmarshall error.
+  (`Programmed=False`/`FailedToCreate`) with an SDK unmarshal error.
   Recovery: change `route.paths`/`route.hosts`/`route.methods` from a bare string
   to a list, e.g. `paths: /mcp/foo` becomes `paths: [/mcp/foo]`.
   [#5804](https://github.com/Kong/kong-operator/pull/5804)
@@ -298,7 +407,7 @@ by the operator's semver:
 
 **Release date**: 2026-09-28
 
-### Breaking changes (before, it was broken)
+### Breaking changes
 
 - `AIGatewayMCPServer`: `route` (under the `conversion-listener`/`conversion-only`/
   `listener`/`passthrough-listener`/`upstream-server` `config`) changes from an
@@ -307,7 +416,7 @@ by the operator's semver:
   previous shape could only hold scalar strings, so `paths`/`hosts`/`methods`
   could never be expressed as the arrays Kong's route matching actually requires,
   and every `AIGatewayMCPServer` with a non-empty `route` failed to reconcile
-  (`Programmed=False`/`FailedToCreate`) with an SDK unmarshall error.
+  (`Programmed=False`/`FailedToCreate`) with an SDK unmarshal error.
   Recovery: change `route.paths`/`route.hosts`/`route.methods` from a bare string
   to a list, e.g. `paths: /mcp/foo` becomes `paths: [/mcp/foo]`.
   [#5804](https://github.com/Kong/kong-operator/pull/5804)
@@ -351,7 +460,7 @@ by the operator's semver:
   only holds scalar values, `paths`/`hosts`/`methods` could not be expressed as the
   lists Kong's route matching requires: `kubectl apply` accepted the resource, but
   every `AIGatewayMCPServer` with a non-empty `route` then failed to reconcile with
-  `Programmed=False`/`FailedToCreate` and an SDK unmarshall error
+  `Programmed=False`/`FailedToCreate` and an SDK unmarshal error
   (`could not unmarshall ... into any supported union types for
   AIGatewayMCPServerRouteWithMatcher`), making the field unusable in practice. The
   root cause was in `crd-from-oas`, which fell back to `map[string]string` for a
@@ -504,7 +613,7 @@ by the operator's semver:
   - introduce `AIGatewayMCPServer` CRD with reconciler.
   [#4836](https://github.com/Kong/kong-operator/pull/4836)
   - `KonnectAIGateway` now supports `spec.source: Mirror`, referencing an
-    existing {{site.konnect_short_name}} {{site.ai_gateway}} by ID (`spec.mirror.konnect.id`) instead of
+    existing Konnect {{site.ai_gateway}} by ID (`spec.mirror.konnect.id`) instead of
     creating one. `Origin` (the default) is unchanged.
     [#4928](https://github.com/Kong/kong-operator/pull/4928)
 - GRPCRoute: enable GRPCRoute for on-prem gateway
@@ -539,8 +648,8 @@ by the operator's semver:
 - `KongCertificate`: `spec.cert`, `spec.key`, `spec.cert_alt` and `spec.key_alt`
   now explicitly support Kong vault references (e.g.
   `{vault://certvault/my-service-key}`) in addition to inline PEM material, so
-  certificate material can be kept out of Kubernetes and resolved by
-  {{site.base_gateway}} at runtime. Values that start with `{vault:` are validated against the
+  certificate material can be kept out of Kubernetes and resolved by Kong
+  Gateway at runtime. Values that start with `{vault:` are validated against the
   vault reference format at admission time, valid references are passed to
   Konnect unchanged.
   [#5159](https://github.com/Kong/kong-operator/pull/5159)
@@ -644,7 +753,7 @@ by the operator's semver:
   [#4714](https://github.com/Kong/kong-operator/pull/4714)
 - Conformance: enable `GRPCRoute` conformance tests for on-prem.
   [#4673](https://github.com/Kong/kong-operator/pull/4673)
-- {{site.event_gateway}}: update the default KEG DataPlane image to `kong/kong-event-gateway:1.2.1`.
+- Kong Event Gateway: update the default KEG DataPlane image to `kong/kong-event-gateway:1.2.1`.
   [#5137](https://github.com/Kong/kong-operator/pull/5137)
 - `AIGateway`: Reference `AIGatewayPolicy` resources by `AIGatewayPolicyRef` in
   the nested fields of `AIGatewayModel` and `AIGatewayMCPServer`.
@@ -793,15 +902,15 @@ by the operator's semver:
   updates so concurrent Routes do not clobber each other's route references, and
   orphan cleanup does not delete resources that changed after the cleanup
   decision. If a shared Kong resource is concurrently deleted before a Route
-  records itself, the Route re-queues to recreate it instead of stalling.
+  records itself, the Route requeues to recreate it instead of stalling.
   [#4567](https://github.com/Kong/kong-operator/pull/4567)
 - `HybridGateway`: use route-scoped `KongService` names for `HTTPRoute` rules
   whose backendRefs resolve to no valid targets. This avoids Konnect name
   conflicts with valid backend services while keeping normally generated service
   names unchanged.
   [#4437](https://github.com/Kong/kong-operator/pull/4437)
 - Prevent recreating consumer credentials on every Konnect sync when running in
-  "KIC in Konnect" mode with on-prem `ControlPlane`.
+  "KIC in Konnect" mode with on prem `ControlPlane`.
   [#4622](https://github.com/Kong/kong-operator/pull/4622)
 - `HybridGateway`: merge `HTTPRoute` filters that map to the same Kong plugin type
   (for example a `URLRewrite` and a `RequestHeaderModifier`, both of which
@@ -830,10 +939,10 @@ by the operator's semver:
   "no corresponding type" for operator-owned CRD kinds (`KegDataPlane`, etc.).
   The `managedfields.TypeConverter` was built once at startup from the API
   server's `/openapi/v3` endpoint, which publishes CRD schemas asynchronously
-  (up to a ~60 s delay). CRDs that were not yet published were silently skipped,
-  permanently breaking SSA, including status writes, until the next restart.
+  (up to ~60 s debounce). CRDs that were not yet published were silently skipped,
+  permanently breaking SSA — including status writes — until the next restart.
   The converter is now built in-process from the live CRD objects (apiserver-style,
-  with no delay) and atomically refreshed by a dedicated CRD controller
+  zero debounce latency) and atomically refreshed by a dedicated CRD controller
   whenever a relevant CRD changes at runtime.
   [#4795](https://github.com/Kong/kong-operator/pull/4795)
 - Dataplane: Fixed the method to compare whether dataplane options are deep
@@ -886,7 +995,7 @@ by the operator's semver:
   deleted, allowing its Konnect counterpart and cleanup finalizer to be removed.
   [#5229](https://github.com/Kong/kong-operator/pull/5229)
 - `DataPlaneMetricsExtension`: the reconciler now returns an error (and gets
-  re-queued with backoff) when it fails to create, update or delete the
+  requeued with backoff) when it fails to create, update or delete the
   Prometheus `KongPlugin` for a Service, instead of logging and giving up.
   Previously a single transient failure (e.g. a rejected admission webhook
   call) left the Service without its `konghq.com/plugins` annotation
@@ -985,7 +1094,7 @@ by the operator's semver:
   deleted, allowing its Konnect counterpart and cleanup finalizer to be removed.
   [#5229](https://github.com/Kong/kong-operator/pull/5229) [#5232](https://github.com/Kong/kong-operator/pull/5232)
 - DataPlaneMetricsExtension: the reconciler now returns an error (and gets
-  re-queued with backoff) when it fails to create, update or delete the
+  requeued with backoff) when it fails to create, update or delete the
   Prometheus `KongPlugin` for a Service, instead of logging and giving up.
   Previously a single transient failure (e.g. a rejected admission webhook
   call) left the Service without its `konghq.com/plugins` annotation
@@ -1055,7 +1164,7 @@ by the operator's semver:
   names unchanged.
   [#4437](https://github.com/Kong/kong-operator/pull/4437) [#4559](https://github.com/Kong/kong-operator/pull/4559)
 - Prevent recreating consumer credentials on every Konnect sync when running in
-  "KIC in Konnect" mode with on-prem `ControlPlane`.
+  "KIC in Konnect" mode with on prem `ControlPlane`.
   [#4622](https://github.com/Kong/kong-operator/pull/4622)
 - Hybridgateway: fix `KongTarget` stuck in `Programmed=False` when multiple
   backendRef Services in an HTTPRoute or TLSRoute rule resolve to the same pod
@@ -1223,7 +1332,7 @@ by the operator's semver:
   to reference existing Konnect control planes by ID.
   [#3612](https://github.com/Kong/kong-operator/pull/3612)
 - Added `managed-by:kong-operator` tag to all Konnect entities to allow
-  filtering resources managed by {{site.operator_product_name}} in {{site.konnect_short_name}}.
+  filtering resources managed by {{site.operator_product_name}} in Konnect.
   [#3609](https://github.com/Kong/kong-operator/pull/3609)
 - Added MCP ControlPlane signalling controller: a new `MCPServerCPReconciler` watches
   `KonnectGatewayControlPlane` resources and, via a `SignalManager`, maintains per-control-plane
@@ -1454,7 +1563,7 @@ by the operator's semver:
 ### Fixes
 
 - Prevent recreating consumer credentials on every Konnect sync when running in
-  "KIC in Konnect" mode with on-prem `ControlPlane`.
+  "KIC in Konnect" mode with on prem `ControlPlane`.
   [#4623](https://github.com/Kong/kong-operator/pull/4622) [#4624](https://github.com/Kong/kong-operator/pull/4624)
 - Hybridgateway: merge `HTTPRoute` filters that map to the same Kong plugin type
   (for example a `URLRewrite` and a `RequestHeaderModifier`, both of which
@@ -2793,7 +2902,7 @@ by the operator's semver:
 - `Gateway` do not have their `Ready` status condition set anymore.
   This aligns with Gateway API and its conformance test suite.
   [#246](https://github.com/kong/kong-operator/pull/246)
-- `Gateway`s' listeners now have their `attachedRoutes` count filled in the status.
+- `Gateway`s' listeners now have their `attachedRoutes` count filled in status.
   [#251](https://github.com/kong/kong-operator/pull/251)
 - Detect when `ControlPlane` has its admission webhook disabled via
   `CONTROLLER_ADMISSION_WEBHOOK_LISTEN` environment variable and ensure that

app/operator/reference/configuration-options.md

@@ -160,6 +160,10 @@ rows:
     type: '`bool`'
     description: "Enable the Konnect controllers."
     default: '`false`'
+  - flag: '`--enable-controller-onpremaigateway`'
+    type: '`bool`'
+    description: "Enable the on-prem AI Gateway (control plane) controller."
+    default: '`false`'
   - flag: '`--enable-controlplane-config-dump`'
     type: '`bool`'
     description: "Enable the server to dump generated Kong configuration from ControlPlanes. Only effective when ControlPlane controller is enabled."
@@ -192,6 +196,10 @@ rows:
     type: '`string`'
     description: "The address the probe endpoint binds to."
     default: '`:8081`'
+  - flag: '`--ip-family`'
+    type: '`string`'
+    description: "IP family of the cluster, used e.g. to decide which IP family (or families) DataPlanes' Kong listens bind to. Possible values: auto, ipv4, ipv6, dual. When 'auto' (default), the operator detects the cluster's IP family at startup and exits with an error if detection fails."
+    default: '`"auto"`'
   - flag: '`--konnect-controller-max-concurrent-reconciles`'
     type: '`uint`'
     description: "Deprecated: Please use '--max-concurrent-reconciles-konnect-controller' instead."
@@ -202,7 +210,7 @@ rows:
     default: '`10s`'
   - flag: '`--konnect-sync-period`'
     type: '`duration`'
-    description: "Sync period for Konnect entities. After a successful reconciliation of Konnect entities the controller will wait this duration before enforcing configuration on Konnect once again."
+    description: "Sync period for Konnect entities. Must be greater than 0. After a successful reconciliation of Konnect entities the controller will wait this duration before enforcing configuration on Konnect once again."
     default: '`1m0s`'
   - flag: '`--kubeconfig`'
     type: '`string`'