접근 로그

접근 로그 (Access Logs)

이 예제는 앞선 HTTP 예제를 바탕으로, Cilium Gateway API가 관리하는 Gateway에 대한 Envoy 접근 로그(access log)를 구성해요. 접근 로깅은 CiliumGatewayClassConfig 리소스의 spec.telemetry.accessLogs 필드로 관리돼요.

출처: Access Logs

본문

접근 로깅은 CiliumGatewayClassConfig 리소스 안의 spec.telemetry.accessLogs 필드를 통해 관리돼요. 이 구성은 GatewayClass 리소스가 spec.parametersRef로 참조하므로, 여기서 정의한 모든 설정은 해당 Gateway Class를 사용하는 모든 Gateway에 자동으로 적용돼요.

Cilium은 Envoy가 접근 로그를 stdout으로 쓰도록 구성해줘요.

구성 옵션 (Configuration Options)

접근 로그를 구성할 때 format 필드는 필수예요. 다음 매개변수로 로그 출력을 커스터마이즈할 수 있어요:

  • format (필수): 로그 출력 유형을 정의해요. 지원 값은 Text 또는 JSON이에요.
  • text (선택): 커스텀 Envoy 텍스트 포맷 문자열이에요. format: Text를 선택했지만 이 필드를 비워두면 Cilium은 기본 Envoy 텍스트 포맷으로 폴백해요.
  • json (선택): 커스텀 JSON 필드 이름을 Envoy 포맷 연산자에 연결하는 key-value 맵이에요. format: JSON을 선택했지만 이 필드를 비워두면 Cilium은 기본 Envoy 텍스트 포맷의 정보를 그대로 반영한 사전 구성된 JSON 템플릿을 적용해요.

참고

이 기본 JSON 매핑은 Cilium이 제공하는 것이지 Envoy의 내장 기본값이 아니에요.

  • targets (선택): 로그로 남길 트래픽 유형을 지정해요. 지원 값은 HTTP와 TCP(TLS 패스스루 포함)예요. 생략하면 Cilium은 기본적으로 HTTP 트래픽만 로그로 남겨요.

커스텀 Cilium 포맷터 (Custom Cilium formatters)

표준 Envoy 연산자 외에도 Cilium은 트래픽의 출처를 식별하는 데 도움이 되는 두 가지 Gateway 전용 포맷터를 제공해요:

  • %CILIUM_GATEWAY_NAMESPACE%는 Gateway의 네임스페이스로 해석돼요.
  • %CILIUM_GATEWAY_NAME%는 Gateway의 이름으로 해석돼요.

그 밖의 모든 포맷 연산자의 전체 목록은 공식 Envoy 접근 로그 치환 포맷터 문서를 참고해주세요.

접근 로그가 있는 Gateway 배포하기 (Deploy a Gateway with access logs)

HTTP 트래픽에 대한 JSON 접근 로그를 활성화하는 CiliumGatewayClassConfig를 만들어볼게요:

apiVersion: cilium.io/v2alpha1
kind: CiliumGatewayClassConfig
metadata:
  name: cilium
  namespace: default
spec:
  telemetry:
    accessLogs:
    - format: JSON
      json:
        gateway: "%CILIUM_GATEWAY_NAMESPACE%/%CILIUM_GATEWAY_NAME%"
        start_time: "%START_TIME%"
        method: "%REQUEST_HEADER(:METHOD)%"
        path: "%REQUEST_HEADER(X-ENVOY-ORIGINAL-PATH?:PATH)%"
        protocol: "%PROTOCOL%"
        response_code: "%RESPONSE_CODE%"
        response_flags: "%RESPONSE_FLAGS%"
        bytes_received: "%BYTES_RECEIVED%"
        bytes_sent: "%BYTES_SENT%"
        duration: "%DURATION%"
        authority: "%REQUEST_HEADER(:AUTHORITY)%"
        upstream_host: "%UPSTREAM_HOST%"

CiliumGatewayClassConfig 리소스를 참조하도록 GatewayClass를 업데이트해볼게요:

apiVersion: gateway.networking.k8s.io/v1
kind: GatewayClass
metadata:
  name: cilium
spec:
  controllerName: io.cilium/gateway-controller
  parametersRef:
    group: cilium.io
    kind: CiliumGatewayClassConfig
    name: cilium
    namespace: default

GatewayClass 구성이 수락됐는지 확인해볼게요:

$ kubectl get ciliumgatewayclassconfig cilium
NAME     ACCEPTED   AGE
cilium   True       33s

Gateway를 통해 요청을 보내볼게요:

$ GATEWAY=$(kubectl get gateway my-gateway -o jsonpath='{.status.addresses[0].value}')
$ curl --fail -s http://"$GATEWAY"/details/1 | jq

접근 로그 확인하기 (Verify access logs)

Gateway 네임스페이스와 이름이 포함된 접근 로그 항목이 있는지 Envoy stdout 로그를 확인해볼게요.

$ kubectl -n kube-system logs -l app.kubernetes.io/name=cilium-envoy,app.kubernetes.io/part-of=cilium | grep default/my-gateway
{"authority":"172.18.255.193","bytes_received":0,"bytes_sent":178,"duration":8,"gateway":"default/my-gateway","method":"GET","path":"/details/1","protocol":"HTTP/1.1","response_code":200,"response_flags":"-","start_time":"2026-07-06T10:10:13.622Z","upstream_host":"10.244.0.221:9080"}

HTTP와 TCP 트래픽 로그 남기기 (Log HTTP and TCP traffic)

HTTP와 TCP 프록시 트래픽 양쪽 모두에 대한 접근 로그를 남기려면 두 대상을 모두 설정해주세요:

spec:
  telemetry:
    accessLogs:
    - format: Text
      text: '[%START_TIME%] %CILIUM_GATEWAY_NAMESPACE%/%CILIUM_GATEWAY_NAME% "%REQUEST_HEADER(:METHOD)% %REQUEST_HEADER(X-ENVOY-ORIGINAL-PATH?:PATH)% %PROTOCOL%" %RESPONSE_CODE% %DURATION%'
      targets:
      - HTTP
      - TCP

여러 접근 로그 항목이 같은 대상을 사용할 수도 있어요. Envoy는 일치하는 각 구성마다 로그 항목 하나를 출력하므로, 중복 구성은 중복된 로그 줄을 만들어내요.

더 알아보기 (Learn more)