From ba884d3d60aa679fad54b2e137a7c73a50dd6c26 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Thu, 9 Jul 2026 16:25:14 -0400
Subject: [PATCH 01/11] feat(helm-chart): Add storage and bundled-MariaDB
 templates.

Adds the Spider Helm chart's templates and values: the storage gRPC service (Deployment +
Service + ConfigMap) and a bundled MariaDB (StatefulSet + Service + Secret), gated on
`spiderConfig.bundled`. Remove "database" from `bundled` to connect to an external MariaDB.
Builds on the chart scaffolding + linting from the companion PR.
---
 .../spider-helm/templates/_helpers.tpl        | 129 ++++++++++++++++++
 .../spider-helm/templates/configmap.yaml      |  21 +++
 .../templates/database-secret.yaml            |  14 ++
 .../templates/database-service.yaml           |  17 +++
 .../templates/database-statefulset.yaml       |  71 ++++++++++
 .../templates/storage-deployment.yaml         |  43 ++++++
 .../templates/storage-service.yaml            |  15 ++
 tools/deployment/spider-helm/values.yaml      |  46 +++++++
 8 files changed, 356 insertions(+)
 create mode 100644 tools/deployment/spider-helm/templates/_helpers.tpl
 create mode 100644 tools/deployment/spider-helm/templates/configmap.yaml
 create mode 100644 tools/deployment/spider-helm/templates/database-secret.yaml
 create mode 100644 tools/deployment/spider-helm/templates/database-service.yaml
 create mode 100644 tools/deployment/spider-helm/templates/database-statefulset.yaml
 create mode 100644 tools/deployment/spider-helm/templates/storage-deployment.yaml
 create mode 100644 tools/deployment/spider-helm/templates/storage-service.yaml

