Deployment, Gateway, and Infrastructure

Overview

This section documents the public ingress path for the API stack and the trust boundary around the new VM deployment. The repo uses a db-less Kong gateway configuration as the edge entrypoint, with traffic routed from the public DNS name to internal services running on the private VM network.

The edge layer enforces request controls before traffic reaches the application: JWT verification, Redis-backed rate limiting, correlation IDs, body-size limits, and IP allowlisting. The migration guide then places the API services, Postgres, and Redis behind that edge so only Kong is exposed to the internet.

Architecture Overview

flowchart TB
    Client[Partner Client]
    DNS[api joinlita com]

    subgraph KongEdge[Kong Edge]
        Gateway[Kong proxy]
        JWT[JWT plugin]
        Rate[Rate limiting plugin]
        CID[Correlation id plugin]
        Size[Request size limiting]
        IP[IP restriction plugin]
    end

    subgraph PrivateVM[Private VM Network]
        API[lita api service]
        Consent[consent service]
        Token[token service]
        Data[us data gateway]
        Scoring[scoring orchestrator]
    end

    subgraph SharedInfra[Shared Infrastructure]
        Postgres[Postgres]
        Redis[Redis]
    end

    Client --> DNS
    DNS --> Gateway
    JWT -.-> Gateway
    Rate -.-> Gateway
    CID -.-> Gateway
    Size -.-> Gateway
    IP -.-> Gateway
    Gateway -->|/v1| API

    API --> Consent
    API --> Token
    API --> Data
    API --> Scoring

    Consent --> Postgres
    Token --> Postgres
    Data --> Postgres
    Scoring --> Postgres

    Rate --> Redis

Edge Trust Model

[!NOTE] The supplied files describe different public prefixes: kong/kong.yml routes "/v1" to http://api:3000, documents/us-jp-api-vm-migration.md describes "/" plus /consent, /scoring, /token, and /us-data, while the US and JP OpenAPI documents publish /api/v1/us and /api/v1/jp. These prefixes are not aligned across the provided sources.

The deployment model in the migration guide is explicit: Kong is the public entrypoint, and the internal API services remain on the private network. The public host name api.joinlita.com points at the Kong proxy port on the new VM, and Kong forwards requests to upstream services based on path routing.

Trust Boundaries

Boundary Enforced by Source Effect
Public ingress Kong proxy documents/us-jp-api-vm-migration.md Only Kong accepts inbound traffic from the internet.
Edge request policy Kong plugins kong/kong.yml JWT, rate limit, request-size, correlation-id, and IP checks happen before upstream routing.
Private application network VM placement and service wiring documents/us-jp-api-vm-migration.md Internal API services stay reachable from Kong and from shared infrastructure, but are not public entrypoints.
Shared persistence and counters Postgres and Redis documents/us-jp-api-vm-migration.md, kong/kong.yml Application state and edge rate-limit counters live on internal infrastructure.

Public Ingress and Path Routing

Source file Documented public path Upstream target Notes
kong/kong.yml /v1 http://api:3000 strip_path: false preserves the route prefix.
documents/us-jp-api-vm-migration.md / US API service Described as the public entrypoint in the migration guide.
documents/us-jp-api-vm-migration.md /consent Consent service Documented as a supporting-service prefix.
documents/us-jp-api-vm-migration.md /scoring Scoring service Documented as a supporting-service prefix.
documents/us-jp-api-vm-migration.md /token Token service Documented as a supporting-service prefix.
documents/us-jp-api-vm-migration.md /us-data US data gateway Documented as a supporting-service prefix.

Kong Edge Configuration

kong/kong.yml

This file is the declarative gateway definition. It defines one upstream service and a set of plugins that enforce edge controls before requests reach the internal API.

Gateway Service and Route

Field Value Meaning
_format_version 3.0 Declarative Kong config format.
services[0].name lita-api Upstream service name.
services[0].url http://api:3000 Internal upstream target.
routes[0].name api-v1 Named route bound to the service.
routes[0].paths "/v1" Public route prefix handled by Kong.
routes[0].strip_path false The route prefix is preserved when forwarded upstream.

Edge Controls

Control File Config Enforced at Purpose
JWT verification kong/kong.yml jwt with uri_param_names: [] and claims_to_verify: [exp] Kong edge Requires JWTs to satisfy the expiry claim and disables token lookup via URI parameters.
Redis-backed rate limiting kong/kong.yml rate-limiting with minute: 300 and policy: redis Kong edge Uses Redis as the counter store for the minute-based limit.
Correlation IDs kong/kong.yml correlation-id with header_name: x-request-id and generator: uuid Kong edge Ensures requests carry a request ID header generated at the gateway boundary.
Body-size limit kong/kong.yml request-size-limiting with allowed_payload_size: 1 Kong edge Rejects oversized request bodies before they reach the upstream service.
IP restrictions kong/kong.yml ip-restriction allow 10.0.0.0/8 and 192.168.0.0/16 Kong edge Restricts public access to the configured source networks.

Control Placement

  • At the edge

    • JWT verification
    • Redis-backed rate limiting
    • Correlation ID generation
    • Request-size limiting
    • IP allowlisting
    • Route selection based on path prefix
  • Inside the application network

    • lita-api
    • consent-service
    • token-service
    • us-data-gateway
    • scoring-orchestrator
    • Postgres
    • Redis

VM Migration and Cutover

documents/us-jp-api-vm-migration.md

The migration guide describes a cutover path to a new VM, with Kong exposed publicly and the API services moved behind it. The stack depends on shared Postgres and Redis infrastructure plus shared JWT and partner credentials.

Prerequisites

Category Values
Infrastructure endpoints Postgres connection string, Redis host and port
Secrets and environment variables DATABASE_URL, REDIS_URL, JWT_PRIVATE_KEY, JWT_PUBLIC_KEY, PARTNER_API_KEYS, PROVIDER, SCORING_CALLBACK_URL
Build and runtime dependencies Docker, Node runtime dependencies, Go runtime dependencies
Network plan New VM IP, DNS or load balancer cutover for api.joinlita.com, firewall rules, security group rules, IP allowlists, VPC peering where required

Migration Flow

sequenceDiagram
    participant Operator as Operator
    participant VM as New VM
    participant Kong as Kong proxy
    participant API as Internal API services
    participant DNS as DNS and load balancer
    participant Client as Partner Client

    Operator->>VM: Provision host and install dependencies
    Operator->>Kong: Deploy kong.yml
    Operator->>API: Start API services
    Operator->>DNS: Point api joinlita com to Kong proxy
    Client->>Kong: Send request to public API
    Kong->>API: Forward to upstream service
    API-->>Kong: Return response
    Kong-->>Client: Return response

High-Level Migration Steps

  1. Provision the new VM.
  2. Deploy the US API services.
  3. Verify connectivity to Postgres and Redis.
  4. Validate end-to-end behavior.
  5. Cut over DNS or load balancer targets to the new VM.
  6. Decommission the old VM after traffic stabilizes.

Validation

The guide uses smoke testing against the new VM after cutover.

newman run services/us-api/postman/us-api.postman_collection.json \
  -e services/us-api/postman/us-api.postman_environment.json \
  --env-var baseUrl=http://<NEW_VM_IP>:8080 \
  --env-var partnerToken=<PARTNER_API_KEY>

Supporting Service Container

services/consent-service/Dockerfile

This Dockerfile defines the runtime image for one of the internal services named in the migration guide. It is part of the private service tier behind Kong.

Instruction Value Responsibility
Base image node:18-alpine Minimal Node runtime for the service container.
Working directory /app Container working directory.
Dependency install npm ci --omit=dev Installs production dependencies only.
Source copy COPY src ./src Adds service code to the image.
Runtime env NODE_ENV=production Runs the service in production mode.
Exposed port 8081 Service listener exposed inside the container network.
Start command node src/index.js Launches the service process.

Ingress and Runtime Dependencies

Dependency Source Role
Kong db-less gateway documents/us-jp-api-vm-migration.md, kong/kong.yml Public ingress, path routing, and request enforcement.
Redis kong/kong.yml, documents/us-jp-api-vm-migration.md Backing store for Kong rate-limiting counters and shared runtime needs.
Postgres documents/us-jp-api-vm-migration.md Shared persistence for the internal services.
JWT keys documents/us-jp-api-vm-migration.md Shared secret material used by the API stack.
Partner API keys documents/us-jp-api-vm-migration.md Partner authentication credentials during runtime.
Docker documents/us-jp-api-vm-migration.md Container build and run path for the VM deployment.
DNS or load balancer documents/us-jp-api-vm-migration.md Routes api.joinlita.com to the Kong proxy on the new VM.

Error Handling

The edge rejects requests before they reach the application when the configured policy fails.

Failure condition Enforcing control Outcome
Invalid JWT or missing required exp claim jwt plugin Request is blocked at Kong.
Rate limit exceeded rate-limiting plugin Request is blocked at Kong using Redis-backed counters.
Oversized request body request-size-limiting plugin Request is blocked at Kong.
Source IP outside allowed ranges ip-restriction plugin Request is blocked at Kong.
Upstream service unavailable Kong route target Request cannot be forwarded to the internal API service.

State Management

The only explicit edge-side state in the provided files is the Redis-backed rate-limit policy in Kong. The VM migration guide also places the internal services on shared Postgres and Redis infrastructure, so the runtime depends on those backends remaining reachable after cutover.

  • Rate-limit counters: stored in Redis through Kong’s rate-limiting plugin.
  • Request correlation: generated as x-request-id by Kong’s correlation-id plugin.
  • Application persistence: handled by the internal services through Postgres and Redis, as described in the migration guide.

Testing Considerations

  • Confirm api.joinlita.com resolves to the Kong proxy on the new VM.
  • Confirm Kong forwards the configured route prefix to the upstream target.
  • Confirm Redis is reachable before enabling rate-limited traffic.
  • Confirm IP allowlisted clients can reach the proxy.
  • Run the Newman command from the migration guide against the new VM.
  • Verify the internal API services can reach Postgres and Redis after cutover.

Key Classes Reference

Class Responsibility
kong.yml Declarative Kong gateway configuration for routing and edge enforcement.
us-jp-api-vm-migration.md VM cutover guide, trust boundary description, and deployment checklist.
Dockerfile Builds the consent-service container for the private service network.