feat(vision): add rollout ADR and default-off flags

Author: a-klos

ADR-vision-embedding-rollout.md

@@ -0,0 +1,53 @@
+# ADR: Vision Embedding Rollout (Flag-Gated)
+
+- Status: Accepted
+- Date: 2026-02-16
+
+## Context
+
+STACKIT published a vision-capable embedder. We want to integrate image-native retrieval into the existing RAG pipeline without destabilizing production traffic.
+
+The current platform already supports `IMAGE` as a content type, but image ingestion/retrieval behavior is not yet consistently routed through a dedicated vision lane end-to-end.
+
+## Decision
+
+Roll out vision support behind explicit feature flags that default to `false`:
+
+- `VISION_IMAGE_LANE_ENABLED=false`
+- `VISION_EMBEDDING_ENABLED=false`
+- `VISION_IMAGE_RETRIEVER_ENABLED=false`
+
+Flags are exposed via Helm values and config maps for backend, admin-backend, and extractor.
+
+## Consequences
+
+### Positive
+
+- No behavior change on merge while flags stay off.
+- Safe staged rollout with reversible steps.
+- Easier incident response by disabling a specific lane.
+
+### Negative
+
+- Temporary configuration overhead while both legacy and vision paths exist.
+- Additional test matrix during rollout.
+
+## Rollout Notes
+
+- Keep all three flags `false` until the final rollout PR is merged and staging is validated.
+- Enable in sequence on staging:
+  1. `VISION_IMAGE_LANE_ENABLED`
+  2. `VISION_EMBEDDING_ENABLED`
+  3. `VISION_IMAGE_RETRIEVER_ENABLED`
+- Promote to production only after mixed-modality retrieval checks pass.
+
+## Telemetry Baseline (No Behavior Change in This ADR)
+
+Track these counters from the first behavior PR onward:
+
+- `vision.image_documents_ingested_total`
+- `vision.image_embeddings_written_total`
+- `vision.image_retrieval_hits_total`
+- `vision.image_retrieval_errors_total`
+
+This ADR only defines the rollout contract; metric instrumentation is introduced in later PRs.

infrastructure/rag/templates/_admin_backend_and_extractor_helpers.tpl

