v3.4 reference deployment declaration¶
This page declares the deployment contract for the v3.4 release line: which topology is the reference, which transports are supported and with what security posture, how each process may be replicated, which components hold durable state and what recovery point objective (RPO) and recovery time objective (RTO) each one carries, and which deployments are unsupported. Reference workflows, recovery drills, and data-integrity evidence measure against this contract; they do not redefine it.
The machine-readable source of truth is deploy/reference/v3.4-reference-deployment.json, validated by deploy/reference/reference-deployment.schema.json. The tables below render that file row for row. A unit test fails when the two disagree, when the declaration fails its schema, or when it names a REST route, worker route, MCP path, gRPC method, Python module or symbol, Compose service or volume, Helm value, manifest, or docs page that does not exist in the repository.
The declaration describes current behavior. It contains only controlled codes and repository-relative references: no hostnames, addresses, credentials, connection strings, or patient data.
Objectives are declared targets, not measured results
objective_evidence is unmeasured_targets. The RPO and RTO values below are the targets for the reference topology when an operator follows the documented backup and restore procedure. They are not guarantees, and no drill result is recorded here. Operators may declare tighter objectives for their own deployment, but must not assume OpenMed provides replication, automated backup, or failover.
Status vocabulary¶
| Status | Meaning |
|---|---|
| reference | The single configuration the release is validated against. |
| supported | Shipped and documented; may be used in production within its constraints. |
| restricted | Shipped, but only safe inside the listed constraints, usually an internal network. |
| unsupported | Present in the code base or repository, but not a supported production deployment. |
Constraint codes are listed exactly as they appear in the declaration.
Topologies¶
The reference topology is compose_single_host: the offline Compose bundle on one host, with bundled PostgreSQL, a one-shot migration, the Journey worker, the REST API, and the optional smoke and mcp profiles on an internal network. Only the REST port is published, and it binds to loopback by default. See Self-hosted Compose deployment and Helm deployment for the operating procedures.
| Topology | Status | Manifests | Services |
|---|---|---|---|
compose_single_host | reference | deploy/openmed-compose.yaml, deploy/docker/Dockerfile.distroless | postgres, journey_migrate, journey_worker, rest_api, journey_golden, mcp_server |
helm_kubernetes | supported | deploy/helm/openmed-service/Chart.yaml, deploy/helm/openmed-service/values.yaml, deploy/helm/openmed-service/templates/deployment.yaml, deploy/helm/openmed-service/templates/network-policy.yaml | rest_api, journey_migrate, journey_worker, postgres |
kubernetes_autoscaled | supported | deploy/k8s/hpa.yaml | rest_api |
kubernetes_model_operator | supported | deploy/operator/kustomization.yaml, deploy/operator/crd/openmedmodel.yaml | rest_api |
development_compose | unsupported | docker-compose.yml, Dockerfile, Dockerfile.mcp | rest_api, mcp_server |
The repository-root Compose file is a development convenience. It publishes the REST port on every interface without authentication and has no Journey store, so it is declared unsupported for production.
Services and replica modes¶
| Service | Replica mode | Status | Constraints |
|---|---|---|---|
rest_api | single | reference | none |
rest_api | horizontal | restricted | synchronous_routes_only, per_replica_warm_pool, per_replica_rate_limits, per_replica_job_state |
journey_worker | single | reference | health_probe_only |
journey_migrate | one_shot | reference | single_migration_runner, completes_before_api_and_worker |
journey_golden | one_shot | supported | smoke_profile_only, synthetic_content_only |
mcp_server | single | supported | optional_profile |
postgres | single | reference | bundled_single_instance |
postgres | external | supported | operator_managed_database, replication_not_managed_by_openmed |
grpc_server | single | unsupported | no_deployment_wiring |
The REST API can run as more than one replica, for example under the Kubernetes autoscaling manifest, only for synchronous routes. Warm model pools, in-process rate limits, async job metadata, FHIR Bulk Data jobs, and SMART backend ingestion jobs are all per process. A status poll that lands on a different replica does not see the job.
The gRPC server is a library factory only. No console entry point, container image, Compose service, chart template, or health service starts it, so it has no supported replica mode.
Transports and security posture¶
| Transport | Status | Encryption | Authentication | Default exposure | Constraints |
|---|---|---|---|---|---|
rest_http | supported | optional_tls | optional | loopback | authentication_disabled_by_default, non_loopback_requires_authentication, non_loopback_requires_tls, non_loopback_requires_trusted_hosts, cluster_ip_service_in_helm |
graphql_http | supported | optional_tls | optional | loopback | shares_rest_listener, authentication_disabled_by_default |
mcp_stdio | supported | not_applicable | not_applicable | local_process | client_spawned_process |
mcp_streamable_http | restricted | none | optional | internal_network | internal_network_only, no_published_port, authorization_disabled_by_default, insecure_loopback_mode_enabled |
journey_worker_health_http | restricted | none | none | internal_network | value_free_health_only, internal_network_only |
postgresql_wire | restricted | none | required | internal_network | tls_not_enforced_by_manifests, internal_network_only, credentials_from_operator_secret |
job_webhook_outbound | restricted | optional_tls | required | outbound_only | hmac_signed_payloads, https_not_enforced, no_egress_on_reference_network |
grpc | unsupported | none | none | not_wired | no_deployment_wiring, insecure_port_only, binds_all_interfaces_by_default, no_health_service |
- REST and GraphQL share one listener. TLS comes from the launcher's TLS flags or from a terminating proxy; API key, JWT, and mTLS authentication are opt-in and disabled by default. The Helm chart exposes it through a cluster-internal Service. Exposing the listener beyond loopback or the cluster requires authentication, TLS, and an explicit trusted-host policy. See REST authentication and mutual TLS.
- MCP over standard input and output opens no listener. The Compose
mcpprofile serves stateless streamable HTTP in plaintext on the internal network only, with no published port. - The Journey worker health listener and the PostgreSQL connection are plaintext inside the internal network. The shipped manifests do not require verified database TLS.
- Job webhooks are signed, but either plaintext or TLS targets are accepted, and the reference network has no egress.
- gRPC is declared
unsupportedas a network transport: the default server opens an insecure port on every interface with no TLS, authentication, or health service, and nothing in the deployment manifests wires it. See gRPC service for the library contract.
Durable components and recovery objectives¶
Every durable component carries both an RPO and an RTO. Each objective is either declared, with a target and a basis code, or unsupported, with a reason code. The schema rejects a component that omits either objective.
| Component | Storage | Replica mode | RPO | RTO |
|---|---|---|---|---|
journey_database | postgresql | single_primary | 24 h (daily_application_consistent_backup) | 4 h (isolated_restore_then_migrate_and_golden_journey) |
journey_artifacts | filesystem_object_store | single_writer_volume | 24 h (paired_with_journey_database_recovery_point) | 4 h (isolated_restore_then_migrate_and_golden_journey) |
model_cache | filesystem_cache | single_writer_volume | 0 s (derived_from_verified_model_artifacts) | 4 h (reprovision_from_offline_model_bundle) |
service_job_metadata | local_json_file | single_process | unsupported (payloads_held_in_process_memory) | unsupported (single_process_job_store) |
service_bulk_job_state | process_memory | per_replica_memory | unsupported (in_memory_job_state) | unsupported (in_memory_job_state) |
database_credentials | operator_secret_store | external_operator_owned | unsupported (operator_owned_secret_store) | unsupported (operator_owned_secret_store) |
journey_databaseandjourney_artifactsform one recovery set. Back them up together as an application-consistent recovery point at least daily, and restore into an isolated namespace, run the migration gate, then run the synthetic golden journey before admitting traffic. The procedure is in Self-hosted Compose deployment and the PostgreSQL and object Journey store guide.model_cacheholds only artifacts derived from verified model bundles. Loss is recovered by re-provisioning from the offline bundle, so there is no recovery point to lose.service_job_metadatais a local JSON file owned by one process. Submitted payloads stay in memory, so queued or running jobs do not survive a restart and the file must not be shared between replicas. Recovery objectives areunsupported; resubmit interrupted jobs.service_bulk_job_statelives in process memory and is lost on restart.database_credentialsare owned by the operator's secret source. OpenMed neither renders nor persists them, so their recovery is out of scope.
Unsupported deployments¶
| Deployment | Reason code | Summary |
|---|---|---|
grpc_network_service | no_deployment_wiring | Serving gRPC as a network service. Nothing in the images, Compose bundle or chart starts it, and its default listener is plaintext and unauthenticated. |
multi_replica_async_jobs | single_process_job_store | Running async jobs, FHIR Bulk Data or SMART ingestion behind more than one REST replica. Job state is process-local, so status polls can miss the owning replica. |
unauthenticated_non_loopback_rest | authentication_and_tls_required_off_loopback | Publishing the REST or GraphQL listener beyond loopback without authentication, TLS and an explicit trusted-host policy. |
public_mcp_streamable_http | insecure_loopback_mode | Publishing the Compose MCP streamable HTTP listener. The profile enables the insecure-loopback authorization mode and has no TLS. |
openmed_managed_database_replication | replication_not_managed_by_openmed | Relying on OpenMed for PostgreSQL replication, failover or multi-primary writes. High availability of the database is an operator responsibility. |
development_compose_in_production | all_interface_publish_without_authentication | Using the repository-root development Compose file for production. It publishes the REST port on every interface without authentication. |
Changing the declaration¶
Edit deploy/reference/v3.4-reference-deployment.json and this page together, then run:
The test validates the schema, resolves every reference, checks that each durable component declares both recovery objectives, compares every table row on this page with the declaration, and scans both files for hostnames, addresses, credentials, and patient-data patterns. Its negative controls prove that a missing route, module, symbol, gRPC method, manifest, Compose service or volume, Helm value, or docs page fails the check.