First-Class Istio Egress Gateway Support in Big Bang
## Description
Redefining this epic as many things have changed since the original creation of this epic.
# Enable First-Class Istio Egress Gateway Support
## Description
Big Bang can deploy an Istio gateway labeled as an `egressgateway`, and bb-common can create outbound `ServiceEntry` resources. However, Big Bang does not yet provide an end-to-end method for routing package traffic through an egress gateway and preventing direct external access.
This epic will provide an opt-in, supported configuration for routing approved package egress through one or more Istio egress gateways.
## Benefits
* Centralizes outbound traffic for monitoring and auditing.
* Allows access to external destinations by workload identity or namespace.
* Supports dedicated egress nodes, NAT addresses, firewalls, and cloud security groups.
* Prevents workloads from directly reaching unapproved external services when combined with network policies.
* Provides a consistent configuration model across Big Bang packages.
* Makes external package dependencies more visible for restricted and air-gapped environments.
## Current Gaps
* Outbound routes cannot select a named egress gateway.
* Required `VirtualService` and `DestinationRule` resources are not generated automatically.
* Existing gateway network-policy logic is primarily ingress-oriented.
* There is no enforcement preventing workloads from bypassing the gateway.
* There is no end-to-end CI validation or complete operator documentation.
* Support expectations for Istio ambient mode are undefined.
## Requirements / Scope
* Support one or more named egress gateways through `istioGateway.values.gateways`.
* Extend bb-common `routes.outbound` so a route can select an egress gateway.
* Generate the required Istio resources:
* `Gateway`
* `ServiceEntry`
* `VirtualService`
* `DestinationRule`, where required
* Initially support HTTPS/TLS traffic, with other protocols documented as supported or unsupported.
* Support multiple routes, packages, and gateways without naming conflicts.
* Support gateway scaling, resources, node selection, tolerations, affinity, and disruption budgets.
* Add optional network-policy enforcement that:
* Allows selected workloads to reach the egress gateway.
* Allows the gateway to reach configured destination CIDRs and ports.
* Blocks workloads from directly reaching external destinations.
* Support optional `AuthorizationPolicy` rules restricting gateway access by workload identity or namespace.
* Preserve existing behavior when egress gateway support is disabled.
* Use current bb-common APIs such as `routes.outbound`; do not build new functionality on legacy `istio.hardened` values.
* Document configuration, security limitations, observability, high availability, and troubleshooting.
* Determine whether ambient mode will be supported in this epic or tracked separately.
Example configuration:
```yaml
istioGateway:
values:
gateways:
outbound:
upstream:
labels:
istio: egressgateway
addons:
examplePackage:
values:
routes:
outbound:
external-api:
enabled: true
hosts:
- api.example.com
ports:
- number: 443
name: tls
protocol: TLS
egressGateway:
enabled: true
name: outbound`
```
The final values structure will be determined during implementation.
## Acceptance Criteria
* Big Bang can deploy one or more named egress gateways.
* A bb-common outbound route can select a named gateway.
* Required Istio routing resources are generated automatically.
* Approved traffic successfully reaches its destination through the gateway.
* Undeclared destinations fail when `REGISTRY_ONLY` is enabled.
* Direct external access fails when network-policy enforcement is enabled.
* Unauthorized workloads are rejected when authorization enforcement is enabled.
* Multiple packages and gateways can be configured without conflicts.
* Existing deployments are unaffected when the feature is disabled.
* Clean-install and upgrade pipelines cover the supported configuration.
* Positive and negative end-to-end tests are included.
* Sidecar and ambient-mode support boundaries are documented.
* Operator documentation and an example configuration are published.
## Out of Scope
* General-purpose forward proxy or web-filter functionality.
* Deep packet inspection.
* Automatic discovery or approval of external destinations.
* Managing external NAT gateways, firewalls, route tables, or security groups.
* FQDN enforcement using standard Kubernetes `NetworkPolicy`.
* Enabling egress gateways for every package by default.
* UDP and ICMP traffic.
## Risks / Considerations
* `REGISTRY_ONLY` alone is not a security boundary; network or infrastructure controls are required to prevent bypass.
* Standard Kubernetes network policies operate on IP addresses, not FQDNs.
* Centralizing egress introduces a potential availability and capacity bottleneck.
* TLS passthrough limits application-level authorization and observability.
* Ambient-mode behavior may require a different implementation than sidecar mode.
## Estimated Effort
Approximately 3–4 sprints, including bb-common changes, gateway updates, testing, package validation, and documentation.
The generic gateway and bb-common work can likely be completed sooner, but claiming support across all Big Bang packages requires an audit of package outbound dependencies, representative integrations, negative-path testing, documentation, and upgrade validation.
epic