Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

api: gRPC Access Log Service (ALS) sink #3078

Merged
merged 9 commits into from
Apr 15, 2024
Merged

api: gRPC Access Log Service (ALS) sink #3078

Show file tree
Hide file tree
Changes from 7 commits
Commits
Show all changes
9 commits
Select commit Hold shift + click to select a range
5b9ebea
api: gRPC Access Log Service (ALS) logging sink
davidalger Apr 1, 2024
ae5788b
Merge branch 'main' into algerdev/als-sink-api
zirain Apr 2, 2024
1ef9b74
Merge branch 'main' into algerdev/als-sink-api
davidalger Apr 2, 2024
f5c13a3
Make type mandatory and remove kubebuilder default for LogName
davidalger Apr 2, 2024
64890e9
Add CEL validations
davidalger Apr 2, 2024
a32679e
Cleanup
davidalger Apr 2, 2024
21ae2a5
Fix missing type in validation
davidalger Apr 2, 2024
8d9e4e4
Merge branch 'main' into algerdev/als-sink-api
davidalger Apr 11, 2024
dd46082
Pluralize backendRefs
davidalger Apr 11, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
60 changes: 59 additions & 1 deletion api/v1alpha1/accesslogging_types.go
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -62,6 +62,10 @@ type ProxyAccessLogFormat struct {
type ProxyAccessLogSinkType string

const (
// ProxyAccessLogSinkTypeALS defines the gRPC Access Log Service (ALS) sink.
// The service must implement the Envoy gRPC Access Log Service streaming API:
// https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/accesslog/v3/als.proto
ProxyAccessLogSinkTypeALS ProxyAccessLogSinkType = "ALS"
// ProxyAccessLogSinkTypeFile defines the file accesslog sink.
ProxyAccessLogSinkTypeFile ProxyAccessLogSinkType = "File"
// ProxyAccessLogSinkTypeOpenTelemetry defines the OpenTelemetry accesslog sink.
Expand All @@ -73,13 +77,17 @@ const (
// ProxyAccessLogSink defines the sink of accesslog.
// +union
//
// +kubebuilder:validation:XValidation:rule="self.type == 'ALS' ? has(self.als) : !has(self.als)",message="If AccessLogSink type is ALS, als field needs to be set."
davidalger marked this conversation as resolved.
Show resolved Hide resolved
// +kubebuilder:validation:XValidation:rule="self.type == 'File' ? has(self.file) : !has(self.file)",message="If AccessLogSink type is File, file field needs to be set."
// +kubebuilder:validation:XValidation:rule="self.type == 'OpenTelemetry' ? has(self.openTelemetry) : !has(self.openTelemetry)",message="If AccessLogSink type is OpenTelemetry, openTelemetry field needs to be set."
type ProxyAccessLogSink struct {
// Type defines the type of accesslog sink.
// +kubebuilder:validation:Enum=File;OpenTelemetry
// +kubebuilder:validation:Enum=ALS;File;OpenTelemetry
// +unionDiscriminator
Type ProxyAccessLogSinkType `json:"type,omitempty"`
// ALS defines the gRPC Access Log Service (ALS) sink.
// +optional
ALS *ALSEnvoyProxyAccessLog `json:"als,omitempty"`
// File defines the file accesslog sink.
// +optional
File *FileEnvoyProxyAccessLog `json:"file,omitempty"`
Expand All @@ -88,6 +96,56 @@ type ProxyAccessLogSink struct {
OpenTelemetry *OpenTelemetryEnvoyProxyAccessLog `json:"openTelemetry,omitempty"`
}

type ALSEnvoyProxyAccessLogType string

const (
// ALSEnvoyProxyAccessLogTypeHTTP defines the HTTP access log type and will populate StreamAccessLogsMessage.http_logs.
ALSEnvoyProxyAccessLogTypeHTTP ALSEnvoyProxyAccessLogType = "HTTP"
// ALSEnvoyProxyAccessLogTypeTCP defines the TCP access log type and will populate StreamAccessLogsMessage.tcp_logs.
ALSEnvoyProxyAccessLogTypeTCP ALSEnvoyProxyAccessLogType = "TCP"
)

// ALSEnvoyProxyAccessLog defines the gRPC Access Log Service (ALS) sink.
// The service must implement the Envoy gRPC Access Log Service streaming API:
// https://www.envoyproxy.io/docs/envoy/latest/api-v3/service/accesslog/v3/als.proto
// Access log format information is passed in the form of gRPC metadata when the
// stream is established. Specifically, the following metadata is passed:
//
// - `x-accesslog-text` - The access log format string when a Text format is used.
// - `x-accesslog-attr` - JSON encoded key/value pairs when a JSON format is used.
//
// +kubebuilder:validation:XValidation:message="BackendRef only supports Service Kind.",rule="!has(self.backendRef.kind) || self.backendRef.kind == 'Service'"
// +kubebuilder:validation:XValidation:rule="self.type == 'HTTP' || !has(self.http)",message="The http field may only be set when type is HTTP."
type ALSEnvoyProxyAccessLog struct {
// BackendRef references a Kubernetes object that represents the gRPC service to which
// the access logs will be sent. Currently only Service is supported.
BackendRef gwapiv1.BackendObjectReference `json:"backendRef"`
Copy link
Contributor Author

@davidalger davidalger Apr 4, 2024 •
edited
Loading

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

@arkodg given the conversation surrounding #3091 today, would it be preferred to amend this to pluralize now or address with sweeping pass updating all affected areas (including this one) when #3091 is done for everything else?

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

prefer if we wait another day or two to make sure #3091 has majority votes, and a decision is made, and that can be incorporated in this PR

Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

looks like there were enough votes to support pluralizing backendRefs , suggest waiting on #3080 which is trying to create a common BackendRef struct that all APIs can reuse

Copy link
Contributor Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

sounds good, thanks for the followup. will wait on that one to polish this one up

// LogName defines the friendly name of the access log to be returned in
// StreamAccessLogsMessage.Identifier. This allows the access log server
// to differentiate between different access logs coming from the same Envoy.
// +optional
// +kubebuilder:validation:MinLength=1
LogName *string `json:"logName,omitempty"`
// Type defines the type of accesslog. Supported types are "HTTP" and "TCP".
// +kubebuilder:validation:Enum=HTTP;TCP
Type ALSEnvoyProxyAccessLogType `json:"type"`
// HTTP defines additional configuration specific to HTTP access logs.
// +optional
HTTP *ALSEnvoyProxyHTTPAccessLogConfig `json:"http,omitempty"`
}

type ALSEnvoyProxyHTTPAccessLogConfig struct {
// RequestHeaders defines request headers to include in log entries sent to the access log service.
// +optional
RequestHeaders []string `json:"requestHeaders,omitempty"`
// ResponseHeaders defines response headers to include in log entries sent to the access log service.
// +optional
ResponseHeaders []string `json:"responseHeaders,omitempty"`
// ResponseTrailers defines response trailers to include in log entries sent to the access log service.
Copy link
Contributor

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

do you have a use case for trailers atm ?

// +optional
ResponseTrailers []string `json:"responseTrailers,omitempty"`
}

type FileEnvoyProxyAccessLog struct {
// Path defines the file path used to expose envoy access log(e.g. /dev/stdout).
// +kubebuilder:validation:MinLength=1
Expand Down
61 changes: 61 additions & 0 deletions api/v1alpha1/zz_generated.deepcopy.go
View file
Open in desktop

Some generated files are not rendered by default. Learn more about how customized files appear on GitHub.

137 changes: 137 additions & 0 deletions charts/gateway-helm/crds/generated/gateway.envoyproxy.io_envoyproxies.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -5886,6 +5886,139 @@ spec:
description: ProxyAccessLogSink defines the sink of
accesslog.
properties:
als:
description: ALS defines the gRPC Access Log Service
(ALS) sink.
properties:
backendRef:
description: |-
BackendRef references a Kubernetes object that represents the gRPC service to which
the access logs will be sent. Currently only Service is supported.
properties:
group:
default: ""
description: |-
Group is the group of the referent. For example, "gateway.networking.k8s.io".
When unspecified or empty string, core API group is inferred.
maxLength: 253
pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$
type: string
kind:
default: Service
description: |-
Kind is the Kubernetes resource kind of the referent. For example
"Service".


Defaults to "Service" when not specified.


ExternalName services can refer to CNAME DNS records that may live
outside of the cluster and as such are difficult to reason about in
terms of conformance. They also may not be safe to forward to (see
CVE-2021-25740 for more information). Implementations SHOULD NOT
support ExternalName Services.


Support: Core (Services with a type other than ExternalName)


Support: Implementation-specific (Services with type ExternalName)
maxLength: 63
minLength: 1
pattern: ^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$
type: string
name:
description: Name is the name of the referent.
maxLength: 253
minLength: 1
type: string
namespace:
description: |-
Namespace is the namespace of the backend. When unspecified, the local
namespace is inferred.


Note that when a namespace different than the local namespace is specified,
a ReferenceGrant object is required in the referent namespace to allow that
namespace's owner to accept the reference. See the ReferenceGrant
documentation for details.


Support: Core
maxLength: 63
minLength: 1
pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$
type: string
port:
description: |-
Port specifies the destination port number to use for this resource.
Port is required when the referent is a Kubernetes Service. In this
case, the port number is the service port number, not the target port.
For other resources, destination port might be derived from the referent
resource or this field.
format: int32
maximum: 65535
minimum: 1
type: integer
required:
- name
type: object
x-kubernetes-validations:
- message: Must have port for Service reference
rule: '(size(self.group) == 0 && self.kind
== ''Service'') ? has(self.port) : true'
http:
description: HTTP defines additional configuration
specific to HTTP access logs.
properties:
requestHeaders:
description: RequestHeaders defines request
headers to include in log entries sent
to the access log service.
items:
type: string
type: array
responseHeaders:
description: ResponseHeaders defines response
headers to include in log entries sent
to the access log service.
items:
type: string
type: array
responseTrailers:
description: ResponseTrailers defines
response trailers to include in log
entries sent to the access log service.
items:
type: string
type: array
type: object
logName:
description: |-
LogName defines the friendly name of the access log to be returned in
StreamAccessLogsMessage.Identifier. This allows the access log server
to differentiate between different access logs coming from the same Envoy.
minLength: 1
type: string
type:
description: Type defines the type of accesslog.
Supported types are "HTTP" and "TCP".
enum:
- HTTP
- TCP
type: string
required:
- backendRef
- type
type: object
x-kubernetes-validations:
- message: BackendRef only supports Service Kind.
rule: '!has(self.backendRef.kind) || self.backendRef.kind
== ''Service'''
- message: The http field may only be set when
type is HTTP.
rule: self.type == 'HTTP' || !has(self.http)
file:
description: File defines the file accesslog sink.
properties:
Expand Down Expand Up @@ -6009,11 +6142,15 @@ spec:
description: Type defines the type of accesslog
sink.
enum:
- ALS
- File
- OpenTelemetry
type: string
type: object
x-kubernetes-validations:
- message: If AccessLogSink type is ALS, als field
needs to be set.
rule: 'self.type == ''ALS'' ? has(self.als) : !has(self.als)'
- message: If AccessLogSink type is File, file field
needs to be set.
rule: 'self.type == ''File'' ? has(self.file) :
Expand Down
Loading
Loading