Skip to content

Architecture

Overview

The Nomad PaaS controlplane implements the Open Application Model (OAM) specification, translating portable application definitions into Nomad job specifications.

Components

flowchart TB
    subgraph CP[Control Plane]
        API[API Server] --> T[Translator]
        T --> NC[Nomad Client]
        API --> S[(Store)]
        S --> CK[(Consul KV)]
    end

    NC --> NR[Nomad Cluster]
    CK --> CC[Consul Cluster]

    subgraph External
        TProxy[Traefik]
        Vault[Vault]
    end

    CC --> TProxy
    CC --> Vault

Translation Flow

1. Application Receipt

The API server receives an OAM Application and validates it against the schema.

2. Component Translation

Each component in the application is translated to a Nomad job:

OAM Concept Nomad Concept
Application Job
Component Job + Task Group
Container Task
Trait Job/Task Group Settings

3. Trait Processing

Traits are decoded and applied to the Nomad job:

  • Scaler → Nomad Scaling Policy
  • Ingress → Traefik tags in Consul
  • Volume → Volume mounts
  • Vault Secret → Template blocks

4. Scope Application

Scopes modify job-level settings:

  • Network Scope → Network mode, Consul Connect
  • Node Pool → Node pool targeting, constraints
  • Namespace → Job namespace

5. Job Submission

The translated jobs are submitted to Nomad via the Nomad API.

Tenancy Model

The controlplane implements multi-tenancy using Nomad namespaces:

graph TD
    Tenant[Tenant] --> NS[Nomad Namespace]
    Tenant --> CN[Consul Namespace]
    Tenant --> VN[Vault Namespace]
    Tenant --> TP[Traefik Prefix]

    NS --> Job1[Job Isolation]
    NS --> Job2[Job Isolation]
    CN --> Svc1[Service Mesh]
    CN --> Svc2[Service Mesh]
    VN --> Sec1[Secret Isolation]
    TP --> L7[L7 Routing]

Data Flow

sequenceDiagram
    participant Tenant
    participant API as API Server
    participant Translator
    participant Nomad as Nomad Cluster
    participant Consul
    participant Traefik

    Tenant->>API: Submit Application
    API->>API: Validate Schema
    API->>Translator: OAM Application
    Translator->>Translator: Convert to Nomad Job
    Translator->>Nomad: Submit Job
    Nomad->>Consul: Register Services
    Consul->>Traefik: Update Routes
    Traefik->>Tenant: Serve Traffic

Scalability

The controlplane is horizontally scalable. Each instance can handle translation requests independently. State is stored in Consul KV, not in the controlplane itself.

graph LR
    subgraph CP1[Control Plane Instance 1]
        API1[API Server]
    end

    subgraph CP2[Control Plane Instance 2]
        API2[API Server]
    end

    subgraph CP3[Control Plane Instance N]
        API3[API Server]
    end

    API1 --> CKV[(Consul KV)]
    API2 --> CKV
    API3 --> CKV

    CKV --> NC[Nomad Cluster]