Identity Service — Deployment Topology
Status: populated
Owner: TBD
Last updated: 2026-04-18
Companion: Service Template · 03 platform-services · 17 Technology Stack
1. Runtime summary
| Property | Value |
|---|
| Runtime | Node.js 22 LTS |
| Framework | NestJS 11 |
| Language | TypeScript 5.x |
| Package | @ghasi/service-identity |
| HTTP port | 3001 |
| Healthcheck | GET /health |
2. Container topology
3. Replica and scaling policy
| Dimension | Value |
|---|
| Min replicas | 3 (one per availability zone) |
| Max replicas | 10 |
| Scale-out trigger | CPU ≥ 60% avg over 90 s |
| Scale-in cooldown | 5 min |
| Pod anti-affinity | requiredDuringSchedulingIgnoredDuringExecution across zones |
| Resource request | cpu: 250m, memory: 256Mi |
| Resource limit | cpu: 1000m, memory: 512Mi |
4. Regional deployment
| Region | Role | Notes |
|---|
| Primary (AF / UAE) | Read + write | Active PostgreSQL primary |
| Secondary (DR) | Read standby | Streaming replica; RTO ≤ 30 min |
| Edge (future) | JWKS cache only | Kong plugin caches JWKS; full service not needed at edge PoP |
Data residency: tenant rows stay in tenant's assigned region. Module catalogue (no tenant PII) is replicated cross-region for availability.
5. Database connection pools
| Store | Pool sizing | Notes |
|---|
| PostgreSQL primary | pgBouncer transaction mode, max 20 conns | Writes; RLS SET app.tenant_id per transaction |
| PostgreSQL replica | pgBouncer, max 10 conns | GET /licensing/nodes/:id/effective read path |
| Redis 7 Cluster | 3 shards, ioredis cluster client | Session revocation bitmap; 5-min license cache; rate-limit counters |
6. Key management
| Secret | Store | Rotation cadence |
|---|
| JWT RS256 private key (JWKS) | AWS KMS asymmetric key | 90 days; 7-day overlap window |
| Device certificate signing key | AWS KMS | 180 days |
| API key HMAC secret | AWS Secrets Manager | On rotation request |
DATABASE_URL | Kubernetes Sealed Secret | Quarterly or on breach |
| Keycloak client secret | Kubernetes Sealed Secret | 90 days |
7. Network policies
| Source | Destination | Port | Protocol |
|---|
| Kong | identity-service | 3001 | HTTP/2 |
| identity-service | PostgreSQL | 5432 | TCP |
| identity-service | Redis | 6379 | TCP |
| identity-service | NATS | 4222 | TCP |
| identity-service | AWS KMS endpoint | 443 | HTTPS |
| identity-service | Keycloak | 8443 | HTTPS |
| tenant-service | /internal/identity/* | 3001 | HTTP cluster-internal |
| All services | /.well-known/jwks.json | 3001 | HTTP cluster-internal |
/internal/* routes are IP-restricted to cluster CIDR — no JWT required.
8. Environment variables
| Variable | Description |
|---|
DATABASE_URL | PostgreSQL primary connection string |
DATABASE_REPLICA_URL | PostgreSQL replica connection string |
REDIS_URL | Redis cluster URL |
NATS_URL | NATS JetStream URL |
IDENTITY_JWT_ISSUER | JWT iss claim value |
IDENTITY_JWT_AUDIENCE | JWT aud claim value |
IDENTITY_KMS_KEY_ARN | ARN of JWT signing key |
IDENTITY_DEVICE_CERT_KEY_ARN | ARN of device cert signing key |
IDENTITY_KEYCLOAK_URL | Keycloak base URL |
IDENTITY_SESSION_ABSOLUTE_TTL_S | Absolute session TTL seconds (default: 28800) |
IDENTITY_ARGON2_MEMORY_KIB | Argon2id memory parameter (default: 65536) |
OTEL_EXPORTER_OTLP_ENDPOINT | OpenTelemetry collector |
OTEL_SERVICE_NAME | identity-service |
All validated at startup via Zod schema in src/infrastructure/config/env.ts; service exits with code 1 if any required variable is missing.
9. CI/CD pipeline
Automatic rollback triggered when error rate > 1% or p99 latency > 2 s during canary window.