api: add ClientCertificateRef field to ExtensionTLS for mTLS support

[wenfengp]

What type of PR is this?

api: add ClientCertificateRef field to ExtensionTLS for mTLS support

Implementation will in a separate PR #6777 after this API PR get approved

What this PR does / why we need it:

This PR adds mutual TLS (mTLS) support for Extension Servers by introducing a new optional ClientCertificateRef field to the ExtensionTLS struct.

Changes:

• Add ClientCertificateRef field to ExtensionTLS struct in api/v1alpha1/envoygateway_types.go
• Update validation logic to handle client certificate references
• Generate corresponding deepcopy methods via make kube-generate
• Update API documentation to reflect mTLS capabilities

Background:
Currently, Envoy Gateway only supports server certificate validation when connecting to extension servers. Many enterprise environments require mutual TLS authentication where the extension server also validates the client (Envoy Gateway) certificate for enhanced security.

API Design:

• ClientCertificateRef is optional, maintaining full backwards compatibility
• References a Kubernetes TLS secret containing both tls.crt and tls.key
• When specified, enables mutual TLS authentication with the extension server
• When not specified, only server certificate validation is performed (existing behavior)

Example Usage:

spec:
  extensionManager:
    service:
      tls:
        # Existing field for server cert validation
        certificateRef:
          kind: Secret
          name: extension-server-ca-cert
        # New field for client cert authentication (mTLS)
        clientCertificateRef:
          kind: Secret
          name: envoy-gateway-client-cert

This API change enables enterprise security requirements while maintaining zero breaking changes for existing users.

Which issue(s) this PR fixes:

Fixes # #5155

Release Notes: Yes

[codecov]

Codecov Report

❌ Patch coverage is 70.00000% with 3 lines in your changes missing coverage. Please review.
✅ Project coverage is 71.09%. Comparing base (6307de9) to head (16ad739).
⚠️ Report is 2 commits behind head on main.

Files with missing lines	Patch %	Lines
api/v1alpha1/validation/envoygateway_validate.go	70.00%	2 Missing and 1 partial ⚠️

Additional details and impacted files

@@            Coverage Diff             @@
##             main    #6674      +/-   ##
==========================================
+ Coverage   71.04%   71.09%   +0.04%     
==========================================
  Files         225      225              
  Lines       39795    39798       +3     
==========================================
+ Hits        28274    28296      +22     
+ Misses       9854     9840      -14     
+ Partials     1667     1662       -5     

☔ View full report in Codecov by Sentry.
📢 Have feedback on the report? Share it here.

🚀 New features to boost your workflow:

• ❄️ Test Analytics: Detect flaky tests, report on failures, and find test suite problems.
• 📦 JS Bundle Analysis: Save yourself from yourself by tracking and limiting bundle sizes in JS merges.

[nareddyt]

@wenfengp run make gen-check

[wenfengp]

Implementation PR: #6777

[arkodg]

LGTM thanks

[guydc]

LGTM

[wenfengp]

e2e test failed, seems flaky, updated branch.

1. e2e-test (v1.30.13, ipv4, default)

--- FAIL: TestEGUpgrade (157.67s)
    --- FAIL: TestEGUpgrade/EnvoyShutdown (85.07s)
        --- FAIL: TestEGUpgrade/EnvoyShutdown/All_requests_must_succeed (85.06s)
        utils.go:278: 2025-08-13T22:10:17.819937151Z: failed to create load: error -1 for http://172.18.0.205/envoy-shutdown (0 bytes)
        utils.go:287: 2025-08-13T22:10:17.81995826Z: Load completed after 0s with 2 requests, 0 success, 2 failures and 2 errors

2. e2e-test (v1.33.1, dual, default)

=== RUN   TestE2E/WasmOCIImageCodeSource/http_route_without_wasm
    utils.go:362: 2025-08-13T22:07:07.097185646Z: EnvoyExtensionPolicy has been accepted: &{TypeMeta:{Kind: APIVersion:} ObjectMeta:{Name:oci-wasm-source-test GenerateName: Namespace:gateway-conformance-infra SelfLink: UID:0ae6fb62-3380-4b95-bafa-ea6e33d3213c ResourceVersion:12308 Generation:1 CreationTimestamp:2025-08-13 22:07:06 +0000 UTC DeletionTimestamp:<nil> DeletionGracePeriodSeconds:<nil> Labels:map[] Annotations:map[] OwnerReferences:[] Finalizers:[] ManagedFields:[{Manager:envoy-gateway Operation:Update APIVersion:gateway.envoyproxy.io/v1alpha1 Time:2025-08-13 22:07:06 +0000 UTC FieldsType:FieldsV1 FieldsV1:{"f:status":{".":{},"f:ancestors":{}}} Subresource:status} {Manager:gateway-api-conformance.test::v1.3.0::WasmOCIImageCodeSource::unknownFeature Operation:Update APIVersion:gateway.envoyproxy.io/v1alpha1 Time:2025-08-13 22:07:06 +0000 UTC FieldsType:FieldsV1 FieldsV1:{"f:spec":{".":{},"f:targetRefs":{},"f:wasm":{}}} Subresource:}]} Spec:{PolicyTargetReferences:{TargetRef:<nil> TargetRefs:[{LocalPolicyTargetReference:{Group:gateway.networking.k8s.io Kind:HTTPRoute Name:http-with-oci-wasm-source} SectionName:<nil>}] TargetSelectors:[]} Wasm:[{Name:0xc001932980 RootID:0xc001932990 Code:{Type:Image HTTP:<nil> Image:0xc001d8a150 PullPolicy:<nil>} Config:nil FailOpen:0xc001bafbbb Env:<nil>}] ExtProc:[] Lua:[]} Status:{Ancestors:[{AncestorRef:{Group:0xc0019329a0 Kind:0xc0019329b0 Namespace:0xc0019329c0 Name:same-namespace SectionName:<nil> Port:<nil>} ControllerName:gateway.envoyproxy.io/gatewayclass-controller Conditions:[{Type:Accepted Status:True ObservedGeneration:1 LastTransitionTime:2025-08-13 22:07:06 +0000 UTC Reason:Accepted Message:Policy has been accepted.}]}]}}
    helpers.go:611: 2025-08-13T22:07:07.101147648Z: Conditions matched expectations
    helpers.go:611: 2025-08-13T22:07:07.101185108Z: Route gateway-conformance-infra/http-without-wasm Parents matched expectations
    wasm_oci.go:164: 2025-08-13T22:07:07.103175727Z: Making GET request to http://172.18.0.203/no-wasm
    roundtripper.go:219: 2025-08-13T22:07:07.103347859Z: Sending Request:
        < GET /no-wasm HTTP/1.1
        < Host: www.example.com
        < User-Agent: Go-http-client/1.1
        < X-Echo-Set-Header: 
        < Accept-Encoding: gzip
        < 
        < 
        
        
    roundtripper.go:235: 2025-08-13T22:07:07.104005398Z: Received Response:
        < HTTP/1.1 503 Service Unavailable
        < Connection: close
        < Date: Wed, 13 Aug 2025 22:07:06 GMT
        < Content-Length: 0
        < 
        <