Middleware Helm Chart
Deploy Middleware, the open-source
DORA metrics platform, with the official middlewareeng/middleware image and a
separate PostgreSQL database. The chart preserves the application's encryption
keys, runs database migrations before startup, and validates the complete
frontend, analytics, sync, and embedded Redis process set before a pod becomes
ready.
Features
- Measures deployment frequency, lead time for changes, change failure rate, and time to restore.
- Uses the HelmForge PostgreSQL subchart or an operator-managed PostgreSQL.
- Runs the upstream-supported embedded Redis process on loopback.
- Persists encryption keys at the path used by Middleware 0.3.1.
- Applies database migrations in an init container before the application.
- Supports configurable application and Service ports, Ingress, scheduling, additional volumes, and extra manifests.
- Creates a tokenless ServiceAccount, RuntimeDefault seccomp profile, capability drop, and NetworkPolicy by default.
- Rejects ambiguous datastore modes and unsupported remote Redis settings.
Installation
Using the HTTPS repository:
helm repo add helmforge https://repo.helmforge.dev
helm repo update
helm install middleware helmforge/middleware --namespace middleware --create-namespace
Using OCI:
helm install middleware oci://ghcr.io/helmforgedev/helm/middleware \
--namespace middleware \
--create-namespace
The default installation creates one Middleware Deployment, a PVC for the application encryption keys, and a standalone PostgreSQL release. Redis runs inside the official application container because the upstream 0.3.1 remote Redis client does not support password authentication and unconditionally uses TLS for non-loopback hosts.
Architecture
Middleware packages three processes in one container:
| Process | Default port | Purpose |
|---|---|---|
| Frontend | 3333 |
Next.js user interface |
| Analytics API | 9696 |
DORA data and API operations |
| Sync server | 9697 |
Provider ingestion and synchronization |
The Service exposes only the frontend through the named http port. Startup
and readiness probes require all three application listeners plus the loopback
Redis listener. Changing
middleware.frontendPort, middleware.analyticsPort, or
middleware.syncPort changes both the Kubernetes ports and the upstream
process environment.
Before the application starts, an init container runs the migrations shipped
in the same official image. It uses dbmate --wait, then writes the signal the
upstream analytics process expects in a shared emptyDir. This is required
because disabling the image's embedded PostgreSQL also disables its original
initializer.
Configuration
Values & Configuration Reference
All schema parameters, types, defaults, and allowed values are extracted directly from the chart repository. Filter and search them in the interactive reference below or customize in Values Studio.
The complete contract is documented in configuration.md
and enforced by values.schema.json plus template validation.
Examples
Bundled PostgreSQL
The defaults are sufficient. For a durable production password, create a Secret and let the subchart consume it:
read -r -s -p 'PostgreSQL superuser password: ' MIDDLEWARE_POSTGRES_PASSWORD
printf '\n'
read -r -s -p 'PostgreSQL application password: ' MIDDLEWARE_DB_PASSWORD
printf '\n'
kubectl create namespace middleware --dry-run=client -o yaml | kubectl apply -f -
kubectl create secret generic middleware-postgresql-credentials \
--namespace middleware \
--from-literal=postgres-password="$MIDDLEWARE_POSTGRES_PASSWORD" \
--from-literal=user-password="$MIDDLEWARE_DB_PASSWORD"
unset MIDDLEWARE_POSTGRES_PASSWORD MIDDLEWARE_DB_PASSWORD
postgresql:
enabled: true
auth:
database: mhq-oss
username: middleware
existingSecret: middleware-postgresql-credentials
existingSecretUserPasswordKey: user-password
persistence:
enabled: true
size: 1Gi
Replication mode additionally requires the configured replication password key.
External PostgreSQL
postgresql:
enabled: false
externalDatabase:
enabled: true
host: postgres.database.svc.cluster.local
port: 5432
name: mhq-oss
user: middleware
existingSecret: middleware-database
existingSecretPasswordKey: password
sslMode: require
Create middleware-database before installation, or source it through an
external secret controller. The chart also accepts an inline
externalDatabase.password for development and places it in a chart-managed
Secret; do not commit that value to source control.
Custom application and Service ports
middleware:
frontendPort: 4333
analyticsPort: 10696
syncPort: 10697
service:
port: 8080
The Service continues to target the named frontend port, so service.port
does not need to match middleware.frontendPort.
Security
The default pod does not receive a Kubernetes API token. The pod uses the
RuntimeDefault seccomp profile, while both the migration and application
containers disallow privilege escalation and drop all Linux capabilities. The
upstream image starts as root and expands packaged runtime artifacts on first
startup, so this chart cannot safely set runAsNonRoot or a read-only root
filesystem without a rebuilt upstream image.
The default NetworkPolicy permits inbound traffic only to the named frontend port. Egress remains unrestricted because Middleware connects to operator- selected Git, issue tracker, and CI providers. Restrict egress at the platform layer only after enumerating all required destinations.
Database passwords are referenced from Kubernetes Secrets. Inline external
passwords are moved into a Secret and are never placed directly in the
Deployment environment. Prefer externalDatabase.existingSecret in GitOps
environments.
See security.md for the threat boundaries and residual upstream constraints.
Operations
Back up both PostgreSQL and the key PVC. PostgreSQL contains DORA records and
integration metadata; the persisted config.ini contains the RSA key pair used
to encrypt stored integration credentials. Restoring only one of these data
sets can make provider credentials unusable.
The application Deployment uses Recreate and a single replica. The key PVC
defaults to ReadWriteOnce, and upstream does not define a multi-replica
coordination model. Scale and protect PostgreSQL independently, but keep the
application tier at one replica.
Detailed backup, restore, rollout, and diagnostic commands are in operations.md.
Troubleshooting
Inspect migration and application logs separately:
kubectl logs -n middleware deployment/middleware-middleware -c migrate-database
kubectl logs -n middleware deployment/middleware-middleware -c middleware --tail=200
kubectl describe pod -n middleware -l app.kubernetes.io/instance=middleware
If the init container waits for PostgreSQL, verify the resolved Service name,
Secret key, network path, and externalDatabase.sslMode. If the frontend is
open but the pod is not Ready, inspect the analytics and sync listener logs;
the readiness probe intentionally checks all three processes.
If integrations cannot be decrypted after a restore, confirm that the PVC was
restored from the same recovery point as PostgreSQL and contains
mhq/config/config.ini at the mounted application path.
Upgrade notes
- Preserve the existing key PVC across upgrades.
- Restore or reuse PostgreSQL credential Secrets when PostgreSQL PVCs already contain data; generating a new password will not change the database user.
- Remote or subchart Redis values are rejected because Middleware 0.3.1 cannot
consume them safely. Remove legacy
redis.enabled: trueandexternalRedis.enabled: trueoverrides. - Verify all three listeners after an image change because they are supervised independently inside the container.
Documentation
- Chart design
- Configuration reference
- External database guide
- Operations and recovery
- Security model
- Production example
- External database example
- Upstream source
Security Scan: middleware
| Framework | Score |
|---|---|
| MITRE + NSA + SOC2 | 79.29292% |
The score is refreshed by CI from rendered manifests. It does not replace application-image vulnerability scanning or a review of external provider credentials.
System Architecture
DESIGN.md SyncedVerified architecture contract rendered dynamically from GitHub DESIGN.md
flowchart LR
client[Browser]
service[Middleware Service]
subgraph pod[Middleware Deployment]
migration[dbmate migration init container]
frontend[Next.js frontend]
analytics[Analytics API]
sync[Sync server]
redis[Embedded Redis]
signal[Shared db_init signal]
keys[Encryption-key PVC]
end
subgraph database[Database boundary]
bundled[Bundled PostgreSQL StatefulSet]
external[External PostgreSQL]
end
client --> service --> frontend
migration --> bundled
migration -. external mode .-> external
migration --> signal --> analytics
frontend --> analytics
frontend --> sync
analytics --> redis
analytics --> keys
analytics --> bundled
analytics -. external mode .-> externalMiddleware Values Schema Reference
Official schema parameters, default values, and types extracted directly from the chart repository.
Global(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| global | object | - | Chart configuration parameter |
Name Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nameOverride | string | "" | Chart configuration parameter |
Fullname Override(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| fullnameOverride | string | "" | Chart configuration parameter |
Common Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| commonLabels | object | - | Chart configuration parameter |
Image(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| image.repository | string | - | Chart configuration parameter |
| image.tag | string | - | Chart configuration parameter |
| image.pullPolicy | string | - | Chart configuration parameter Allowed: AlwaysIfNotPresentNever |
Image Pull Secrets(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| imagePullSecrets | array | - | Chart configuration parameter |
Middleware(8)
| Parameter | Type | Default | Description |
|---|---|---|---|
| middleware.frontendPort | integer | - | Chart configuration parameter |
| middleware.analyticsPort | integer | - | Chart configuration parameter |
| middleware.syncPort | integer | - | Chart configuration parameter |
| middleware.environment | string | - | Chart configuration parameter |
| middleware.internalDbEnabled | string | false | Chart configuration parameter |
| middleware.internalRedisEnabled | string | true | Chart configuration parameter |
| middleware.timezone | string | - | Chart configuration parameter |
| middleware.extraEnv | array | - | Chart configuration parameter |
External Database(9)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalDatabase.enabled | boolean | - | Chart configuration parameter |
| externalDatabase.host | string | - | Chart configuration parameter |
| externalDatabase.port | integer | - | Chart configuration parameter |
| externalDatabase.name | string | - | Chart configuration parameter |
| externalDatabase.user | string | - | Chart configuration parameter |
| externalDatabase.password | string | - | Chart configuration parameter |
| externalDatabase.existingSecret | string | - | Chart configuration parameter |
| externalDatabase.existingSecretPasswordKey | string | - | Chart configuration parameter |
| externalDatabase.sslMode | string | - | Chart configuration parameter Allowed: disablerequireverify-caverify-full |
External Redis(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| externalRedis.enabled | boolean | - | Chart configuration parameter |
| externalRedis.host | string | - | Chart configuration parameter |
| externalRedis.port | integer | - | Chart configuration parameter |
Persistence(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| persistence.enabled | boolean | - | Chart configuration parameter |
| persistence.size | string | - | Chart configuration parameter |
| persistence.storageClass | string | - | Chart configuration parameter |
| persistence.accessModes | array | - | Chart configuration parameter |
| persistence.existingClaim | string | - | Chart configuration parameter |
Service Account(4)
| Parameter | Type | Default | Description |
|---|---|---|---|
| serviceAccount.create | boolean | - | Chart configuration parameter |
| serviceAccount.name | string | - | Chart configuration parameter |
| serviceAccount.annotations | object | - | Chart configuration parameter |
| serviceAccount.automountServiceAccountToken | boolean | - | Chart configuration parameter |
Service & Networking(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| service.type | string | - | Chart configuration parameter Allowed: ClusterIPNodePortLoadBalancer |
| service.port | integer | - | Chart configuration parameter |
| service.annotations | object | - | Chart configuration parameter |
Ingress(5)
| Parameter | Type | Default | Description |
|---|---|---|---|
| ingress.enabled | boolean | - | Chart configuration parameter |
| ingress.ingressClassName | string | - | Chart configuration parameter |
| ingress.annotations | object | - | Chart configuration parameter |
| ingress.hosts | array | - | Chart configuration parameter |
| ingress.tls | array | - | Chart configuration parameter |
Health Probes(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| probes.startup | any | - | Chart configuration parameter |
| probes.liveness | any | - | Chart configuration parameter |
| probes.readiness | any | - | Chart configuration parameter |
Resources(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| resources | object | - | Chart configuration parameter |
Pod Security(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podSecurityContext.seccompProfile.type | string | - | Chart configuration parameter Allowed: RuntimeDefaultLocalhostUnconfined |
Container Security(2)
| Parameter | Type | Default | Description |
|---|---|---|---|
| securityContext.allowPrivilegeEscalation | boolean | - | Chart configuration parameter |
| securityContext.capabilities.drop | array | - | Chart configuration parameter |
Network Policy(3)
| Parameter | Type | Default | Description |
|---|---|---|---|
| networkPolicy.enabled | boolean | - | Chart configuration parameter |
| networkPolicy.additionalIngressFrom | array | - | Chart configuration parameter |
| networkPolicy.additionalEgress | array | - | Chart configuration parameter |
Node Selector(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| nodeSelector | object | - | Chart configuration parameter |
Tolerations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| tolerations | array | - | Chart configuration parameter |
Affinity(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| affinity | object | - | Chart configuration parameter |
Topology Spread Constraints(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| topologySpreadConstraints | array | - | Chart configuration parameter |
Priority Class Name(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| priorityClassName | string | - | Chart configuration parameter |
Termination Grace Period Seconds(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| terminationGracePeriodSeconds | integer | - | Chart configuration parameter |
Pod Labels(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podLabels | object | - | Chart configuration parameter |
Pod Annotations(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| podAnnotations | object | - | Chart configuration parameter |
Extra Volumes(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumes | array | - | Chart configuration parameter |
Extra Volume Mounts(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraVolumeMounts | array | - | Chart configuration parameter |
Extra Manifests(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| extraManifests | array | - | Chart configuration parameter |
Postgresql(10)
| Parameter | Type | Default | Description |
|---|---|---|---|
| postgresql.enabled | boolean | - | Chart configuration parameter |
| postgresql.nameOverride | string | - | Chart configuration parameter |
| postgresql.fullnameOverride | string | - | Chart configuration parameter |
| postgresql.architecture | string | - | Chart configuration parameter Allowed: standalonereplication |
| postgresql.auth.database | string | - | Chart configuration parameter |
| postgresql.auth.username | string | - | Chart configuration parameter |
| postgresql.auth.password | string | - | Chart configuration parameter |
| postgresql.auth.existingSecret | string | - | Chart configuration parameter |
| postgresql.auth.existingSecretUserPasswordKey | string | - | Chart configuration parameter |
| postgresql.initdb.scripts.02-middleware-database-owner.sh | string | - | Chart configuration parameter |
Redis(1)
| Parameter | Type | Default | Description |
|---|---|---|---|
| redis.enabled | boolean | - | Chart configuration parameter |
No schema parameters match your search
Try searching for a different keyword or reset the filter.