ProjectContour中Envoy自定义请求头日志配置实践

在云原生应用开发中，日志记录是系统可观测性的重要组成部分。ProjectContour作为Kubernetes的Ingress控制器，使用Envoy作为数据平面代理，其访问日志的定制化配置对于运维和调试至关重要。本文将深入探讨如何为Envoy配置自定义请求头日志记录。

传统配置方式

在早期版本的Contour中，日志格式通过ConfigMap进行配置。典型配置示例如下：

apiVersion: v1
kind: ConfigMap
metadata:
  name: contour
  namespace: projectcontour
data:
  contour.yaml: |
    accesslog-format: envoy
    accesslog-format-string: "[%START_TIME%] \"%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%\" %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% \"%REQ(X-FORWARDED-FOR)%\" \"%REQ(USER-AGENT)%\" \"%REQ(X-REQUEST-ID)%\" \"%REQ(x-custom-header)%\" \"%REQ(:AUTHORITY)%\" \"%UPSTREAM_HOST%\"\n"

这种配置方式需要注意：

1. 使用%REQ(header-name)%语法引用请求头
2. 修改后需要重启Contour控制器Pod使配置生效
3. 日志格式字符串需要正确转义引号

Gateway Provisioner模式下的新配置方式

随着Gateway API的普及，Contour提供了基于Gateway Provisioner的部署模式。在这种模式下，配置方式发生了显著变化：

1. 通过ContourDeployment CRD定义全局配置
2. 使用runtimeSettings指定Envoy运行时参数
3. 日志格式直接在CRD中声明

典型配置示例：

apiVersion: projectcontour.io/v1alpha1
kind: ContourDeployment
metadata:
  name: contour
  namespace: projectcontour
spec:
  envoy:
    networkPublishing:
      type: NodePortService
  runtimeSettings:
    envoy:
      logging:
        accessLogFormatString: |
          [%START_TIME%] "%REQ(:METHOD)% %REQ(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" 
          %RESPONSE_CODE% %RESPONSE_FLAGS% %BYTES_RECEIVED% %BYTES_SENT% %DURATION% 
          %RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)% "%REQ(X-FORWARDED-FOR)%" 
          "%REQ(USER-AGENT)%" "%REQ(X-REQUEST-ID)%" "%REQ(x-custom-header)%" 
          "%REQ(:AUTHORITY)%" "%UPSTREAM_HOST%"

配置验证与调试技巧

为确保自定义请求头日志正常工作，建议采用以下验证流程：

1. 确认配置已正确应用到ContourConfig资源

kubectl get contourconfig -n projectcontour -o yaml

2. 发送包含自定义头的测试请求

curl -H "x-custom-header: test-value" http://service.example.com

3. 检查Envoy日志输出

kubectl logs -l app=envoy -n projectcontour -c envoy

常见问题解决

1. 日志中缺少自定义头：

   • 确认请求确实包含该头
   • 检查头名称大小写是否匹配
   • 验证配置是否已正确应用到运行中的Envoy实例

2. 配置未生效：

   • 在Gateway Provisioner模式下，确保通过ContourDeployment配置而非ConfigMap
   • 检查相关GatewayClass的parametersRef引用是否正确

3. 日志格式错误：

   • 确保字符串中的引号正确转义
   • 避免在格式字符串中使用未定义或无效的变量

最佳实践建议

1. 为重要的业务请求头配置日志记录，如跟踪ID、用户标识等
2. 保持日志格式的一致性，便于后续日志分析
3. 在生产环境变更前，先在测试环境验证日志配置
4. 考虑日志量的影响，避免记录过多不必要的信息

通过合理配置Envoy的访问日志，可以极大提升系统的可观测性，为故障排查和性能分析提供有力支持。随着Contour的演进，建议用户逐步迁移到Gateway Provisioner模式，以获得更现代化的配置体验。