Helm Deployment¶

The deploy/helm/openmed-service chart deploys the OpenMed de-identification REST service on Kubernetes with separate liveness and readiness probes, a persistent model cache volume, and configurable service runtime settings. Its optional production Journey profile adds a pre-install/pre-upgrade migration gate, a worker Deployment, durable artifact storage, dependency-aware readiness, and a default-deny NetworkPolicy.

Install¶

Build and publish an OpenMed service image to a registry your cluster can pull, then install the chart with the matching image repository and tag:

helm upgrade --install openmed-service deploy/helm/openmed-service \
  --namespace openmed \
  --create-namespace \
  --set image.repository=ghcr.io/maziyarpanahi/openmed \
  --set image.tag=v2.5.0

The default chart creates:

• a Deployment running the REST service on port 8080
• a Service exposing the HTTP port inside the cluster
• a ConfigMap for non-secret OpenMed service settings
• a PersistentVolumeClaim mounted at /root/.cache/huggingface

The service stores OpenMed model cache files under /root/.cache/huggingface/openmed, so downloads survive pod restarts when the PVC is retained.

Production Journey profile¶

Create a PostgreSQL database and a least-privilege application role, then put its DSN in an existing Secret. The chart deliberately never accepts the DSN as a plain Helm value:

kubectl -n openmed create secret generic openmed-journey-database \
  --from-literal=dsn='postgresql://USER:PASSWORD@postgres.openmed.svc:5432/openmed'

Install with Journey enabled and explicitly identify the in-cluster database pods allowed by the default-deny egress policy:

helm upgrade --install openmed-service deploy/helm/openmed-service \
  --namespace openmed \
  --create-namespace \
  --set journey.enabled=true \
  --set journey.networkPolicy.databasePodSelector.app=postgres

For an external database, keep databasePodSelector empty and supply a reviewed journey.networkPolicy.additionalEgress IP block. Do not disable the whole policy merely to make an unknown destination reachable. DNS is the only default egress other than an explicitly selected database.

The Helm hook job runs openmed-journey migrate before install and upgrade. It uses an advisory migration lock and checksum verification, so concurrent releases cannot race the schema. The API readiness command then distinguishes migration, metadata-store, artifact-store, worker, and local model state. The worker has separate liveness and readiness probes and no service-account token.

Upgrade¶

Upgrade by changing values and running the same release name:

helm upgrade openmed-service deploy/helm/openmed-service \
  --namespace openmed \
  --set image.repository=ghcr.io/maziyarpanahi/openmed \
  --set image.tag=v2.5.0

The chart does not create an Ingress or autoscaling object. Add those in environment-specific overlays so cluster ingress classes, certificates, and HPA policy stay outside the reusable chart.

For Journey releases, take a paired PostgreSQL and artifact-volume recovery point before helm upgrade. Wait for the migration hook, both Deployments, and the value-free golden journey before declaring success. Migrations are additive; a Helm rollback never reverses them. Roll back only to an image whose documented compatibility major accepts the current schema, or restore the paired recovery point into new storage.

Probes¶

The chart wires Kubernetes probes to the service endpoints added for orchestrated deployments:

• liveness probe: GET /livez
• readiness probe: GET /readyz

/livez reports that the process is running. /readyz returns success only after configured model preload completes and flips back to not ready during graceful shutdown. Probe requests set Host: localhost so the service trusted host middleware accepts kubelet checks without weakening the application host allowlist.

Secrets¶

Do not put tokens or other secrets in values.yaml. Reference an existing Kubernetes Secret through extraEnv:

extraEnv:
  - name: HF_TOKEN
    valueFrom:
      secretKeyRef:
        name: openmed-hf-token
        key: token

Rotate the database credential with overlapping roles: create the successor role, update the referenced Secret, roll migration/worker/API in order, verify health, and revoke the old role after the rollback window. Kubernetes Secret objects are not backups; use the cluster's encrypted secret manager.

Values Reference¶