feat: add Gateway API controller foundation (GEP-1748)

.github/.copilot/breadcrumbs/2026-08-17-2356-gep-1748-gateway-api.md

@@ -0,0 +1,236 @@
+# GEP-1748 Gateway API Design
+
+## Requirements
+
+- Produce a fresh design focused on Gateway API and the GEP-1748 interaction model.
+- Keep `networking.fleet.azure.com/v1alpha1 ServiceImport` unchanged.
+- Use optional annotations for Azure Front Door, WAF, and Private Link configuration.
+- Identify feasibility and repository ownership.
+- Produce a detailed, tests-first implementation plan.
+- Commit the documentation on a completely new pull request branch using Conventional Commits.
+
+## Additional comments from user
+
+- The design must not migrate to `multicluster.x-k8s.io/ServiceImport`.
+- The public ingress API must not depend on the prior `FrontDoor*` CRD proposal.
+- The working branch is `rchinchani/gep-1748-gateway-api`, created from the latest `origin/main`.
+- The architecture should align with GKE's multi-cluster Gateway requirements where the concepts
+  apply to Fleet and Azure.
+- The user approved proceeding with implementation after the design commit.
+- The user requested PR-scoped E2E coverage for the Gateway API foundation changes.
+- The user selected a managed Fleet hub as a prerequisite for Gateway API integration; hubless
+  Fleet Manager resources are out of scope for this architecture.
+
+## Plan
+
+### Phase 1: Verify current contracts
+
+- [x] **Task 1.1: Review repository instructions and documentation conventions.**
+  - Success criteria: repository-specific design, planning, and breadcrumb requirements are
+    reflected in the documentation.
+- [x] **Task 1.2: Verify ServiceImport and internal export behavior.**
+  - Success criteria: the design accurately preserves the existing ServiceImport group, version,
+    schema, status, and aggregation behavior.
+
+### Phase 2: Create design documentation
+
+- [x] **Task 2.1: Write the architecture design.**
+  - Success criteria: the document covers API boundaries, GEP compatibility, annotations,
+    controllers, AFD/WAF/PLS behavior, status, ownership, security, feasibility, and repository
+    placement.
+- [x] **Task 2.2: Write the implementation plan.**
+  - Success criteria: the plan is phased, tests-first, independently reviewable, and includes
+    measurable completion criteria.
+
+### Phase 3: Validate and commit
+
+- [x] **Task 3.1: Review documentation consistency and git diff.**
+  - Success criteria: links, examples, terminology, and referenced repository paths are coherent,
+    with no unrelated changes.
+- [x] **Task 3.2: Commit the design package.**
+  - Success criteria: the design, plan, and breadcrumb are committed with a detailed Conventional
+    Commit message and required trailers.
+
+### Phase 4: Implement the Gateway foundation
+
+- [x] **Task 4.1: Add Gateway API dependency and scheme tests.**
+  - Success criteria: Gateway, HTTPRoute, ReferenceGrant, and the unchanged Fleet ServiceImport GVK
+    are registered.
+- [x] **Task 4.2: Add typed AFD annotation parsing.**
+  - Success criteria: defaults, supported values, misspellings, malformed values, reserved keys,
+    and cross-resource compatibility are tested.
+- [x] **Task 4.3: Add normalized model primitives.**
+  - Success criteria: listeners, routes, filters, Fleet ServiceImport backends, origins, probes,
+    WAF, deterministic ordering, and weight validation are represented.
+- [x] **Task 4.4: Add the separate hub Gateway manager skeleton.**
+  - Success criteria: the binary registers schemes, validates controller-wide Azure configuration,
+    exposes health/readiness, uses repository-standard structured logging, and registers no
+    reconcilers while the feature is disabled.
+- [x] **Task 4.5: Add public and private configuration documentation.**
+  - Success criteria: separate subsections identify actors and placement for public AFD origins,
+    optional WAF, internal load balancers, PLS, approval, and cleanup.
+- [x] **Task 4.6: Run focused validation.**
+  - Success criteria: unit tests, build, vet, dependency tidy, and diff checks pass. Race validation
+    is delegated to CI because this Windows host does not have a C compiler.
+
+### Phase 5: Add live-cluster Gateway API contract coverage
+
+- [x] **Task 5.1: Document the managed-hub prerequisite and install the supported Gateway API CRDs
+  in the E2E hub.**
+  - Success criteria: the design and configuration guide state that hubless Fleet Manager is
+    ARM-only and unsupported by this architecture, identify upgrading to a managed hub as the
+    supported path, and the E2E bootstrap installs the Gateway API v1.2.1 standard CRDs selected by
+    this PR before tests run.
+- [x] **Task 5.2: Add tests-first Gateway API object builders and scheme registration.**
+  - Success criteria: the E2E client recognizes GatewayClass, Gateway, HTTPRoute, ReferenceGrant,
+    and the unchanged Fleet ServiceImport GVK without duplicating production annotation parsing.
+- [x] **Task 5.3: Add a live API contract E2E scenario.**
+  - Success criteria: a real hub API server accepts and round-trips the Fleet GatewayClass,
+    Gateway annotations, same-namespace and ReferenceGrant-authorized cross-namespace HTTPRoutes,
+    and exact `networking.fleet.azure.com/v1alpha1 ServiceImport` backend references.
+- [ ] **Task 5.4: Validate cleanup and the E2E build path.**
+  - Success criteria: test resources are removed reliably, E2E-tagged packages compile, focused
+    unit tests and vet pass, formatting is clean, and no Azure Front Door programming is claimed
+    before reconcilers exist.
+
+### Detailed checklist
+
+- [x] Phase 1 / Task 1.1 completed.
+- [x] Phase 1 / Task 1.2 completed.
+- [x] Phase 2 / Task 2.1 completed.
+- [x] Phase 2 / Task 2.2 completed.
+- [x] Phase 3 / Task 3.1 completed.
+- [x] Phase 3 / Task 3.2 completed.
+- [x] Phase 4 / Task 4.1 completed.
+- [x] Phase 4 / Task 4.2 completed.
+- [x] Phase 4 / Task 4.3 completed.
+- [x] Phase 4 / Task 4.4 completed.
+- [x] Phase 4 / Task 4.5 completed.
+- [x] Phase 4 / Task 4.6 completed.
+- [x] Phase 5 / Task 5.1 completed.
+- [x] Phase 5 / Task 5.2 completed.
+- [x] Phase 5 / Task 5.3 completed.
+- [ ] Phase 5 / Task 5.4 completed.
+
+### Overall success criteria
+
+- The design is independent of prior AFD CRD branches.
+- Fleet ServiceImport remains unchanged.
+- Gateway API is the only public AFD routing API.
+- Azure-specific options are optional annotations.
+- Formal upstream GEP conformance limitations are explicit.
+- The implementation plan can be delivered as focused follow-up pull requests.
+
+## Decisions
+
+- Keep the Fleet ServiceImport API because existing controllers, users, and status consumers already
+  depend on its group and cluster list.
+- Follow GEP-1748 semantics without claiming upstream Extended conformance, because the GEP names
+  the upstream MCS API group.
+- Use annotations rather than Azure policy CRDs, accepting weaker API-server validation in exchange
+  for a smaller and more portable public API.
+- Compensate for annotation limitations with typed parsing, admission validation, status
+  conditions, and warning events.
+- Put all controller implementation in `fleet-networking`; `fleet` needs only optional examples or
+  placement documentation.
+- Use a separate hub Gateway controller manager to isolate Azure permissions, rollout, failures,
+  and ARM throttling.
+- Require Fleet Manager with a managed hub for Gateway API integration. Hubless Fleet Manager is
+  an ARM grouping and update-orchestration boundary without the Kubernetes configuration plane,
+  MemberCluster resources, ServiceImport aggregation, or controller placement required by this
+  design. Supporting a designated member or external ARM-native control plane requires a separate
+  architecture proposal.
+- Start with direct per-Service member origins; shared per-cluster ingress gateways are deferred.
+- Treat the Fleet hub as the configuration cluster and install the multi-cluster GatewayClass there.
+- Accept only Fleet ServiceImport backends for the multi-cluster GatewayClass, matching GKE's
+  separation between single-cluster and multi-cluster GatewayClasses.
+- Require explicit feature enablement, Fleet/MCS health, managed identity, Azure provider
+  registration, quota readiness, and controller readiness.
+- Fail static during hub/configuration-plane outages or migrations when Azure resource ownership
+  cannot be proven.
+
+## Implementation Details
+
+- `docs/design/gep-1748-gateway-api.md` defines the architecture and compatibility contract.
+- `docs/design/gep-1748-implementation-plan.md` defines the tests-first delivery phases and pull
+  request sequence.
+- Gateway API `v1.2.1` is the selected dependency because it matches Kubernetes `v0.31.1`; newer
+  Gateway API releases require a repository-wide Kubernetes/controller-runtime upgrade.
+- The first implementation slice covers dependency and scheme registration, a separate manager
+  skeleton, typed annotations, and normalized model primitives.
+- The design uses `networking.fleet.azure.com/afd-*` annotations on Gateway and ServiceImport
+  resources.
+- `HTTPRoute.backendRefs` targets the unchanged Fleet ServiceImport group.
+- Per-logical-backend weight uses `HTTPRoute.backendRefs.weight`; per-member-cluster weight retains
+  the existing ServiceExport weight annotation.
+- PLS discovery is transported through internal resources rather than public ServiceImport status.
+- `cmd/hub-gateway-controller-manager` is a separate process with health, readiness, leader
+  election, Gateway API schemes, feature gating, and controller-wide Azure configuration.
+- `pkg/annotations` rejects unknown reserved AFD annotations and invalid explicit values rather
+  than silently applying defaults.
+- `pkg/controllers/hub/gatewaymodel` provides a provider-neutral, deeply copied, deterministic
+  model with distinct Gateway API backend weights and Fleet ServiceExport origin weights.
+
+## Changes Made
+
+- Added a new design directory for the GEP-1748 Gateway API proposal.
+- Added the architecture design.
+- Added the detailed implementation plan.
+- Added a configuration guide with separate public-origin and private
+  internal-load-balancer/PLS subsections, each including optional WAF.
+- Added an actor-and-placement matrix and labeled each configuration step with
+  who applies it and whether it belongs in the Fleet hub, member clusters, or Azure.
+- Documented the private AFD + optional WAF + PLS topology's SFI-NS253 alignment and clarified that
+  public member load balancers are not the SFI-NS253 topology. The foundation PR does not claim
+  compliance until Private Link reconciliation, enforcement, and end-to-end evidence are complete.
+- Added the Gateway API dependency, scheme registration tests, manager skeleton, annotation parser,
+  normalized model, Makefile build target, and focused unit tests.
+- Documented the managed-hub prerequisite and one-way hubless upgrade path in the design and
+  operator guide.
+- Updated the E2E bootstrap to install the Gateway API v1.2.1 standard-channel CRDs selected by
+  `go.mod` on the hub cluster.
+- Registered Gateway API v1 and v1beta1 types in the E2E client scheme and added reusable builders
+  for GatewayClass, Gateway, HTTPRoute, ReferenceGrant, and Fleet ServiceImport resources.
+- Added a live hub API-server contract scenario covering same-namespace and ReferenceGrant-approved
+  cross-namespace Fleet ServiceImport backends, AFD annotation round-tripping, exact backend
+  group/kind/port/weight preservation, and cleanup.
+- The scenario creates backing `InternalServiceExport` resources and waits for the existing hub
+  controllers to derive each `ServiceImport`; it does not create controller-owned imports directly.
+- The E2E-tagged packages compiled successfully before the controller-ownership correction.
+  Formatting, focused tests, vet, and recompilation after that correction are pending because the
+  local execution backend fails before process startup while attempting to change the DACL on
+  `C:\Program Files\nodejs`.
+- Focused tests pass with 81.8% coverage for the manager, 95.1% for annotation parsing, and 89.7%
+  for the normalized model. Race mode could not run locally because `gcc` is not installed; CI
+  will provide race validation.
+- Added this breadcrumb as the decision and documentation trail.
+
+## Before/After Comparison
+
+- **Before:** The main branch had Service export/import and Traffic Manager documentation but no
+  Gateway API global-ingress design.
+- **After:** The branch has a standalone Gateway API design and phased plan for AFD, optional WAF,
+  and optional PLS while preserving Fleet ServiceImport.
+
+## References
+
+- `api/v1alpha1/serviceimport_types.go`: Existing ServiceImport contract.
+- `api/v1alpha1/serviceexport_types.go`: Existing ServiceExport and cluster weight annotation.
+- `api/v1alpha1/internalserviceexport_types.go`: Existing member-to-hub transport.
+- `pkg/controllers/hub/serviceimport/controller.go`: ServiceImport aggregation behavior.
+- `pkg/controllers/hub/trafficmanagerbackend/controller.go`: Existing Azure reconciliation
+  patterns.
+- `cmd/hub-net-controller-manager/main.go`: Existing hub controller process boundary.
+- `docs/concepts/ExportingService/README.md`: Service export/import user model.
+- `docs/concepts/DNSBasedGlobalLoadBalancing/README.md`: Existing global-routing ownership model.
+- `docs/howtos/gateway-api-afd-configuration.md`: Proposed public and Private Link configuration
+  workflow.
+- GEP-1748: <https://gateway-api.sigs.k8s.io/geps/gep-1748/>
+- Gateway API v1.2.1 type definitions:
+  <https://github.com/kubernetes-sigs/gateway-api/blob/v1.2.1/apis/v1/gateway_types.go>
+- GKE multi-cluster Gateway requirements:
+  <https://docs.cloud.google.com/kubernetes-engine/docs/how-to/prepare-environment-multi-cluster-gateways#requirements>
+- Azure Front Door Private Link: <https://learn.microsoft.com/azure/frontdoor/private-link>
+- Azure Front Door WAF: <https://learn.microsoft.com/azure/web-application-firewall/afds/afds-overview>
+- Repository domain knowledge: no files were present under `.github/.copilot/domain_knowledge`.
+- Repository specifications: no files were present under `.github/.copilot/specifications`.

