Make Istio the primary application edge with explicit NPM legacy passthrough

kiyi commented

2026-09-01 17:18:49 -05:00

Collaborator

Objective

Make the UDS Istio tenant gateway at 10.0.0.241 the primary edge for application traffic while preserving access to applications that still run behind Nginx Proxy Manager (NPM) during the migration.

This issue establishes the ingress transition layer required before the first production application migration. It does not block #6, which can be completed first.

Architecture decisions

Public HTTP/HTTPS forwarding and LAN application DNS will send traffic to the Istio tenant gateway at 10.0.0.241.
The Istio admin gateway at 10.0.0.240 remains LAN-only.
*.dev.gitchegumi.com is owned exclusively by Istio for migration testing.
Migrated production hostnames terminate TLS at Istio and route directly to Kubernetes services.
Known unmigrated production hostnames use TLS/SNI passthrough from Istio to NPM on port 443. NPM continues terminating TLS and routing those applications.
Unknown hostnames are rejected. There will be no unrestricted wildcard fallback to NPM.
Port 80 terminates at Istio and redirects to HTTPS.
The current NPM proxy-host inventory is the authoritative initial legacy allowlist.
As each application migrates, its hostname is removed from the passthrough allowlist and added to its native Istio route.
Existing production hostnames remain unchanged.

Implementation outline

Export and reconcile the current NPM hostname inventory with the migration-plan wiki.
Record the current router/NAT, public DNS, and LAN/hosts-file routing so rollback is explicit.
Represent NPM as a reachable external destination for the tenant gateway using an appropriate Istio ServiceEntry or static Kubernetes service/endpoint.
Configure the tenant gateway for native TLS termination on Istio-owned hosts.
Configure TLS PASSTHROUGH and VirtualService.tls SNI matches for the explicit legacy-host allowlist.
Configure *.dev.gitchegumi.com DNS and certificate coverage for the tenant gateway.
Validate the design before changing the router or production DNS.
Switch LAN DNS and public NAT/forwarding to the tenant gateway.
Validate every legacy NPM hostname through the new Istio edge.
Document the per-application removal and native-route activation procedure.
Retire the passthrough configuration and NPM after the legacy allowlist reaches zero.

Validation matrix

Traffic class	Expected behavior
`<app>.dev.gitchegumi.com`	Istio terminates TLS and routes to the Kubernetes test deployment
Migrated production hostname	Istio terminates TLS and routes to the Kubernetes production service
Explicit legacy hostname	Istio preserves TLS/SNI and passes the connection to NPM
Unknown hostname	Connection is rejected; it is not forwarded to NPM
`*.admin.app.gitchegumi.com`	Routes through the admin gateway on `10.0.0.240` and remains LAN-only

Acceptance criteria

Current NPM hostnames are captured as an explicit legacy allowlist.
NPM is reachable from the tenant gateway as a defined external destination.
*.dev.gitchegumi.com resolves to 10.0.0.241 on the LAN and presents a valid certificate.
At least one test hostname terminates TLS and routes natively through Istio.
Every allowlisted legacy hostname passes through Istio to NPM with its existing certificate and application behavior intact.
An unknown hostname is rejected rather than forwarded.
Public HTTP traffic redirects to HTTPS.
Public NAT/forwarding targets the tenant gateway.
LAN clients reach application hostnames directly through split DNS or explicit local resolution rather than router hairpinning.
The admin gateway remains inaccessible from the public edge.
Existing production hostnames are preserved.
Istio and NPM logs provide enough evidence to distinguish native and passthrough requests.
Rollback to direct NPM ingress is documented and tested to the agreed extent.
The migration-plan wiki documents the final ingress architecture and hostname-removal procedure.

Rollback

Restore the previous router/NAT and LAN DNS destinations so HTTP/HTTPS traffic reaches NPM directly. No NPM Proxy Host is removed until its native Istio replacement has passed validation.

Roadmap relationship

UDS Core deployment and gateway validation in #10 is complete.
#6 is independent and may be completed before this issue.
This issue must be complete before the first production application cutover.
#11 and all application-migration issues should use the resulting *.dev.gitchegumi.com and production-hostname handoff procedure.