diff --git a/tools/deployment/spider-helm/templates/_helpers.tpl b/tools/deployment/spider-helm/templates/_helpers.tpl
new file mode 100644
index 00000000..e2773ae0
--- /dev/null
+++ b/tools/deployment/spider-helm/templates/_helpers.tpl
@@ -0,0 +1,129 @@
+{{/*
+Expands the name of the chart.
+
+@return {string} The chart name (truncated to 63 characters)
+*/}}
+{{- define "spider.name" -}}
+{{- default .Chart.Name .Values.nameOverride | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Creates a default fully qualified app name (truncated to 63 chars for the DNS naming spec). If the
+release name already contains the chart name it is used as-is.
+
+@return {string} The fully qualified app name (truncated to 63 characters)
+*/}}
+{{- define "spider.fullname" -}}
+{{- if .Values.fullnameOverride }}
+{{- .Values.fullnameOverride | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- $name := default .Chart.Name .Values.nameOverride }}
+{{- if contains $name .Release.Name }}
+{{- .Release.Name | trunc 63 | trimSuffix "-" }}
+{{- else }}
+{{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
+{{- end }}
+{{- end }}
+{{- end }}
+
+{{/*
+Creates chart name and version as used by the chart label.
+
+@return {string} Chart name and version (truncated to 63 characters)
+*/}}
+{{- define "spider.chart" -}}
+{{- printf "%s-%s" .Chart.Name .Chart.Version | replace "+" "_" | trunc 63 | trimSuffix "-" }}
+{{- end }}
+
+{{/*
+Creates common labels for all resources.
+
+@return {string} YAML-formatted common labels
+*/}}
+{{- define "spider.labels" -}}
+helm.sh/chart: {{ include "spider.chart" . }}
+{{ include "spider.selectorLabels" . }}
+{{- if .Chart.AppVersion }}
+app.kubernetes.io/version: {{ .Chart.AppVersion | quote }}
+{{- end }}
+app.kubernetes.io/managed-by: {{ .Release.Service }}
+{{- end }}
+
+{{/*
+Creates selector labels for matching resources.
+
+@return {string} YAML-formatted selector labels
+*/}}
+{{- define "spider.selectorLabels" -}}
+app.kubernetes.io/name: {{ include "spider.name" . }}
+app.kubernetes.io/instance: {{ .Release.Name }}
+{{- end }}
+
+{{/*
+Creates a container image reference from `.Values.image.<component>`.
+
+The tag defaults to the chart's appVersion when the component omits it.
+
+@param {object} root Root template context (required)
+@param {string} component Key under `.Values.image` (e.g. "storage", "mariadb")
+@return {string} Full image reference (repository:tag)
+*/}}
+{{- define "spider.imageRef" -}}
+{{- $img := index .root.Values.image .component -}}
+{{- $tag := $img.tag | default .root.Chart.AppVersion -}}
+{{- printf "%s:%s" $img.repository $tag -}}
+{{- end }}
+
+{{/*
+Creates timings for readiness probes (faster checks for quicker startup).
+
+@return {string} YAML-formatted readiness probe timing configuration
+*/}}
+{{- define "spider.readinessProbeTimings" -}}
+initialDelaySeconds: 6
+periodSeconds: 2
+timeoutSeconds: 2
+failureThreshold: 10
+{{- end }}
+
+{{/*
+Creates timings for liveness probes.
+
+@return {string} YAML-formatted liveness probe timing configuration
+*/}}
+{{- define "spider.livenessProbeTimings" -}}
+initialDelaySeconds: 180
+periodSeconds: 30
+timeoutSeconds: 4
+failureThreshold: 3
+{{- end }}
+
+{{/*
+Gets the database host. When "database" is bundled, this is the in-cluster MariaDB Service; when not
+bundled, it is the external `spiderConfig.database.host`.
+
+@param {object} . Root template context
+@return {string} The database host
+*/}}
+{{- define "spider.databaseHost" -}}
+{{- if has "database" .Values.spiderConfig.bundled -}}
+{{- printf "%s-database" (include "spider.fullname" .) -}}
+{{- else -}}
+{{- .Values.spiderConfig.database.host -}}
+{{- end -}}
+{{- end }}
+
+{{/*
+Gets the database port. When "database" is bundled, this is 3306 (the bundled MariaDB's port);
+otherwise it is the external `spiderConfig.database.port`.
+
+@param {object} . Root template context
+@return {string} The database port
+*/}}
+{{- define "spider.databasePort" -}}
+{{- if has "database" .Values.spiderConfig.bundled -}}
+3306
+{{- else -}}
+{{- .Values.spiderConfig.database.port -}}
+{{- end -}}
+{{- end }}
diff --git a/tools/deployment/spider-helm/templates/configmap.yaml b/tools/deployment/spider-helm/templates/configmap.yaml
new file mode 100644
index 00000000..98a4d276
--- /dev/null
+++ b/tools/deployment/spider-helm/templates/configmap.yaml
@@ -0,0 +1,21 @@
+apiVersion: "v1"
+kind: "ConfigMap"
+metadata:
+  name: {{ include "spider.fullname" . }}-config
+  labels:
+    {{- include "spider.labels" . | nindent 4 }}
+data:
+  storage.yaml: |
+    host: "0.0.0.0"
+    port: {{ .Values.spiderConfig.storage_endpoint.port }}
+    runtime:
+      db_config:
+        host: {{ include "spider.databaseHost" . | quote }}
+        port: {{ include "spider.databasePort" . }}
+        name: {{ .Values.spiderConfig.database.name | quote }}
+        username: {{ .Values.spiderConfig.database.username | quote }}
+        password: {{ .Values.spiderConfig.database.password | quote }}
+        max_connections: {{ .Values.spiderConfig.storage.max_connections }}
+      {{- with omit .Values.spiderConfig.storage "max_connections" }}
+      {{- toYaml . | nindent 6 }}
+      {{- end }}
diff --git a/tools/deployment/spider-helm/templates/database-secret.yaml b/tools/deployment/spider-helm/templates/database-secret.yaml
new file mode 100644
index 00000000..fde491cd
--- /dev/null
+++ b/tools/deployment/spider-helm/templates/database-secret.yaml
@@ -0,0 +1,14 @@
+{{- if has "database" .Values.spiderConfig.bundled }}
+apiVersion: "v1"
+kind: "Secret"
+metadata:
+  name: {{ include "spider.fullname" . }}-database
+  labels:
+    {{- include "spider.labels" . | nindent 4 }}
+    app.kubernetes.io/component: "database"
+type: "Opaque"
+stringData:
+  username: {{ .Values.spiderConfig.database.username | quote }}
+  password: {{ .Values.spiderConfig.database.password | quote }}
+  root_password: {{ .Values.spiderConfig.database.root_password | quote }}
+{{- end }}
diff --git a/tools/deployment/spider-helm/templates/database-service.yaml b/tools/deployment/spider-helm/templates/database-service.yaml
new file mode 100644
index 00000000..eb086897
--- /dev/null
+++ b/tools/deployment/spider-helm/templates/database-service.yaml
@@ -0,0 +1,17 @@
+{{- if has "database" .Values.spiderConfig.bundled }}
+apiVersion: "v1"
+kind: "Service"
+metadata:
+  name: {{ include "spider.fullname" . }}-database
+  labels:
+    {{- include "spider.labels" . | nindent 4 }}
+    app.kubernetes.io/component: "database"
+spec:
+  clusterIP: "None"
+  selector:
+    {{- include "spider.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: "database"
+  ports:
+    - port: 3306
+      targetPort: "database"
+{{- end }}
diff --git a/tools/deployment/spider-helm/templates/database-statefulset.yaml b/tools/deployment/spider-helm/templates/database-statefulset.yaml
new file mode 100644
index 00000000..388bd953
--- /dev/null
+++ b/tools/deployment/spider-helm/templates/database-statefulset.yaml
@@ -0,0 +1,71 @@
+{{- if has "database" .Values.spiderConfig.bundled }}
+apiVersion: "apps/v1"
+kind: "StatefulSet"
+metadata:
+  name: {{ include "spider.fullname" . }}-database
+  labels:
+    {{- include "spider.labels" . | nindent 4 }}
+    app.kubernetes.io/component: "database"
+spec:
+  serviceName: {{ include "spider.fullname" . }}-database
+  replicas: 1
+  selector:
+    matchLabels:
+      {{- include "spider.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: "database"
+  template:
+    metadata:
+      labels:
+        {{- include "spider.labels" . | nindent 8 }}
+        app.kubernetes.io/component: "database"
+    spec:
+      containers:
+        - name: "database"
+          image: {{ include "spider.imageRef" (dict "root" . "component" "mariadb") | quote }}
+          imagePullPolicy: {{ .Values.image.mariadb.pullPolicy | quote }}
+          env:
+            - name: "MYSQL_DATABASE"
+              value: {{ .Values.spiderConfig.database.name | quote }}
+            - name: "MYSQL_USER"
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "spider.fullname" . }}-database
+                  key: "username"
+            - name: "MYSQL_PASSWORD"
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "spider.fullname" . }}-database
+                  key: "password"
+            - name: "MYSQL_ROOT_PASSWORD"
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "spider.fullname" . }}-database
+                  key: "root_password"
+          ports:
+            - name: "database"
+              containerPort: 3306
+          volumeMounts:
+            - name: "data"
+              mountPath: "/var/lib/mysql"
+          readinessProbe:
+            {{- include "spider.readinessProbeTimings" . | nindent 12 }}
+            exec: &health-check
+              command: [
+                "mysqladmin", "ping",
+                "--host=127.0.0.1",
+                "--port=3306",
+                "--user=$(MYSQL_USER)",
+                "--password=$(MYSQL_PASSWORD)"
+              ]
+          livenessProbe:
+            {{- include "spider.livenessProbeTimings" . | nindent 12 }}
+            exec: *health-check
+  volumeClaimTemplates:
+    - metadata:
+        name: "data"
+      spec:
+        accessModes: ["ReadWriteOnce"]
+        resources:
+          requests:
+            storage: "20Gi"
+{{- end }}
diff --git a/tools/deployment/spider-helm/templates/storage-deployment.yaml b/tools/deployment/spider-helm/templates/storage-deployment.yaml
new file mode 100644
index 00000000..66535855
--- /dev/null
+++ b/tools/deployment/spider-helm/templates/storage-deployment.yaml
@@ -0,0 +1,43 @@
+apiVersion: "apps/v1"
+kind: "Deployment"
+metadata:
+  name: {{ include "spider.fullname" . }}-storage
+  labels:
+    {{- include "spider.labels" . | nindent 4 }}
+    app.kubernetes.io/component: "storage"
+spec:
+  replicas: 1
+  selector:
+    matchLabels:
+      {{- include "spider.selectorLabels" . | nindent 6 }}
+      app.kubernetes.io/component: "storage"
+  template:
+    metadata:
+      labels:
+        {{- include "spider.labels" . | nindent 8 }}
+        app.kubernetes.io/component: "storage"
+    spec:
+      containers:
+        - name: "storage"
+          image: {{ include "spider.imageRef" (dict "root" . "component" "storage") | quote }}
+          imagePullPolicy: {{ .Values.image.storage.pullPolicy | quote }}
+          command: ["spider-storage", "--config", "/etc/spider/storage.yaml"]
+          ports:
+            - name: "grpc"
+              containerPort: {{ .Values.spiderConfig.storage_endpoint.port }}
+          volumeMounts:
+            - name: "config"
+              mountPath: "/etc/spider"
+              readOnly: true
+          readinessProbe:
+            {{- include "spider.readinessProbeTimings" . | nindent 12 }}
+            tcpSocket:
+              port: "grpc"
+          livenessProbe:
+            {{- include "spider.livenessProbeTimings" . | nindent 12 }}
+            tcpSocket:
+              port: "grpc"
+      volumes:
+        - name: "config"
+          configMap:
+            name: {{ include "spider.fullname" . }}-config
diff --git a/tools/deployment/spider-helm/templates/storage-service.yaml b/tools/deployment/spider-helm/templates/storage-service.yaml
new file mode 100644
index 00000000..ca9c1332
--- /dev/null
+++ b/tools/deployment/spider-helm/templates/storage-service.yaml
@@ -0,0 +1,15 @@
+apiVersion: "v1"
+kind: "Service"
+metadata:
+  name: {{ include "spider.fullname" . }}-storage
+  labels:
+    {{- include "spider.labels" . | nindent 4 }}
+    app.kubernetes.io/component: "storage"
+spec:
+  selector:
+    {{- include "spider.selectorLabels" . | nindent 4 }}
+    app.kubernetes.io/component: "storage"
+  ports:
+    - name: "grpc"
+      port: {{ .Values.spiderConfig.storage_endpoint.port }}
+      targetPort: "grpc"
diff --git a/tools/deployment/spider-helm/values.yaml b/tools/deployment/spider-helm/values.yaml
index 8b137891..898e8c83 100644
--- a/tools/deployment/spider-helm/values.yaml
+++ b/tools/deployment/spider-helm/values.yaml
@@ -1 +1,47 @@
+nameOverride: ""
+fullnameOverride: ""
 
