Closure handling and varnish example

Author: attilaedelenyi

charts/ontoserver-extras/README.md

@@ -19,7 +19,26 @@ data:
         .between_bytes_timeout = 60s;
     }
 
+    {{- if .Values.varnish.closureBackend }}
+    # Dedicated backend for $closure — stateful operation requiring sticky routing to one instance
+    backend closure {
+        .host = "{{ .Values.varnish.closureBackend }}";
+        .port = "80";
+        .connect_timeout = 60s;
+        .first_byte_timeout = 300s;
+        .between_bytes_timeout = 60s;
+    }
+    {{- end }}
+
     sub vcl_recv {
+        {{- if .Values.varnish.closureBackend }}
+        # Route $closure to a dedicated backend — $closure maintains per-session state
+        # and must always hit the same Ontoserver instance.
+        if (req.url ~ "^/fhir/ConceptMap/\$closure") {
+            set req.backend_hint = closure;
+            return (pass);
+        }
+        {{- end }}
         {{- if .Values.varnish.opentelemetry.enabled }}
         set req.http.X-Start-Time-Sec = std.time2real(now, 0.0);
 
@@ -140,6 +159,12 @@ data:
     {{- end }}
 
     sub vcl_backend_response {
+        {{- if gt (int .Values.varnish.graceSeconds) 0 }}
+        # Serve stale content for graceSeconds if the backend is unavailable
+        # (e.g. during a rolling update of the Ontoserver StatefulSet)
+        set beresp.grace = {{ .Values.varnish.graceSeconds }}s;
+        {{- end }}
+
         if (beresp.status == 200) {
             # Ignore any Cache-Control/Pragma no-cache directives from the origin
             # (mirrors Azure CDN "Ignore Origin No-Cache = 200" rule)

charts/ontoserver-extras/templates/varnish-configmap.yaml

@@ -7,7 +7,7 @@ metadata:
     {{- include "ontoserver-extras.labels" . | nindent 4 }}
     {{- include "ontoserver-extras.varnish.selectorLabels" . | nindent 4 }}
 spec:
-  replicas: 1
+  replicas: {{ .Values.varnish.replicas }}
   selector:
     matchLabels:
       {{- include "ontoserver-extras.varnish.selectorLabels" . | nindent 6 }}

charts/ontoserver-extras/templates/varnish-deployment.yaml

@@ -76,6 +76,32 @@ tests:
           path: data["default.vcl"]
           pattern: 'beresp\.ttl = 2m'
 
+  - it: includes grace period by default
+    set:
+      varnish.enabled: true
+    asserts:
+      - matchRegex:
+          path: data["default.vcl"]
+          pattern: 'beresp\.grace = 30s'
+
+  - it: uses custom grace period from values
+    set:
+      varnish.enabled: true
+      varnish.graceSeconds: 60
+    asserts:
+      - matchRegex:
+          path: data["default.vcl"]
+          pattern: 'beresp\.grace = 60s'
+
+  - it: omits grace period when graceSeconds is 0
+    set:
+      varnish.enabled: true
+      varnish.graceSeconds: 0
+    asserts:
+      - notMatchRegex:
+          path: data["default.vcl"]
+          pattern: 'beresp\.grace'
+
   - it: includes opentelemetry VCL blocks when otel enabled
     set:
       varnish.enabled: true
@@ -93,3 +119,38 @@ tests:
       - notMatchRegex:
           path: data["default.vcl"]
           pattern: 'OTEL_SPAN'
+
+  - it: omits closure backend and routing when closureBackend not set
+    set:
+      varnish.enabled: true
+    asserts:
+      - notMatchRegex:
+          path: data["default.vcl"]
+          pattern: 'backend closure'
+      - notMatchRegex:
+          path: data["default.vcl"]
+          pattern: '\$closure'
+
+  - it: adds closure backend block when closureBackend is set
+    set:
+      varnish.enabled: true
+      varnish.closureBackend: "my-release-statefulset-0.my-release-ontoserver-headless"
+    asserts:
+      - matchRegex:
+          path: data["default.vcl"]
+          pattern: 'backend closure'
+      - matchRegex:
+          path: data["default.vcl"]
+          pattern: '\.host = "my-release-statefulset-0\.my-release-ontoserver-headless"'
+
+  - it: routes closure requests to closure backend and passes through
+    set:
+      varnish.enabled: true
+      varnish.closureBackend: "my-release-statefulset-0.my-release-ontoserver-headless"
+    asserts:
+      - matchRegex:
+          path: data["default.vcl"]
+          pattern: 'req\.backend_hint = closure'
+      - matchRegex:
+          path: data["default.vcl"]
+          pattern: 'ConceptMap/\\\$closure'

charts/ontoserver-extras/tests/varnish_configmap_test.yaml

@@ -121,6 +121,23 @@ tests:
             name: trace-pipe
             emptyDir: {}
 
+  - it: defaults to 1 replica
+    set:
+      varnish.enabled: true
+    asserts:
+      - equal:
+          path: spec.replicas
+          value: 1
+
+  - it: uses replicas from values
+    set:
+      varnish.enabled: true
+      varnish.replicas: 2
+    asserts:
+      - equal:
+          path: spec.replicas
+          value: 2
+
   - it: sets tolerations when provided
     set:
       varnish.enabled: true

charts/ontoserver-extras/tests/varnish_deployment_test.yaml

@@ -22,6 +22,11 @@
           "default": "",
           "description": "Override the Kubernetes service name Varnish proxies to. Defaults to RELEASE-ontoserver-service (the ontoserver chart's service). Only needed when the extras chart and ontoserver chart have different release names."
         },
+        "closureBackend": {
+          "type": "string",
+          "default": "",
+          "description": "Kubernetes hostname for the $closure operation backend. The $closure FHIR operation is stateful — set to a stable pod hostname (e.g. RELEASE-statefulset-0.RELEASE-ontoserver-headless) for scaled deployments. Empty string disables dedicated $closure routing."
+        },
         "metrics": {
           "type": "object",
           "description": "Prometheus metrics exporter sidecar",
@@ -74,6 +79,18 @@
             }
           }
         },
