feat(helm): support agentgateway ingress

[danehans]

User Story

As a Kubernetes operator using agentgateway, I want OpenShell to create a dedicated Gateway so that I can use agentgateway without deploying Envoy Gateway or maintaining separate ingress manifests.

Problem Statement

OpenShell documents and tests Envoy Gateway as its Kubernetes Gateway API implementation. Agentgateway is not covered by the chart or Kubernetes E2E suite, and its generated proxy Service conflicts with OpenShell's Service when both use the chart's default name.

Impact / Why This Matters

Agentgateway operators must maintain custom Gateway and GRPCRoute manifests and cannot rely on OpenShell's CI coverage. The naming conflict also makes a straightforward GatewayClass override fail.

Proposed Design

Keep the chart controller-neutral while supporting the existing chart-owned Gateway model with agentgateway.

• Let the OpenShell release create a dedicated agentgateway Gateway and GRPCRoute.
• Require a Gateway name distinct from the OpenShell Service, such as openshell-ingress.
• Preserve the existing Envoy Gateway defaults and behavior.
• Generalize Kubernetes E2E gateway selection so the same harness can test Envoy or agentgateway.
• Cover plaintext, HA, frontend TLS termination, and backend TLS re-encryption.
• Document TLS termination, OIDC identity, BackendTLSPolicy behavior, and the naming constraint.
• Keep agentgateway controllers and CRDs outside the OpenShell chart.
• Defer shared, platform-managed Gateway attachment and ListenerSet support to feat(helm): support shared agentgateway Gateway #3715.

Acceptance Criteria

• The chart can create a dedicated agentgateway Gateway with a non-conflicting name.
• The chart rejects an agentgateway Gateway name that conflicts with the OpenShell Service.
• Existing Envoy Gateway values and behavior remain compatible.
• Helm tests cover dedicated HTTP and HTTPS listeners, certificate validation, and the naming constraint.
• Kubernetes E2E covers plaintext, HA, frontend TLS, and backend TLS re-encryption with agentgateway.
• Documentation covers installation, TLS and OIDC boundaries, BackendTLSPolicy, and troubleshooting.
• The OpenShell chart does not install or own agentgateway cluster infrastructure.

Alternatives Considered

• Documentation-only class override: rejected because it does not prevent the Service name collision or provide runtime coverage.
• Bundling agentgateway with the OpenShell chart: rejected because cluster-scoped CRDs and controller lifecycle should remain platform-owned.
• A shared, platform-managed Gateway: deferred to feat(helm): support shared agentgateway Gateway #3715 to keep the initial integration aligned with the existing Envoy topology.
• TLS/TCP passthrough: deferred because it loses gRPC-aware routing and expands the chart surface.

Agent Investigation

Revalidated against OpenShell main at 924486805, agentgateway v1.5.0, and Gateway API v1.6.2.

• The existing Gateway and GRPCRoute templates are portable to agentgateway.
• Agentgateway names its proxy Service after the Gateway, requiring a name distinct from the OpenShell Service.
• PR feat(helm): add BackendTLSPolicy support #2728 added standard BackendTLSPolicy support, which this integration reuses and validates.
• PR feat(helm): add agentgateway ingress support #3714 generalizes Kubernetes E2E gateway selection for Envoy and agentgateway.
• Branch conformance validates dedicated frontend TLS and backend TLS re-encryption.

Checklist

• I have reviewed existing issues and the architecture docs
• This is a design proposal, not a please-build-this request

[matthewgrossman]

📋 triage-agent

Triage Assessment

Classification: feature-valid

Summary

Agentgateway support is feasible without bundling its controller, and the shared-Gateway design keeps the OpenShell chart controller-neutral.

Investigation

The chart renders portable Gateway and GRPCRoute resources, but defaults and documentation are Envoy-specific. templates/grpcroute.yaml has no parent sectionName. Agentgateway provisions a proxy Service for each Gateway using the Gateway name, so a chart-created Gateway named openshell can collide with OpenShell’s existing Service. Closed #2097 and open PR #2108 address different controller/TLS concerns and do not provide this integration.

Recommendation

Keep the issue open. Use a shared Gateway as the production path, require a non-conflicting name for chart-created development Gateways, and validate CLI plus sandbox operations through test:e2e-kubernetes.

[danehans]

/assign

[danehans]

🏗️ build-plan

Implementation Plan

Issue type: feat
Complexity: Medium
Confidence: High

Summary