+image:
+  storage:
+    repository: "ghcr.io/y-scope/spider/storage"
+    pullPolicy: "Always"
+    tag: "main"
+  mariadb:
+    repository: "mariadb"
+    pullPolicy: "Always"
+    tag: "10.11.16"
+
+spiderConfig:
+  # List of third-party services bundled (deployed) as part of the chart.
+  # Remove a service from this list to use an external instance instead, and configure its host/port
+  # accordingly in the service-specific sections below.
+  bundled:
+    - "database"
+
+  database:
+    # Host and port for the database service. When "database" is in `bundled`, the host is
+    # automatically set to the bundled service name (ignored). When external, set these to the
+    # external service's address.
+    host: "127.0.0.1"
+    port: 3306
+    username: "spider-user"
+    password: "spider-password"
+    root_password: "spider-root-password"
+    name: "spider-db"
+
+  storage_endpoint:
+    port: 50051
+
+  storage:
+    max_connections: 64
+    # task_instance_pool_config:
+    #   execution_manager_stale_cutoff_sec: 30
+    #   gc_interval_sec: 5
+    #   message_channel_capacity: 1024
+    # job_cache_gc_config:
+    #   terminated_job_retention_sec: 300
+    #   gc_interval_sec: 10
+    ready_queue_config:
+      task_capacity: 1048576
+      commit_capacity: 256
+      cleanup_capacity: 256

From 67060661633ca50bcedb6665858add17d0be8294 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <60459812+20001020ycx@users.noreply.github.com>
Date: Mon, 13 Jul 2026 09:58:59 -0700
Subject: [PATCH 02/11] Apply suggestions from code review

Co-authored-by: Junhao Liao <junhao@junhao.ca>
---
 tools/deployment/spider-helm/templates/_helpers.tpl | 12 +++++-------
 1 file changed, 5 insertions(+), 7 deletions(-)

diff --git a/tools/deployment/spider-helm/templates/_helpers.tpl b/tools/deployment/spider-helm/templates/_helpers.tpl
index e2773ae0..b338bf0f 100644
--- a/tools/deployment/spider-helm/templates/_helpers.tpl
+++ b/tools/deployment/spider-helm/templates/_helpers.tpl
@@ -22,9 +22,9 @@ release name already contains the chart name it is used as-is.
 {{- .Release.Name | trunc 63 | trimSuffix "-" }}
 {{- else }}
 {{- printf "%s-%s" .Release.Name $name | trunc 63 | trimSuffix "-" }}