+        "replicas": {
+          "type": "integer",
+          "default": 1,
+          "minimum": 0,
+          "description": "Number of Varnish pod replicas"
+        },
+        "graceSeconds": {
+          "type": "integer",
+          "default": 30,
+          "minimum": 0,
+          "description": "Seconds to serve stale cached content when the backend is unavailable"
+        },
         "image": {
           "type": "string",
           "default": "varnish:7.7.1",

charts/ontoserver-extras/values.schema.json

@@ -4,6 +4,12 @@ varnish:
   enabled: false
   ## @param varnish.backendServiceName                        Kubernetes service name for the Varnish backend (defaults to RELEASE-ontoserver-service)
   backendServiceName: ""
+  ## @param varnish.closureBackend                            Kubernetes hostname for the $closure operation backend. The $closure FHIR operation is stateful — it requires all requests to hit the same instance. Set to a stable pod hostname (e.g. RELEASE-statefulset-0.RELEASE-ontoserver-headless) when using a scaled deployment. Empty string disables dedicated $closure routing.
+  closureBackend: ""
+  ## @param varnish.replicas                                   Number of Varnish pod replicas. For a scaled Ontoserver deployment consider 2+ to avoid a single point of failure. Note: multiple replicas each maintain their own independent cache.
+  replicas: 1
+  ## @param varnish.graceSeconds                               Seconds to serve stale cached content when the backend is unavailable (e.g. during a rolling update). Set to 0 to disable grace mode.
+  graceSeconds: 30
   opentelemetry:
     ## @param varnish.opentelemetry.enabled                     Enable tracing VCL and sidecar containers (trace-converter + trace-forwarder)
     enabled: false

charts/ontoserver-extras/values.yaml

@@ -67,7 +67,7 @@ The recommended production topology separates content development from publicati
 
 **Development / local** — ephemeral storage with the sidecar PostgreSQL avoids cloud disk provisioning. The index is rebuilt from syndication feeds on each start, which is acceptable at small scale.
 
-> **`$closure` note:** The [`$closure` FHIR operation](https://www.hl7.org/fhir/conceptmap-operation-closure.html) is stateful. On a scaled read-only cluster it requires either sticky sessions (client-side routing) or a dedicated stateful instance alongside the cluster — the scaled cluster provides no built-in sticky session support.
+> **`$closure` routing:** The [`$closure` FHIR operation](https://www.hl7.org/fhir/conceptmap-operation-closure.html) is stateful — all requests for a given closure table must reach the same instance. For scaled StatefulSet deployments, the chart automatically creates a dedicated `RELEASE-ontoserver-pod0-service` that selects only pod-0, and routes `/fhir/ConceptMap/$closure` to it in both the Gateway HTTPRoute and Ingress — before the catchall `/` rule. This keeps `$closure` functional on a scaled cluster without requiring client-side sticky sessions. The routing is active whenever `deployment.kind: StatefulSet` and `deployment.type: scaled`, regardless of other settings.
 >
 > **Feeds must stay available:** New instances (after a pod is rescheduled or the cluster is scaled up) rebuild their local index from the syndication feeds that originally loaded the content. If those feeds become unavailable, new instances cannot complete startup and will not become ready.
 

charts/ontoserver/README.md

@@ -67,6 +67,20 @@ spec:
       name: {{ $.Release.Name }}-gw
   {{- end }}
   rules:
+    {{- if and (eq .Values.ontoserver.deployment.kind "StatefulSet") (eq .Values.ontoserver.deployment.type "scaled") }}
+    # Route $closure to a dedicated pod — this FHIR operation is stateful and requires
+    # all requests to always hit the same Ontoserver instance.
+    - backendRefs:
+        - group: ''
+          kind: Service
+          name: {{ .Release.Name }}-ontoserver-pod0-service
+          port: 80
+          weight: 1
+      matches:
+        - path:
+            type: PathPrefix
+            value: /fhir/ConceptMap/$closure
+    {{- end }}
     - backendRefs:
         - group: ''
           kind: Service

charts/ontoserver/templates/gateway.yaml

@@ -34,6 +34,17 @@ spec:
     - host: {{ . | quote }}
       http:
         paths:
+          {{- if and (eq $.Values.ontoserver.deployment.kind "StatefulSet") (eq $.Values.ontoserver.deployment.type "scaled") }}
+          # Route $closure to a dedicated pod — this FHIR operation is stateful and requires
+          # all requests to always hit the same Ontoserver instance.
+          - path: /fhir/ConceptMap/$closure
+            pathType: Prefix
+            backend:
+              service:
+                name: {{ $releaseName }}-ontoserver-pod0-service
+                port:
+                  number: 80
+          {{- end }}
           - path: /
             pathType: Prefix
             backend: