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.ymlroutes"/v1"tohttp://api:3000,documents/us-jp-api-vm-migration.mddescribes"/"plus/consent,/scoring,/token, and/us-data, while the US and JP OpenAPI documents publish/api/v1/usand/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-apiconsent-servicetoken-serviceus-data-gatewayscoring-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
- Provision the new VM.
- Deploy the US API services.
- Verify connectivity to Postgres and Redis.
- Validate end-to-end behavior.
- Cut over DNS or load balancer targets to the new VM.
- 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-limitingplugin. - Request correlation: generated as
x-request-idby Kong’scorrelation-idplugin. - Application persistence: handled by the internal services through Postgres and Redis, as described in the migration guide.
Testing Considerations
- Confirm
api.joinlita.comresolves 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. |