Design Document: HTTP/2 h2c Support for AWS ALB Integration (PR #1394)

[starlightromero]

Design Document: HTTP/2 h2c Support for AWS ALB Integration

Related PR: #1394

Overview

This design document provides comprehensive documentation for the HTTP/2 cleartext (h2c) protocol support implementation in the KEDA HTTP Add-on interceptor. This enhancement enables AWS Application Load Balancers and other clients to communicate with the interceptor using HTTP/2 over plain HTTP connections.

Problem Statement

When using the AWS Load Balancer Controller Gateway API implementation, setting appProtocol: kubernetes.io/h2c on a Kubernetes Service instructs the controller to create ALB target groups with ProtocolVersion: HTTP2. However, the KEDA HTTP Add-on interceptor did not support h2c, causing health checks and traffic to fail.

Solution Overview

The implementation wraps non-TLS handlers with h2c support, which automatically:

• Handles HTTP/2 connections with prior knowledge (what ALBs use)
• Falls back to HTTP/1.1 for standard requests
• Requires no configuration changes in Kubernetes manifests

Architecture

Current vs Proposed Architecture

Current:

• HTTP/1.1 over plain HTTP
• HTTP/2 over TLS (native Go support)

Proposed:

• HTTP/1.1 over plain HTTP (unchanged)
• HTTP/2 over TLS (unchanged)
• HTTP/2 cleartext (h2c) over plain HTTP (new)

Component Integration

┌─────────────────┐    ┌──────────────────┐    ┌─────────────────┐
│   AWS ALB       │    │   Interceptor    │    │  Target App     │
│                 │    │                  │    │                 │
│ HTTP/2 Target   ├────┤  h2c Handler     ├────┤ HTTP/1.1 or     │
│ Groups          │    │  (New)           │    │ HTTP/2          │
│                 │    │                  │    │                 │
│ HTTP/1.1 Target ├────┤  Standard        ├────┤                 │
│ Groups          │    │  Handler         │    │                 │
└─────────────────┘    └──────────────────┘    └─────────────────┘

Technical Implementation

Modified Components

HTTP Server (pkg/http/server.go)

func ServeContext(ctx context.Context, addr string, hdl http.Handler, tlsConfig *tls.Config) error {
    // For non-TLS connections, wrap handler with h2c to support HTTP/2 cleartext
    if tlsConfig == nil {
        h2s := &http2.Server{}
        hdl = h2c.NewHandler(hdl, h2s)
    }
    // ... rest of implementation
}

Test Suite (pkg/http/h2c_test.go)

• HTTP/1.1 compatibility verification
• HTTP/2 h2c functionality validation
• Protocol negotiation testing

Protocol Compatibility

Request Flow Matrix

Client Protocol	Server Support	Result
HTTP/1.1	h2c enabled	HTTP/1.1 (fallback)
HTTP/2 h2c	h2c enabled	HTTP/2
HTTP/1.1	HTTP/1.1 only	HTTP/1.1
HTTP/2 h2c	HTTP/1.1 only	Connection error

Negotiation Behavior

• TLS Connections: Native HTTP/2 via ALPN
• Non-TLS Connections: h2c with HTTP/1.1 fallback
• Prior Knowledge: ALB uses HTTP/2 with prior knowledge

Benefits

Performance Improvements

• Multiplexing: Multiple requests over single connection
• Header Compression: Reduced bandwidth usage with HPACK
• Server Push: Potential for proactive resource delivery
• Binary Protocol: More efficient parsing than HTTP/1.1

AWS Integration

• Native ALB Support: Works with appProtocol: kubernetes.io/h2c
• Health Checks: ALB health checks work over HTTP/2
• Target Groups: Supports ProtocolVersion: HTTP2 configuration
• Performance: Improved ALB → Interceptor communication efficiency

Backward Compatibility

Guaranteed Compatibility

• ✅ Existing HTTP/1.1 clients continue to work unchanged
• ✅ TLS-based HTTP/2 connections remain unaffected
• ✅ No configuration changes required for existing deployments
• ✅ Graceful fallback for unsupported clients

Migration Path

1. Deploy updated interceptor with h2c support
2. Update ALB target group configuration to use HTTP/2
3. Verify health checks and traffic flow
4. Monitor performance and error rates

Testing Strategy

Test Coverage

• Unit Tests: Protocol-specific request handling
• Integration Tests: ALB → Interceptor → Backend flows
• E2E Tests: Complete request lifecycle validation
• Performance Tests: HTTP/1.1 vs HTTP/2 benchmarking

Test Scenarios

• HTTP/1.1 client → h2c server
• h2c client → HTTP/1.1 backend
• Mixed protocol environments
• Error conditions and fallback behavior
• Concurrent connection handling

Security Considerations

Protocol Security

• h2c provides same application-level security as HTTP/1.1
• No additional authentication or authorization changes required
• Existing security policies remain effective

Attack Surface Analysis

• No new attack vectors introduced
• Standard HTTP/2 security considerations apply
• Existing rate limiting and filtering remain effective

Monitoring and Observability

Recommended Metrics

• Protocol distribution (HTTP/1.1 vs HTTP/2 requests)
• Connection establishment success rates
• Protocol negotiation failures
• Performance comparison between protocols

Logging Enhancements

• Protocol version for each request
• h2c negotiation events
• Fallback occurrences
• Error conditions and recovery

Alternative Approaches Considered

1. External Proxy Solution

Approach: Use external proxy (nginx, envoy) for h2c termination

• Pros: Mature, battle-tested solutions
• Cons: Additional complexity, deployment overhead, performance impact
• Decision: Rejected in favor of native implementation

2. Configuration-Based h2c

Approach: Make h2c support configurable via flags/environment variables

• Pros: Explicit control, easier debugging
• Cons: Additional configuration complexity, potential misconfiguration
• Decision: Rejected in favor of automatic detection

3. Separate h2c Service

Approach: Deploy separate service for h2c handling

• Pros: Clear separation of concerns, independent scaling
• Cons: Increased operational complexity, additional network hops
• Decision: Rejected in favor of integrated solution

Implementation Status

This design document addresses PR #1394 which implements the h2c support. The implementation includes:

• ✅ Core h2c handler implementation
• ✅ HTTP/1.1 backward compatibility
• ✅ Basic test coverage
• 🔄 Addressing review feedback (in progress)
• 🔄 Enhanced test coverage (planned)
• 🔄 Documentation updates (planned)

Review Comments Resolution

The following review comments from PR #1394 are being addressed:

1. Use Standard Library HTTP/2: Investigating Go 1.24's native HTTP/2 support
2. Protocol Compatibility: Documenting HTTP/1.1 ↔ h2c interaction behavior
3. Dynamic Port Allocation: Updating tests to use automatic port assignment
4. TLS Configuration Clarity: Adding detailed comments for h2c client setup
5. End-to-End Testing: Implementing comprehensive e2e test matrix

Usage Examples

Kubernetes Service Configuration

apiVersion: v1
kind: Service
metadata:
  name: keda-add-ons-http-interceptor-proxy
  annotations:
    service.beta.kubernetes.io/aws-load-balancer-type: "nlb"
spec:
  ports:
  - name: http
    port: 8080
    protocol: TCP
    appProtocol: kubernetes.io/h2c  # Enables HTTP/2 target groups
  selector:
    app: keda-add-ons-http-interceptor

ALB Target Group Configuration

apiVersion: elbv2.k8s.aws/v1beta1
kind: TargetGroupBinding
metadata:
  name: interceptor-tgb
spec:
  serviceRef:
    name: keda-add-ons-http-interceptor-proxy
    port: 8080
  targetGroupARN: arn:aws:elasticloadbalancing:region:account:targetgroup/name/id
  # ALB Controller automatically sets ProtocolVersion: HTTP2 based on appProtocol

Future Enhancements

Potential Improvements

• HTTP/3 Support: Consider QUIC protocol support for future versions
• Advanced Multiplexing: Optimize connection pooling for high-throughput scenarios
• Metrics Enhancement: Add detailed HTTP/2-specific metrics and dashboards
• Configuration Options: Add optional fine-tuning parameters for advanced users

Performance Optimizations

• Connection Reuse: Optimize HTTP/2 connection lifecycle management
• Memory Management: Tune HTTP/2 frame handling for memory efficiency
• Compression Tuning: Optimize HPACK compression settings for typical workloads

Conclusion

The HTTP/2 h2c support enhancement enables seamless integration with AWS Application Load Balancers while maintaining full backward compatibility. This implementation provides immediate performance benefits through HTTP/2's advanced features while requiring no configuration changes for existing deployments.

The design prioritizes simplicity, reliability, and performance, ensuring that the KEDA HTTP Add-on can effectively serve as a bridge between modern load balancing infrastructure and diverse backend applications.

---

Links:

• Implementation PR: feat(interceptor): add HTTP/2 h2c support for cleartext connections #1394
• Related Issues: This design document
• Documentation: KEDA HTTP Add-on Docs