ADR-013-kong-api-gateway.md

ADR-013: Kong API Gateway for API Management

Metadata	Value
Status	Accepted
Date	2026-01-26
Deciders	Platform Architecture Team
Categories	API Management, Gateway, Security

Context

HelpDev platform needs an API Management layer to:

• Expose internal services to external consumers (public APIs)
• Manage internal API routing between service domains
• Centralize OpenAPI specifications for documentation and governance
• Provide authentication, rate limiting, and plugin management
• Integrate with the existing GitOps pipeline workflow

Requirements

1. Multi-tenant: Support multiple Kong instances per domain (e.g., ecommerce-internal, payments-external)
2. GitOps-native: All configuration managed declaratively in Git
3. Self-service: Service teams can configure routes/plugins without Platform Team intervention
4. Multi-region: Follow existing {account}/{env}/{region}/ path patterns
5. Keycloak integration: Leverage existing identity provider for authentication
6. Observability: Integrate with Grafana Stack (Mimir, Loki, Tempo)

Decision

We will implement Kong Gateway in DB-less mode with a two-repository architecture:

Repository Structure

Repository	Purpose	Ownership
platform-kong	Kong infrastructure (Helm, base config)	Platform Team
platform-apis	API configuration (OpenAPI, routes, plugins)	Service Teams + Platform Team

Key Design Choices

1. DB-less Mode: Kong runs without a database, using declarative YAML configuration synced via GitOps
2. Separation of Concerns: Infrastructure (platform-kong) vs Configuration (platform-apis)
3. Kong per Domain: One Kong instance serves multiple services within a domain (e.g., ecommerce-external)
4. Aggregated Config: A GitHub Action combines per-service configs into a single kong.yaml per instance

Architecture

┌─────────────────────────────────────────────────────────────────────────┐
│                         API MANAGEMENT STACK                            │
│                                                                         │
│  ┌──────────────────┐    ┌──────────────────┐    ┌──────────────────┐   │
│  │   Backstage      │    │   platform-apis  │    │  platform-kong   │   │
│  │                  │    │   (API Config)   │    │   (Infra Only)   │   │
│  │ • Create Kong    │    │ • OpenAPI specs  │    │ • Kong deploy    │   │
│  │ • Associate svc  │    │ • Routes config  │    │ • Helm values    │   │
│  │ • Update catalog │    │ • Plugins config │    │ • Base settings  │   │
│  └──────────────────┘    └──────────────────┘    └──────────────────┘   │
│                                   │                       │             │
│                                   ▼                       ▼             │
│                          ┌──────────────────────────────────────┐       │
│                          │           Kong Runtime               │       │
│                          │  (DB-less, config from platform-apis)│       │
│                          └──────────────────────────────────────┘       │
└─────────────────────────────────────────────────────────────────────────┘

Path Patterns

platform-apis:

platform-apis/{account}/{env}/{region}/{kong-instance}/{service}/
├── openapi.yaml     # API specification (auto-published by pipeline)
├── routes.yaml      # Kong routes (auto + manual PR)
└── plugins.yaml     # Kong plugins (manual PR)

platform-kong:

platform-kong/{account}/{env}/{region}/{kong-instance}/
├── values.yaml          # Helm values (replicas, resources)
└── kustomization.yaml   # Kustomize overlay

Alternatives Considered

1. Kong with PostgreSQL (Traditional Mode)

Pros:

• Admin API for dynamic configuration
• Better for large-scale deployments with many changes

Cons:

• Requires database management per environment
• Configuration drift risk (state outside Git)
• Doesn't align with GitOps principles

Decision: Rejected - GitOps is a core principle (PRD P2)

2. AWS API Gateway

Pros:

• Managed service, no infrastructure to maintain
• Native AWS integration

Cons:

• Vendor lock-in
• Limited plugin ecosystem
• Configuration via Terraform, not Kubernetes-native
• Harder to integrate with Istio service mesh

Decision: Rejected - Kubernetes-native solution preferred

3. Istio Gateway (No Additional Gateway)

Pros:

• Already part of the stack
• No additional component

Cons:

• Limited API management features (no rate limiting, API keys, developer portal)
• No OpenAPI-driven routing
• Less mature plugin ecosystem

Decision: Rejected - Need full API management capabilities

4. Single Repository for Kong Config + Infrastructure

Pros:

• Simpler structure
• All Kong-related code in one place

Cons:

• Service teams need access to infrastructure repo
• Harder to enforce CODEOWNERS
• Mixes concerns (Platform Team owns infra, Service Teams own routes)

Decision: Rejected - Separation of concerns is cleaner

Consequences

Positive

1. GitOps-native: All configuration in Git, auditable, reviewable
2. Self-service: Service teams configure routes/plugins via PR to platform-apis
3. Clear ownership: Platform Team owns platform-kong, Service Teams own their configs
4. Consistent patterns: Follows existing {account}/{env}/{region}/ structure
5. Keycloak integration: OIDC plugin leverages existing identity infrastructure
6. Multi-region ready: Each region has independent configuration

Negative

1. Learning curve: Teams need to learn Kong declarative configuration
2. Aggregation complexity: GitHub Action needed to combine configs into kong.yaml
3. Two repositories: Slight overhead in managing two repos vs one

Risks & Mitigations

Risk	Mitigation
Configuration errors	Validation in CI before merge
Breaking API changes	OpenAPI diff detection in pipeline
Kong version upgrades	Platform Team manages via platform-kong
Plugin misconfiguration	Pre-approved plugin templates

Implementation

Phase 1: Foundation

• Create platform-apis and platform-kong repository structures
• Define CODEOWNERS for governance
• Create ADR documentation

Phase 2: Backstage Integration

• Kong instance creation template
• Service-to-Kong association template
• catalog-info.yaml annotations for Kong

Phase 3: Pipeline Integration

• validate-openapi action
• publish-api-config action
• aggregate-kong-config workflow
• Update service pipeline templates

Phase 4: Multi-Region

• Phased rollout with OpenAPI publish
• Kong health check integration

References

• Kong DB-less Mode
• Kong Declarative Configuration
• PRD Section 5 - Repository Structure
• PRD Section 10.4 - GitOps Governance