Deploying the JDR Module (K8s/Docker)
Relevant source files
The following files were used as context for generating this wiki page:
The JDR (Java Domain & Reliability) module provides a hardened persistence and domain service for the Isabella Villaseñor AI project. It acts as a companion service to the Node.js/Vite frontend, handling complex domain rules, character persistence, and transactional auditing. The module supports both local development via Docker Compose and production-grade orchestration using Kubernetes.
Sources: README.md:213-219, jdr-generator/api/pom.xml:13-15
Deployment Architecture
The JDR module operates as a Spring Boot 3.3.5 application running on Java 17. It integrates with a MySQL database for durable storage and follows a sidecar-compatible architecture where authorization is delegated to the Isabella Core Gateway via JWT/OIDC.
Infrastructure Components
The diagram shows the high-level flow from a load balancer through the Kubernetes service to redundant JDR pod instances, which consume secrets to connect to a MySQL database.
Sources: jdr-generator/deploy/k8s/deployment.yaml:1-68, README.md:217-230
Kubernetes Deployment
The production environment utilizes a Kubernetes Deployment resource named isabella-jdr. It ensures high availability by maintaining two active replicas and enforces strict security contexts to minimize the attack surface.
Security and Hardening
The deployment enforces several security constraints:
- Non-Root Execution: The container runs as user ID
10001. - Filesystem Security: The root filesystem is set to read-only.
- Privilege Escalation: Explicitly disabled (
allowPrivilegeEscalation: false). - Resource Limits: Restricts CPU and memory to prevent resource exhaustion.
| Security Context | Value | Description |
|---|---|---|
runAsNonRoot | true | Prevents the container from running with root privileges. |
readOnlyRootFilesystem | true | Ensures no writes to the system partition. |
capabilities.drop | ["ALL"] | Removes all standard Linux capabilities. |
seccompProfile | RuntimeDefault | Restricts system calls to safe defaults. |
Sources: jdr-generator/deploy/k8s/deployment.yaml:20-29, jdr-generator/deploy/k8s/deployment.yaml:52-56
Environmental Configuration
Sensitive configuration is injected into the container via Kubernetes Secrets.
| Environment Variable | Secret Source Key | Purpose |
|---|---|---|
JDR_DB_URL | db-url | MySQL connection string. |
JDR_DB_USERNAME | db-username | Database credentials. |
JDR_DB_PASSWORD | db-password | Database credentials. |
OIDC_ISSUER | oidc-issuer | Isabella Auth identity provider URL. |
OIDC_AUDIENCE | oidc-audience | Expected audience in the JWT. |
Sources: jdr-generator/deploy/k8s/deployment.yaml:35-51
Local Development (Docker)
For local development, the system provides a docker-compose.local.yml configuration. This environment allows developers to spin up the JDR service alongside its required MySQL dependency without configuring a full Kubernetes cluster.
Local Initialization Sequence
The sequence illustrates the steps to verify the code, start the local database, and run the Spring Boot application.
Health Monitoring
The JDR module exposes health and readiness indicators via Spring Boot Actuator. These endpoints are used by Kubernetes probes to manage the container lifecycle.
- Readiness Probe: Checks
/actuator/health/readinessto determine if the pod can receive traffic. - Liveness Probe: Checks
/actuator/health/livenessto determine if the container needs a restart. - Metrics: Exposes Prometheus-formatted metrics at
/actuator/prometheus.
Sources: jdr-generator/deploy/k8s/deployment.yaml:63-74, README.md:228, jdr-generator/api/pom.xml:53-57
Build and CI/CD Pipeline
The JDR module requires Maven and JDK 17 for builds. The pipeline includes quality gates such as Checkstyle, SpotBugs, and OWASP Dependency Check to ensure code maturity before deployment.
- Verification: Execute
mvn -B verifyto run tests and quality checks. - Packaging: The Spring Boot plugin is configured with
layersenabled to optimize Docker image layer caching. - Security Scanning: The GitHub Actions workflow performs Trivy scans and generates a Software Bill of Materials (SBOM) for every build.
Sources: jdr-generator/api/pom.xml:65-80, jdr-generator/api/pom.xml:84-110, README.md:205-209
Summary
Deploying the JDR module requires a coordinated setup of Java 17 runtimes, MySQL persistence, and OIDC-based security. While Docker Compose facilitates local iteration, the Kubernetes deployment provides the necessary hardening—including immutable image digests and restricted security contexts—required for a production "Nodo Cero" environment. Success depends on the Isabella Core Gateway being available to provide the identity and authorization context for all JDR operations.
Sources: README.md:217-219, jdr-generator/deploy/k8s/deployment.yaml:32-34