Service Architecture

This page documents how OSDU services are deployed, configured, and bootstrapped within the cimpl-azure-provisioning stack. It covers the reusable Terraform module pattern, the Helm + Kustomize postrender framework, feature flags, and the service dependency chain.

Reusable OSDU Service Module

Each OSDU service is deployed via the modules/osdu-service/ wrapper module (see ADR-0015). This standardizes:

• Helm release creation with OCI chart reference
• Kustomize postrender integration
• Timeout and retry configuration
• Chart version management

A typical service definition is ~20 lines in the calling .tf file:

module "partition" {
  source = "./modules/osdu-service"
  count  = var.enable_partition ? 1 : 0

  name            = "partition"
  namespace       = local.osdu_namespace
  chart_version   = local.osdu_versions["partition"]
  kustomize_dir   = "${path.module}/kustomize/services/partition"
  # ... values and dependencies
}

Module Organization

Helm + Kustomize Postrender

All Helm charts are deployed with a Kustomize postrender to ensure AKS safeguards compliance (see ADR-0004).

How It Works

The postrender pipeline transforms Helm output before it reaches the cluster:

Kustomize patches are organized per component:

Each directory contains a kustomization.yaml with strategic merge patches targeting specific Deployments (by type=core label for OSDU services).

OSDU Service Probes

OSDU Java services use Spring Boot actuator on management port 8081:

• Liveness: /health/liveness on port 8081
• Readiness: /health/readiness on port 8081
• initialDelaySeconds: 150-250 (Java startup time)

Feature Flag System

All middleware and OSDU services are controlled by enable_* boolean variables defined in software/stack/variables-flags-*.tf.

Design Principles

• Opt-out model: Everything defaults to enabled. Set TF_VAR_enable_<component>=false to disable.
• Two-level control: Group flags (enable_osdu_core_services, enable_osdu_reference_services, enable_osdu_domain_services) disable entire capability blocks. Individual flags (enable_partition, enable_search, etc.) provide fine-grained opt-out within a group. See ADR-0019.
• Cascading locals: locals.tf computes local.deploy_* for each service as group_flag && individual_flag. Resource files reference local.deploy_* instead of var.enable_* for OSDU services. Platform middleware flags remain direct variable references.
• Dependency cascade: Reference and domain groups require core. Disabling core automatically disables downstream groups.
• Clean environment: No need to set flags for the default deployment.

Example

# Deploy platform middleware only — no OSDU services
azd env set TF_VAR_enable_osdu_core_services false

# Or disable specific middleware and let dependency chains propagate
azd env set TF_VAR_enable_elasticsearch false
# Search and Indexer won't deploy since they depend on Elasticsearch

Service Dependency Chain

OSDU services form a dependency graph. Terraform's depends_on and conditional count guards enforce the correct deployment order:

Each service waits for its dependencies to be healthy before deploying. Bootstrap containers call upstream APIs to seed initial data (e.g., Partition bootstrap registers the osdu data partition with all middleware endpoints).

CNPG Database Bootstrapping

PostgreSQL databases are bootstrapped using a CNPG initdb script that creates 14 separate databases (12 for OSDU services + 2 for platform components), matching the ROSA topology (see ADR-0014):

Each database has a service-specific schema with the standard OSM table pattern: (id text, pk bigint IDENTITY, data jsonb NOT NULL) + GIN index.

A shared osdu user owns all OSDU databases, a simplification from ROSA's per-service user model.

Bootstrap Sequence

After services are deployed, bootstrap containers seed initial data:

1. Partition bootstrap — Registers the osdu data partition with all middleware endpoints (PostgreSQL, Elasticsearch, Redis, RabbitMQ, MinIO)
2. Entitlements bootstrap — Acquires a token from Keycloak (datafier client) and provisions tenant entitlements groups via the Entitlements API
3. Per-service bootstrap (if applicable) — Seeds service-specific reference data

Chart Version Management

OSDU services use CIMPL Helm charts from the OCI registry with chart-default images (see ADR-0013):

# Default version for all services
variable "osdu_chart_version" {
  default = "0.0.7-latest"
}

# Per-service overrides
variable "osdu_service_versions" {
  type    = map(string)
  default = {}
}

Secrets and Configuration

OSDU services discover middleware via Kubernetes secrets created by the osdu-common module:

Secret key names align with ROSA conventions (see ADR-0014).

Adding a New Service

To add a new OSDU service to the stack:

1. Create the module call in the appropriate .tf file (osdu-services-core.tf, osdu-services-reference.tf, or osdu-services-domain.tf):

   module "new_service" {
     source = "./modules/osdu-service"
     count  = local.deploy_new_service ? 1 : 0
     name   = "new-service"
     # ...
   }
   

2. Add the feature flag in the matching variables-flags-*.tf file:

   variable "enable_new_service" {
     type    = bool
     default = true
   }
   

3. Add the cascading local in locals.tf:

   deploy_new_service = var.enable_osdu_core_services && var.enable_new_service
   

4. Create Kustomize patches in kustomize/services/new-service/:

   • kustomization.yaml with strategic merge patch
   • Probe injection targeting type=core Deployments
   • Resource limits, seccomp profile, security context

5. Add the database (if needed) to the CNPG initdb script in modules/postgresql/

6. Add secrets (if needed) to modules/osdu-common/ for middleware credentials

7. Wire dependencies using depends_on to ensure upstream services are healthy

8. Add the chart version to the osdu_versions local map in locals.tf