-{{- end }}
-{{- end }}
-{{- end }}
+{{- end }}{{/* if contains $name .Release.Name */}}
+{{- end }}{{/* if .Values.fullnameOverride */}}
+{{- end }}{{/* define "spider.fullname" */}}
 
 {{/*
 Creates chart name and version as used by the chart label.
@@ -99,8 +99,7 @@ failureThreshold: 3
 {{- end }}
 
 {{/*
-Gets the database host. When "database" is bundled, this is the in-cluster MariaDB Service; when not
-bundled, it is the external `spiderConfig.database.host`.
+Gets the bundled MariaDB Service host or external `spiderConfig.database.host`.
 
 @param {object} . Root template context
 @return {string} The database host
@@ -114,8 +113,7 @@ bundled, it is the external `spiderConfig.database.host`.
 {{- end }}
 
 {{/*
-Gets the database port. When "database" is bundled, this is 3306 (the bundled MariaDB's port);
-otherwise it is the external `spiderConfig.database.port`.
+Gets the bundled MariaDB port or external `spiderConfig.database.port`.
 
 @param {object} . Root template context
 @return {string} The database port

From 0505d992aaa1440ded050a75b3283105c943a1c8 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Mon, 13 Jul 2026 13:27:50 -0700
Subject: [PATCH 03/11] fix(helm-chart): Reserve suffix space in component
 names for the 63-char limit.

`spider.fullname` truncates to 63, but appending `-storage`/`-config`/
`-database` afterward can exceed Kubernetes' 63-character name limit for long
release names. Introduce `spider.componentFullname`, which trims the base to
`63 - len(suffix)` before appending, and use it for all resource names,
`serviceName`, Secret/ConfigMap references, and `databaseHost`.
---
 .../spider-helm/templates/_helpers.tpl           | 16 +++++++++++++++-
 .../spider-helm/templates/configmap.yaml         |  2 +-
 .../spider-helm/templates/database-secret.yaml   |  2 +-
 .../spider-helm/templates/database-service.yaml  |  2 +-
 .../templates/database-statefulset.yaml          | 10 +++++-----
 .../templates/storage-deployment.yaml            |  4 ++--
 .../spider-helm/templates/storage-service.yaml   |  2 +-
 7 files changed, 26 insertions(+), 12 deletions(-)

diff --git a/tools/deployment/spider-helm/templates/_helpers.tpl b/tools/deployment/spider-helm/templates/_helpers.tpl
index b338bf0f..6dd9dc16 100644
--- a/tools/deployment/spider-helm/templates/_helpers.tpl
+++ b/tools/deployment/spider-helm/templates/_helpers.tpl
@@ -26,6 +26,20 @@ release name already contains the chart name it is used as-is.
 {{- end }}{{/* if .Values.fullnameOverride */}}
 {{- end }}{{/* define "spider.fullname" */}}
 
+{{/*
+Creates a fully qualified component name while preserving its suffix within the 63-character limit.
+
+@param {object} root Root template context (required)
+@param {string} component Component name suffix (required)
+@return {string} The fully qualified component name
+*/}}
+{{- define "spider.componentFullname" -}}
+{{- $suffix := printf "-%s" .component -}}
+{{- $maxBaseLength := sub 63 (len $suffix) | int -}}
+{{- $base := include "spider.fullname" .root | trunc $maxBaseLength | trimSuffix "-" -}}
+{{- printf "%s%s" $base $suffix -}}
+{{- end }}
+
 {{/*
 Creates chart name and version as used by the chart label.
 
@@ -106,7 +120,7 @@ Gets the bundled MariaDB Service host or external `spiderConfig.database.host`.
 */}}
 {{- define "spider.databaseHost" -}}
 {{- if has "database" .Values.spiderConfig.bundled -}}
-{{- printf "%s-database" (include "spider.fullname" .) -}}
+{{- include "spider.componentFullname" (dict "root" . "component" "database") -}}
 {{- else -}}
 {{- .Values.spiderConfig.database.host -}}
 {{- end -}}
diff --git a/tools/deployment/spider-helm/templates/configmap.yaml b/tools/deployment/spider-helm/templates/configmap.yaml
index 98a4d276..1fd37720 100644
--- a/tools/deployment/spider-helm/templates/configmap.yaml
+++ b/tools/deployment/spider-helm/templates/configmap.yaml
@@ -1,7 +1,7 @@
 apiVersion: "v1"
 kind: "ConfigMap"
 metadata:
-  name: {{ include "spider.fullname" . }}-config
+  name: {{ include "spider.componentFullname" (dict "root" . "component" "config") }}
   labels:
     {{- include "spider.labels" . | nindent 4 }}
 data:
diff --git a/tools/deployment/spider-helm/templates/database-secret.yaml b/tools/deployment/spider-helm/templates/database-secret.yaml
index fde491cd..69ae1749 100644
--- a/tools/deployment/spider-helm/templates/database-secret.yaml
+++ b/tools/deployment/spider-helm/templates/database-secret.yaml
@@ -2,7 +2,7 @@
 apiVersion: "v1"
 kind: "Secret"
 metadata:
-  name: {{ include "spider.fullname" . }}-database
+  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
   labels:
     {{- include "spider.labels" . | nindent 4 }}
     app.kubernetes.io/component: "database"
diff --git a/tools/deployment/spider-helm/templates/database-service.yaml b/tools/deployment/spider-helm/templates/database-service.yaml
index eb086897..98bbab3b 100644
--- a/tools/deployment/spider-helm/templates/database-service.yaml
+++ b/tools/deployment/spider-helm/templates/database-service.yaml
@@ -2,7 +2,7 @@
 apiVersion: "v1"
 kind: "Service"
 metadata:
-  name: {{ include "spider.fullname" . }}-database
+  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
   labels:
     {{- include "spider.labels" . | nindent 4 }}
     app.kubernetes.io/component: "database"