@@ -140,10 +140,18 @@
 {{- printf "%s-source-uploader-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
 {{- end -}}
 
+{{- define "configmap.adminVisionName" -}}
+{{- printf "%s-admin-vision-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
 {{- define "configmap.extractorSitemapName" -}}
 {{- printf "%s-extractor-sitemap-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
 {{- end -}}
 
+{{- define "configmap.extractorVisionName" -}}
+{{- printf "%s-extractor-vision-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
 # image
 {{- define "adminBackend.fullImageName" -}}
 {{- $tag := default .Chart.AppVersion .Values.adminBackend.image.tag -}}

infrastructure/rag/templates/_backend_helpers.tpl

@@ -103,6 +103,10 @@ basic-auth
 {{- printf "%s-retriever-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
 {{- end -}}
 
+{{- define "configmap.backendVisionName" -}}
+{{- printf "%s-backend-vision-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
+{{- end -}}
+
 {{- define "configmap.langfuseName" -}}
 {{- printf "%s-langfuse-configmap" .Release.Name | trunc 63 | trimSuffix "-" -}}
 {{- end -}}

infrastructure/rag/templates/admin-backend/configmap.yaml

@@ -42,3 +42,12 @@ data:
   {{- range $key, $value := .Values.adminBackend.envs.sourceUploader }}
   {{ $key }}: {{ $value | quote }}
   {{- end }}
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ template "configmap.adminVisionName" . }}
+data:
+  {{- range $key, $value := .Values.adminBackend.envs.vision }}
+  {{ $key }}: {{ $value | quote }}
+  {{- end }}

infrastructure/rag/templates/admin-backend/deployment.yaml

@@ -117,6 +117,8 @@ spec:
               name: {{ template "configmap.keyValueStoreName" . }}
           - configMapRef:
               name: {{ template "configmap.sourceUploaderName" . }}
+          - configMapRef:
+              name: {{ template "configmap.adminVisionName" . }}
           - configMapRef:
               name: {{ template "configmap.retryDecoratorName" . }}
           - configMapRef:

infrastructure/rag/templates/backend/configmap.yaml

@@ -18,6 +18,15 @@ data:
 ---
 apiVersion: v1
 kind: ConfigMap
+metadata:
+  name: {{ template "configmap.backendVisionName" . }}
+data:
+  {{- range $key, $value := .Values.backend.envs.vision }}
+  {{ $key }}: {{ $value | quote }}
+  {{- end }}
+---
+apiVersion: v1
+kind: ConfigMap
 metadata:
   name: {{ template "configmap.langfuseName" . }}
 data:

infrastructure/rag/templates/backend/deployment.yaml

@@ -109,6 +109,8 @@ spec:
               name: {{ template "configmap.embedderClassTypesName" . }}
           - configMapRef:
               name: {{ template "configmap.retrieverName" . }}
+          - configMapRef:
+              name: {{ template "configmap.backendVisionName" . }}
           - configMapRef:
               name: {{ template "configmap.rerankerName" . }}
           - configMapRef:

infrastructure/rag/templates/extractor/configmap.yaml

@@ -6,3 +6,12 @@ data:
   {{- range $key, $value := .Values.extractor.envs.sitemap }}
   {{ $key }}: {{ $value | quote }}
   {{- end }}
+---
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: {{ template "configmap.extractorVisionName" . }}
+data:
+  {{- range $key, $value := .Values.extractor.envs.vision }}
+  {{ $key }}: {{ $value | quote }}
+  {{- end }}

infrastructure/rag/templates/extractor/deployment.yaml

@@ -112,6 +112,8 @@ spec:
               name: {{ template "configmap.s3Name" . }}
           - configMapRef:
               name: {{ template "configmap.extractorSitemapName" . }}
+          - configMapRef:
+              name: {{ template "configmap.extractorVisionName" . }}
           - secretRef:
               name: {{ template "secret.s3RefName" . }}
         {{- $hfCacheDir := include "extractor.huggingfaceCacheDir" . }}

infrastructure/rag/values.yaml

@@ -196,6 +196,10 @@ backend:
       RETRIEVER_TABLE_K_DOCUMENTS: 10
       RETRIEVER_IMAGE_THRESHOLD: 0.7
       RETRIEVER_IMAGE_K_DOCUMENTS: 10
+    vision:
+      VISION_IMAGE_LANE_ENABLED: false
+      VISION_EMBEDDING_ENABLED: false
+      VISION_IMAGE_RETRIEVER_ENABLED: false
     errorMessages:
       ERROR_MESSAGES_NO_DOCUMENTS_MESSAGE: "I'm sorry, my responses are limited. You must ask the right questions."
       ERROR_MESSAGES_NO_OR_EMPTY_COLLECTION: "No documents were provided for searching."
@@ -390,6 +394,10 @@ adminBackend:
     sourceUploader:
       # Large sitemap ingestions (per-page summaries) can take > 1 hour.
       SOURCE_UPLOADER_TIMEOUT: 3600
+    vision:
+      VISION_IMAGE_LANE_ENABLED: false
+      VISION_EMBEDDING_ENABLED: false
+      VISION_IMAGE_RETRIEVER_ENABLED: false
 
 extractor:
   replicaCount: 1
@@ -448,6 +456,10 @@ extractor:
       # Options: "docusaurus" (default), "astro", "generic"
       # Note: https://docs.stackit.cloud is built with Astro/Starlight -> use "astro".
       SITEMAP_PARSER: docusaurus
+    vision:
+      VISION_IMAGE_LANE_ENABLED: false
+      VISION_EMBEDDING_ENABLED: false
+      VISION_IMAGE_RETRIEVER_ENABLED: false
 
 adminFrontend:
   name: admin-frontend