Skip to content

Commit f2c147f

Browse files
miledxzmiledxz
committed
Add ObservabilityPolicy CRD (nginx#1848)
Problem: Users want to be able to configure observability settings for their HTTPRoutes, such as tracing. Solution: Add the ObservabilityPolicy CRD, which is a direct policy that will attach to HTTPRoutes to configure these settings. Note: this pR contains the CRD only. A subsequent PR will add the implementation. Also removed some regex restrictions in the NginxProxy CRD.
1 parent e8e1e60 commit f2c147f

8 files changed

+817
-60
lines changed

‎apis/v1alpha1/nginxproxy_types.go

Lines changed: 0 additions & 17 deletions
Original file line numberDiff line numberDiff line change
@@ -88,20 +88,3 @@ type TelemetryExporter struct {
8888
// +kubebuilder:validation:Pattern=`^(?:http?:\/\/)?[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?(?:\.[a-z0-9]([a-z0-9-]{0,61}[a-z0-9])?)*(?::\d{1,5})?$`
8989
Endpoint string `json:"endpoint"`
9090
}
91-
92-
// SpanAttribute is a key value pair to be added to a tracing span.
93-
type SpanAttribute struct {
94-
// Key is the key for a span attribute.
95-
//
96-
// +kubebuilder:validation:MinLength=1
97-
// +kubebuilder:validation:MaxLength=255
98-
// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_-]+$`
99-
Key string `json:"key"`
100-
101-
// Value is the value for a span attribute.
102-
//
103-
// +kubebuilder:validation:MinLength=1
104-
// +kubebuilder:validation:MaxLength=255
105-
// +kubebuilder:validation:Pattern=`^[a-zA-Z0-9_-]+$`
106-
Value string `json:"value"`
107-
}

‎apis/v1alpha1/observabilitypolicy_types.go

Lines changed: 126 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,126 @@
1+
package v1alpha1
2+
3+
import (
4+
metav1 "k8s.io/apimachinery/pkg/apis/meta/v1"
5+
gatewayv1alpha2 "sigs.k8s.io/gateway-api/apis/v1alpha2"
6+
)
7+
8+
// +kubebuilder:object:root=true
9+
// +kubebuilder:storageversion
10+
// +kubebuilder:subresource:status
11+
// +kubebuilder:resource:categories=nginx-gateway-fabric,scope=Namespaced
12+
// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp`
13+
// +kubebuilder:metadata:labels="gateway.networking.k8s.io/policy=direct"
14+
15+
// ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for
16+
// the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the
17+
// GatewayClass parametersRef.
18+
type ObservabilityPolicy struct {
19+
metav1.TypeMeta `json:",inline"`
20+
metav1.ObjectMeta `json:"metadata,omitempty"`
21+
22+
// Spec defines the desired state of the ObservabilityPolicy.
23+
Spec ObservabilityPolicySpec `json:"spec"`
24+
25+
// Status defines the state of the ObservabilityPolicy.
26+
Status gatewayv1alpha2.PolicyStatus `json:"status,omitempty"`
27+
}
28+
29+
// +kubebuilder:object:root=true
30+
31+
// ObservabilityPolicyList contains a list of ObservabilityPolicies.
32+
type ObservabilityPolicyList struct {
33+
metav1.TypeMeta `json:",inline"`
34+
metav1.ListMeta `json:"metadata,omitempty"`
35+
Items []ObservabilityPolicy `json:"items"`
36+
}
37+
38+
// ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.
39+
type ObservabilityPolicySpec struct {
40+
// TargetRef identifies an API object to apply the policy to.
41+
// Object must be in the same namespace as the policy.
42+
//
43+
// Support: HTTPRoute
44+
TargetRef gatewayv1alpha2.PolicyTargetReference `json:"targetRef"`
45+
46+
// Tracing allows for enabling and configuring tracing.
47+
//
48+
// +optional
49+
Tracing *Tracing `json:"tracing,omitempty"`
50+
}
51+
52+
// Tracing allows for enabling and configuring OpenTelemetry tracing.
53+
//
54+
// +kubebuilder:validation:XValidation:message="ratio can only be specified if strategy is of type ratio",rule="!(has(self.ratio) && self.strategy != 'ratio')"
55+
//
56+
//nolint:lll
57+
type Tracing struct {
58+
// Strategy defines if tracing is ratio-based or parent-based.
59+
Strategy TraceStrategy `json:"strategy"`
60+
61+
// Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100.
62+
// By default, 100% of http requests are traced. Not applicable for parent-based tracing.
63+
//
64+
// +optional
65+
// +kubebuilder:validation:Minimum=0
66+
// +kubebuilder:validation:Maximum=100
67+
Ratio *int32 `json:"ratio,omitempty"`
68+
69+
// Context specifies how to propagate traceparent/tracestate headers.
70+
// Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context
71+
//
72+
// +optional
73+
Context *TraceContext `json:"context,omitempty"`
74+
75+
// SpanName defines the name of the Otel span. By default is the name of the location for a request.
76+
// If specified, applies to all locations that are created for a route.
77+
// Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\'
78+
// Examples of invalid names: some-$value, quoted-"value"-name, unescaped\
79+
//
80+
// +optional
81+
// +kubebuilder:validation:MinLength=1
82+
// +kubebuilder:validation:MaxLength=255
83+
// +kubebuilder:validation:Pattern=`^([^"$\\]|\\[^$])*$`
84+
SpanName *string `json:"spanName,omitempty"`
85+
86+
// SpanAttributes are custom key/value attributes that are added to each span.
87+
//
88+
// +optional
89+
// +listType=map
90+
// +listMapKey=key
91+
// +kubebuilder:validation:MaxItems=64
92+
SpanAttributes []SpanAttribute `json:"spanAttributes,omitempty"`
93+
}
94+
95+
// TraceStrategy defines the tracing strategy.
96+
//
97+
// +kubebuilder:validation:Enum=ratio;parent
98+
type TraceStrategy string
99+
100+
const (
101+
// TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate.
102+
TraceStrategyRatio TraceStrategy = "ratio"
103+
104+
// TraceStrategyParent enables tracing and only records spans if the parent span was sampled.
105+
TraceStrategyParent TraceStrategy = "parent"
106+
)
107+
108+
// TraceContext specifies how to propagate traceparent/tracestate headers.
109+
//
110+
// +kubebuilder:validation:Enum=extract;inject;propagate;ignore
111+
type TraceContext string
112+
113+
const (
114+
// TraceContextExtract uses an existing trace context from the request, so that the identifiers
115+
// of a trace and the parent span are inherited from the incoming request.
116+
TraceContextExtract TraceContext = "extract"
117+
118+
// TraceContextInject adds a new context to the request, overwriting existing headers, if any.
119+
TraceContextInject TraceContext = "inject"
120+
121+
// TraceContextPropagate updates the existing context (combines extract and inject).
122+
TraceContextPropagate TraceContext = "propagate"
123+
124+
// TraceContextIgnore skips context headers processing.
125+
TraceContextIgnore TraceContext = "ignore"
126+
)

‎apis/v1alpha1/register.go

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -36,6 +36,8 @@ func addKnownTypes(scheme *runtime.Scheme) error {
3636
&NginxGatewayList{},
3737
&NginxProxy{},
3838
&NginxProxyList{},
39+
&ObservabilityPolicy{},
40+
&ObservabilityPolicyList{},
3941
&ClientSettingsPolicy{},
4042
&ClientSettingsPolicyList{},
4143
)

‎apis/v1alpha1/shared_types.go

Lines changed: 19 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,3 +6,22 @@ package v1alpha1
66
//
77
// +kubebuilder:validation:Pattern=`^\d{1,4}(ms|s)?$`
88
type Duration string
9+
10+
// SpanAttribute is a key value pair to be added to a tracing span.
11+
type SpanAttribute struct {
12+
// Key is the key for a span attribute.
13+
// Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\'
14+
//
15+
// +kubebuilder:validation:MinLength=1
16+
// +kubebuilder:validation:MaxLength=255
17+
// +kubebuilder:validation:Pattern=`^([^"$\\]|\\[^$])*$`
18+
Key string `json:"key"`
19+
20+
// Value is the value for a span attribute.
21+
// Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\'
22+
//
23+
// +kubebuilder:validation:MinLength=1
24+
// +kubebuilder:validation:MaxLength=255
25+
// +kubebuilder:validation:Pattern=`^([^"$\\]|\\[^$])*$`
26+
Value string `json:"value"`
27+
}

‎apis/v1alpha1/zz_generated.deepcopy.go

Lines changed: 115 additions & 0 deletions
Some generated files are not rendered by default. Learn more about customizing how changed files appear on GitHub.

‎config/crd/bases/gateway.nginx.org_nginxproxies.yaml

Lines changed: 8 additions & 4 deletions
Original file line numberDiff line numberDiff line change
@@ -98,16 +98,20 @@ spec:
9898
a tracing span.
9999
properties:
100100
key:
101-
description: Key is the key for a span attribute.
101+
description: |-
102+
Key is the key for a span attribute.
103+
Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\'
102104
maxLength: 255
103105
minLength: 1
104-
pattern: ^[a-zA-Z0-9_-]+$
106+
pattern: ^([^"$\\]|\\[^$])*$
105107
type: string
106108
value:
107-
description: Value is the value for a span attribute.
109+
description: |-
110+
Value is the value for a span attribute.
111+
Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\'
108112
maxLength: 255
109113
minLength: 1
110-
pattern: ^[a-zA-Z0-9_-]+$
114+
pattern: ^([^"$\\]|\\[^$])*$
111115
type: string
112116
required:
113117
- key

0 commit comments

Comments
 (0)