diff --git a/tools/deployment/spider-helm/templates/database-statefulset.yaml b/tools/deployment/spider-helm/templates/database-statefulset.yaml
index 388bd953..c3a69365 100644
--- a/tools/deployment/spider-helm/templates/database-statefulset.yaml
+++ b/tools/deployment/spider-helm/templates/database-statefulset.yaml
@@ -2,12 +2,12 @@
 apiVersion: "apps/v1"
 kind: "StatefulSet"
 metadata:
-  name: {{ include "spider.fullname" . }}-database
+  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
   labels:
     {{- include "spider.labels" . | nindent 4 }}
     app.kubernetes.io/component: "database"
 spec:
-  serviceName: {{ include "spider.fullname" . }}-database
+  serviceName: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
   replicas: 1
   selector:
     matchLabels:
@@ -29,17 +29,17 @@ spec:
             - name: "MYSQL_USER"
               valueFrom:
                 secretKeyRef:
-                  name: {{ include "spider.fullname" . }}-database
+                  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
                   key: "username"
             - name: "MYSQL_PASSWORD"
               valueFrom:
                 secretKeyRef:
-                  name: {{ include "spider.fullname" . }}-database
+                  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
                   key: "password"
             - name: "MYSQL_ROOT_PASSWORD"
               valueFrom:
                 secretKeyRef:
-                  name: {{ include "spider.fullname" . }}-database
+                  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
                   key: "root_password"
           ports:
             - name: "database"
diff --git a/tools/deployment/spider-helm/templates/storage-deployment.yaml b/tools/deployment/spider-helm/templates/storage-deployment.yaml
index 66535855..be65e762 100644
--- a/tools/deployment/spider-helm/templates/storage-deployment.yaml
+++ b/tools/deployment/spider-helm/templates/storage-deployment.yaml
@@ -1,7 +1,7 @@
 apiVersion: "apps/v1"
 kind: "Deployment"
 metadata:
-  name: {{ include "spider.fullname" . }}-storage
+  name: {{ include "spider.componentFullname" (dict "root" . "component" "storage") }}
   labels:
     {{- include "spider.labels" . | nindent 4 }}
     app.kubernetes.io/component: "storage"
@@ -40,4 +40,4 @@ spec:
       volumes:
         - name: "config"
           configMap:
-            name: {{ include "spider.fullname" . }}-config
+            name: {{ include "spider.componentFullname" (dict "root" . "component" "config") }}
diff --git a/tools/deployment/spider-helm/templates/storage-service.yaml b/tools/deployment/spider-helm/templates/storage-service.yaml
index ca9c1332..57df9d25 100644
--- a/tools/deployment/spider-helm/templates/storage-service.yaml
+++ b/tools/deployment/spider-helm/templates/storage-service.yaml
@@ -1,7 +1,7 @@
 apiVersion: "v1"
 kind: "Service"
 metadata:
-  name: {{ include "spider.fullname" . }}-storage
+  name: {{ include "spider.componentFullname" (dict "root" . "component" "storage") }}
   labels:
     {{- include "spider.labels" . | nindent 4 }}
     app.kubernetes.io/component: "storage"

From d1c039b389e43f80502a2bacc4d3a20304c105cf Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Wed, 15 Jul 2026 09:04:49 -0700
Subject: [PATCH 04/11] feat(helm-chart): Inject storage DB credentials from a
 Secret via environment variables.

Stop rendering the database username/password into the storage ConfigMap.
Storage now reads them from `SPIDER_STORAGE_DB_USERNAME`/`SPIDER_STORAGE_DB_PASSWORD`
(spider-storage #397), injected via `secretKeyRef` from the database Secret. The
Secret now renders in both bundled and external modes (`root_password` stays
bundled-only) so the credentials are available regardless of deployment mode.
---
 tools/deployment/spider-helm/templates/configmap.yaml |  2 --
 .../spider-helm/templates/database-secret.yaml        |  4 ++--
 .../spider-helm/templates/storage-deployment.yaml     | 11 +++++++++++
 3 files changed, 13 insertions(+), 4 deletions(-)

diff --git a/tools/deployment/spider-helm/templates/configmap.yaml b/tools/deployment/spider-helm/templates/configmap.yaml
index 1fd37720..a6860495 100644
--- a/tools/deployment/spider-helm/templates/configmap.yaml
+++ b/tools/deployment/spider-helm/templates/configmap.yaml
@@ -13,8 +13,6 @@ data:
         host: {{ include "spider.databaseHost" . | quote }}
         port: {{ include "spider.databasePort" . }}
         name: {{ .Values.spiderConfig.database.name | quote }}
-        username: {{ .Values.spiderConfig.database.username | quote }}
-        password: {{ .Values.spiderConfig.database.password | quote }}
         max_connections: {{ .Values.spiderConfig.storage.max_connections }}
       {{- with omit .Values.spiderConfig.storage "max_connections" }}
       {{- toYaml . | nindent 6 }}
diff --git a/tools/deployment/spider-helm/templates/database-secret.yaml b/tools/deployment/spider-helm/templates/database-secret.yaml
index 69ae1749..5d34650c 100644
--- a/tools/deployment/spider-helm/templates/database-secret.yaml
+++ b/tools/deployment/spider-helm/templates/database-secret.yaml
@@ -1,4 +1,3 @@
-{{- if has "database" .Values.spiderConfig.bundled }}
 apiVersion: "v1"
 kind: "Secret"
 metadata:
@@ -10,5 +9,6 @@ type: "Opaque"
 stringData:
   username: {{ .Values.spiderConfig.database.username | quote }}
   password: {{ .Values.spiderConfig.database.password | quote }}
+  {{- if has "database" .Values.spiderConfig.bundled }}
   root_password: {{ .Values.spiderConfig.database.root_password | quote }}
-{{- end }}
+  {{- end }}
diff --git a/tools/deployment/spider-helm/templates/storage-deployment.yaml b/tools/deployment/spider-helm/templates/storage-deployment.yaml
index be65e762..c6a72c8b 100644
--- a/tools/deployment/spider-helm/templates/storage-deployment.yaml
+++ b/tools/deployment/spider-helm/templates/storage-deployment.yaml
@@ -22,6 +22,17 @@ spec:
           image: {{ include "spider.imageRef" (dict "root" . "component" "storage") | quote }}
           imagePullPolicy: {{ .Values.image.storage.pullPolicy | quote }}
           command: ["spider-storage", "--config", "/etc/spider/storage.yaml"]
+          env:
+            - name: "SPIDER_STORAGE_DB_USERNAME"
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
+                  key: "username"
+            - name: "SPIDER_STORAGE_DB_PASSWORD"
+              valueFrom:
+                secretKeyRef:
+                  name: {{ include "spider.componentFullname" (dict "root" . "component" "database") }}
+                  key: "password"
           ports:
             - name: "grpc"
               containerPort: {{ .Values.spiderConfig.storage_endpoint.port }}

From 02a27f56373c13d831802e4fac0327a3772907c3 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Wed, 15 Jul 2026 10:08:11 -0700
Subject: [PATCH 05/11] refactor(helm-chart): Rename the `image.mariadb` key to
 `image.database` to keep it DB-type agnostic.

---
 tools/deployment/spider-helm/templates/_helpers.tpl         | 6 +++---
 .../spider-helm/templates/database-statefulset.yaml         | 4 ++--
 tools/deployment/spider-helm/values.yaml                    | 2 +-
 3 files changed, 6 insertions(+), 6 deletions(-)

diff --git a/tools/deployment/spider-helm/templates/_helpers.tpl b/tools/deployment/spider-helm/templates/_helpers.tpl
index 6dd9dc16..354a83c6 100644
--- a/tools/deployment/spider-helm/templates/_helpers.tpl
+++ b/tools/deployment/spider-helm/templates/_helpers.tpl
@@ -79,7 +79,7 @@ Creates a container image reference from `.Values.image.<component>`.
 The tag defaults to the chart's appVersion when the component omits it.
 
 @param {object} root Root template context (required)
-@param {string} component Key under `.Values.image` (e.g. "storage", "mariadb")
+@param {string} component Key under `.Values.image` (e.g. "storage", "database")
 @return {string} Full image reference (repository:tag)
 */}}
 {{- define "spider.imageRef" -}}