## Objective Make the UDS Istio tenant gateway at `10.0.0.241` the primary edge for application traffic while preserving access to applications that still run behind Nginx Proxy Manager (NPM) during the migration. This issue establishes the ingress transition layer required before the first production application migration. It does not block #6, which can be completed first. ## Architecture decisions - Public HTTP/HTTPS forwarding and LAN application DNS will send traffic to the Istio tenant gateway at `10.0.0.241`. - The Istio admin gateway at `10.0.0.240` remains LAN-only. - `*.dev.gitchegumi.com` is owned exclusively by Istio for migration testing. - Migrated production hostnames terminate TLS at Istio and route directly to Kubernetes services. - Known unmigrated production hostnames use TLS/SNI passthrough from Istio to NPM on port 443. NPM continues terminating TLS and routing those applications. - Unknown hostnames are rejected. There will be no unrestricted wildcard fallback to NPM. - Port 80 terminates at Istio and redirects to HTTPS. - The current NPM proxy-host inventory is the authoritative initial legacy allowlist. - As each application migrates, its hostname is removed from the passthrough allowlist and added to its native Istio route. - Existing production hostnames remain unchanged. ## Implementation outline 1. Export and reconcile the current NPM hostname inventory with the migration-plan wiki. 2. Record the current router/NAT, public DNS, and LAN/hosts-file routing so rollback is explicit. 3. Represent NPM as a reachable external destination for the tenant gateway using an appropriate Istio `ServiceEntry` or static Kubernetes service/endpoint. 4. Configure the tenant gateway for native TLS termination on Istio-owned hosts. 5. Configure TLS `PASSTHROUGH` and `VirtualService.tls` SNI matches for the explicit legacy-host allowlist. 6. Configure `*.dev.gitchegumi.com` DNS and certificate coverage for the tenant gateway. 7. Validate the design before changing the router or production DNS. 8. Switch LAN DNS and public NAT/forwarding to the tenant gateway. 9. Validate every legacy NPM hostname through the new Istio edge. 10. Document the per-application removal and native-route activation procedure. 11. Retire the passthrough configuration and NPM after the legacy allowlist reaches zero. ## Validation matrix | Traffic class | Expected behavior | | --- | --- | | `<app>.dev.gitchegumi.com` | Istio terminates TLS and routes to the Kubernetes test deployment | | Migrated production hostname | Istio terminates TLS and routes to the Kubernetes production service | | Explicit legacy hostname | Istio preserves TLS/SNI and passes the connection to NPM | | Unknown hostname | Connection is rejected; it is not forwarded to NPM | | `*.admin.app.gitchegumi.com` | Routes through the admin gateway on `10.0.0.240` and remains LAN-only | ## Acceptance criteria - [x] Current NPM hostnames are captured as an explicit legacy allowlist. - [x] NPM is reachable from the tenant gateway as a defined external destination. - [ ] `*.dev.gitchegumi.com` resolves to `10.0.0.241` on the LAN and presents a valid certificate. - [x] At least one test hostname terminates TLS and routes natively through Istio. - [x] Every allowlisted legacy hostname passes through Istio to NPM with its existing certificate and application behavior intact. - [x] An unknown hostname is rejected rather than forwarded. - [x] Public HTTP traffic redirects to HTTPS. - [ ] Public NAT/forwarding targets the tenant gateway. - [ ] LAN clients reach application hostnames directly through split DNS or explicit local resolution rather than router hairpinning. - [ ] The admin gateway remains inaccessible from the public edge. - [ ] Existing production hostnames are preserved. - [ ] Istio and NPM logs provide enough evidence to distinguish native and passthrough requests. - [ ] Rollback to direct NPM ingress is documented and tested to the agreed extent. - [ ] The migration-plan wiki documents the final ingress architecture and hostname-removal procedure. ## Rollback Restore the previous router/NAT and LAN DNS destinations so HTTP/HTTPS traffic reaches NPM directly. No NPM Proxy Host is removed until its native Istio replacement has passed validation. ## Roadmap relationship - UDS Core deployment and gateway validation in #10 is complete. - #6 is independent and may be completed before this issue. - This issue must be complete before the first production application cutover. - #11 and all application-migration issues should use the resulting `*.dev.gitchegumi.com` and production-hostname handoff procedure.

kiyi added this to the App Migration milestone

2026-09-01 17:18:49 -05:00

kiyi added the

networking

app-migration

security

labels

2026-09-01 17:18:49 -05:00

kiyi self-assigned this

2026-09-01 17:18:49 -05:00

kiyi added this to the Homelab k8s Setup project

2026-09-01 17:18:49 -05:00