From 5100d98e3c62912cef5e1e89be6e97ab3a8f335a Mon Sep 17 00:00:00 2001 From: d-robotics Date: Thu, 3 Sep 2026 12:21:54 +0800 Subject: [PATCH] deploy: add Kubernetes Helm delivery --- Makefile | 13 +- README.md | 5 +- deploy/helm/environments/values.example.yaml | 50 +++ deploy/helm/knowledge-platform/Chart.yaml | 15 + .../charts/rabbitmq/Chart.yaml | 6 + .../charts/rabbitmq/templates/_helpers.tpl | 11 + .../charts/rabbitmq/templates/service.yaml | 16 + .../rabbitmq/templates/serviceaccount.yaml | 8 + .../rabbitmq/templates/statefulset.yaml | 109 ++++++ .../charts/rabbitmq/values.schema.json | 69 ++++ .../charts/rabbitmq/values.yaml | 25 ++ .../knowledge-platform/templates/NOTES.txt | 12 + .../knowledge-platform/templates/_helpers.tpl | 106 ++++++ .../templates/api-deployment.yaml | 75 ++++ .../templates/api-service.yaml | 17 + .../templates/configmap.yaml | 66 ++++ .../knowledge-platform/templates/ingress.yaml | 42 +++ .../templates/mcp-deployment.yaml | 72 ++++ .../templates/mcp-service.yaml | 17 + .../templates/migration-job.yaml | 59 +++ .../templates/scheduler-deployment.yaml | 71 ++++ .../templates/serviceaccount.yaml | 13 + .../templates/tests/preflight-references.yaml | 17 + .../templates/worker-deployment.yaml | 71 ++++ .../knowledge-platform/values.schema.json | 338 ++++++++++++++++++ deploy/helm/knowledge-platform/values.yaml | 218 +++++++++++ docs/architecture/ARCHITECTURE.md | 5 + docs/development/CONTAINER_IMAGES.md | 7 +- docs/development/KUBERNETES_DEPLOYMENT.md | 143 ++++++++ docs/plans/PROGRESS.md | 28 ++ docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md | 8 +- docs/plans/TASKS.md | 2 +- docs/plans/V1_EXECUTION_PLAN.md | 2 +- docs/product/PRD.md | 4 + scripts/deploy.sh | 130 +++++++ tests/unit/test_helm_deployment.py | 154 ++++++++ 36 files changed, 1993 insertions(+), 11 deletions(-) create mode 100644 deploy/helm/environments/values.example.yaml create mode 100644 deploy/helm/knowledge-platform/Chart.yaml create mode 100644 deploy/helm/knowledge-platform/charts/rabbitmq/Chart.yaml create mode 100644 deploy/helm/knowledge-platform/charts/rabbitmq/templates/_helpers.tpl create mode 100644 deploy/helm/knowledge-platform/charts/rabbitmq/templates/service.yaml create mode 100644 deploy/helm/knowledge-platform/charts/rabbitmq/templates/serviceaccount.yaml create mode 100644 deploy/helm/knowledge-platform/charts/rabbitmq/templates/statefulset.yaml create mode 100644 deploy/helm/knowledge-platform/charts/rabbitmq/values.schema.json create mode 100644 deploy/helm/knowledge-platform/charts/rabbitmq/values.yaml create mode 100644 deploy/helm/knowledge-platform/templates/NOTES.txt create mode 100644 deploy/helm/knowledge-platform/templates/_helpers.tpl create mode 100644 deploy/helm/knowledge-platform/templates/api-deployment.yaml create mode 100644 deploy/helm/knowledge-platform/templates/api-service.yaml create mode 100644 deploy/helm/knowledge-platform/templates/configmap.yaml create mode 100644 deploy/helm/knowledge-platform/templates/ingress.yaml create mode 100644 deploy/helm/knowledge-platform/templates/mcp-deployment.yaml create mode 100644 deploy/helm/knowledge-platform/templates/mcp-service.yaml create mode 100644 deploy/helm/knowledge-platform/templates/migration-job.yaml create mode 100644 deploy/helm/knowledge-platform/templates/scheduler-deployment.yaml create mode 100644 deploy/helm/knowledge-platform/templates/serviceaccount.yaml create mode 100644 deploy/helm/knowledge-platform/templates/tests/preflight-references.yaml create mode 100644 deploy/helm/knowledge-platform/templates/worker-deployment.yaml create mode 100644 deploy/helm/knowledge-platform/values.schema.json create mode 100644 deploy/helm/knowledge-platform/values.yaml create mode 100644 docs/development/KUBERNETES_DEPLOYMENT.md create mode 100755 scripts/deploy.sh create mode 100644 tests/unit/test_helm_deployment.py diff --git a/Makefile b/Makefile index ed9b9f0..9ee587b 100644 --- a/Makefile +++ b/Makefile @@ -1,4 +1,4 @@ -.PHONY: help install run run-mcp run-worker images images-print images-push format format-check lint typecheck test test-unit test-integration migration-check eval live-acceptance up down +.PHONY: help install run run-mcp run-worker images images-print images-push deploy deploy-lint deploy-render format format-check lint typecheck test test-unit test-integration migration-check eval live-acceptance up down UV_CACHE_DIR ?= /tmp/ekp-uv-cache export UV_CACHE_DIR @@ -12,6 +12,9 @@ help: @echo " images Build production images for the current builder" @echo " images-print Render the multi-architecture image build plan" @echo " images-push Build and push amd64/arm64 production images" + @echo " deploy Install or upgrade Kubernetes with VALUES=" + @echo " deploy-lint Validate Helm values and templates" + @echo " deploy-render Render non-secret Kubernetes manifests" @echo " format Format code" @echo " format-check Check formatting without modifying files" @echo " lint Run linters" @@ -39,6 +42,14 @@ images-print: docker buildx bake -f deploy/docker/docker-bake.hcl --print images-push: docker buildx bake -f deploy/docker/docker-bake.hcl --push +deploy: + ./scripts/deploy.sh "$(VALUES)" +deploy-lint: + @test -n "$(VALUES)" || (echo "VALUES must point to an environment values file" >&2; exit 2) + helm lint deploy/helm/knowledge-platform --values "$(VALUES)" +deploy-render: + @test -n "$(VALUES)" || (echo "VALUES must point to an environment values file" >&2; exit 2) + helm template "$${RELEASE:-knowledge-platform}" deploy/helm/knowledge-platform --namespace "$${NAMESPACE:-knowledge-platform}" --values "$(VALUES)" format: uv run ruff format . format-check: diff --git a/README.md b/README.md index 6488b15..6fa12c0 100644 --- a/README.md +++ b/README.md @@ -77,8 +77,9 @@ only document upload, document management, and Search Lab pages. See `docs/development/ADMIN_CONSOLE.md` for the operation and scope boundaries. DEPLOY-001 provides locked, non-root `api`, `mcp`, and `worker` production image targets with an -amd64/arm64 Buildx Bake plan. See `docs/development/CONTAINER_IMAGES.md`; cluster manifests and -Secret injection remain in DEPLOY-002. +amd64/arm64 Buildx Bake plan. DEPLOY-002 adds the Kubernetes/Helm Chart, runtime Secret references, +serialized Migration, Ingress/TLS and the `make deploy VALUES=` entrypoint. See +`docs/development/CONTAINER_IMAGES.md` and `docs/development/KUBERNETES_DEPLOYMENT.md`. Run the development checks with: diff --git a/deploy/helm/environments/values.example.yaml b/deploy/helm/environments/values.example.yaml new file mode 100644 index 0000000..38e09ad --- /dev/null +++ b/deploy/helm/environments/values.example.yaml @@ -0,0 +1,50 @@ +# Copy this file outside the repository for one environment. It contains only +# non-sensitive settings and Kubernetes Secret references; never add values for +# DATABASE_URL, RABBITMQ_URL, provider keys, passwords or MCP_AUTH_TOKEN here. +existingSecret: knowledge-platform-runtime + +images: + api: + repository: registry.example.internal/knowledge/enterprise-knowledge-api + tag: "0.1.0" + digest: "" + mcp: + repository: registry.example.internal/knowledge/enterprise-knowledge-mcp + tag: "0.1.0" + digest: "" + worker: + repository: registry.example.internal/knowledge/enterprise-knowledge-worker + tag: "0.1.0" + digest: "" + +ingress: + enabled: true + className: nginx + api: + host: knowledge.example.internal + tlsSecretName: knowledge-platform-api-tls + mcp: + host: mcp.example.internal + tlsSecretName: knowledge-platform-mcp-tls + +config: + objectStorage: + endpoint: https://s3.example.internal + bucket: knowledge-platform + vectorStore: + uri: oceanbase.example.internal:2881 + user: knowledge-platform + database: knowledge_platform + mcp: + publicUrl: https://mcp.example.internal/mcp + issuerUrl: https://mcp.example.internal + allowedHosts: + - mcp.example.internal + allowedOrigins: + - https://mcp.example.internal + +# External RabbitMQ is the production default. If this local dependency is +# explicitly enabled for a demo cluster, create its Secret before deployment. +rabbitmq: + enabled: false + existingSecret: knowledge-platform-rabbitmq diff --git a/deploy/helm/knowledge-platform/Chart.yaml b/deploy/helm/knowledge-platform/Chart.yaml new file mode 100644 index 0000000..5ea793c --- /dev/null +++ b/deploy/helm/knowledge-platform/Chart.yaml @@ -0,0 +1,15 @@ +apiVersion: v2 +name: knowledge-platform +description: Enterprise Knowledge Platform public-knowledge deployment +type: application +version: 0.1.0 +appVersion: "0.1.0" + +# This local dependency is disabled by default. Production deployments should +# use an externally managed RabbitMQ service with an independently owned data +# lifecycle; the subchart exists only for explicit development/demo use. +dependencies: + - name: rabbitmq + version: 0.1.0 + repository: file://charts/rabbitmq + condition: rabbitmq.enabled diff --git a/deploy/helm/knowledge-platform/charts/rabbitmq/Chart.yaml b/deploy/helm/knowledge-platform/charts/rabbitmq/Chart.yaml new file mode 100644 index 0000000..2645274 --- /dev/null +++ b/deploy/helm/knowledge-platform/charts/rabbitmq/Chart.yaml @@ -0,0 +1,6 @@ +apiVersion: v2 +name: rabbitmq +description: Minimal single-node RabbitMQ dependency for local demo clusters only +type: application +version: 0.1.0 +appVersion: "4.1.4" diff --git a/deploy/helm/knowledge-platform/charts/rabbitmq/templates/_helpers.tpl b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/_helpers.tpl new file mode 100644 index 0000000..a073609 --- /dev/null +++ b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/_helpers.tpl @@ -0,0 +1,11 @@ +{{- define "rabbitmq.fullname" -}} +{{- printf "%s-rabbitmq" .Release.Name | trunc 63 | trimSuffix "-" -}} +{{- end -}} + +{{- define "rabbitmq.image" -}} +{{- if .Values.image.digest -}} +{{- printf "%s@%s" .Values.image.repository .Values.image.digest -}} +{{- else -}} +{{- printf "%s:%s" .Values.image.repository .Values.image.tag -}} +{{- end -}} +{{- end -}} diff --git a/deploy/helm/knowledge-platform/charts/rabbitmq/templates/service.yaml b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/service.yaml new file mode 100644 index 0000000..45f5d8a --- /dev/null +++ b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/service.yaml @@ -0,0 +1,16 @@ +apiVersion: v1 +kind: Service +metadata: + name: {{ include "rabbitmq.fullname" . }} + labels: + app.kubernetes.io/name: rabbitmq + app.kubernetes.io/instance: {{ .Release.Name }} +spec: + clusterIP: None + ports: + - name: amqp + port: {{ .Values.service.port }} + targetPort: amqp + selector: + app.kubernetes.io/name: rabbitmq + app.kubernetes.io/instance: {{ .Release.Name }} diff --git a/deploy/helm/knowledge-platform/charts/rabbitmq/templates/serviceaccount.yaml b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/serviceaccount.yaml new file mode 100644 index 0000000..99ba019 --- /dev/null +++ b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/serviceaccount.yaml @@ -0,0 +1,8 @@ +apiVersion: v1 +kind: ServiceAccount +metadata: + name: {{ include "rabbitmq.fullname" . }} + labels: + app.kubernetes.io/name: rabbitmq + app.kubernetes.io/instance: {{ .Release.Name }} +automountServiceAccountToken: false diff --git a/deploy/helm/knowledge-platform/charts/rabbitmq/templates/statefulset.yaml b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/statefulset.yaml new file mode 100644 index 0000000..06bfca6 --- /dev/null +++ b/deploy/helm/knowledge-platform/charts/rabbitmq/templates/statefulset.yaml @@ -0,0 +1,109 @@ +apiVersion: apps/v1 +kind: StatefulSet +metadata: + name: {{ include "rabbitmq.fullname" . }} + labels: + app.kubernetes.io/name: rabbitmq + app.kubernetes.io/instance: {{ .Release.Name }} +spec: + serviceName: {{ include "rabbitmq.fullname" . }} + replicas: 1 + selector: + matchLabels: + app.kubernetes.io/name: rabbitmq + app.kubernetes.io/instance: {{ .Release.Name }} + template: + metadata: + labels: + app.kubernetes.io/name: rabbitmq + app.kubernetes.io/instance: {{ .Release.Name }} + spec: + serviceAccountName: {{ include "rabbitmq.fullname" . }} + automountServiceAccountToken: false + securityContext: + runAsNonRoot: true + runAsUser: 999 + runAsGroup: 999 + fsGroup: 999 + seccompProfile: + type: RuntimeDefault + containers: + - name: rabbitmq + image: {{ include "rabbitmq.image" . | quote }} + imagePullPolicy: {{ .Values.image.pullPolicy }} + securityContext: + allowPrivilegeEscalation: false + readOnlyRootFilesystem: true + capabilities: + drop: ["ALL"] + ports: + - name: amqp + containerPort: 5672 + env: + - name: RABBITMQ_DEFAULT_USER + valueFrom: + secretKeyRef: + name: {{ .Values.existingSecret }} + key: {{ .Values.secretKeys.username }} + - name: RABBITMQ_DEFAULT_PASS + valueFrom: + secretKeyRef: + name: {{ .Values.existingSecret }} + key: {{ .Values.secretKeys.password }} + - name: RABBITMQ_ERLANG_COOKIE + valueFrom: + secretKeyRef: + name: {{ .Values.existingSecret }} + key: {{ .Values.secretKeys.erlangCookie }} + startupProbe: + exec: + command: ["rabbitmq-diagnostics", "-q", "ping"] + periodSeconds: 5 + failureThreshold: 24 + readinessProbe: + exec: + command: ["rabbitmq-diagnostics", "-q", "check_running"] + periodSeconds: 10 + timeoutSeconds: 5 + failureThreshold: 3 + livenessProbe: + exec: + command: ["rabbitmq-diagnostics", "-q", "ping"] + periodSeconds: 20 + timeoutSeconds: 5 + failureThreshold: 3 + resources: + {{- toYaml .Values.resources | nindent 12 }} + volumeMounts: + - name: data + mountPath: /var/lib/rabbitmq + - name: config + mountPath: /etc/rabbitmq/conf.d + - name: log + mountPath: /var/log/rabbitmq + - name: tmp + mountPath: /tmp + volumes: + - name: config + emptyDir: {} + - name: log + emptyDir: {} + - name: tmp + emptyDir: {} + {{- if not .Values.persistence.enabled }} + - name: data + emptyDir: {} + {{- end }} + {{- if .Values.persistence.enabled }} + volumeClaimTemplates: + - metadata: + name: data + spec: + accessModes: [{{ .Values.persistence.accessMode | quote }}] + {{- if .Values.persistence.storageClass }} + storageClassName: {{ .Values.persistence.storageClass | quote }} + {{- end }} + resources: + requests: + storage: {{ .Values.persistence.size }} + {{- end }} diff --git a/deploy/helm/knowledge-platform/charts/rabbitmq/values.schema.json b/deploy/helm/knowledge-platform/charts/rabbitmq/values.schema.json new file mode 100644 index 0000000..b670a0c --- /dev/null +++ b/deploy/helm/knowledge-platform/charts/rabbitmq/values.schema.json @@ -0,0 +1,69 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "type": "object", + "additionalProperties": false, + "required": ["enabled", "existingSecret", "secretKeys", "image", "service", "persistence", "resources"], + "properties": { + "global": {"type": "object"}, + "enabled": {"type": "boolean"}, + "existingSecret": {"type": "string", "minLength": 1}, + "secretKeys": { + "type": "object", + "additionalProperties": false, + "required": ["username", "password", "erlangCookie"], + "properties": { + "username": {"type": "string", "minLength": 1}, + "password": {"type": "string", "minLength": 1}, + "erlangCookie": {"type": "string", "minLength": 1} + } + }, + "image": { + "type": "object", + "additionalProperties": false, + "required": ["repository", "tag", "digest", "pullPolicy"], + "properties": { + "repository": {"type": "string", "minLength": 1}, + "tag": {"type": "string", "minLength": 1, "not": {"enum": ["latest"]}}, + "digest": {"type": "string", "pattern": "^$|^sha256:[a-f0-9]{64}$"}, + "pullPolicy": {"enum": ["Always", "IfNotPresent", "Never"]} + } + }, + "service": { + "type": "object", + "additionalProperties": false, + "required": ["port"], + "properties": {"port": {"type": "integer", "minimum": 1, "maximum": 65535}} + }, + "persistence": { + "type": "object", + "additionalProperties": false, + "required": ["enabled", "storageClass", "accessMode", "size"], + "properties": { + "enabled": {"type": "boolean"}, + "storageClass": {"type": "string"}, + "accessMode": {"enum": ["ReadWriteOnce", "ReadWriteMany"]}, + "size": {"type": "string", "minLength": 2} + } + }, + "resources": { + "type": "object", + "additionalProperties": false, + "required": ["requests", "limits"], + "properties": { + "requests": {"$ref": "#/definitions/resourcePair"}, + "limits": {"$ref": "#/definitions/resourcePair"} + } + } + }, + "definitions": { + "resourcePair": { + "type": "object", + "additionalProperties": false, + "required": ["cpu", "memory"], + "properties": { + "cpu": {"type": ["string", "number"]}, + "memory": {"type": "string", "minLength": 2} + } + } + } +} diff --git a/deploy/helm/knowledge-platform/charts/rabbitmq/values.yaml b/deploy/helm/knowledge-platform/charts/rabbitmq/values.yaml new file mode 100644 index 0000000..d9ff5c2 --- /dev/null +++ b/deploy/helm/knowledge-platform/charts/rabbitmq/values.yaml @@ -0,0 +1,25 @@ +enabled: false +existingSecret: knowledge-platform-rabbitmq +secretKeys: + username: username + password: password + erlangCookie: erlang-cookie +image: + repository: rabbitmq + tag: 4.1.4-alpine + digest: sha256:b736d649308e1b3e1a116c3f36986b605ee3d03e88f10166be2900083d2e63f2 + pullPolicy: IfNotPresent +service: + port: 5672 +persistence: + enabled: true + storageClass: "" + accessMode: ReadWriteOnce + size: 8Gi +resources: + requests: + cpu: 250m + memory: 512Mi + limits: + cpu: "1" + memory: 1Gi diff --git a/deploy/helm/knowledge-platform/templates/NOTES.txt b/deploy/helm/knowledge-platform/templates/NOTES.txt new file mode 100644 index 0000000..a16c66f --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/NOTES.txt @@ -0,0 +1,12 @@ +Enterprise Knowledge Platform {{ .Chart.AppVersion }} is managed by Helm release {{ .Release.Name }}. + +Runtime credentials are read only from Secret {{ .Values.existingSecret }}. +{{- if .Values.ingress.enabled }} +Admin/API: https://{{ .Values.ingress.api.host }}{{ .Values.ingress.api.path }} +MCP: https://{{ .Values.ingress.mcp.host }}{{ .Values.ingress.mcp.path }} +{{- else }} +Ingress is disabled. Enable it in the environment values file before remote use. +{{- end }} + +Inspect rollout state without printing environment variables: + kubectl -n {{ .Release.Namespace }} get deploy,job,pod diff --git a/deploy/helm/knowledge-platform/templates/_helpers.tpl b/deploy/helm/knowledge-platform/templates/_helpers.tpl new file mode 100644 index 0000000..6c18f44 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/_helpers.tpl @@ -0,0 +1,106 @@ +{{/* Stable resource name helpers keep every workload under one release identity. */}} +{{- define "knowledge-platform.name" -}} +{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" -}} +{{- end -}} + +{{- define "knowledge-platform.fullname" -}} +{{- if .Values.fullnameOverride -}} +{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" -}} +{{- else -}} +{{- $name := include "knowledge-platform.name" . -}} +{{- if contains $name .Release.Name -}} +{{- .Release.Name | trunc 63 | trimSuffix "-" -}} +{{- else -}} +{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" -}} +{{- end -}} +{{- end -}} +{{- end -}} + +{{- define "knowledge-platform.labels" -}} +helm.sh/chart: {{ printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | quote }} +app.kubernetes.io/name: {{ include "knowledge-platform.name" . }} +app.kubernetes.io/instance: {{ .Release.Name }} +app.kubernetes.io/version: {{ .Chart.AppVersion | quote }} +app.kubernetes.io/managed-by: {{ .Release.Service }} +{{- end -}} + +{{- define "knowledge-platform.selectorLabels" -}} +app.kubernetes.io/name: {{ include "knowledge-platform.name" . }} +app.kubernetes.io/instance: {{ .Release.Name }} +{{- end -}} + +{{- define "knowledge-platform.serviceAccountName" -}} +{{- if .Values.serviceAccount.create -}} +{{- default (include "knowledge-platform.fullname" .) .Values.serviceAccount.name -}} +{{- else -}} +{{- required "serviceAccount.name is required when serviceAccount.create=false" .Values.serviceAccount.name -}} +{{- end -}} +{{- end -}} + +{{/* A supplied digest takes precedence over the immutable release tag. */}} +{{- define "knowledge-platform.image" -}} +{{- if .digest -}} +{{- printf "%s@%s" .repository .digest -}} +{{- else -}} +{{- printf "%s:%s" .repository .tag -}} +{{- end -}} +{{- end -}} + +{{- define "knowledge-platform.configMapName" -}} +{{- printf "%s-runtime" (include "knowledge-platform.fullname" .) -}} +{{- end -}} + +{{/* Cross-field rules complement values.schema.json's structural checks. */}} +{{- define "knowledge-platform.validateValues" -}} +{{- if lt (float64 .Values.config.ingestion.retryBackoffMaxSeconds) (float64 .Values.config.ingestion.retryBackoffSeconds) -}} +{{- fail "config.ingestion.retryBackoffMaxSeconds must be >= retryBackoffSeconds" -}} +{{- end -}} +{{- if lt (float64 .Values.config.ingestion.batchMaxTotalBytes) (float64 .Values.config.ingestion.maxUploadBytes) -}} +{{- fail "config.ingestion.batchMaxTotalBytes must be >= maxUploadBytes" -}} +{{- end -}} +{{- if ge (float64 .Values.config.chunking.overlapTokens) (float64 .Values.config.chunking.maxTokens) -}} +{{- fail "config.chunking.overlapTokens must be < maxTokens" -}} +{{- end -}} +{{- if gt (float64 .Values.config.retrieval.searchTopK) (float64 .Values.config.retrieval.denseTopN) -}} +{{- fail "config.retrieval.searchTopK must be <= denseTopN" -}} +{{- end -}} +{{- end -}} + +{{- define "knowledge-platform.podSecurityContext" -}} +runAsNonRoot: true +runAsUser: 10001 +runAsGroup: 10001 +fsGroup: 10001 +fsGroupChangePolicy: OnRootMismatch +seccompProfile: + type: RuntimeDefault +{{- end -}} + +{{- define "knowledge-platform.containerSecurityContext" -}} +allowPrivilegeEscalation: false +readOnlyRootFilesystem: true +runAsNonRoot: true +runAsUser: 10001 +runAsGroup: 10001 +capabilities: + drop: + - ALL +{{- end -}} + +{{- define "knowledge-platform.envFrom" -}} +- configMapRef: + name: {{ include "knowledge-platform.configMapName" . }} +- secretRef: + name: {{ .Values.existingSecret }} +{{- end -}} + +{{- define "knowledge-platform.tmpVolume" -}} +- name: tmp + emptyDir: + sizeLimit: 1Gi +{{- end -}} + +{{- define "knowledge-platform.tmpMount" -}} +- name: tmp + mountPath: /tmp +{{- end -}} diff --git a/deploy/helm/knowledge-platform/templates/api-deployment.yaml b/deploy/helm/knowledge-platform/templates/api-deployment.yaml new file mode 100644 index 0000000..9eca02d --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/api-deployment.yaml @@ -0,0 +1,75 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "knowledge-platform.fullname" . }}-api + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + app.kubernetes.io/component: api +spec: + replicas: {{ .Values.api.replicaCount }} + minReadySeconds: 5 + strategy: + type: RollingUpdate + rollingUpdate: + maxUnavailable: 0 + maxSurge: 1 + selector: + matchLabels: + {{- include "knowledge-platform.selectorLabels" . | nindent 6 }} + app.kubernetes.io/component: api + template: + metadata: + labels: + {{- include "knowledge-platform.selectorLabels" . | nindent 8 }} + app.kubernetes.io/component: api + {{- with .Values.podLabels }} + {{- toYaml . | nindent 8 }} + {{- end }} + annotations: + checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }} + checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }} + {{- with .Values.podAnnotations }} + {{- toYaml . | nindent 8 }} + {{- end }} + spec: + serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }} + automountServiceAccountToken: false + securityContext: + {{- include "knowledge-platform.podSecurityContext" . | nindent 8 }} + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: api + image: {{ include "knowledge-platform.image" .Values.images.api | quote }} + imagePullPolicy: {{ .Values.images.api.pullPolicy }} + securityContext: + {{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }} + ports: + - name: http + containerPort: 8000 + protocol: TCP + envFrom: + {{- include "knowledge-platform.envFrom" . | nindent 12 }} + startupProbe: + httpGet: + path: /healthz + port: http + {{- toYaml .Values.api.probes.startup | nindent 12 }} + readinessProbe: + httpGet: + path: /healthz + port: http + {{- toYaml .Values.api.probes.readiness | nindent 12 }} + livenessProbe: + httpGet: + path: /healthz + port: http + {{- toYaml .Values.api.probes.liveness | nindent 12 }} + resources: + {{- toYaml .Values.api.resources | nindent 12 }} + volumeMounts: + {{- include "knowledge-platform.tmpMount" . | nindent 12 }} + volumes: + {{- include "knowledge-platform.tmpVolume" . | nindent 8 }} diff --git a/deploy/helm/knowledge-platform/templates/api-service.yaml b/deploy/helm/knowledge-platform/templates/api-service.yaml new file mode 100644 index 0000000..c26c6e1 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/api-service.yaml @@ -0,0 +1,17 @@ +apiVersion: v1 +kind: Service +metadata: + name: {{ include "knowledge-platform.fullname" . }}-api + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + app.kubernetes.io/component: api +spec: + type: {{ .Values.api.service.type }} + ports: + - name: http + port: {{ .Values.api.service.port }} + targetPort: http + protocol: TCP + selector: + {{- include "knowledge-platform.selectorLabels" . | nindent 4 }} + app.kubernetes.io/component: api diff --git a/deploy/helm/knowledge-platform/templates/configmap.yaml b/deploy/helm/knowledge-platform/templates/configmap.yaml new file mode 100644 index 0000000..9c456f5 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/configmap.yaml @@ -0,0 +1,66 @@ +{{- include "knowledge-platform.validateValues" . }} +apiVersion: v1 +kind: ConfigMap +metadata: + name: {{ include "knowledge-platform.configMapName" . }} + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} +data: + # Only the explicitly enumerated non-sensitive settings are rendered here. + APP_ENV: "production" + APP_NAME: {{ .Values.config.appName | quote }} + LOG_LEVEL: {{ .Values.config.logLevel | quote }} + API_HOST: "0.0.0.0" + API_PORT: "8000" + API_PREFIX: "/api/v1" + DATABASE_POOL_SIZE: {{ .Values.config.database.poolSize | quote }} + DATABASE_MAX_OVERFLOW: {{ .Values.config.database.maxOverflow | quote }} + DATABASE_POOL_RECYCLE_SECONDS: {{ .Values.config.database.poolRecycleSeconds | quote }} + DATABASE_POOL_TIMEOUT_SECONDS: {{ .Values.config.database.poolTimeoutSeconds | quote }} + DATABASE_CONNECT_TIMEOUT_SECONDS: {{ .Values.config.database.connectTimeoutSeconds | quote }} + INGESTION_MAX_ATTEMPTS: {{ .Values.config.ingestion.maxAttempts | quote }} + INGESTION_RETRY_BACKOFF_SECONDS: {{ .Values.config.ingestion.retryBackoffSeconds | quote }} + INGESTION_RETRY_BACKOFF_MAX_SECONDS: {{ .Values.config.ingestion.retryBackoffMaxSeconds | quote }} + INGESTION_WORKER_LEASE_SECONDS: {{ .Values.config.ingestion.workerLeaseSeconds | quote }} + INGESTION_RECOVERY_INTERVAL_SECONDS: {{ .Values.config.ingestion.recoveryIntervalSeconds | quote }} + BATCH_MAX_FILES: {{ .Values.config.ingestion.batchMaxFiles | quote }} + BATCH_MAX_TOTAL_BYTES: {{ printf "%.0f" .Values.config.ingestion.batchMaxTotalBytes | quote }} + MAX_UPLOAD_BYTES: {{ printf "%.0f" .Values.config.ingestion.maxUploadBytes | quote }} + OBJECT_STORAGE_PROVIDER: {{ .Values.config.objectStorage.provider | quote }} + BOS_ENDPOINT: {{ .Values.config.objectStorage.endpoint | quote }} + BOS_BUCKET: {{ .Values.config.objectStorage.bucket | quote }} + BOS_KEY_PREFIX: {{ .Values.config.objectStorage.keyPrefix | quote }} + BOS_TIMEOUT_SECONDS: {{ .Values.config.objectStorage.timeoutSeconds | quote }} + CHUNK_MAX_TOKENS: {{ .Values.config.chunking.maxTokens | quote }} + CHUNK_OVERLAP_TOKENS: {{ .Values.config.chunking.overlapTokens | quote }} + CHUNK_MAX_CHARACTERS: {{ .Values.config.chunking.maxCharacters | quote }} + EMBEDDING_PROVIDER: {{ .Values.config.embedding.provider | quote }} + EMBEDDING_MODEL: {{ .Values.config.embedding.model | quote }} + EMBEDDING_ENDPOINT: {{ .Values.config.embedding.endpoint | quote }} + EMBEDDING_TIMEOUT_SECONDS: {{ .Values.config.embedding.timeoutSeconds | quote }} + VECTOR_STORE_PROVIDER: {{ .Values.config.vectorStore.provider | quote }} + OCEANBASE_VECTOR_URI: {{ .Values.config.vectorStore.uri | quote }} + OCEANBASE_VECTOR_USER: {{ .Values.config.vectorStore.user | quote }} + OCEANBASE_VECTOR_DATABASE: {{ .Values.config.vectorStore.database | quote }} + OCEANBASE_VECTOR_TABLE: {{ .Values.config.vectorStore.table | quote }} + OCEANBASE_VECTOR_INDEX: {{ .Values.config.vectorStore.index | quote }} + OCEANBASE_VECTOR_BATCH_SIZE: {{ .Values.config.vectorStore.batchSize | quote }} + OCEANBASE_VECTOR_TIMEOUT_SECONDS: {{ .Values.config.vectorStore.timeoutSeconds | quote }} + INDEX_PROFILE_ID: {{ .Values.config.retrieval.indexProfileId | quote }} + DENSE_TOP_N: {{ .Values.config.retrieval.denseTopN | quote }} + SEARCH_TOP_K: {{ .Values.config.retrieval.searchTopK | quote }} + RERANKER_PROVIDER: {{ .Values.config.reranker.provider | quote }} + RERANKER_MODEL: {{ .Values.config.reranker.model | quote }} + RERANKER_ENDPOINT: {{ .Values.config.reranker.endpoint | quote }} + RERANKER_TIMEOUT_SECONDS: {{ .Values.config.reranker.timeoutSeconds | quote }} + MCP_HOST: "0.0.0.0" + MCP_PORT: "8766" + MCP_PATH: "/mcp" + MCP_PUBLIC_URL: {{ .Values.config.mcp.publicUrl | quote }} + MCP_ISSUER_URL: {{ .Values.config.mcp.issuerUrl | quote }} + MCP_CLIENT_ID: {{ .Values.config.mcp.clientId | quote }} + MCP_SERVICE_IDENTITY: {{ .Values.config.mcp.serviceIdentity | quote }} + MCP_REQUIRED_SCOPE: {{ .Values.config.mcp.requiredScope | quote }} + MCP_ALLOWED_HOSTS: {{ .Values.config.mcp.allowedHosts | toJson | quote }} + MCP_ALLOWED_ORIGINS: {{ .Values.config.mcp.allowedOrigins | toJson | quote }} + MCP_MAX_REQUEST_BODY_BYTES: {{ printf "%.0f" .Values.config.mcp.maxRequestBodyBytes | quote }} diff --git a/deploy/helm/knowledge-platform/templates/ingress.yaml b/deploy/helm/knowledge-platform/templates/ingress.yaml new file mode 100644 index 0000000..0bde4e7 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/ingress.yaml @@ -0,0 +1,42 @@ +{{- if .Values.ingress.enabled }} +apiVersion: networking.k8s.io/v1 +kind: Ingress +metadata: + name: {{ include "knowledge-platform.fullname" . }} + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + {{- with .Values.ingress.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +spec: + ingressClassName: {{ .Values.ingress.className }} + tls: + - hosts: + - {{ .Values.ingress.api.host | quote }} + secretName: {{ .Values.ingress.api.tlsSecretName }} + - hosts: + - {{ .Values.ingress.mcp.host | quote }} + secretName: {{ .Values.ingress.mcp.tlsSecretName }} + rules: + - host: {{ .Values.ingress.api.host | quote }} + http: + paths: + - path: {{ .Values.ingress.api.path }} + pathType: Prefix + backend: + service: + name: {{ include "knowledge-platform.fullname" . }}-api + port: + number: {{ .Values.api.service.port }} + - host: {{ .Values.ingress.mcp.host | quote }} + http: + paths: + - path: {{ .Values.ingress.mcp.path }} + pathType: Prefix + backend: + service: + name: {{ include "knowledge-platform.fullname" . }}-mcp + port: + number: {{ .Values.mcp.service.port }} +{{- end }} diff --git a/deploy/helm/knowledge-platform/templates/mcp-deployment.yaml b/deploy/helm/knowledge-platform/templates/mcp-deployment.yaml new file mode 100644 index 0000000..2efc0d2 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/mcp-deployment.yaml @@ -0,0 +1,72 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "knowledge-platform.fullname" . }}-mcp + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + app.kubernetes.io/component: mcp +spec: + replicas: {{ .Values.mcp.replicaCount }} + minReadySeconds: 5 + strategy: + type: RollingUpdate + rollingUpdate: + maxUnavailable: 0 + maxSurge: 1 + selector: + matchLabels: + {{- include "knowledge-platform.selectorLabels" . | nindent 6 }} + app.kubernetes.io/component: mcp + template: + metadata: + labels: + {{- include "knowledge-platform.selectorLabels" . | nindent 8 }} + app.kubernetes.io/component: mcp + {{- with .Values.podLabels }} + {{- toYaml . | nindent 8 }} + {{- end }} + annotations: + checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }} + checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }} + {{- with .Values.podAnnotations }} + {{- toYaml . | nindent 8 }} + {{- end }} + spec: + serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }} + automountServiceAccountToken: false + securityContext: + {{- include "knowledge-platform.podSecurityContext" . | nindent 8 }} + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: mcp + image: {{ include "knowledge-platform.image" .Values.images.mcp | quote }} + imagePullPolicy: {{ .Values.images.mcp.pullPolicy }} + securityContext: + {{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }} + ports: + - name: mcp + containerPort: 8766 + protocol: TCP + envFrom: + {{- include "knowledge-platform.envFrom" . | nindent 12 }} + startupProbe: + tcpSocket: + port: mcp + {{- toYaml .Values.mcp.probes.startup | nindent 12 }} + readinessProbe: + tcpSocket: + port: mcp + {{- toYaml .Values.mcp.probes.readiness | nindent 12 }} + livenessProbe: + tcpSocket: + port: mcp + {{- toYaml .Values.mcp.probes.liveness | nindent 12 }} + resources: + {{- toYaml .Values.mcp.resources | nindent 12 }} + volumeMounts: + {{- include "knowledge-platform.tmpMount" . | nindent 12 }} + volumes: + {{- include "knowledge-platform.tmpVolume" . | nindent 8 }} diff --git a/deploy/helm/knowledge-platform/templates/mcp-service.yaml b/deploy/helm/knowledge-platform/templates/mcp-service.yaml new file mode 100644 index 0000000..109c3ce --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/mcp-service.yaml @@ -0,0 +1,17 @@ +apiVersion: v1 +kind: Service +metadata: + name: {{ include "knowledge-platform.fullname" . }}-mcp + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + app.kubernetes.io/component: mcp +spec: + type: {{ .Values.mcp.service.type }} + ports: + - name: mcp + port: {{ .Values.mcp.service.port }} + targetPort: mcp + protocol: TCP + selector: + {{- include "knowledge-platform.selectorLabels" . | nindent 4 }} + app.kubernetes.io/component: mcp diff --git a/deploy/helm/knowledge-platform/templates/migration-job.yaml b/deploy/helm/knowledge-platform/templates/migration-job.yaml new file mode 100644 index 0000000..4f5569a --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/migration-job.yaml @@ -0,0 +1,59 @@ +{{- if .Values.migration.enabled }} +apiVersion: batch/v1 +kind: Job +metadata: + name: {{ include "knowledge-platform.fullname" . }}-migration + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + app.kubernetes.io/component: migration + annotations: + # Helm waits for pre-install/pre-upgrade hooks. A failed migration blocks + # the application rollout, and the previous Job remains until the next run. + helm.sh/hook: pre-install,pre-upgrade + helm.sh/hook-weight: "-10" + helm.sh/hook-delete-policy: before-hook-creation +spec: + backoffLimit: {{ .Values.migration.backoffLimit }} + activeDeadlineSeconds: {{ .Values.migration.activeDeadlineSeconds }} + ttlSecondsAfterFinished: {{ .Values.migration.ttlSecondsAfterFinished }} + template: + metadata: + labels: + {{- include "knowledge-platform.selectorLabels" . | nindent 8 }} + app.kubernetes.io/component: migration + spec: + restartPolicy: Never + # Pre-install hooks run before the release ServiceAccount exists. The + # namespace default account is used with token mounting disabled; the + # migration needs no Kubernetes API permissions. + serviceAccountName: default + automountServiceAccountToken: false + securityContext: + {{- include "knowledge-platform.podSecurityContext" . | nindent 8 }} + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: migration + image: {{ include "knowledge-platform.image" .Values.images.api | quote }} + imagePullPolicy: {{ .Values.images.api.pullPolicy }} + command: ["alembic"] + args: ["upgrade", "head"] + securityContext: + {{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }} + env: + - name: APP_ENV + value: production + - name: DATABASE_URL + valueFrom: + secretKeyRef: + name: {{ .Values.existingSecret }} + key: DATABASE_URL + resources: + {{- toYaml .Values.migration.resources | nindent 12 }} + volumeMounts: + {{- include "knowledge-platform.tmpMount" . | nindent 12 }} + volumes: + {{- include "knowledge-platform.tmpVolume" . | nindent 8 }} +{{- end }} diff --git a/deploy/helm/knowledge-platform/templates/scheduler-deployment.yaml b/deploy/helm/knowledge-platform/templates/scheduler-deployment.yaml new file mode 100644 index 0000000..f80b6e4 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/scheduler-deployment.yaml @@ -0,0 +1,71 @@ +{{- if .Values.scheduler.enabled }} +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "knowledge-platform.fullname" . }}-scheduler + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + app.kubernetes.io/component: scheduler +spec: + # A single Celery Beat owns periodic durable-Job recovery. Recreate prevents + # two schedulers from overlapping during upgrades. + replicas: 1 + strategy: + type: Recreate + selector: + matchLabels: + {{- include "knowledge-platform.selectorLabels" . | nindent 6 }} + app.kubernetes.io/component: scheduler + template: + metadata: + labels: + {{- include "knowledge-platform.selectorLabels" . | nindent 8 }} + app.kubernetes.io/component: scheduler + {{- with .Values.podLabels }} + {{- toYaml . | nindent 8 }} + {{- end }} + annotations: + checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }} + checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }} + {{- with .Values.podAnnotations }} + {{- toYaml . | nindent 8 }} + {{- end }} + spec: + serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }} + automountServiceAccountToken: false + securityContext: + {{- include "knowledge-platform.podSecurityContext" . | nindent 8 }} + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: scheduler + image: {{ include "knowledge-platform.image" .Values.images.worker | quote }} + imagePullPolicy: {{ .Values.images.worker.pullPolicy }} + workingDir: /tmp + command: ["celery"] + args: + - --app=ekp_api.worker:celery_app + - beat + - --loglevel=INFO + - --schedule=/tmp/celerybeat-schedule + securityContext: + {{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }} + envFrom: + {{- include "knowledge-platform.envFrom" . | nindent 12 }} + startupProbe: + exec: + command: ["python", "-c", "import os; os.kill(1, 0)"] + {{- toYaml .Values.scheduler.probes.startup | nindent 12 }} + livenessProbe: + exec: + command: ["python", "-c", "import os; os.kill(1, 0)"] + {{- toYaml .Values.scheduler.probes.liveness | nindent 12 }} + resources: + {{- toYaml .Values.scheduler.resources | nindent 12 }} + volumeMounts: + {{- include "knowledge-platform.tmpMount" . | nindent 12 }} + volumes: + {{- include "knowledge-platform.tmpVolume" . | nindent 8 }} +{{- end }} diff --git a/deploy/helm/knowledge-platform/templates/serviceaccount.yaml b/deploy/helm/knowledge-platform/templates/serviceaccount.yaml new file mode 100644 index 0000000..d0d50d7 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/serviceaccount.yaml @@ -0,0 +1,13 @@ +{{- if .Values.serviceAccount.create }} +apiVersion: v1 +kind: ServiceAccount +metadata: + name: {{ include "knowledge-platform.serviceAccountName" . }} + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + {{- with .Values.serviceAccount.annotations }} + annotations: + {{- toYaml . | nindent 4 }} + {{- end }} +automountServiceAccountToken: false +{{- end }} diff --git a/deploy/helm/knowledge-platform/templates/tests/preflight-references.yaml b/deploy/helm/knowledge-platform/templates/tests/preflight-references.yaml new file mode 100644 index 0000000..8ead8f3 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/tests/preflight-references.yaml @@ -0,0 +1,17 @@ +apiVersion: v1 +kind: ConfigMap +metadata: + name: {{ include "knowledge-platform.fullname" . }}-preflight-references + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + annotations: + # The Make preflight renders this test hook to discover only resource + # names. It never renders or reads Secret data. + helm.sh/hook: test +data: + runtimeSecret: {{ .Values.existingSecret | quote }} + ingressEnabled: {{ .Values.ingress.enabled | quote }} + apiTlsSecret: {{ .Values.ingress.api.tlsSecretName | quote }} + mcpTlsSecret: {{ .Values.ingress.mcp.tlsSecretName | quote }} + rabbitmqEnabled: {{ .Values.rabbitmq.enabled | quote }} + rabbitmqSecret: {{ .Values.rabbitmq.existingSecret | quote }} diff --git a/deploy/helm/knowledge-platform/templates/worker-deployment.yaml b/deploy/helm/knowledge-platform/templates/worker-deployment.yaml new file mode 100644 index 0000000..d39cbd2 --- /dev/null +++ b/deploy/helm/knowledge-platform/templates/worker-deployment.yaml @@ -0,0 +1,71 @@ +apiVersion: apps/v1 +kind: Deployment +metadata: + name: {{ include "knowledge-platform.fullname" . }}-worker + labels: + {{- include "knowledge-platform.labels" . | nindent 4 }} + app.kubernetes.io/component: worker +spec: + replicas: {{ .Values.worker.replicaCount }} + strategy: + type: RollingUpdate + rollingUpdate: + maxUnavailable: 1 + maxSurge: 1 + selector: + matchLabels: + {{- include "knowledge-platform.selectorLabels" . | nindent 6 }} + app.kubernetes.io/component: worker + template: + metadata: + labels: + {{- include "knowledge-platform.selectorLabels" . | nindent 8 }} + app.kubernetes.io/component: worker + {{- with .Values.podLabels }} + {{- toYaml . | nindent 8 }} + {{- end }} + annotations: + checksum/runtime-config: {{ include (print $.Template.BasePath "/configmap.yaml") . | sha256sum }} + checksum/runtime-secret-reference: {{ .Values.existingSecret | sha256sum }} + {{- with .Values.podAnnotations }} + {{- toYaml . | nindent 8 }} + {{- end }} + spec: + serviceAccountName: {{ include "knowledge-platform.serviceAccountName" . }} + automountServiceAccountToken: false + terminationGracePeriodSeconds: {{ .Values.worker.terminationGracePeriodSeconds }} + securityContext: + {{- include "knowledge-platform.podSecurityContext" . | nindent 8 }} + {{- with .Values.imagePullSecrets }} + imagePullSecrets: + {{- toYaml . | nindent 8 }} + {{- end }} + containers: + - name: worker + image: {{ include "knowledge-platform.image" .Values.images.worker | quote }} + imagePullPolicy: {{ .Values.images.worker.pullPolicy }} + workingDir: /tmp + command: ["celery"] + args: + - --app=ekp_api.worker:celery_app + - worker + - --loglevel=INFO + - --queues=ingestion + securityContext: + {{- include "knowledge-platform.containerSecurityContext" . | nindent 12 }} + envFrom: + {{- include "knowledge-platform.envFrom" . | nindent 12 }} + startupProbe: + exec: + command: ["python", "-c", "import os; os.kill(1, 0)"] + {{- toYaml .Values.worker.probes.startup | nindent 12 }} + livenessProbe: + exec: + command: ["python", "-c", "import os; os.kill(1, 0)"] + {{- toYaml .Values.worker.probes.liveness | nindent 12 }} + resources: + {{- toYaml .Values.worker.resources | nindent 12 }} + volumeMounts: + {{- include "knowledge-platform.tmpMount" . | nindent 12 }} + volumes: + {{- include "knowledge-platform.tmpVolume" . | nindent 8 }} diff --git a/deploy/helm/knowledge-platform/values.schema.json b/deploy/helm/knowledge-platform/values.schema.json new file mode 100644 index 0000000..6162933 --- /dev/null +++ b/deploy/helm/knowledge-platform/values.schema.json @@ -0,0 +1,338 @@ +{ + "$schema": "https://json-schema.org/draft-07/schema#", + "title": "Enterprise Knowledge Platform Helm values", + "type": "object", + "additionalProperties": false, + "required": [ + "existingSecret", + "images", + "serviceAccount", + "api", + "mcp", + "worker", + "scheduler", + "migration", + "ingress", + "config", + "rabbitmq" + ], + "properties": { + "nameOverride": {"type": "string"}, + "fullnameOverride": {"type": "string"}, + "existingSecret": {"$ref": "#/definitions/kubernetesName"}, + "imagePullSecrets": { + "type": "array", + "items": { + "type": "object", + "additionalProperties": false, + "required": ["name"], + "properties": {"name": {"$ref": "#/definitions/kubernetesName"}} + } + }, + "images": { + "type": "object", + "additionalProperties": false, + "required": ["api", "mcp", "worker"], + "properties": { + "api": {"$ref": "#/definitions/image"}, + "mcp": {"$ref": "#/definitions/image"}, + "worker": {"$ref": "#/definitions/image"} + } + }, + "serviceAccount": { + "type": "object", + "additionalProperties": false, + "required": ["create", "name", "annotations"], + "properties": { + "create": {"type": "boolean"}, + "name": {"type": "string"}, + "annotations": {"$ref": "#/definitions/stringMap"} + } + }, + "podAnnotations": {"$ref": "#/definitions/stringMap"}, + "podLabels": {"$ref": "#/definitions/stringMap"}, + "api": {"$ref": "#/definitions/httpWorkload"}, + "mcp": {"$ref": "#/definitions/httpWorkload"}, + "worker": { + "type": "object", + "additionalProperties": false, + "required": ["replicaCount", "terminationGracePeriodSeconds", "resources", "probes"], + "properties": { + "replicaCount": {"type": "integer", "minimum": 1, "maximum": 100}, + "terminationGracePeriodSeconds": {"type": "integer", "minimum": 30, "maximum": 3600}, + "resources": {"$ref": "#/definitions/resources"}, + "probes": {"$ref": "#/definitions/processProbes"} + } + }, + "scheduler": { + "type": "object", + "additionalProperties": false, + "required": ["enabled", "resources", "probes"], + "properties": { + "enabled": {"type": "boolean"}, + "resources": {"$ref": "#/definitions/resources"}, + "probes": {"$ref": "#/definitions/processProbes"} + } + }, + "migration": { + "type": "object", + "additionalProperties": false, + "required": ["enabled", "activeDeadlineSeconds", "backoffLimit", "ttlSecondsAfterFinished", "resources"], + "properties": { + "enabled": {"type": "boolean"}, + "activeDeadlineSeconds": {"type": "integer", "minimum": 60, "maximum": 3600}, + "backoffLimit": {"type": "integer", "minimum": 0, "maximum": 3}, + "ttlSecondsAfterFinished": {"type": "integer", "minimum": 0}, + "resources": {"$ref": "#/definitions/resources"} + } + }, + "ingress": { + "type": "object", + "additionalProperties": false, + "required": ["enabled", "className", "annotations", "api", "mcp"], + "properties": { + "enabled": {"type": "boolean"}, + "className": {"type": "string", "minLength": 1}, + "annotations": {"$ref": "#/definitions/stringMap"}, + "api": {"$ref": "#/definitions/ingressRoute"}, + "mcp": {"$ref": "#/definitions/ingressRoute"} + } + }, + "config": { + "type": "object", + "additionalProperties": false, + "required": ["appName", "logLevel", "database", "ingestion", "objectStorage", "chunking", "embedding", "vectorStore", "retrieval", "reranker", "mcp"], + "properties": { + "appName": {"type": "string", "minLength": 1}, + "logLevel": {"enum": ["DEBUG", "INFO", "WARNING", "ERROR", "CRITICAL"]}, + "database": {"$ref": "#/definitions/databaseConfig"}, + "ingestion": {"$ref": "#/definitions/ingestionConfig"}, + "objectStorage": {"$ref": "#/definitions/objectStorageConfig"}, + "chunking": {"$ref": "#/definitions/chunkingConfig"}, + "embedding": {"$ref": "#/definitions/embeddingConfig"}, + "vectorStore": {"$ref": "#/definitions/vectorStoreConfig"}, + "retrieval": {"$ref": "#/definitions/retrievalConfig"}, + "reranker": {"$ref": "#/definitions/rerankerConfig"}, + "mcp": {"$ref": "#/definitions/mcpConfig"} + } + }, + "rabbitmq": { + "type": "object", + "required": ["enabled", "existingSecret"], + "properties": { + "enabled": {"type": "boolean"}, + "existingSecret": {"$ref": "#/definitions/kubernetesName"} + } + } + }, + "definitions": { + "kubernetesName": { + "type": "string", + "minLength": 1, + "maxLength": 253, + "pattern": "^[a-z0-9]([-a-z0-9.]*[a-z0-9])?$" + }, + "stringMap": { + "type": "object", + "additionalProperties": {"type": "string"} + }, + "image": { + "type": "object", + "additionalProperties": false, + "required": ["repository", "tag", "digest", "pullPolicy"], + "properties": { + "repository": {"type": "string", "minLength": 1}, + "tag": {"type": "string", "minLength": 1, "not": {"enum": ["latest"]}}, + "digest": {"type": "string", "pattern": "^$|^sha256:[a-f0-9]{64}$"}, + "pullPolicy": {"enum": ["Always", "IfNotPresent", "Never"]} + } + }, + "probeTiming": { + "type": "object", + "additionalProperties": false, + "required": ["failureThreshold", "periodSeconds"], + "properties": { + "failureThreshold": {"type": "integer", "minimum": 1}, + "periodSeconds": {"type": "integer", "minimum": 1}, + "timeoutSeconds": {"type": "integer", "minimum": 1} + } + }, + "httpProbes": { + "type": "object", + "additionalProperties": false, + "required": ["startup", "readiness", "liveness"], + "properties": { + "startup": {"$ref": "#/definitions/probeTiming"}, + "readiness": {"$ref": "#/definitions/probeTiming"}, + "liveness": {"$ref": "#/definitions/probeTiming"} + } + }, + "processProbes": { + "type": "object", + "additionalProperties": false, + "required": ["startup", "liveness"], + "properties": { + "startup": {"$ref": "#/definitions/probeTiming"}, + "liveness": {"$ref": "#/definitions/probeTiming"} + } + }, + "resources": { + "type": "object", + "additionalProperties": false, + "required": ["requests", "limits"], + "properties": { + "requests": {"$ref": "#/definitions/resourcePair"}, + "limits": {"$ref": "#/definitions/resourcePair"} + } + }, + "resourcePair": { + "type": "object", + "additionalProperties": false, + "required": ["cpu", "memory"], + "properties": { + "cpu": {"type": ["string", "number"]}, + "memory": {"type": "string", "minLength": 2} + } + }, + "httpWorkload": { + "type": "object", + "additionalProperties": false, + "required": ["replicaCount", "service", "resources", "probes"], + "properties": { + "replicaCount": {"type": "integer", "minimum": 2, "maximum": 100}, + "service": { + "type": "object", + "additionalProperties": false, + "required": ["type", "port"], + "properties": { + "type": {"enum": ["ClusterIP"]}, + "port": {"type": "integer", "minimum": 1, "maximum": 65535} + } + }, + "resources": {"$ref": "#/definitions/resources"}, + "probes": {"$ref": "#/definitions/httpProbes"} + } + }, + "ingressRoute": { + "type": "object", + "additionalProperties": false, + "required": ["host", "path", "tlsSecretName"], + "properties": { + "host": {"type": "string", "minLength": 1}, + "path": {"type": "string", "pattern": "^/"}, + "tlsSecretName": {"$ref": "#/definitions/kubernetesName"} + } + }, + "databaseConfig": { + "type": "object", + "additionalProperties": false, + "required": ["poolSize", "maxOverflow", "poolRecycleSeconds", "poolTimeoutSeconds", "connectTimeoutSeconds"], + "properties": { + "poolSize": {"type": "integer", "minimum": 1, "maximum": 100}, + "maxOverflow": {"type": "integer", "minimum": 0, "maximum": 100}, + "poolRecycleSeconds": {"type": "integer", "minimum": 1}, + "poolTimeoutSeconds": {"type": "number", "exclusiveMinimum": 0}, + "connectTimeoutSeconds": {"type": "integer", "minimum": 1} + } + }, + "ingestionConfig": { + "type": "object", + "additionalProperties": false, + "required": ["maxAttempts", "retryBackoffSeconds", "retryBackoffMaxSeconds", "workerLeaseSeconds", "recoveryIntervalSeconds", "batchMaxFiles", "batchMaxTotalBytes", "maxUploadBytes"], + "properties": { + "maxAttempts": {"type": "integer", "minimum": 1, "maximum": 10}, + "retryBackoffSeconds": {"type": "integer", "minimum": 1}, + "retryBackoffMaxSeconds": {"type": "integer", "minimum": 1}, + "workerLeaseSeconds": {"type": "integer", "minimum": 30}, + "recoveryIntervalSeconds": {"type": "integer", "minimum": 5}, + "batchMaxFiles": {"type": "integer", "minimum": 1, "maximum": 100}, + "batchMaxTotalBytes": {"type": "integer", "minimum": 1}, + "maxUploadBytes": {"type": "integer", "minimum": 1} + } + }, + "objectStorageConfig": { + "type": "object", + "additionalProperties": false, + "required": ["provider", "endpoint", "bucket", "keyPrefix", "timeoutSeconds"], + "properties": { + "provider": {"const": "bos"}, + "endpoint": {"type": "string", "minLength": 1}, + "bucket": {"type": "string", "minLength": 1}, + "keyPrefix": {"type": "string", "minLength": 1}, + "timeoutSeconds": {"type": "number", "exclusiveMinimum": 0} + } + }, + "chunkingConfig": { + "type": "object", + "additionalProperties": false, + "required": ["maxTokens", "overlapTokens", "maxCharacters"], + "properties": { + "maxTokens": {"type": "integer", "minimum": 1}, + "overlapTokens": {"type": "integer", "minimum": 0}, + "maxCharacters": {"type": "integer", "minimum": 4} + } + }, + "embeddingConfig": { + "type": "object", + "additionalProperties": false, + "required": ["provider", "model", "endpoint", "timeoutSeconds"], + "properties": { + "provider": {"const": "qianfan"}, + "model": {"const": "bge-large-zh"}, + "endpoint": {"type": "string", "minLength": 1}, + "timeoutSeconds": {"type": "number", "exclusiveMinimum": 0} + } + }, + "vectorStoreConfig": { + "type": "object", + "additionalProperties": false, + "required": ["provider", "uri", "user", "database", "table", "index", "batchSize", "timeoutSeconds"], + "properties": { + "provider": {"const": "oceanbase"}, + "uri": {"type": "string", "minLength": 1}, + "user": {"type": "string", "minLength": 1}, + "database": {"type": "string", "minLength": 1}, + "table": {"type": "string", "minLength": 1}, + "index": {"type": "string", "minLength": 1}, + "batchSize": {"type": "integer", "minimum": 1, "maximum": 1000}, + "timeoutSeconds": {"type": "number", "exclusiveMinimum": 0} + } + }, + "retrievalConfig": { + "type": "object", + "additionalProperties": false, + "required": ["indexProfileId", "denseTopN", "searchTopK"], + "properties": { + "indexProfileId": {"type": "string", "minLength": 1}, + "denseTopN": {"type": "integer", "minimum": 1, "maximum": 64}, + "searchTopK": {"type": "integer", "minimum": 1, "maximum": 64} + } + }, + "rerankerConfig": { + "type": "object", + "additionalProperties": false, + "required": ["provider", "model", "endpoint", "timeoutSeconds"], + "properties": { + "provider": {"const": "qianfan"}, + "model": {"const": "bce-reranker-base"}, + "endpoint": {"type": "string", "minLength": 1}, + "timeoutSeconds": {"type": "number", "exclusiveMinimum": 0} + } + }, + "mcpConfig": { + "type": "object", + "additionalProperties": false, + "required": ["publicUrl", "issuerUrl", "clientId", "serviceIdentity", "requiredScope", "allowedHosts", "allowedOrigins", "maxRequestBodyBytes"], + "properties": { + "publicUrl": {"type": "string", "pattern": "^https://"}, + "issuerUrl": {"type": "string", "pattern": "^https://"}, + "clientId": {"type": "string", "minLength": 1}, + "serviceIdentity": {"type": "string", "minLength": 1}, + "requiredScope": {"const": "knowledge:search"}, + "allowedHosts": {"type": "array", "minItems": 1, "items": {"type": "string", "minLength": 1}}, + "allowedOrigins": {"type": "array", "minItems": 1, "items": {"type": "string", "pattern": "^https://"}}, + "maxRequestBodyBytes": {"type": "integer", "minimum": 1024, "maximum": 4194304} + } + } + } +} diff --git a/deploy/helm/knowledge-platform/values.yaml b/deploy/helm/knowledge-platform/values.yaml new file mode 100644 index 0000000..9a255ae --- /dev/null +++ b/deploy/helm/knowledge-platform/values.yaml @@ -0,0 +1,218 @@ +# DEPLOY-002 safe defaults. Real endpoints, immutable image coordinates and +# Secret names are supplied in an environment-specific values file. +nameOverride: "" +fullnameOverride: "" + +existingSecret: knowledge-platform-runtime +imagePullSecrets: [] + +images: + api: + repository: knowledge-platform/enterprise-knowledge-api + tag: "0.1.0" + digest: "" + pullPolicy: IfNotPresent + mcp: + repository: knowledge-platform/enterprise-knowledge-mcp + tag: "0.1.0" + digest: "" + pullPolicy: IfNotPresent + worker: + repository: knowledge-platform/enterprise-knowledge-worker + tag: "0.1.0" + digest: "" + pullPolicy: IfNotPresent + +serviceAccount: + create: true + name: "" + annotations: {} + +podAnnotations: {} +podLabels: {} + +api: + replicaCount: 2 + service: + type: ClusterIP + port: 80 + resources: + requests: + cpu: 250m + memory: 512Mi + limits: + cpu: "1" + memory: 1Gi + probes: + startup: + failureThreshold: 30 + periodSeconds: 2 + readiness: + periodSeconds: 10 + timeoutSeconds: 2 + failureThreshold: 3 + liveness: + periodSeconds: 20 + timeoutSeconds: 2 + failureThreshold: 3 + +mcp: + replicaCount: 2 + service: + type: ClusterIP + port: 80 + resources: + requests: + cpu: 250m + memory: 512Mi + limits: + cpu: "1" + memory: 1Gi + probes: + startup: + failureThreshold: 30 + periodSeconds: 2 + readiness: + periodSeconds: 10 + timeoutSeconds: 2 + failureThreshold: 3 + liveness: + periodSeconds: 20 + timeoutSeconds: 2 + failureThreshold: 3 + +worker: + replicaCount: 2 + terminationGracePeriodSeconds: 60 + resources: + requests: + cpu: 500m + memory: 1Gi + limits: + cpu: "2" + memory: 2Gi + probes: + startup: + failureThreshold: 30 + periodSeconds: 2 + liveness: + periodSeconds: 20 + timeoutSeconds: 2 + failureThreshold: 3 + +# Celery Beat is separated from scalable workers so only one recovery +# scheduler publishes due durable Jobs at a time. +scheduler: + enabled: true + resources: + requests: + cpu: 100m + memory: 256Mi + limits: + cpu: 500m + memory: 512Mi + probes: + startup: + failureThreshold: 30 + periodSeconds: 2 + liveness: + periodSeconds: 20 + timeoutSeconds: 2 + failureThreshold: 3 + +migration: + enabled: true + activeDeadlineSeconds: 600 + backoffLimit: 0 + ttlSecondsAfterFinished: 86400 + resources: + requests: + cpu: 100m + memory: 256Mi + limits: + cpu: 500m + memory: 512Mi + +ingress: + enabled: false + className: nginx + annotations: {} + api: + host: knowledge.example.invalid + path: / + tlsSecretName: knowledge-platform-api-tls + mcp: + host: mcp.example.invalid + path: /mcp + tlsSecretName: knowledge-platform-mcp-tls + +# Only non-sensitive runtime settings belong here. The templates enumerate +# keys explicitly so credentials cannot be added to this ConfigMap by mistake. +config: + appName: enterprise-knowledge-platform + logLevel: INFO + database: + poolSize: 10 + maxOverflow: 10 + poolRecycleSeconds: 600 + poolTimeoutSeconds: 30 + connectTimeoutSeconds: 30 + ingestion: + maxAttempts: 3 + retryBackoffSeconds: 2 + retryBackoffMaxSeconds: 60 + workerLeaseSeconds: 300 + recoveryIntervalSeconds: 30 + batchMaxFiles: 20 + batchMaxTotalBytes: 209715200 + maxUploadBytes: 52428800 + objectStorage: + provider: bos + endpoint: https://s3.example.invalid + bucket: knowledge-platform + keyPrefix: knowledge-platform + timeoutSeconds: 30 + chunking: + maxTokens: 450 + overlapTokens: 75 + maxCharacters: 2000 + embedding: + provider: qianfan + model: bge-large-zh + endpoint: https://qianfan.baidubce.com/v2/embeddings + timeoutSeconds: 30 + vectorStore: + provider: oceanbase + uri: oceanbase.example.invalid:2881 + user: knowledge-platform + database: knowledge_platform + table: knowledge_chunks_v1 + index: vidx_knowledge_chunks_embedding + batchSize: 100 + timeoutSeconds: 30 + retrieval: + indexProfileId: demo-bge-large-zh-structure-v1-oceanbase-v1 + denseTopN: 20 + searchTopK: 5 + reranker: + provider: qianfan + model: bce-reranker-base + endpoint: https://qianfan.baidubce.com/v2/rerank + timeoutSeconds: 30 + mcp: + publicUrl: https://mcp.example.invalid/mcp + issuerUrl: https://mcp.example.invalid + clientId: workbuddy-enterprise + serviceIdentity: workbuddy-public-knowledge + requiredScope: knowledge:search + allowedHosts: + - mcp.example.invalid + allowedOrigins: + - https://mcp.example.invalid + maxRequestBodyBytes: 1048576 + +# Optional local dependency. Keep disabled for production and provide +# RABBITMQ_URL through existingSecret for an externally managed broker. +rabbitmq: + enabled: false + existingSecret: knowledge-platform-rabbitmq diff --git a/docs/architecture/ARCHITECTURE.md b/docs/architecture/ARCHITECTURE.md index fd769ea..13a0aae 100644 --- a/docs/architecture/ARCHITECTURE.md +++ b/docs/architecture/ARCHITECTURE.md @@ -763,6 +763,11 @@ readiness/liveness、资源限制、非 root 与只读根文件系统、多副 本地开发资产,不能作为集群模板。详细依赖和验收见 [`PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md`](../plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md)。 +DEPLOY-002 的运行拓扑将 Celery Worker 与 Celery Beat 恢复调度器拆成独立 Pod:Worker 可横向 +扩缩,Beat 固定单副本并使用 `Recreate`,避免每个 Worker 都发布周期恢复消息。二者仍调用同一 +应用服务与持久化 Job/Attempt 状态,不形成新业务服务,也不改变 ADR-002。Migration 使用 Helm +`pre-install,pre-upgrade` Hook;失败会在业务 Deployment 更新前终止原子升级。 + --- ## 17. V1 验收重点 diff --git a/docs/development/CONTAINER_IMAGES.md b/docs/development/CONTAINER_IMAGES.md index fb814d5..b135607 100644 --- a/docs/development/CONTAINER_IMAGES.md +++ b/docs/development/CONTAINER_IMAGES.md @@ -10,8 +10,9 @@ DEPLOY-001 使用同一个锁定运行时构建三个独立镜像目标: | `mcp` | `enterprise-knowledge-mcp` | `ekp-mcp` | `8766` | PID 1 存活 | | `worker` | `enterprise-knowledge-worker` | `ekp-worker` | 无 | PID 1 存活 | -镜像没有内置数据库迁移、Helm、Ingress 或 Secret 对象;这些属于 DEPLOY-002。API 镜像已包含 -Alembic 和 migrations,可由 DEPLOY-002 的一次性 Migration Job 覆盖命令后复用。 +镜像没有内置数据库迁移、Helm、Ingress 或 Secret 对象;DEPLOY-002 已在独立 Chart 中提供这些 +编排能力。API 镜像包含 Alembic 和 migrations,由一次性 Migration Job 覆盖命令后复用。详见 +[`KUBERNETES_DEPLOYMENT.md`](KUBERNETES_DEPLOYMENT.md)。 ## 可重复构建基线 @@ -61,7 +62,7 @@ make images-push 时由 Secret 注入。镜像构建参数、Layer、标签、健康检查和启动命令都不得包含这些值。 API 的 `/healthz` 只证明进程存活,不读取云端凭据或探测依赖。Kubernetes readiness、资源限制、 -只读根文件系统所需临时卷及依赖就绪策略由 DEPLOY-002 配置。MCP endpoint 需要认证,Worker +只读根文件系统所需临时卷及依赖就绪策略由 DEPLOY-002 Chart 配置。MCP endpoint 需要认证,Worker 没有 HTTP server,因此这两个镜像的 Docker 健康检查只验证主进程;业务可恢复性仍以持久化 Job/Attempt 和 DEPLOY-003 故障验收为准。 diff --git a/docs/development/KUBERNETES_DEPLOYMENT.md b/docs/development/KUBERNETES_DEPLOYMENT.md new file mode 100644 index 0000000..c1a1ecc --- /dev/null +++ b/docs/development/KUBERNETES_DEPLOYMENT.md @@ -0,0 +1,143 @@ +# Kubernetes / Helm 部署说明 + +## 1. 交付范围 + +DEPLOY-002 提供单一 Helm Chart,将以下运行角色部署到已有 Kubernetes 集群: + +- API/Admin:默认两个副本,提供 `/healthz`、`/admin/*` 和 `/api/v1/*`; +- MCP Gateway:默认两个副本,提供经 Bearer Token 保护的 `/mcp`; +- Async Worker:默认两个副本,只消费 `ingestion` 队列; +- Recovery Scheduler:固定单副本,以 `Recreate` 策略运行 Celery Beat; +- Migration Job:每次安装/升级前串行执行 `alembic upgrade head`; +- 可选 RabbitMQ:只供开发/演示集群显式启用,生产默认使用外部 Broker。 + +OceanBase MySQL、BOS、Embedding/Reranker 服务继续使用集群外已有资源。Chart 不创建数据库、 +BOS Bucket、域名、证书或云账号,也没有扩大公共知识库阶段的业务范围。 + +## 2. 前置条件 + +操作者需要提前准备: + +1. 可用的 Kubernetes Namespace 和对应 `kubectl` 上下文; +2. Helm 3/4 与 Kubernetes 客户端; +3. 已推送到目标 Registry 的 API、MCP、Worker 不可变 tag 或 digest; +4. Namespace 内的运行时 Secret、TLS Secret,以及私有 Registry 所需的 ImagePullSecret; +5. 集群到 OceanBase、BOS、RabbitMQ 和模型服务的网络连通性。 + +Chart 默认引用 `knowledge-platform-runtime`,但不会创建它。该 Secret 至少包含以下键: + +```text +DATABASE_URL +RABBITMQ_URL +BOS_ACCESS_KEY_ID +BOS_SECRET_ACCESS_KEY +BAIDU_QIANFAN_API_KEY +OCEANBASE_VECTOR_PASSWORD +MCP_AUTH_TOKEN +``` + +`RERANKER_API_KEY` 可单独提供;未提供时应用按既有契约复用 +`BAIDU_QIANFAN_API_KEY`。`MCP_AUTH_TOKEN` 至少 32 个字符,只具备 +`knowledge:search` 服务范围。不要使用 `kubectl --from-literal`、Shell 参数或 Helm +`--set` 传递以上值;应由受控 Secret 管理系统或运维流程预先写入 Namespace。 + +## 3. 环境 Values + +复制 [`values.example.yaml`](../../deploy/helm/environments/values.example.yaml) 到仓库外的受控 +路径,填写以下非敏感信息: + +- 三个镜像的 Registry 路径与不可变 tag/digest; +- `existingSecret` 和 `imagePullSecrets` 的资源名称; +- OceanBase/BOS 的非敏感 Endpoint、数据库标识和 Bucket; +- Admin/API 与 MCP 的 Ingress Host、TLS Secret 名称; +- 与外部地址一致的 MCP Public URL、Issuer、Allowed Host/Origin; +- 副本、资源、超时和批量上传限制。 + +`values.schema.json` 拒绝未知顶层字段、`latest` tag、无效 digest、单副本 API/MCP、错误类型和 +空的关键引用;模板还会校验 Chunk、检索和入库限制之间的大小关系。Values 只允许非敏感配置, +模板逐项生成 ConfigMap,不提供任意 `extraEnv` 入口,避免把凭据误写进渲染产物。 + +## 4. 安装与幂等升级 + +先做离线校验和清单检查: + +```bash +make deploy-lint VALUES=/secure/path/environment-values.yaml +make deploy-render VALUES=/secure/path/environment-values.yaml +``` + +安装或升级: + +```bash +NAMESPACE=knowledge-platform \ +RELEASE=knowledge-platform \ +make deploy VALUES=/secure/path/environment-values.yaml +``` + +`make deploy` 只接收 Values 文件路径。脚本会先验证 Chart、Namespace、运行时 Secret 及必需 +键名、可选 RabbitMQ Secret 键名,以及启用 Ingress 时的两个 TLS Secret 引用,然后执行带失败 +回滚和等待语义的 `helm upgrade --install`;脚本对 Helm 3 使用 `--atomic`,对 Helm 4 使用等价 +的 `--rollback-on-failure`。它只验证 Secret 资源和键是否存在,不读取或输出 Secret 值。 + +Migration 是 `pre-install,pre-upgrade` Hook,固定名称配合 +`before-hook-creation` 保证同一 Release 内不会并发执行。Helm 等待 Migration 成功后才更新业务 +工作负载;失败时 Helm 保留上一版本。完成的 Job 最长保留一天供日志追查,并在下次升级前删除。 +安装命令可以重复执行;数据库迁移必须保持 forward-only 与幂等。 + +## 5. Ingress、探针与 Pod 安全 + +生产环境启用 Ingress 后,Admin/API 与 MCP 使用独立稳定 HTTPS Host,也可由同一 Ingress +Controller 托管。证书只通过预建 TLS Secret 引用,不进入 Values。 + +- API 的 startup/readiness/liveness 调用无凭据 `/healthz`; +- MCP 的三类探针使用 TCP 端口,不发送或记录 Token; +- Worker/Scheduler 使用 PID 1 存活探针,业务恢复正确性由持久化 Job/Attempt 保证; +- 全部应用容器固定 UID/GID `10001`、禁止提权、丢弃 Linux capabilities、使用 + `RuntimeDefault` seccomp 和只读根文件系统; +- `/tmp` 使用有大小上限的 `emptyDir`,ServiceAccount 不挂载 API Token; +- API/MCP 滚动更新使用 `maxUnavailable: 0`,未 Ready Pod 不进入 Service Endpoint。 + +`/healthz` 当前只表示 API 进程存活,不探测所有外部 Provider;真实依赖故障、滚动重启和 +Worker 恢复行为由 DEPLOY-003 在目标集群验收。 + +## 6. 可选 Demo RabbitMQ + +生产默认 `rabbitmq.enabled=false`,`RABBITMQ_URL` 指向外部受管 Broker。仅开发/演示时可开启 +本地子 Chart;它使用单节点 StatefulSet 和 PVC,并要求预建 Secret 包含: + +```text +username +password +erlang-cookie +``` + +同时必须让运行时 Secret 中的 `RABBITMQ_URL` 指向该 Service。子 Chart 使用固定 +`rabbitmq:4.1.4-alpine` tag 与 multi-architecture manifest digest;它不具备生产 RabbitMQ 的 +高可用、备份或升级保证,禁止作为生产默认值。卸载 Release 时 StatefulSet PVC 默认保留, +删除前必须由数据责任人确认。 + +## 7. 回滚、卸载与 Secret 轮换 + +查看历史并回滚时不要输出 Pod 环境变量: + +```bash +helm -n knowledge-platform history knowledge-platform +helm -n knowledge-platform rollback knowledge-platform --wait +``` + +更新外部 Secret 后,Secret 名称不变;用户和 WorkBuddy 配置无需重新注入。当前应通过受控 +滚动重启让 Pod 读取新值,目标集群的无中断验证属于 DEPLOY-003。 + +卸载只删除本 Release 管理的 Kubernetes 对象: + +```bash +helm -n knowledge-platform uninstall knowledge-platform +``` + +外部 OceanBase、BOS、RabbitMQ、TLS/运行时 Secret 和可选 RabbitMQ PVC 不由卸载命令删除。 + +## 8. DEPLOY-002 验收边界 + +本任务完成 Chart lint、双路径渲染、严格 Kubernetes Schema、Values 失败关闭、Secret 泄漏扫描 +以及本地集群两次安装/升级验证。目标企业集群的稳定 HTTPS、滚动重启、Worker 故障恢复、真实 +Provider 和远程 WorkBuddy 验收统一属于后续 `DEPLOY-003`,不得提前宣称完成。 diff --git a/docs/plans/PROGRESS.md b/docs/plans/PROGRESS.md index c3493bf..2f4da57 100644 --- a/docs/plans/PROGRESS.md +++ b/docs/plans/PROGRESS.md @@ -396,3 +396,31 @@ Provider 架构迁移按 `ARCH-001 → ARCH-002 → ARCH-003 → ARCH-004 → AR 默认 CMD 与 HEALTHCHECK 元数据核对通过。真实 Provider/Broker 启动仍属于 DEPLOY-003。 - Ruff Format/Lint、Mypy、Docker Bake 渲染、JavaScript/依赖锁/Alembic 与完整测试门禁通过; Unit + Integration `187 passed`,RAG Evaluation `5 passed`。下一任务:`DEPLOY-002`。 + +### DEPLOY-002(已完成) + +- 新增 `deploy/helm/knowledge-platform` Helm Chart,部署 API/Admin、MCP Gateway、Async Worker、 + 单实例 Recovery Scheduler、串行 Migration Job、Service、Ingress/TLS 和可选 Demo RabbitMQ; + API/MCP 默认各两个副本,Worker 可独立扩缩,Beat 使用 `Recreate` 避免重复调度。 +- 新增严格 `values.schema.json` 与仓库外环境 Values 示例,拒绝未知顶层字段、`latest` tag、 + 非法 digest、API/MCP 单副本和错误类型;跨字段模板校验继续约束批量大小、重试、Chunk 和 + Top-K 关系。应用和可选 RabbitMQ 镜像均支持 digest,Demo RabbitMQ 已固定 manifest digest。 +- 敏感配置只通过预建 `existingSecret` 注入;ConfigMap 仅渲染显式白名单内的非敏感字段, + 没有任意 `extraEnv` 或 Secret 对象。`scripts/deploy.sh` 在部署前校验 Values、Namespace、运行时 + Secret/必需键、可选 RabbitMQ Secret/键和启用 Ingress 时的 TLS Secret 引用,不读取 Secret + 值;Helm 3/4 分别使用等价的原子失败回滚参数。 +- Migration 使用 `pre-install,pre-upgrade` Hook、固定名称和 `before-hook-creation`,安装/升级在 + Migration 成功前不更新业务 Pod。应用容器固定非 root UID/GID、只读根文件系统、丢弃全部 + capabilities、禁用 ServiceAccount Token,并为临时目录、RabbitMQ 日志和 Beat 状态提供 + `emptyDir`;API/MCP/Worker/Scheduler 均配置启动和存活/就绪探针及资源 requests/limits。 +- 本机使用 K3s `v1.35.0+k3s1`、Helm `4.2.4` 和 DEPLOY-001 ARM64 镜像完成真实安装;Migration + 成功,API/MCP 为 `2/2`,Worker、Scheduler 与可选 RabbitMQ 全部 Ready。首次安装暴露的 + RabbitMQ 只读日志目录和 Beat 调度文件权限问题已修复,随后相同 Values 连续升级至 Revision + 3~5 均成功;API `/healthz` 和 Admin 上传页 smoke test 通过。 +- 默认、环境示例和 RabbitMQ 三种 Helm lint 均通过;含 Ingress/TLS/RabbitMQ 的 14 个最终 + 资源通过 kubeconform strict 校验。仓库、Helm manifest、Pod 日志三路 Secret 值扫描均为 `0`; + Ruff Format/Lint、Mypy、Alembic、Bash 语法与完整门禁通过,Unit + Integration `195 passed`, + RAG Evaluation `5 passed`。 +- 目标企业集群的稳定 HTTPS、滚动重启、Worker 故障恢复、真实外部依赖监测与远程 WorkBuddy + 仍属于 `DEPLOY-003`;本任务没有把这些项提前标记完成,也没有改变 Accepted ADR 或公共知识库 + 范围。下一任务:`DEPLOY-003`。 diff --git a/docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md b/docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md index 1373833..ebfbea2 100644 --- a/docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md +++ b/docs/plans/PUBLIC_KNOWLEDGE_CLUSTER_PLAN.md @@ -92,9 +92,11 @@ Celery/RabbitMQ。队列调用保持在抽象边界后,不允许业务服务 ### DEPLOY-002 -交付 Kubernetes/Helm Chart、环境 Values Schema、`existingSecret`、Migration Job、Ingress/TLS、 -Pod 安全、资源限制、探针和 `make deploy` 入口。现有 `docker-compose.dev.yml` 仍仅作为旧的 -本地开发文件,因其 PostgreSQL/MinIO 假设与 ADR-012 不一致,不得作为集群交付模板。 +**已完成。** 交付 Kubernetes/Helm Chart、严格环境 Values Schema、`existingSecret`、串行 +Migration Hook、Ingress/TLS、Pod 安全、资源限制、探针和 `make deploy` 入口;Worker 与单实例 +恢复调度器已分离。现有 `docker-compose.dev.yml` 仍仅作为旧的本地开发文件,因其 +PostgreSQL/MinIO 假设与 ADR-012 不一致,不得作为集群交付模板。下一交付门槛为 DEPLOY-003 +的目标集群可用性与远程验收。 ### DEPLOY-003 diff --git a/docs/plans/TASKS.md b/docs/plans/TASKS.md index b3777c8..4710f5c 100644 --- a/docs/plans/TASKS.md +++ b/docs/plans/TASKS.md @@ -31,7 +31,7 @@ validation. Provider credentials and internal endpoints are runtime inputs and n - [x] DEMO-015 Async ingestion Job + Celery/RabbitMQ + bounded retry + pre-retry cleanup - [x] DEMO-016 Batch async upload API + per-file Job status + Admin Console - [x] DEPLOY-001 Production images for API/Admin, MCP Gateway and Async Worker -- [ ] DEPLOY-002 Kubernetes/Helm one-click deployment + Secret/Migration/Ingress baseline +- [x] DEPLOY-002 Kubernetes/Helm one-click deployment + Secret/Migration/Ingress baseline - [ ] DEPLOY-003 Availability, rolling upgrade and remote WorkBuddy acceptance Dependencies and acceptance boundaries are defined in diff --git a/docs/plans/V1_EXECUTION_PLAN.md b/docs/plans/V1_EXECUTION_PLAN.md index eebce7a..bb754b0 100644 --- a/docs/plans/V1_EXECUTION_PLAN.md +++ b/docs/plans/V1_EXECUTION_PLAN.md @@ -19,7 +19,7 @@ 2. `DEMO-015`(已完成):持久化异步 Job、Celery/RabbitMQ 执行器、自动重试和重试前清理; 3. `DEMO-016`(已完成):批量异步上传、批次/Job 查询和 Admin Console 状态展示; 4. `DEPLOY-001`(已完成):API/Admin、MCP Gateway、Async Worker 生产镜像; -5. `DEPLOY-002`:Kubernetes/Helm、Secret、Migration、Ingress/TLS 和一键部署入口; +5. `DEPLOY-002`(已完成):Kubernetes/Helm、Secret、Migration、Ingress/TLS 和一键部署入口; 6. `DEPLOY-003`:多副本可用性、滚动升级、Worker 恢复和远程 WorkBuddy 验收。 严格依赖为: diff --git a/docs/product/PRD.md b/docs/product/PRD.md index 225e221..783dee6 100644 --- a/docs/product/PRD.md +++ b/docs/product/PRD.md @@ -471,6 +471,10 @@ Document ID 和 Ingestion Job;单个文件处理失败不得阻塞或回滚批 公共知识库集群交付使用分别可扩缩的 API/Admin、MCP Gateway 和 Async Worker 生产镜像; 镜像只包含锁定代码与非敏感默认值,环境凭据必须在部署时注入。 +集群编排由 Helm Chart 统一管理:API/MCP 默认多副本,Worker 与单实例恢复调度器分离;敏感值 +只引用预建 Kubernetes Secret,数据库 Migration 在安装/升级前串行完成。Ingress/TLS、探针、 +资源限制和 Pod 安全默认值属于部署契约,不改变 REST/MCP 业务接口。 + **REQ-INGEST-004** 展示处理阶段: diff --git a/scripts/deploy.sh b/scripts/deploy.sh new file mode 100755 index 0000000..a75b5e7 --- /dev/null +++ b/scripts/deploy.sh @@ -0,0 +1,130 @@ +#!/usr/bin/env bash +set -euo pipefail + +# DEPLOY-002 accepts a values file path only. Secret contents remain in +# Kubernetes and are never expanded into this process or Helm arguments. +values_file="${1:-}" +chart_dir="${CHART:-deploy/helm/knowledge-platform}" +release_name="${RELEASE:-knowledge-platform}" +namespace="${NAMESPACE:-knowledge-platform}" +deploy_timeout="${DEPLOY_TIMEOUT:-10m}" + +if [[ -z "${values_file}" || ! -f "${values_file}" ]]; then + echo "VALUES must point to an existing environment values file" >&2 + exit 2 +fi + +for tool in helm kubectl; do + if ! command -v "${tool}" >/dev/null 2>&1; then + echo "required deployment tool is missing: ${tool}" >&2 + exit 2 + fi +done + +# Helm 4 renamed --atomic to --rollback-on-failure. Select the equivalent flag +# by major version while preserving compatibility with supported Helm 3. +helm_version="$(helm version --template '{{.Version}}')" +if [[ "${helm_version}" =~ ^v?([0-9]+) ]] && (( BASH_REMATCH[1] >= 4 )); then + rollback_flag=(--rollback-on-failure) +else + rollback_flag=(--atomic) +fi + +helm lint "${chart_dir}" --values "${values_file}" + +# The test-hook ConfigMap contains resource names only. Its fixed, controlled +# shape lets awk extract names without adding a YAML parser or reading Secrets. +preflight_yaml="$({ + helm template "${release_name}" "${chart_dir}" \ + --namespace "${namespace}" \ + --values "${values_file}" \ + --show-only templates/tests/preflight-references.yaml +})" +runtime_secret="$({ + printf '%s\n' "${preflight_yaml}" | awk '$1 == "runtimeSecret:" {gsub(/\"/, "", $2); print $2}' +})" +ingress_enabled="$({ + printf '%s\n' "${preflight_yaml}" | awk '$1 == "ingressEnabled:" {gsub(/\"/, "", $2); print $2}' +})" +rabbitmq_enabled="$({ + printf '%s\n' "${preflight_yaml}" | awk '$1 == "rabbitmqEnabled:" {gsub(/\"/, "", $2); print $2}' +})" + +if [[ -z "${runtime_secret}" || -z "${ingress_enabled}" || -z "${rabbitmq_enabled}" ]]; then + echo "failed to resolve Helm Secret references" >&2 + exit 2 +fi + +secret_has_key() { + local secret_name="$1" + local key_name="$2" + local present + present="$({ + kubectl -n "${namespace}" get secret "${secret_name}" \ + -o go-template="{{with .data}}{{if index . \"${key_name}\"}}present{{end}}{{end}}" + })" + [[ "${present}" == "present" ]] +} + +if ! kubectl get namespace "${namespace}" >/dev/null; then + echo "target namespace does not exist: ${namespace}" >&2 + exit 2 +fi +if ! kubectl -n "${namespace}" get secret "${runtime_secret}" >/dev/null; then + echo "referenced runtime Secret does not exist: ${runtime_secret}" >&2 + exit 2 +fi +required_runtime_keys=( + DATABASE_URL + RABBITMQ_URL + BOS_ACCESS_KEY_ID + BOS_SECRET_ACCESS_KEY + BAIDU_QIANFAN_API_KEY + OCEANBASE_VECTOR_PASSWORD + MCP_AUTH_TOKEN +) +for key in "${required_runtime_keys[@]}"; do + if ! secret_has_key "${runtime_secret}" "${key}"; then + echo "referenced runtime Secret is missing required key: ${key}" >&2 + exit 2 + fi +done + +if [[ "${ingress_enabled}" == "true" ]]; then + for key in apiTlsSecret mcpTlsSecret; do + tls_secret="$({ + printf '%s\n' "${preflight_yaml}" | awk -v field="${key}:" '$1 == field {gsub(/\"/, "", $2); print $2}' + })" + if ! kubectl -n "${namespace}" get secret "${tls_secret}" >/dev/null; then + echo "referenced TLS Secret does not exist: ${tls_secret}" >&2 + exit 2 + fi + done +fi + +if [[ "${rabbitmq_enabled}" == "true" ]]; then + rabbitmq_secret="$({ + printf '%s\n' "${preflight_yaml}" | awk '$1 == "rabbitmqSecret:" {gsub(/\"/, "", $2); print $2}' + })" + if ! kubectl -n "${namespace}" get secret "${rabbitmq_secret}" >/dev/null; then + echo "referenced RabbitMQ Secret does not exist: ${rabbitmq_secret}" >&2 + exit 2 + fi + for key in username password erlang-cookie; do + if ! secret_has_key "${rabbitmq_secret}" "${key}"; then + echo "referenced RabbitMQ Secret is missing required key: ${key}" >&2 + exit 2 + fi + done +fi + +# The version-specific rollback flag keeps the previous release active when a +# pre-upgrade migration or rollout fails. Helm serializes operations for this +# release and waits for hook/workload readiness before returning success. +helm upgrade --install "${release_name}" "${chart_dir}" \ + --namespace "${namespace}" \ + --values "${values_file}" \ + "${rollback_flag[@]}" \ + --wait \ + --timeout "${deploy_timeout}" \ + --history-max 10 diff --git a/tests/unit/test_helm_deployment.py b/tests/unit/test_helm_deployment.py new file mode 100644 index 0000000..b3a187d --- /dev/null +++ b/tests/unit/test_helm_deployment.py @@ -0,0 +1,154 @@ +"""Static and rendered contracts for the DEPLOY-002 Helm delivery.""" + +import json +import shutil +import subprocess +from pathlib import Path + +import pytest + +ROOT = Path(__file__).resolve().parents[2] +CHART = ROOT / "deploy" / "helm" / "knowledge-platform" +EXAMPLE_VALUES = ROOT / "deploy" / "helm" / "environments" / "values.example.yaml" + + +def _helm(*arguments: str, expect_success: bool = True) -> subprocess.CompletedProcess[str]: + """Run Helm when installed; static checks still run on Python-only hosts.""" + executable = shutil.which("helm") + if executable is None: + pytest.skip("Helm is required for rendered chart assertions") + result = subprocess.run( + [executable, *arguments], + cwd=ROOT, + check=False, + capture_output=True, + text=True, + ) + if expect_success and result.returncode != 0: + pytest.fail(f"Helm failed: {result.stderr or result.stdout}") + return result + + +def _render(*extra_arguments: str) -> str: + """Render deterministic manifests without contacting a cluster.""" + result = _helm( + "template", + "knowledge-platform", + str(CHART), + "--namespace", + "knowledge-platform", + "--values", + str(EXAMPLE_VALUES), + *extra_arguments, + ) + return result.stdout + + +def test_chart_has_machine_validated_values_schemas() -> None: + """Both the application and optional broker expose valid JSON Schemas.""" + for schema_path in ( + CHART / "values.schema.json", + CHART / "charts" / "rabbitmq" / "values.schema.json", + ): + schema = json.loads(schema_path.read_text()) + assert schema["$schema"] == "https://json-schema.org/draft-07/schema#" + assert schema["type"] == "object" + + +def test_default_chart_renders_secret_only_sensitive_configuration() -> None: + """Credentials are references; the chart never creates or embeds a Secret.""" + rendered = _render() + + assert "kind: Secret\n" not in rendered + assert "secretRef:\n name: knowledge-platform-runtime" in rendered + assert "key: DATABASE_URL" in rendered + assert "helm.sh/hook: pre-install,pre-upgrade" in rendered + assert 'args: ["upgrade", "head"]' in rendered + assert "value: mysql+pymysql://" not in rendered + assert "change-me" not in rendered + + +def test_workloads_render_availability_and_restricted_pod_defaults() -> None: + """API/MCP are multi-replica and every application process is non-root.""" + rendered = _render() + + assert "name: knowledge-platform-api" in rendered + assert "name: knowledge-platform-mcp" in rendered + assert rendered.count("replicas: 2") >= 3 + assert rendered.count("readOnlyRootFilesystem: true") >= 5 + assert rendered.count("allowPrivilegeEscalation: false") >= 5 + assert rendered.count("automountServiceAccountToken: false") >= 6 + assert "maxUnavailable: 0" in rendered + assert "readinessProbe:" in rendered + assert "livenessProbe:" in rendered + assert "startupProbe:" in rendered + + +def test_scheduler_is_singleton_and_workers_do_not_embed_beat() -> None: + """Scaled workers cannot accidentally create multiple periodic schedulers.""" + rendered = _render() + + scheduler = rendered[rendered.index("name: knowledge-platform-scheduler") :] + scheduler = scheduler[: scheduler.index("---", 1)] + worker = rendered[rendered.index("name: knowledge-platform-worker") :] + worker = worker[: worker.index("---", 1)] + assert "replicas: 1" in scheduler + assert "type: Recreate" in scheduler + assert "- beat" in scheduler + assert "- worker" in worker + assert "- beat" not in worker + + +def test_ingress_and_optional_rabbitmq_are_explicitly_renderable() -> None: + """TLS routes and the persistent demo broker remain opt-in values.""" + rendered = _render("--set", "rabbitmq.enabled=true") + + assert "kind: Ingress" in rendered + assert "secretName: knowledge-platform-api-tls" in rendered + assert "secretName: knowledge-platform-mcp-tls" in rendered + assert "kind: StatefulSet" in rendered + assert "volumeClaimTemplates:" in rendered + assert "name: RABBITMQ_DEFAULT_PASS" in rendered + assert "valueFrom:" in rendered + + +def test_values_schema_rejects_latest_image_tags() -> None: + """Cluster releases require a non-latest immutable tag or digest.""" + result = _helm( + "lint", + str(CHART), + "--set", + "images.api.tag=latest", + expect_success=False, + ) + + assert result.returncode != 0 + assert "/images/api/tag" in (result.stdout + result.stderr) + + +def test_cross_field_validation_rejects_unsafe_ingestion_limits() -> None: + """Rendered settings preserve the application's own configuration rules.""" + result = _helm( + "template", + "knowledge-platform", + str(CHART), + "--set", + "config.ingestion.batchMaxTotalBytes=1", + expect_success=False, + ) + + assert result.returncode != 0 + assert "batchMaxTotalBytes must be >= maxUploadBytes" in (result.stdout + result.stderr) + + +def test_deploy_entrypoint_uses_atomic_upgrade_and_never_reads_secret_values() -> None: + """The one-command wrapper checks references and performs an atomic wait.""" + script = (ROOT / "scripts" / "deploy.sh").read_text() + + assert "helm upgrade --install" in script + assert "--atomic" in script + assert "--rollback-on-failure" in script + assert "--wait" in script + assert 'kubectl -n "${namespace}" get secret' in script + assert 'awk \'$1 == "runtimeSecret:"' in script + assert "DATABASE_URL}'" not in script