@@ -113,7 +113,7 @@ failureThreshold: 3
 {{- end }}
 
 {{/*
-Gets the bundled MariaDB Service host or external `spiderConfig.database.host`.
+Gets the bundled database Service host or external `spiderConfig.database.host`.
 
 @param {object} . Root template context
 @return {string} The database host
@@ -127,7 +127,7 @@ Gets the bundled MariaDB Service host or external `spiderConfig.database.host`.
 {{- end }}
 
 {{/*
-Gets the bundled MariaDB port or external `spiderConfig.database.port`.
+Gets the bundled database port or external `spiderConfig.database.port`.
 
 @param {object} . Root template context
 @return {string} The database port
diff --git a/tools/deployment/spider-helm/templates/database-statefulset.yaml b/tools/deployment/spider-helm/templates/database-statefulset.yaml
index c3a69365..60b09efc 100644
--- a/tools/deployment/spider-helm/templates/database-statefulset.yaml
+++ b/tools/deployment/spider-helm/templates/database-statefulset.yaml
@@ -21,8 +21,8 @@ spec:
     spec:
       containers:
         - name: "database"
-          image: {{ include "spider.imageRef" (dict "root" . "component" "mariadb") | quote }}
-          imagePullPolicy: {{ .Values.image.mariadb.pullPolicy | quote }}
+          image: {{ include "spider.imageRef" (dict "root" . "component" "database") | quote }}
+          imagePullPolicy: {{ .Values.image.database.pullPolicy | quote }}
           env:
             - name: "MYSQL_DATABASE"
               value: {{ .Values.spiderConfig.database.name | quote }}
diff --git a/tools/deployment/spider-helm/values.yaml b/tools/deployment/spider-helm/values.yaml
index 898e8c83..04448fb9 100644
--- a/tools/deployment/spider-helm/values.yaml
+++ b/tools/deployment/spider-helm/values.yaml
@@ -6,7 +6,7 @@ image:
     repository: "ghcr.io/y-scope/spider/storage"
     pullPolicy: "Always"
     tag: "main"
-  mariadb:
+  database:
     repository: "mariadb"
     pullPolicy: "Always"
     tag: "10.11.16"

From bcd72232d081733a56eac630b927752f2f3ba876 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <60459812+20001020ycx@users.noreply.github.com>
Date: Mon, 13 Jul 2026 17:08:56 -0700
Subject: [PATCH 06/11] Update
 tools/deployment/spider-helm/templates/_helpers.tpl

Co-authored-by: Junhao Liao <junhao@junhao.ca>
---
 .../deployment/spider-helm/templates/_helpers.tpl  | 14 +++++++++-----
 1 file changed, 9 insertions(+), 5 deletions(-)

diff --git a/tools/deployment/spider-helm/templates/_helpers.tpl b/tools/deployment/spider-helm/templates/_helpers.tpl
index 354a83c6..c2f75c79 100644
--- a/tools/deployment/spider-helm/templates/_helpers.tpl
+++ b/tools/deployment/spider-helm/templates/_helpers.tpl
@@ -74,18 +74,22 @@ app.kubernetes.io/instance: {{ .Release.Name }}
 {{- end }}
 
 {{/*
-Creates a container image reference from `.Values.image.<component>`.
+Creates a container image reference from .Values.image.
 
-The tag defaults to the chart's appVersion when the component omits it.
+Renders repository@digest when "digest" is set; otherwise, requires "tag" and renders repository:tag.
 
 @param {object} root Root template context (required)
-@param {string} component Key under `.Values.image` (e.g. "storage", "database")
-@return {string} Full image reference (repository:tag)
+@param {string} component Key under .Values.image (e.g., "storage", "database")
+@return {string} Full image reference (repository@digest or repository:tag)
 */}}
 {{- define "spider.imageRef" -}}
 {{- $img := index .root.Values.image .component -}}
