Log Service

By default, Emissary puts the access logs on stdout; such that the can be read using kubectl logs. The format of those logs, and the local destination of them, can be configured using the envoy_log_ settings in the ambassador Module. However, the options there only allow for logging local to Emissary’s Pod. By configuring a LogService, you can configure Emissary to report its access logs to a remote service, in addition to the usual ambassador Module configured logging.

The remote access log service (or ALS) must implement the AccessLogService gRPC interface, defined in Envoy’s als.proto.

---
apiVersion: getambassador.io/v3alpha1
kind: LogService
metadata:
  name: example-log-service
spec:
  # Common to all Emissary resources
  ambassador_id: []string           # optional; default is ["default"]

  # LogService specific
  service: "string"                 # required
  driver: "enum-string:[tcp, http]" # required
  driver_config:                    # required
    additional_log_headers:           # optional; default is [] (only for `driver: http`)
    - header_name: string               # required
      during_request: boolean           # optional; default is true
      during_response: boolean          # optional; default is true
      during_trailer: boolean           # optional; default is true
  flush_interval_time: int-seconds  # optional; default is 1
  flush_interval_byte_size: integer # optional; default is 16384
  grpc: boolean                     # optional; default is false
  protocol_version: enum            # optional; default is v2

• service is where to route the access log gRPC requests to

• driver identifies which type of accesses to log; HTTP requests ("http") or TLS connections ("tcp").

• driver_config stores the configuration that is specific to the driver:

  • driver: tcp has no additional configuration; the config must be set as driver_config: {}.

  • driver: http

    • additional_log_headers identifies HTTP headers to include in the access log, and when in the logged-request’s lifecycle to include them.

• flush_interval_time is the maximum number of seconds to buffer accesses for before sending them to the ALS. The logs will be flushed to the ALS every time this duration is reached, or when the buffered data reaches flush_interval_byte_size, whichever comes first. See the Envoy documentation on buffer_flush_interval for more information.

• flush_interval_byte_size is a soft size limit for the access log buffer. The logs will be flushed to the ALS every time the buffered data reaches this size, or whenever flush_interval_time elapses, whichever comes first. See the Envoy documentation on buffer_size_bytes for more information.

• grpc must be true.

• protocol_version was used in previous versions of Emissary to control the gRPC service name used to communicate with the LogService. Emissary 3.x is running an updated version of Envoy that has dropped support for the v2 protocol, so starting in 3.x, if protocol_version is not specified, the default value of v2 will cause an error to be posted and a static response will be returned. Therefore, you must set it to protocol_version: v3. If upgrading from a previous version, you will want to set it to v3 and ensure it is working before upgrading to Emissary 3.Y. The default value for protocol_version remains v2 in the getambassador.io/v3alpha1 CRD specifications to avoid making breaking changes outside of a CRD version change. Future versions of CRD’s will deprecate it.

Example

---
apiVersion: getambassador.io/v3alpha1
kind: LogService
metadata:
  name: als
spec:
  service: "als.default:3000"
  driver: http
  driver_config: {}  # NB: driver_config must be set, even if it's empty
  grpc: true         # NB: grpc must be true and it will use the V3 transport protocol

Transport Protocol Migration

Note: The following information is only applicable to AuthServices using proto: grpc As of Emissary version 2.3, the v2 transport protocol is deprecated and any AuthServices making use of it should migrate to v3 before support for v2 is removed in a future release.

The following imports simply need to be updated to migrate an AuthService

v2 Imports:

	envoyCoreV2 "github.com/datawire/ambassador/pkg/api/envoy/api/v2/core"
	envoyAuthV2 "github.com/datawire/ambassador/pkg/api/envoy/service/auth/v2"
	envoyType "github.com/datawire/ambassador/pkg/api/envoy/type"

v3 Imports:

	envoyCoreV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/config/core/v3"
	envoyAuthV3 "github.com/datawire/ambassador/v2/pkg/api/envoy/service/auth/v3"
	envoyType "github.com/datawire/ambassador/v2/pkg/api/envoy/type/v3"