Ingress Info Service

Introduction

The Ingress Info Service exposes a read-only, filtered, and typed view of Kubernetes Ingress resources to internal cluster clients. The service MUST provide a single REST endpoint to list ingresses, protect business endpoints via bearer keys, and support deterministic caching with ETag. The scope excludes active reachability probing and any mutating APIs.

Primary use case: power an end-user links portal by exposing host- and path-level metadata for web services deployed in the cluster (see ADR-0001).

1. Glossary

2. Goals and Non-Goals

• Goals:
  • G-001: Provide a deterministic, typed list of ingresses with host/path metadata and best-effort reachability.
  • G-002: Offer conditional GET via ETag (If-None-Match) for efficient caching.
  • G-003: Secure API endpoints under /v1/* with static bearer keys from a Kubernetes Secret.
  • G-004: Expose OpenAPI JSON and a minimal UI via Huma v2.
  • G-005: Provide readiness/liveness probes and Prometheus metrics for operations.
  • G-006: Optimize the response shape for a links portal client by exposing a top-level hosts array with nested paths (per ADR-0001).
• Non-Goals:
  • NG-001: No mutation of cluster resources.
  • NG-002: No active network probing; reachability remains passive and best-effort.
  • NG-003: No pagination or detail-by-name endpoint in MVP.

3. Stakeholders

4. System Context

• Context overview and external dependencies
  • Runs as a Deployment in-cluster (ClusterIP Service), consumes the Kubernetes API (in-cluster or kubeconfig when run locally), reads a ConfigMap for selection/mapping and a Secret for API keys. Exposes HTTP on a configurable address (default :8080).
  • Primary consumer is an end-user Links Portal that renders web-service links using host and path metadata from this service (see ADR-0001).
• Diagram:

flowchart TD
  subgraph Cluster[Kubernetes Cluster]
    LinksPortal[Links Portal (primary consumer)] -->|GET /v1/ingresses| API[(Ingress Info Service)]
    Client[Other Internal Clients] -->|GET /v1/ingresses| API
    API -->|List/Watch| K8sAPI[(Kubernetes API)]
    ConfigMap[(ConfigMap ingress-info-config)] --> API
    Secret[(Secret ingress-info-keys)] --> API
    API -->|/metrics| Prometheus[(Prometheus)]
    API -->|/openapi.json + UI| Devs[Developers]
  end

5. Technology Stack

Enumerate the selected technologies and rationale. This section MUST be used by subsequent plans and breakdowns.

6. Functional Requirements

Use FR-XXX identifiers; each MUST be testable.

7. Non-Functional Requirements

Use NFR-XXX identifiers covering performance, reliability, security, compliance, operability.

8. Domain and Data Model

8.1 Domain Entities

classDiagram
  class IngressRecord {
    string namespace
    string name
    HostEntry[] hosts
  }
  class HostEntry {
    string host
    string servicename
    string user_group
    string description
    string contact_information
    bool missing_annotations
    PathEntry[] paths
  }
  class PathEntry {
    string path
    string pathType
    string reachability  // reachable | unreachable | unknown
    string backendService
  }
  IngressRecord --> HostEntry
  HostEntry --> PathEntry

8.2 Data Schemas

Provide JSON Schemas for API-visible structures.

Ingress list response (Snapshot):

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:ingress-info:HostsList",
  "type": "object",
  "properties": {
    "hosts": {
      "type": "array",
      "items": { "$ref": "#/$defs/HostEntry" }
    }
  },
  "required": ["hosts"],
  "$defs": {
    "HostEntry": {
      "type": "object",
      "properties": {
        "host": { "type": "string", "minLength": 1 },
        "servicename": { "type": "string" },
        "user_group": { "type": "string" },
        "description": { "type": "string" },
        "contact_information": { "type": "string" },
        "missing_annotations": { "type": "boolean" },
        "paths": {
          "type": "array",
          "items": { "$ref": "#/$defs/PathEntry" }
        }
      },
      "required": ["host", "missing_annotations", "paths"],
      "additionalProperties": false
    },
    "PathEntry": {
      "type": "object",
      "properties": {
        "path": { "type": "string" },
        "pathType": { "type": "string", "enum": ["Exact", "Prefix", "ImplementationSpecific", ""] },
        "reachability": { "type": "string", "enum": ["reachable", "unreachable", "unknown"] },
        "backendService": { "type": "string" }
      },
      "required": ["path", "reachability"],
      "additionalProperties": false
    }
  }
}

Error response model:

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12

{
  "$schema": "https://json-schema.org/draft/2020-12/schema",
  "$id": "urn:ingress-info:Error",
  "type": "object",
  "properties": {
    "message": { "type": "string" },
    "code": { "type": "string" },
    "details": { "type": "object", "additionalProperties": true }
  },
  "required": ["message"],
  "additionalProperties": false
}

9. API Specification

Use API-XXX identifiers per endpoint. Include method, path, auth, request/response schemas, status codes, examples, and error model.

API-001: GET /v1/ingresses

• Auth: Authorization: Bearer KEY
• Request Headers:
  • If-None-Match (optional)
• Query/Path Params: none
• Request Body: none
• Responses:
  • 200 OK — application/json schema: HostsList

 1
 2
 3
 4
 5
 6
 7
 8
 9
10
11
12
13
14
15

{
  "hosts": [
    {
      "host": "shop.example.com",
      "servicename": "shop-frontend",
      "user_group": "web",
      "description": "Customer storefront",
      "contact_information": "oncall@example.com",
      "missing_annotations": false,
      "paths": [
        { "path": "/", "pathType": "Prefix", "backendService": "shop-frontend", "reachability": "reachable" }
      ]
    }
  ]
}

• 304 Not Modified — no body
• 401 Unauthorized — Error schema

1

{ "message": "unauthorized", "code": "UNAUTHORIZED" }

• 500 Internal Server Error — Error schema

1

{ "message": "internal error", "code": "INTERNAL" }

• Headers:
  • ETag: strong validator computed from resourceVersions map
  • Cache-Control: no-store (SHOULD be configurable per deployment policy)

10. Configuration

Enumerate all configuration keys, sources, defaults, and validation.

Validation rules:

• LISTEN_ADDR MUST parse as valid TCP address.
• labelSelector MUST be a valid Kubernetes label selector string.

11. Security

Use SEC-XXX identifiers. Cover authentication, authorization, data protection, secrets, and supply chain.

12. Observability

Use OBS-XXX identifiers. Define metrics, logs, traces, and alerts.

Note: For the Links Portal use case, request metrics and handler latency for GET /v1/ingresses, as well as projection_size, are especially relevant to monitor perceived portal responsiveness and data freshness.

Alerts (suggested):

• High 5xx rate on /v1/ingresses over 5 minutes.
• Ready=false for > 5 minutes after rollout.

13. Operations

Runbooks, SLOs, scaling, rollout, rollback, backups, DR, upgrades.

14. Compatibility and Versioning

Use COMP-XXX identifiers. Define versioning policy, API stability, and deprecation.

• COMP-001: API versioning via path prefix /v1; backward-compatible additions allowed; breaking changes require /v2.
• COMP-002: ETag semantics MUST remain stable (resourceVersions-hash) within a minor line.
• COMP-003: Supported Kubernetes versions: 1.30–1.33; other versions are best-effort.

15. Dependencies

Use DEP-XXX identifiers. List runtime and build-time dependencies with versions and licenses.

16. Risks, Assumptions, Decisions

Assumptions are maintained in Appendix (ASM-###).

17. Acceptance Criteria

Use AC-XXX identifiers; map each to FR/NFR.

18. Test Plan

Use TEST-XXX identifiers. Outline unit, integration, e2e, performance, and security tests. Link ACs.

19. Documentation Plan

Following Diátaxis Framework principles. Use DOC-XXX identifiers for traceability.

Documentation Types

• Tutorials: Step-by-step learning experiences for new users
• How-to Guides: Task-oriented instructions for specific goals
• Reference: Complete, accurate descriptions of the system
• Explanations: Conceptual discussions of design decisions and architecture

20. Out of Scope

• Pagination and detail-by-name endpoints
• Multi-tenant authorization and per-key scoping
• Active reachability probes (HTTP/TCP checks)
• Non-Kubernetes deployments

21. Appendix

ADR Changes

• Changed by ADR-0001: Hosts Top-Level Response Shape for GET /v1/ingresses on 2025-09-15.

References, prior art, ADR links, and diagrams.

Assumptions Ledger

Provenance

• Interactive Q&A conducted with one-at-a-time confirmations.
• Key confirmations: name (Ingress Info Service), port 8080 (configurable), static bearer auth, single endpoint, ETag-only, Huma v2 + OpenAPI/UI, strict typed schemas, K8s 1.30–1.33, Go 1.25, object names unchanged, structured logs with request_id/client_id, CI with GitHub Actions.

Additional Notes

• Implementation MUST update server listen address to be configurable and default to :8080.
• Implementation SHOULD wire Huma v2 as the primary router, exposing /openapi.json and the built-in UI. Legacy net/http mux MAY be retained internally if needed during migration.
• Deterministic ordering MUST be enforced for the response body to aid diffability; ETag remains based on the resourceVersions map and is independent of host/path order.

Change History

• 2025-09-15: Specification approved; status set to Approved
• 2025-09-15: Updated response schema and examples to use top-level hosts per ADR-0001 (docs/adr/adr-0001-hosts-top-level-response.md)