Keep the chart controller-neutral and attach OpenShell to a shared,
platform-managed agentgateway Gateway. Support plaintext through the
Gateway's existing listener, shared HTTPS through an OpenShell-owned
ListenerSet, and dedicated HTTPS through a direct Gateway listener. Test agentgateway v1.5.0 with Gateway API v1.6.2.

Scope

• Keep the existing Gateway and GRPCRoute defaults compatible with Envoy.
• Add the shared agentgateway Gateway fixture, pinned setup task, Helm overlay,
  readiness checks, diagnostics, documentation, and branch E2E coverage.
• Cover multi-replica routing and pod rotation through agentgateway using the
  existing external PostgreSQL HA fixture.
• Add optional ListenerSet values and a chart template. The ListenerSet,
  certificate Secret, and GRPCRoute remain in the OpenShell namespace while
  the shared Gateway remains in agentgateway-system.
• Configure allowedListeners on the shared Gateway, route the GRPCRoute to the
  ListenerSet, and terminate frontend TLS at agentgateway.
• Reuse standard BackendTLSPolicy for optional backend re-encryption. Do not
  add AgentgatewayPolicy, a second Gateway, or a controller dependency.
• Add a dedicated agentgateway backend TLS overlay, policy readiness checks,
  conformance task, and branch E2E job.
• Add a dedicated chart-owned agentgateway Gateway overlay with a direct HTTPS
  listener, topology assertions, conformance task, and branch E2E job.

Implementation Steps

1. Add shared and dedicated agentgateway routing support without changing the
   existing Envoy path.
2. Add agentgateway setup, plaintext E2E, HA rebalancing coverage, and failure
   diagnostics.
3. Add the optional ListenerSet template, HTTPS values overlay, validation,
   and Helm unit tests.
4. Add a verified-HTTPS conformance task and CI lane using a short-lived test
   certificate.
5. Add dedicated-Gateway HTTPS coverage that verifies no ListenerSet or shared
   Gateway is created.
6. Add backend TLS re-encryption coverage through the standard
   BackendTLSPolicy.
7. Update ingress documentation, generated Helm docs, and cluster debugging
   skills.

Test Plan

• mise run helm:lint
• mise run helm:test
• mise run helm:docs:check
• mise run e2e:kubernetes:agentgateway
• mise run e2e:kubernetes:agentgateway-shared-tls
• mise run e2e:kubernetes:agentgateway-dedicated-tls
• mise run e2e:kubernetes:agentgateway-backend-tls
• mise run e2e:kubernetes:agentgateway-ha-rebalancing
• mise run pre-commit
• mise run ci

The shared frontend TLS E2E requires the ListenerSet and GRPCRoute conditions
to be healthy. The dedicated frontend TLS E2E requires the Gateway and GRPCRoute to be healthy and verifies that no ListenerSet or shared Gateway exists.
Both run status, create, exec, delete, and stop/start lifecycle operations over verified HTTPS. The backend TLS E2E additionally requires the
BackendTLSPolicy to report Accepted=True and ResolvedRefs=True, then runs
the same conformance scenarios over the re-encrypted connection.
HA coverage validates routing while two gateway replicas scale
and rotate.

Documentation Impact

Update the Kubernetes ingress guide, Helm README, contributor Helm environment
skill, and public cluster-debug skill. No gateway TOML or architecture boundary
changes are required.

---

Revision 5 - adds tested dedicated agentgateway HTTPS through a direct chart-owned Gateway listener
Revision 4 - adds tested agentgateway backend TLS re-encryption through the standard BackendTLSPolicy
Revision 3 - adds agentgateway HA coverage and HTTPS termination through a namespace-local ListenerSet on the shared Gateway
Revision 2 - refreshed against main at 62df6462, agentgateway v1.5.0, Gateway API v1.6.2, closed PR #2108, and merged PR #2728
Revision 1 - refreshed against main at eb380d71, agentgateway v1.4.0, #2097, and PR #2108

[github-actions]

This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.

[danehans]

@matthewgrossman when you have a moment, can you PTAL at this issue. I have been vouched, I reviewed the contrib guide, etc. and would like to work on this issue.

[danehans]

@elezar thanks for removing the stale label. Can I be assigned this issue? The agentgateway community is looking forward to integrating with OpenShell.

[github-actions]

This issue has had no activity for 14 days and is now marked stale. It may be closed in 7 days if there is no further activity. Comment or remove the state:stale label to keep it open.