Documentation
Security
Access logging

Access logging

Capture an access log for all the requests that enter the gateway.

About access logging

Access logs, sometimes referred to as audit logs, represent all traffic requests that pass through the gateway proxy. The access log entries can be customized to include data from the request, the routing destination, and the response.

Access logs can be written to a file, the stdout stream of the gateway proxy container, or exported to a gRPC server for custom handling. The access logs capture information from requests that the Envoy HttpConnectionManager in your gateway proxy handles.

Envoy data that can be logged

Envoy exposes a lot of data that can be used when customizing access logs. The following data properties are available for both TCP and HTTP access logging:

  • The downstream (client) address, connection information, TLS configuration, and timing
  • The backend (service) address, connection information, TLS configuration, timing, and Envoy routing information
  • Relevant Envoy configuration, such as rate of sampling (if used)
  • Filter-specific context that is published to Envoy’s dynamic metadata during the filter chain

Additional HTTP properties

When Envoy is used as an HTTP proxy, additional HTTP information is available for access logging, including:

  • Request data, including the method, path, scheme, port, user agent, headers, body, and more
  • Response data, including the response code, headers, body, and trailers, as well as a string representation of the response code
  • Protocol version

Before you begin

  1. Follow the Get started guide to install kgateway.

  2. Follow the Sample app guide to create an API gateway proxy with an HTTP listener and deploy the httpbin sample app.

  3. Get the external address of the gateway and save it in an environment variable. 

    export INGRESS_GW_ADDRESS=$(kubectl get svc -n kgateway-system http -o jsonpath="{.status.loadBalancer.ingress[0]['hostname','ip']}")
echo $INGRESS_GW_ADDRESS  
    kubectl port-forward deployment/http -n kgateway-system 8080:8080

Access logs to stdout

You can set up access logs to write to a standard (stdout/stderr) stream. The following example writes access logs to a stdout in the pod of the selected http gateway.

  1. Create an HTTPListenerPolicy resource to define your access logging rules. The following example writes access logs to the stdout stream of the gateway proxy container by using a custom string format that is defined in the jsonFormat field.

    kubectl apply -f- <<EOF
apiVersion: gateway.kgateway.dev/v1alpha1
kind: HTTPListenerPolicy
metadata:
  name: access-logs
  namespace: kgateway-system
spec:
  targetRefs:
  - group: gateway.networking.k8s.io
    kind: Gateway
    name: http
  accessLog:
  - fileSink:
      path: /dev/stdout
      jsonFormat:
          start_time: "%START_TIME%"
          method: "%REQ(X-ENVOY-ORIGINAL-METHOD?:METHOD)%"
          path: "%REQ(X-ENVOY-ORIGINAL-PATH?:PATH)%"
          protocol: "%PROTOCOL%"
          response_code: "%RESPONSE_CODE%"
          response_flags: "%RESPONSE_FLAGS%"
          bytes_received: "%BYTES_RECEIVED%"
          bytes_sent: "%BYTES_SENT%"
          total_duration: "%DURATION%"
          resp_backend_service_time: "%RESP(X-ENVOY-UPSTREAM-SERVICE-TIME)%"
          req_x_forwarded_for: "%REQ(X-FORWARDED-FOR)%"
          user_agent: "%REQ(USER-AGENT)%"
          request_id: "%REQ(X-REQUEST-ID)%"
          authority: "%REQ(:AUTHORITY)%"
          backendHost: "%UPSTREAM_HOST%"
          backendCluster: "%UPSTREAM_CLUSTER%"
EOF
    Setting Description
    targetRefs Select the Gateway to enable access logging for. The example selects the http gateway that you created from the sample app guide.
    accessLog Configure the details for access logging. You can use multiple fileSink configurations for multiple outputs. The example sets up a fileSink for standard logging (stdout) in JSON format at /dev/stdout. You can also send the access logs to a grpcService instead of fileSink.
    path The path in the gateway proxy to write access logs to, such as /dev/stdout.
    jsonFormat The structured JSON format to write logs in. For more information about the JSON format dictionaries and command operators you can use, see the Envoy docs. To format as a string, use the stringFormat setting instead. If you omit or leave this setting blank, the Envoy default format string is used.
    stringFormat The string format to write logs in. For more information about the string format and command operators you can use, see the Envoy docs. To format as JSON, use the jsonFormat setting instead. If you omit or leave this setting blank, the Envoy default format string is used.

  2. Send a request to the httpbin app on the www.example.com domain. Verify that your request succeeds and that you get back a 200 HTTP response code.

    curl -i http://$INGRESS_GW_ADDRESS:8080/status/200 -H "host: www.example.com:8080"
    curl -i localhost:8080/status/200 -H "host: www.example.com:8080"

    Example output:

    HTTP/1.1 200 OK
access-control-allow-credentials: true
access-control-allow-origin: *
date: Fri, 07 Jun 2024 21:10:03 GMT
x-envoy-upstream-service-time: 2
server: envoy
transfer-encoding: chunked

  3. Get the logs for the gateway pod and verify that you see a stdout JSON entry for each request that you sent to the httpbin app.

    kubectl -n kgateway-system logs deployments/http | tail -1 | jq --sort-keys

    Example output:

    {
  "authority": "www.example.com:8080",
  "bytes_received": 0,
  "bytes_sent": 0,
  "method": "GET",
  "path": "/status/200",
  "protocol": "HTTP/1.1",
  "req_x_forwarded_for": null,
  "request_id": "a6758866-0f26-4c95-95d9-4032c365c498",
  "resp_backend_service_time": "0",
  "response_code": 200,
  "response_flags": "-",
  "start_time": "2024-08-19T20:57:57.511Z",
  "total_duration": 1,
  "backendCluster": "kube-svc:httpbin-httpbin-8000_httpbin",
  "backendHost": "10.36.0.14:8080",
  "user_agent": "curl/7.77.0"
}

Cleanup

You can remove the resources that you created in this guide. 
kubectl delete HTTPListenerPolicy access-logs -n kgateway-system
External auth