-{{- $tag := $img.tag | default .root.Chart.AppVersion -}}
+{{- if $img.digest -}}
+{{- printf "%s@%s" $img.repository $img.digest -}}
+{{- else -}}
+{{- $tag := required (printf "image.%s.tag is required" .component) $img.tag -}}
 {{- printf "%s:%s" $img.repository $tag -}}
+{{- end -}}
 {{- end }}
 
 {{/*

From b8bc2c1af4b8cb6b597235c1566b4b9b8d444916 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Wed, 15 Jul 2026 10:24:02 -0700
Subject: [PATCH 07/11] chore(helm-chart): Bump the chart version to 0.1.1 for
 the version-increment lint.

---
 tools/deployment/spider-helm/Chart.yaml | 2 +-
 1 file changed, 1 insertion(+), 1 deletion(-)

diff --git a/tools/deployment/spider-helm/Chart.yaml b/tools/deployment/spider-helm/Chart.yaml
index 9e83a862..ee7b3008 100644
--- a/tools/deployment/spider-helm/Chart.yaml
+++ b/tools/deployment/spider-helm/Chart.yaml
@@ -2,7 +2,7 @@ apiVersion: "v2"
 name: "spider"
 description: "A Helm chart for the Spider Huntsman deployment"
 type: "application"
-version: "0.1.0"
+version: "0.1.1"
 appVersion: "0.1.0"
 home: "https://github.com/y-scope/spider"
 sources: ["https://github.com/y-scope/spider"]

From 8b6d2a5c3cff1912b983dc5db666545082be2fd5 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Thu, 16 Jul 2026 13:10:29 -0700
Subject: [PATCH 08/11] fix(helm-chart): Mount only storage.yaml into the
 storage pod via subPath.

---
 tools/deployment/spider-helm/templates/storage-deployment.yaml | 3 ++-
 1 file changed, 2 insertions(+), 1 deletion(-)

diff --git a/tools/deployment/spider-helm/templates/storage-deployment.yaml b/tools/deployment/spider-helm/templates/storage-deployment.yaml
index c6a72c8b..f88037ea 100644
--- a/tools/deployment/spider-helm/templates/storage-deployment.yaml
+++ b/tools/deployment/spider-helm/templates/storage-deployment.yaml
@@ -38,7 +38,8 @@ spec:
               containerPort: {{ .Values.spiderConfig.storage_endpoint.port }}
           volumeMounts:
             - name: "config"
-              mountPath: "/etc/spider"
+              mountPath: "/etc/spider/storage.yaml"
+              subPath: "storage.yaml"
               readOnly: true
           readinessProbe:
             {{- include "spider.readinessProbeTimings" . | nindent 12 }}

From fdd7f3105fe821e52fb54c8ca7831b697947d8ad Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Thu, 16 Jul 2026 13:14:41 -0700
Subject: [PATCH 09/11] refactor(helm-chart): Move DB `max_connections` under
 `spiderConfig.database`.

---
 tools/deployment/spider-helm/templates/configmap.yaml | 4 ++--
 tools/deployment/spider-helm/values.yaml              | 2 +-
 2 files changed, 3 insertions(+), 3 deletions(-)

diff --git a/tools/deployment/spider-helm/templates/configmap.yaml b/tools/deployment/spider-helm/templates/configmap.yaml
index a6860495..dc864fd8 100644
--- a/tools/deployment/spider-helm/templates/configmap.yaml
+++ b/tools/deployment/spider-helm/templates/configmap.yaml
@@ -13,7 +13,7 @@ data:
         host: {{ include "spider.databaseHost" . | quote }}
         port: {{ include "spider.databasePort" . }}
         name: {{ .Values.spiderConfig.database.name | quote }}
-        max_connections: {{ .Values.spiderConfig.storage.max_connections }}
-      {{- with omit .Values.spiderConfig.storage "max_connections" }}
+        max_connections: {{ .Values.spiderConfig.database.max_connections }}
+      {{- with .Values.spiderConfig.storage }}
       {{- toYaml . | nindent 6 }}
       {{- end }}
diff --git a/tools/deployment/spider-helm/values.yaml b/tools/deployment/spider-helm/values.yaml
index 04448fb9..3b2a6487 100644
--- a/tools/deployment/spider-helm/values.yaml
+++ b/tools/deployment/spider-helm/values.yaml
@@ -28,12 +28,12 @@ spiderConfig:
     password: "spider-password"
     root_password: "spider-root-password"
     name: "spider-db"
+    max_connections: 64
 
   storage_endpoint:
     port: 50051
 
   storage:
-    max_connections: 64
     # task_instance_pool_config:
     #   execution_manager_stale_cutoff_sec: 30
     #   gc_interval_sec: 5

From 119e176ffc9bd75d090b7a64de755fde77699439 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Thu, 16 Jul 2026 13:30:51 -0700
Subject: [PATCH 10/11] refactor(helm-chart): Move the storage port under
 `spiderConfig.storage` and alphabetize config keys.

---
 .../spider-helm/templates/configmap.yaml      |  8 ++--
 .../templates/storage-deployment.yaml         |  2 +-
 .../templates/storage-service.yaml            |  2 +-
 tools/deployment/spider-helm/values.yaml      | 47 +++++++++----------
 4 files changed, 29 insertions(+), 30 deletions(-)

diff --git a/tools/deployment/spider-helm/templates/configmap.yaml b/tools/deployment/spider-helm/templates/configmap.yaml
index dc864fd8..7e0aa0a6 100644
--- a/tools/deployment/spider-helm/templates/configmap.yaml
+++ b/tools/deployment/spider-helm/templates/configmap.yaml
@@ -7,13 +7,13 @@ metadata:
 data:
   storage.yaml: |
     host: "0.0.0.0"
-    port: {{ .Values.spiderConfig.storage_endpoint.port }}
+    port: {{ .Values.spiderConfig.storage.port }}
     runtime:
       db_config:
         host: {{ include "spider.databaseHost" . | quote }}
-        port: {{ include "spider.databasePort" . }}
-        name: {{ .Values.spiderConfig.database.name | quote }}
         max_connections: {{ .Values.spiderConfig.database.max_connections }}
-      {{- with .Values.spiderConfig.storage }}
+        name: {{ .Values.spiderConfig.database.name | quote }}
+        port: {{ include "spider.databasePort" . }}
+      {{- with .Values.spiderConfig.storage.runtime }}
       {{- toYaml . | nindent 6 }}
       {{- end }}
diff --git a/tools/deployment/spider-helm/templates/storage-deployment.yaml b/tools/deployment/spider-helm/templates/storage-deployment.yaml
index f88037ea..5bc1b635 100644
--- a/tools/deployment/spider-helm/templates/storage-deployment.yaml
+++ b/tools/deployment/spider-helm/templates/storage-deployment.yaml
@@ -35,7 +35,7 @@ spec:
                   key: "password"
           ports:
             - name: "grpc"
-              containerPort: {{ .Values.spiderConfig.storage_endpoint.port }}
+              containerPort: {{ .Values.spiderConfig.storage.port }}
           volumeMounts:
             - name: "config"
               mountPath: "/etc/spider/storage.yaml"
diff --git a/tools/deployment/spider-helm/templates/storage-service.yaml b/tools/deployment/spider-helm/templates/storage-service.yaml
index 57df9d25..a853f94d 100644
--- a/tools/deployment/spider-helm/templates/storage-service.yaml
+++ b/tools/deployment/spider-helm/templates/storage-service.yaml
@@ -11,5 +11,5 @@ spec:
     app.kubernetes.io/component: "storage"
   ports:
     - name: "grpc"
-      port: {{ .Values.spiderConfig.storage_endpoint.port }}
+      port: {{ .Values.spiderConfig.storage.port }}
       targetPort: "grpc"
diff --git a/tools/deployment/spider-helm/values.yaml b/tools/deployment/spider-helm/values.yaml
index 3b2a6487..2383019a 100644
--- a/tools/deployment/spider-helm/values.yaml
+++ b/tools/deployment/spider-helm/values.yaml
@@ -1,15 +1,15 @@
-nameOverride: ""
 fullnameOverride: ""
+nameOverride: ""
 
 image:
-  storage:
-    repository: "ghcr.io/y-scope/spider/storage"
-    pullPolicy: "Always"
-    tag: "main"
   database:
-    repository: "mariadb"
     pullPolicy: "Always"
+    repository: "mariadb"
     tag: "10.11.16"
+  storage:
+    pullPolicy: "Always"
+    repository: "ghcr.io/y-scope/spider/storage"
+    tag: "main"
 
 spiderConfig:
   # List of third-party services bundled (deployed) as part of the chart.
@@ -23,25 +23,24 @@ spiderConfig:
     # automatically set to the bundled service name (ignored). When external, set these to the
     # external service's address.
     host: "127.0.0.1"
-    port: 3306
-    username: "spider-user"
+    max_connections: 64
+    name: "spider-db"
     password: "spider-password"
+    port: 3306
     root_password: "spider-root-password"
-    name: "spider-db"
-    max_connections: 64
-
-  storage_endpoint:
-    port: 50051
+    username: "spider-user"
 
   storage:
-    # task_instance_pool_config:
-    #   execution_manager_stale_cutoff_sec: 30
-    #   gc_interval_sec: 5
-    #   message_channel_capacity: 1024
-    # job_cache_gc_config:
-    #   terminated_job_retention_sec: 300
-    #   gc_interval_sec: 10
-    ready_queue_config:
-      task_capacity: 1048576
-      commit_capacity: 256
-      cleanup_capacity: 256
+    port: 50051
+    runtime:
+      # job_cache_gc_config:
+      #   gc_interval_sec: 10
+      #   terminated_job_retention_sec: 300
+      ready_queue_config:
+        cleanup_capacity: 256
+        commit_capacity: 256
+        task_capacity: 1048576
+      # task_instance_pool_config:
+      #   execution_manager_stale_cutoff_sec: 30
+      #   gc_interval_sec: 5
+      #   message_channel_capacity: 1024

From e973a30274ecfb968bb2e9e6b6ea2f1949bf26c1 Mon Sep 17 00:00:00 2001
From: ChenXing Yang <20001020ycx@gmail.com>
Date: Thu, 16 Jul 2026 13:38:27 -0700
Subject: [PATCH 11/11] docs(helm-chart): Drop commented-out runtime config
 from values.yaml.

---
 tools/deployment/spider-helm/values.yaml | 7 -------
 1 file changed, 7 deletions(-)

diff --git a/tools/deployment/spider-helm/values.yaml b/tools/deployment/spider-helm/values.yaml
index 2383019a..5d47931a 100644
--- a/tools/deployment/spider-helm/values.yaml
+++ b/tools/deployment/spider-helm/values.yaml
@@ -33,14 +33,7 @@ spiderConfig:
   storage:
     port: 50051
     runtime:
-      # job_cache_gc_config:
-      #   gc_interval_sec: 10
-      #   terminated_job_retention_sec: 300
       ready_queue_config:
         cleanup_capacity: 256
         commit_capacity: 256
         task_capacity: 1048576
-      # task_instance_pool_config:
-      #   execution_manager_stale_cutoff_sec: 30
-      #   gc_interval_sec: 5
-      #   message_channel_capacity: 1024