.github/.copilot/breadcrumbs/2026-08-31-1959-e2e-readme-feature-guidance.md

@@ -0,0 +1,101 @@
+# E2E README Feature Guidance
+
+## Requirements
+
+- Update `test/README.md` so local E2E setup is clear and feature-specific.
+- Separate the baseline networking, Azure Traffic Manager (ATM), and Azure Front Door (AFD)
+  requirements and commands.
+- Accurately describe which AFD behavior is testable today.
+- Preserve the existing setup, test, and cleanup workflow.
+
+## Additional comments from user
+
+- The user asked whether the README can be updated separately for ATM and AFD.
+
+## Plan
+
+### Phase 1: Verify the current E2E wiring
+
+- [x] **Task 1.1: Review the E2E README and Makefile entrypoints.**
+  - Success criteria: the guide uses the repository's actual `e2e-setup`, `e2e-tests`,
+    `e2e-collect-logs`, and `e2e-cleanup` targets.
+- [x] **Task 1.2: Review feature gates and CI coverage.**
+  - Success criteria: the guide accurately reflects `AZURE_NETWORK_SETTING`,
+    `ENABLE_TRAFFIC_MANAGER`, and the current AFD contract-test behavior.
+
+### Phase 2: Restructure the local developer guide
+
+- [x] **Task 2.1: Document shared prerequisites and lifecycle.**
+  - Success criteria: common Azure, tool, cluster, test, and cleanup instructions are stated once.
+- [x] **Task 2.2: Add baseline networking and ATM scenarios.**
+  - Success criteria: each scenario provides the exact environment variables, supported network
+    settings, setup command, and test-selection behavior.
+- [x] **Task 2.3: Add the AFD scenario and limitation.**
+  - Success criteria: the guide explains that Gateway API CRDs and the live Kubernetes API contract
+    are covered, while AFD resource reconciliation is not yet implemented or deployed by E2E.
+
+### Phase 3: Review the documentation
+
+- [x] **Task 3.1: Check commands, links, terminology, and diff.**
+  - Success criteria: commands match the scripts and Makefile, ATM and AFD are not conflated, and
+    the resulting diff contains only the README and breadcrumb.
+
+### Detailed checklist
+
+- [x] Phase 1 / Task 1.1 completed.
+- [x] Phase 1 / Task 1.2 completed.
+- [x] Phase 2 / Task 2.1 completed.
+- [x] Phase 2 / Task 2.2 completed.
+- [x] Phase 2 / Task 2.3 completed.
+- [x] Phase 3 / Task 3.1 completed.
+
+### Overall success criteria
+
+- A developer can choose a baseline networking, ATM, or AFD-oriented E2E workflow without guessing
+  which flags apply.
+- The guide does not claim that the current AFD E2E creates or validates Azure Front Door resources.
+- Existing Makefile and script behavior remains unchanged.
+
+## Decisions
+
+- Keep one shared lifecycle and use scenario sections only for differing environment variables and
+  behavior.
+- Describe the current AFD suite as a Gateway API contract scenario because the Gateway manager has
+  no reconcilers yet.
+- Do not introduce new scripts or feature flags in this documentation-only change.
+
+## Implementation Details
+
+- `test/README.md` now has one common lifecycle with separate baseline networking, Traffic Manager,
+  and AFD/Gateway API scenario sections.
+- The AFD section identifies the exact live API resources and backend-reference behavior exercised
+  today.
+- The guide states that real AFD reconciliation requires controller deployment, Azure
+  configuration, validators, status assertions, and cleanup that do not exist yet.
+
+## Changes Made
+
+- Added this breadcrumb as the documentation and decision trail.
+- Expanded prerequisites to cover the tools invoked by the E2E setup.
+- Added feature-specific environment examples and behavior.
+- Added focused Gateway API contract-test execution and log-collection guidance.
+- Reviewed the final documentation diff and confirmed it has no whitespace errors.
+
+## Before/After Comparison
+
+- **Before:** The E2E guide presents Traffic Manager variables as if they apply to every local run
+  and does not explain Gateway API or AFD coverage.
+- **After:** The guide separates shared setup from baseline, ATM, and current AFD contract coverage
+  and explicitly identifies the missing real-AFD reconciliation wiring.
+
+## References
+
+- `test/README.md`: Existing local E2E guide.
+- `Makefile`: E2E setup, execution, log collection, and cleanup targets.
+- `test/scripts/bootstrap.sh`: Network-setting and Traffic Manager feature setup.
+- `test/e2e/e2e_test.go`: Shared E2E suite and Gateway API scheme registration.
+- `test/e2e/traffic_manager_test.go`: Traffic Manager feature gate and Azure validation.
+- `test/e2e/gateway_api_test.go`: Current Gateway API live-cluster contract coverage.
+- `.github/workflows/e2e-tests.yml`: CI scenario matrix.
+- Repository domain knowledge: no files are present under `.github/.copilot/domain_knowledge`.
+- Repository specifications: no files are present under `.github/.copilot/specifications`.

Makefile

@@ -183,9 +183,14 @@ generate: $(CONTROLLER_GEN)
 .PHONY: build
 build: generate fmt vet ## Build binaries.
 	go build -o bin/hub-net-controller-manager cmd/hub-net-controller-manager/main.go
+	go build -o bin/hub-gateway-controller-manager cmd/hub-gateway-controller-manager/main.go
 	go build -o bin/member-net-controller-manager cmd/member-net-controller-manager/main.go
 	go build -o bin/mcs-controller-manager cmd/mcs-controller-manager/main.go
 
+.PHONY: run-hub-gateway-controller-manager
+run-hub-gateway-controller-manager: manifests generate fmt vet ## Run the hub Gateway controller from your host.
+	go run ./cmd/hub-gateway-controller-manager/main.go
+
 .PHONY: run-hub-net-controller-manager
 run-hub-net-controller-manager: manifests generate fmt vet ## Run a controllers from your host.
 	go run ./cmd/hub-net-controller-manager/main.go