From 514748f69c7eb9daeafe911fba211e6508a41d51 Mon Sep 17 00:00:00 2001 From: Saloni Date: Wed, 6 Nov 2024 10:16:10 -0800 Subject: [PATCH 1/2] update api to have minimum one target refs --- apis/v1alpha1/observabilitypolicy_types.go | 3 +- apis/v1alpha2/doc.go | 6 + apis/v1alpha2/observabilitypolicy_types.go | 152 ++++++ apis/v1alpha2/register.go | 41 ++ apis/v1alpha2/zz_generated.deepcopy.go | 144 ++++++ ...teway.nginx.org_observabilitypolicies.yaml | 459 ++++++++++++++++++ deploy/crds.yaml | 459 ++++++++++++++++++ site/content/reference/api.md | 362 ++++++++++++++ 8 files changed, 1625 insertions(+), 1 deletion(-) create mode 100644 apis/v1alpha2/doc.go create mode 100644 apis/v1alpha2/observabilitypolicy_types.go create mode 100644 apis/v1alpha2/register.go create mode 100644 apis/v1alpha2/zz_generated.deepcopy.go diff --git a/apis/v1alpha1/observabilitypolicy_types.go b/apis/v1alpha1/observabilitypolicy_types.go index 6e95d28cc..c4d49930f 100644 --- a/apis/v1alpha1/observabilitypolicy_types.go +++ b/apis/v1alpha1/observabilitypolicy_types.go @@ -7,11 +7,12 @@ import ( // +genclient // +kubebuilder:object:root=true -// +kubebuilder:storageversion +// +kubebuilder:deprecatedversion:warning="The 'v1alpha1' version of ObservabilityPolicy API is deprecated, please migrate to 'v1alpha2'" // +kubebuilder:subresource:status // +kubebuilder:resource:categories=nginx-gateway-fabric,scope=Namespaced // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` // +kubebuilder:metadata:labels="gateway.networking.k8s.io/policy=direct" +//nolint:lll // ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for // the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the diff --git a/apis/v1alpha2/doc.go b/apis/v1alpha2/doc.go new file mode 100644 index 000000000..6e93a89ac --- /dev/null +++ b/apis/v1alpha2/doc.go @@ -0,0 +1,6 @@ +// Package v1alpha2 contains API Schema definitions for the +// gateway.nginx.org API group. +// +// +kubebuilder:object:generate=true +// +groupName=gateway.nginx.org +package v1alpha2 diff --git a/apis/v1alpha2/observabilitypolicy_types.go b/apis/v1alpha2/observabilitypolicy_types.go new file mode 100644 index 000000000..4a7cb0cd2 --- /dev/null +++ b/apis/v1alpha2/observabilitypolicy_types.go @@ -0,0 +1,152 @@ +package v1alpha2 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + gatewayv1alpha2 "sigs.k8s.io/gateway-api/apis/v1alpha2" +) + +// +genclient +// +kubebuilder:object:root=true +// +kubebuilder:storageversion +// +kubebuilder:subresource:status +// +kubebuilder:resource:categories=nginx-gateway-fabric,scope=Namespaced +// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` +// +kubebuilder:metadata:labels="gateway.networking.k8s.io/policy=direct" + +// ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for +// the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the +// GatewayClass parametersRef. +type ObservabilityPolicy struct { + metav1.TypeMeta `json:",inline"` + metav1.ObjectMeta `json:"metadata,omitempty"` + + // Spec defines the desired state of the ObservabilityPolicy. + Spec ObservabilityPolicySpec `json:"spec"` + + // Status defines the state of the ObservabilityPolicy. + Status gatewayv1alpha2.PolicyStatus `json:"status,omitempty"` +} + +// +kubebuilder:object:root=true + +// ObservabilityPolicyList contains a list of ObservabilityPolicies. +type ObservabilityPolicyList struct { + metav1.TypeMeta `json:",inline"` + metav1.ListMeta `json:"metadata,omitempty"` + Items []ObservabilityPolicy `json:"items"` +} + +// ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy. +type ObservabilityPolicySpec struct { + // Tracing allows for enabling and configuring tracing. + // + // +optional + Tracing *Tracing `json:"tracing,omitempty"` + + // TargetRefs identifies the API object(s) to apply the policy to. + // Objects must be in the same namespace as the policy. + // Support: HTTPRoute, GRPCRoute. + // + // +kubebuilder:validation:MinItems=1 + // +kubebuilder:validation:MaxItems=16 + // +kubebuilder:validation:XValidation:message="TargetRef Kind must be: HTTPRoute or GRPCRoute",rule="(self.exists(t, t.kind=='HTTPRoute') || self.exists(t, t.kind=='GRPCRoute'))" + // +kubebuilder:validation:XValidation:message="TargetRef Group must be gateway.networking.k8s.io.",rule="self.all(t, t.group=='gateway.networking.k8s.io')" + //nolint:lll + TargetRefs []gatewayv1alpha2.LocalPolicyTargetReference `json:"targetRefs"` +} + +// Tracing allows for enabling and configuring OpenTelemetry tracing. +// +// +kubebuilder:validation:XValidation:message="ratio can only be specified if strategy is of type ratio",rule="!(has(self.ratio) && self.strategy != 'ratio')" +// +//nolint:lll +type Tracing struct { + // Strategy defines if tracing is ratio-based or parent-based. + Strategy TraceStrategy `json:"strategy"` + + // Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. + // By default, 100% of http requests are traced. Not applicable for parent-based tracing. + // If ratio is set to 0, tracing is disabled. + // + // +optional + // +kubebuilder:validation:Minimum=0 + // +kubebuilder:validation:Maximum=100 + Ratio *int32 `json:"ratio,omitempty"` + + // Context specifies how to propagate traceparent/tracestate headers. + // Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context + // + // +optional + Context *TraceContext `json:"context,omitempty"` + + // SpanName defines the name of the Otel span. By default is the name of the location for a request. + // If specified, applies to all locations that are created for a route. + // Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + // Examples of invalid names: some-$value, quoted-"value"-name, unescaped\ + // + // +optional + // +kubebuilder:validation:MinLength=1 + // +kubebuilder:validation:MaxLength=255 + // +kubebuilder:validation:Pattern=`^([^"$\\]|\\[^$])*$` + SpanName *string `json:"spanName,omitempty"` + + // SpanAttributes are custom key/value attributes that are added to each span. + // + // +optional + // +listType=map + // +listMapKey=key + // +kubebuilder:validation:MaxItems=64 + SpanAttributes []SpanAttribute `json:"spanAttributes,omitempty"` +} + +// SpanAttribute is a key value pair to be added to a tracing span. +type SpanAttribute struct { + // Key is the key for a span attribute. + // Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + // + // +kubebuilder:validation:MinLength=1 + // +kubebuilder:validation:MaxLength=255 + // +kubebuilder:validation:Pattern=`^([^"$\\]|\\[^$])*$` + Key string `json:"key"` + + // Value is the value for a span attribute. + // Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + // + // +kubebuilder:validation:MinLength=1 + // +kubebuilder:validation:MaxLength=255 + // +kubebuilder:validation:Pattern=`^([^"$\\]|\\[^$])*$` + Value string `json:"value"` +} + +// TraceStrategy defines the tracing strategy. +// +// +kubebuilder:validation:Enum=ratio;parent +type TraceStrategy string + +const ( + // TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate. + TraceStrategyRatio TraceStrategy = "ratio" + + // TraceStrategyParent enables tracing and only records spans if the parent span was sampled. + TraceStrategyParent TraceStrategy = "parent" +) + +// TraceContext specifies how to propagate traceparent/tracestate headers. +// +// +kubebuilder:validation:Enum=extract;inject;propagate;ignore +type TraceContext string + +const ( + // TraceContextExtract uses an existing trace context from the request, so that the identifiers + // of a trace and the parent span are inherited from the incoming request. + TraceContextExtract TraceContext = "extract" + + // TraceContextInject adds a new context to the request, overwriting existing headers, if any. + TraceContextInject TraceContext = "inject" + + // TraceContextPropagate updates the existing context (combines extract and inject). + TraceContextPropagate TraceContext = "propagate" + + // TraceContextIgnore skips context headers processing. + TraceContextIgnore TraceContext = "ignore" +) diff --git a/apis/v1alpha2/register.go b/apis/v1alpha2/register.go new file mode 100644 index 000000000..f15729b98 --- /dev/null +++ b/apis/v1alpha2/register.go @@ -0,0 +1,41 @@ +package v1alpha2 + +import ( + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" + "k8s.io/apimachinery/pkg/runtime" + "k8s.io/apimachinery/pkg/runtime/schema" +) + +// GroupName specifies the group name used to register the objects. +const GroupName = "gateway.nginx.org" + +// SchemeGroupVersion is group version used to register these objects. +var SchemeGroupVersion = schema.GroupVersion{Group: GroupName, Version: "v1alpha2"} + +// Resource takes an unqualified resource and returns a Group qualified GroupResource. +func Resource(resource string) schema.GroupResource { + return SchemeGroupVersion.WithResource(resource).GroupResource() +} + +var ( + // SchemeBuilder collects functions that add things to a scheme. It's to allow + // code to compile without explicitly referencing generated types. You should + // declare one in each package that will have generated deep copy or conversion + // functions. + SchemeBuilder = runtime.NewSchemeBuilder(addKnownTypes) + + // AddToScheme applies all the stored functions to the scheme. A non-nil error + // indicates that one function failed and the attempt was abandoned. + AddToScheme = SchemeBuilder.AddToScheme +) + +// Adds the list of known types to Scheme. +func addKnownTypes(scheme *runtime.Scheme) error { + scheme.AddKnownTypes(SchemeGroupVersion, + &ObservabilityPolicy{}, + &ObservabilityPolicyList{}, + ) + // AddToGroupVersion allows the serialization of client types like ListOptions. + metav1.AddToGroupVersion(scheme, SchemeGroupVersion) + return nil +} diff --git a/apis/v1alpha2/zz_generated.deepcopy.go b/apis/v1alpha2/zz_generated.deepcopy.go new file mode 100644 index 000000000..cad2f3726 --- /dev/null +++ b/apis/v1alpha2/zz_generated.deepcopy.go @@ -0,0 +1,144 @@ +//go:build !ignore_autogenerated + +// Code generated by controller-gen. DO NOT EDIT. + +package v1alpha2 + +import ( + "k8s.io/apimachinery/pkg/runtime" + apisv1alpha2 "sigs.k8s.io/gateway-api/apis/v1alpha2" +) + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *ObservabilityPolicy) DeepCopyInto(out *ObservabilityPolicy) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ObjectMeta.DeepCopyInto(&out.ObjectMeta) + in.Spec.DeepCopyInto(&out.Spec) + in.Status.DeepCopyInto(&out.Status) +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ObservabilityPolicy. +func (in *ObservabilityPolicy) DeepCopy() *ObservabilityPolicy { + if in == nil { + return nil + } + out := new(ObservabilityPolicy) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *ObservabilityPolicy) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *ObservabilityPolicyList) DeepCopyInto(out *ObservabilityPolicyList) { + *out = *in + out.TypeMeta = in.TypeMeta + in.ListMeta.DeepCopyInto(&out.ListMeta) + if in.Items != nil { + in, out := &in.Items, &out.Items + *out = make([]ObservabilityPolicy, len(*in)) + for i := range *in { + (*in)[i].DeepCopyInto(&(*out)[i]) + } + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ObservabilityPolicyList. +func (in *ObservabilityPolicyList) DeepCopy() *ObservabilityPolicyList { + if in == nil { + return nil + } + out := new(ObservabilityPolicyList) + in.DeepCopyInto(out) + return out +} + +// DeepCopyObject is an autogenerated deepcopy function, copying the receiver, creating a new runtime.Object. +func (in *ObservabilityPolicyList) DeepCopyObject() runtime.Object { + if c := in.DeepCopy(); c != nil { + return c + } + return nil +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *ObservabilityPolicySpec) DeepCopyInto(out *ObservabilityPolicySpec) { + *out = *in + if in.Tracing != nil { + in, out := &in.Tracing, &out.Tracing + *out = new(Tracing) + (*in).DeepCopyInto(*out) + } + if in.TargetRefs != nil { + in, out := &in.TargetRefs, &out.TargetRefs + *out = make([]apisv1alpha2.LocalPolicyTargetReference, len(*in)) + copy(*out, *in) + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new ObservabilityPolicySpec. +func (in *ObservabilityPolicySpec) DeepCopy() *ObservabilityPolicySpec { + if in == nil { + return nil + } + out := new(ObservabilityPolicySpec) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *SpanAttribute) DeepCopyInto(out *SpanAttribute) { + *out = *in +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new SpanAttribute. +func (in *SpanAttribute) DeepCopy() *SpanAttribute { + if in == nil { + return nil + } + out := new(SpanAttribute) + in.DeepCopyInto(out) + return out +} + +// DeepCopyInto is an autogenerated deepcopy function, copying the receiver, writing into out. in must be non-nil. +func (in *Tracing) DeepCopyInto(out *Tracing) { + *out = *in + if in.Ratio != nil { + in, out := &in.Ratio, &out.Ratio + *out = new(int32) + **out = **in + } + if in.Context != nil { + in, out := &in.Context, &out.Context + *out = new(TraceContext) + **out = **in + } + if in.SpanName != nil { + in, out := &in.SpanName, &out.SpanName + *out = new(string) + **out = **in + } + if in.SpanAttributes != nil { + in, out := &in.SpanAttributes, &out.SpanAttributes + *out = make([]SpanAttribute, len(*in)) + copy(*out, *in) + } +} + +// DeepCopy is an autogenerated deepcopy function, copying the receiver, creating a new Tracing. +func (in *Tracing) DeepCopy() *Tracing { + if in == nil { + return nil + } + out := new(Tracing) + in.DeepCopyInto(out) + return out +} diff --git a/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml b/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml index d55574e35..a38a25e92 100644 --- a/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml +++ b/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml @@ -22,6 +22,9 @@ spec: - jsonPath: .metadata.creationTimestamp name: Age type: date + deprecated: true + deprecationWarning: The 'v1alpha1' version of ObservabilityPolicy API is deprecated, + please migrate to 'v1alpha2' name: v1alpha1 schema: openAPIV3Schema: @@ -470,6 +473,462 @@ spec: - spec type: object served: true + storage: false + subresources: + status: {} + - additionalPrinterColumns: + - jsonPath: .metadata.creationTimestamp + name: Age + type: date + name: v1alpha2 + schema: + openAPIV3Schema: + description: |- + ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for + the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the + GatewayClass parametersRef. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + description: Spec defines the desired state of the ObservabilityPolicy. + properties: + targetRefs: + description: |- + TargetRefs identifies the API object(s) to apply the policy to. + Objects must be in the same namespace as the policy. + Support: HTTPRoute, GRPCRoute. + items: + description: |- + LocalPolicyTargetReference identifies an API object to apply a direct or + inherited policy to. This should be used as part of Policy resources + that can target Gateway API resources. For more information on how this + policy attachment model works, and a sample Policy resource, refer to + the policy attachment documentation for Gateway API. + properties: + group: + description: Group is the group of the target resource. + maxLength: 253 + pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string + kind: + description: Kind is kind of the target resource. + 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 target resource. + maxLength: 253 + minLength: 1 + type: string + required: + - group + - kind + - name + type: object + maxItems: 16 + minItems: 1 + type: array + x-kubernetes-validations: + - message: 'TargetRef Kind must be: HTTPRoute or GRPCRoute' + rule: (self.exists(t, t.kind=='HTTPRoute') || self.exists(t, t.kind=='GRPCRoute')) + - message: TargetRef Group must be gateway.networking.k8s.io. + rule: self.all(t, t.group=='gateway.networking.k8s.io') + tracing: + description: Tracing allows for enabling and configuring tracing. + properties: + context: + description: |- + Context specifies how to propagate traceparent/tracestate headers. + Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context + enum: + - extract + - inject + - propagate + - ignore + type: string + ratio: + description: |- + Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. + By default, 100% of http requests are traced. Not applicable for parent-based tracing. + If ratio is set to 0, tracing is disabled. + format: int32 + maximum: 100 + minimum: 0 + type: integer + spanAttributes: + description: SpanAttributes are custom key/value attributes that + are added to each span. + items: + description: SpanAttribute is a key value pair to be added to + a tracing span. + properties: + key: + description: |- + Key is the key for a span attribute. + Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + maxLength: 255 + minLength: 1 + pattern: ^([^"$\\]|\\[^$])*$ + type: string + value: + description: |- + Value is the value for a span attribute. + Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + maxLength: 255 + minLength: 1 + pattern: ^([^"$\\]|\\[^$])*$ + type: string + required: + - key + - value + type: object + maxItems: 64 + type: array + x-kubernetes-list-map-keys: + - key + x-kubernetes-list-type: map + spanName: + description: |- + SpanName defines the name of the Otel span. By default is the name of the location for a request. + If specified, applies to all locations that are created for a route. + Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + Examples of invalid names: some-$value, quoted-"value"-name, unescaped\ + maxLength: 255 + minLength: 1 + pattern: ^([^"$\\]|\\[^$])*$ + type: string + strategy: + description: Strategy defines if tracing is ratio-based or parent-based. + enum: + - ratio + - parent + type: string + required: + - strategy + type: object + x-kubernetes-validations: + - message: ratio can only be specified if strategy is of type ratio + rule: '!(has(self.ratio) && self.strategy != ''ratio'')' + required: + - targetRefs + type: object + status: + description: Status defines the state of the ObservabilityPolicy. + properties: + ancestors: + description: |- + Ancestors is a list of ancestor resources (usually Gateways) that are + associated with the policy, and the status of the policy with respect to + each ancestor. When this policy attaches to a parent, the controller that + manages the parent and the ancestors MUST add an entry to this list when + the controller first sees the policy and SHOULD update the entry as + appropriate when the relevant ancestor is modified. + + Note that choosing the relevant ancestor is left to the Policy designers; + an important part of Policy design is designing the right object level at + which to namespace this status. + + Note also that implementations MUST ONLY populate ancestor status for + the Ancestor resources they are responsible for. Implementations MUST + use the ControllerName field to uniquely identify the entries in this list + that they are responsible for. + + Note that to achieve this, the list of PolicyAncestorStatus structs + MUST be treated as a map with a composite key, made up of the AncestorRef + and ControllerName fields combined. + + A maximum of 16 ancestors will be represented in this list. An empty list + means the Policy is not relevant for any ancestors. + + If this slice is full, implementations MUST NOT add further entries. + Instead they MUST consider the policy unimplementable and signal that + on any related resources such as the ancestor that would be referenced + here. For example, if this list was full on BackendTLSPolicy, no + additional Gateways would be able to reference the Service targeted by + the BackendTLSPolicy. + items: + description: |- + PolicyAncestorStatus describes the status of a route with respect to an + associated Ancestor. + + Ancestors refer to objects that are either the Target of a policy or above it + in terms of object hierarchy. For example, if a policy targets a Service, the + Policy's Ancestors are, in order, the Service, the HTTPRoute, the Gateway, and + the GatewayClass. Almost always, in this hierarchy, the Gateway will be the most + useful object to place Policy status on, so we recommend that implementations + SHOULD use Gateway as the PolicyAncestorStatus object unless the designers + have a _very_ good reason otherwise. + + In the context of policy attachment, the Ancestor is used to distinguish which + resource results in a distinct application of this policy. For example, if a policy + targets a Service, it may have a distinct result per attached Gateway. + + Policies targeting the same resource may have different effects depending on the + ancestors of those resources. For example, different Gateways targeting the same + Service may have different capabilities, especially if they have different underlying + implementations. + + For example, in BackendTLSPolicy, the Policy attaches to a Service that is + used as a backend in a HTTPRoute that is itself attached to a Gateway. + In this case, the relevant object for status is the Gateway, and that is the + ancestor object referred to in this status. + + Note that a parent is also an ancestor, so for objects where the parent is the + relevant object for status, this struct SHOULD still be used. + + This struct is intended to be used in a slice that's effectively a map, + with a composite key made up of the AncestorRef and the ControllerName. + properties: + ancestorRef: + description: |- + AncestorRef corresponds with a ParentRef in the spec that this + PolicyAncestorStatus struct describes the status of. + properties: + group: + default: gateway.networking.k8s.io + description: |- + Group is the group of the referent. + When unspecified, "gateway.networking.k8s.io" is inferred. + To set the core API group (such as for a "Service" kind referent), + Group must be explicitly set to "" (empty string). + + Support: Core + 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: Gateway + description: |- + Kind is kind of the referent. + + There are two kinds of parent resources with "Core" support: + + * Gateway (Gateway conformance profile) + * Service (Mesh conformance profile, ClusterIP Services only) + + Support for other resources is Implementation-Specific. + 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. + + Support: Core + maxLength: 253 + minLength: 1 + type: string + namespace: + description: |- + Namespace is the namespace of the referent. When unspecified, this refers + to the local namespace of the Route. + + Note that there are specific rules for ParentRefs which cross namespace + boundaries. Cross-namespace references are only valid if they are explicitly + allowed by something in the namespace they are referring to. For example: + Gateway has the AllowedRoutes field, and ReferenceGrant provides a + generic way to enable any other kind of cross-namespace reference. + + + ParentRefs from a Route to a Service in the same namespace are "producer" + routes, which apply default routing rules to inbound connections from + any namespace to the Service. + + ParentRefs from a Route to a Service in a different namespace are + "consumer" routes, and these routing rules are only applied to outbound + connections originating from the same namespace as the Route, for which + the intended destination of the connections are a Service targeted as a + ParentRef of the Route. + + + Support: Core + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ + type: string + port: + description: |- + Port is the network port this Route targets. It can be interpreted + differently based on the type of parent resource. + + When the parent resource is a Gateway, this targets all listeners + listening on the specified port that also support this kind of Route(and + select this Route). It's not recommended to set `Port` unless the + networking behaviors specified in a Route must apply to a specific port + as opposed to a listener(s) whose port(s) may be changed. When both Port + and SectionName are specified, the name and port of the selected listener + must match both specified values. + + + When the parent resource is a Service, this targets a specific port in the + Service spec. When both Port (experimental) and SectionName are specified, + the name and port of the selected port must match both specified values. + + + Implementations MAY choose to support other parent resources. + Implementations supporting other types of parent resources MUST clearly + document how/if Port is interpreted. + + For the purpose of status, an attachment is considered successful as + long as the parent resource accepts it partially. For example, Gateway + listeners can restrict which Routes can attach to them by Route kind, + namespace, or hostname. If 1 of 2 Gateway listeners accept attachment + from the referencing Route, the Route MUST be considered successfully + attached. If no Gateway listeners accept attachment from this Route, + the Route MUST be considered detached from the Gateway. + + Support: Extended + format: int32 + maximum: 65535 + minimum: 1 + type: integer + sectionName: + description: |- + SectionName is the name of a section within the target resource. In the + following resources, SectionName is interpreted as the following: + + * Gateway: Listener name. When both Port (experimental) and SectionName + are specified, the name and port of the selected listener must match + both specified values. + * Service: Port name. When both Port (experimental) and SectionName + are specified, the name and port of the selected listener must match + both specified values. + + Implementations MAY choose to support attaching Routes to other resources. + If that is the case, they MUST clearly document how SectionName is + interpreted. + + When unspecified (empty string), this will reference the entire resource. + For the purpose of status, an attachment is considered successful if at + least one section in the parent resource accepts it. For example, Gateway + listeners can restrict which Routes can attach to them by Route kind, + namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from + the referencing Route, the Route MUST be considered successfully + attached. If no Gateway listeners accept attachment from this Route, the + Route MUST be considered detached from the Gateway. + + Support: Core + maxLength: 253 + minLength: 1 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string + required: + - name + type: object + conditions: + description: Conditions describes the status of the Policy with + respect to the given Ancestor. + items: + description: Condition contains details for one aspect of + the current state of this API Resource. + properties: + lastTransitionTime: + description: |- + lastTransitionTime is the last time the condition transitioned from one status to another. + This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + format: date-time + type: string + message: + description: |- + message is a human readable message indicating details about the transition. + This may be an empty string. + maxLength: 32768 + type: string + observedGeneration: + description: |- + observedGeneration represents the .metadata.generation that the condition was set based upon. + For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date + with respect to the current state of the instance. + format: int64 + minimum: 0 + type: integer + reason: + description: |- + reason contains a programmatic identifier indicating the reason for the condition's last transition. + Producers of specific condition types may define expected values and meanings for this field, + and whether the values are considered a guaranteed API. + The value should be a CamelCase string. + This field may not be empty. + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: type of condition in CamelCase or in foo.example.com/CamelCase. + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + maxItems: 8 + minItems: 1 + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map + controllerName: + description: |- + ControllerName is a domain/path string that indicates the name of the + controller that wrote this status. This corresponds with the + controllerName field on GatewayClass. + + Example: "example.net/gateway-controller". + + The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are + valid Kubernetes names + (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). + + Controllers MUST populate this field when writing status. Controllers should ensure that + entries to status populated with their ControllerName are cleaned up when they are no + longer necessary. + maxLength: 253 + minLength: 1 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$ + type: string + required: + - ancestorRef + - controllerName + type: object + maxItems: 16 + type: array + required: + - ancestors + type: object + required: + - spec + type: object + served: true storage: true subresources: status: {} diff --git a/deploy/crds.yaml b/deploy/crds.yaml index 1e87d7477..a0fafd598 100644 --- a/deploy/crds.yaml +++ b/deploy/crds.yaml @@ -841,6 +841,9 @@ spec: - jsonPath: .metadata.creationTimestamp name: Age type: date + deprecated: true + deprecationWarning: The 'v1alpha1' version of ObservabilityPolicy API is deprecated, + please migrate to 'v1alpha2' name: v1alpha1 schema: openAPIV3Schema: @@ -1289,6 +1292,462 @@ spec: - spec type: object served: true + storage: false + subresources: + status: {} + - additionalPrinterColumns: + - jsonPath: .metadata.creationTimestamp + name: Age + type: date + name: v1alpha2 + schema: + openAPIV3Schema: + description: |- + ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for + the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the + GatewayClass parametersRef. + properties: + apiVersion: + description: |- + APIVersion defines the versioned schema of this representation of an object. + Servers should convert recognized schemas to the latest internal value, and + may reject unrecognized values. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources + type: string + kind: + description: |- + Kind is a string value representing the REST resource this object represents. + Servers may infer this from the endpoint the client submits requests to. + Cannot be updated. + In CamelCase. + More info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds + type: string + metadata: + type: object + spec: + description: Spec defines the desired state of the ObservabilityPolicy. + properties: + targetRefs: + description: |- + TargetRefs identifies the API object(s) to apply the policy to. + Objects must be in the same namespace as the policy. + Support: HTTPRoute, GRPCRoute. + items: + description: |- + LocalPolicyTargetReference identifies an API object to apply a direct or + inherited policy to. This should be used as part of Policy resources + that can target Gateway API resources. For more information on how this + policy attachment model works, and a sample Policy resource, refer to + the policy attachment documentation for Gateway API. + properties: + group: + description: Group is the group of the target resource. + maxLength: 253 + pattern: ^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string + kind: + description: Kind is kind of the target resource. + 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 target resource. + maxLength: 253 + minLength: 1 + type: string + required: + - group + - kind + - name + type: object + maxItems: 16 + minItems: 1 + type: array + x-kubernetes-validations: + - message: 'TargetRef Kind must be: HTTPRoute or GRPCRoute' + rule: (self.exists(t, t.kind=='HTTPRoute') || self.exists(t, t.kind=='GRPCRoute')) + - message: TargetRef Group must be gateway.networking.k8s.io. + rule: self.all(t, t.group=='gateway.networking.k8s.io') + tracing: + description: Tracing allows for enabling and configuring tracing. + properties: + context: + description: |- + Context specifies how to propagate traceparent/tracestate headers. + Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context + enum: + - extract + - inject + - propagate + - ignore + type: string + ratio: + description: |- + Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. + By default, 100% of http requests are traced. Not applicable for parent-based tracing. + If ratio is set to 0, tracing is disabled. + format: int32 + maximum: 100 + minimum: 0 + type: integer + spanAttributes: + description: SpanAttributes are custom key/value attributes that + are added to each span. + items: + description: SpanAttribute is a key value pair to be added to + a tracing span. + properties: + key: + description: |- + Key is the key for a span attribute. + Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + maxLength: 255 + minLength: 1 + pattern: ^([^"$\\]|\\[^$])*$ + type: string + value: + description: |- + Value is the value for a span attribute. + Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + maxLength: 255 + minLength: 1 + pattern: ^([^"$\\]|\\[^$])*$ + type: string + required: + - key + - value + type: object + maxItems: 64 + type: array + x-kubernetes-list-map-keys: + - key + x-kubernetes-list-type: map + spanName: + description: |- + SpanName defines the name of the Otel span. By default is the name of the location for a request. + If specified, applies to all locations that are created for a route. + Format: must have all '"' escaped and must not contain any '$' or end with an unescaped '\' + Examples of invalid names: some-$value, quoted-"value"-name, unescaped\ + maxLength: 255 + minLength: 1 + pattern: ^([^"$\\]|\\[^$])*$ + type: string + strategy: + description: Strategy defines if tracing is ratio-based or parent-based. + enum: + - ratio + - parent + type: string + required: + - strategy + type: object + x-kubernetes-validations: + - message: ratio can only be specified if strategy is of type ratio + rule: '!(has(self.ratio) && self.strategy != ''ratio'')' + required: + - targetRefs + type: object + status: + description: Status defines the state of the ObservabilityPolicy. + properties: + ancestors: + description: |- + Ancestors is a list of ancestor resources (usually Gateways) that are + associated with the policy, and the status of the policy with respect to + each ancestor. When this policy attaches to a parent, the controller that + manages the parent and the ancestors MUST add an entry to this list when + the controller first sees the policy and SHOULD update the entry as + appropriate when the relevant ancestor is modified. + + Note that choosing the relevant ancestor is left to the Policy designers; + an important part of Policy design is designing the right object level at + which to namespace this status. + + Note also that implementations MUST ONLY populate ancestor status for + the Ancestor resources they are responsible for. Implementations MUST + use the ControllerName field to uniquely identify the entries in this list + that they are responsible for. + + Note that to achieve this, the list of PolicyAncestorStatus structs + MUST be treated as a map with a composite key, made up of the AncestorRef + and ControllerName fields combined. + + A maximum of 16 ancestors will be represented in this list. An empty list + means the Policy is not relevant for any ancestors. + + If this slice is full, implementations MUST NOT add further entries. + Instead they MUST consider the policy unimplementable and signal that + on any related resources such as the ancestor that would be referenced + here. For example, if this list was full on BackendTLSPolicy, no + additional Gateways would be able to reference the Service targeted by + the BackendTLSPolicy. + items: + description: |- + PolicyAncestorStatus describes the status of a route with respect to an + associated Ancestor. + + Ancestors refer to objects that are either the Target of a policy or above it + in terms of object hierarchy. For example, if a policy targets a Service, the + Policy's Ancestors are, in order, the Service, the HTTPRoute, the Gateway, and + the GatewayClass. Almost always, in this hierarchy, the Gateway will be the most + useful object to place Policy status on, so we recommend that implementations + SHOULD use Gateway as the PolicyAncestorStatus object unless the designers + have a _very_ good reason otherwise. + + In the context of policy attachment, the Ancestor is used to distinguish which + resource results in a distinct application of this policy. For example, if a policy + targets a Service, it may have a distinct result per attached Gateway. + + Policies targeting the same resource may have different effects depending on the + ancestors of those resources. For example, different Gateways targeting the same + Service may have different capabilities, especially if they have different underlying + implementations. + + For example, in BackendTLSPolicy, the Policy attaches to a Service that is + used as a backend in a HTTPRoute that is itself attached to a Gateway. + In this case, the relevant object for status is the Gateway, and that is the + ancestor object referred to in this status. + + Note that a parent is also an ancestor, so for objects where the parent is the + relevant object for status, this struct SHOULD still be used. + + This struct is intended to be used in a slice that's effectively a map, + with a composite key made up of the AncestorRef and the ControllerName. + properties: + ancestorRef: + description: |- + AncestorRef corresponds with a ParentRef in the spec that this + PolicyAncestorStatus struct describes the status of. + properties: + group: + default: gateway.networking.k8s.io + description: |- + Group is the group of the referent. + When unspecified, "gateway.networking.k8s.io" is inferred. + To set the core API group (such as for a "Service" kind referent), + Group must be explicitly set to "" (empty string). + + Support: Core + 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: Gateway + description: |- + Kind is kind of the referent. + + There are two kinds of parent resources with "Core" support: + + * Gateway (Gateway conformance profile) + * Service (Mesh conformance profile, ClusterIP Services only) + + Support for other resources is Implementation-Specific. + 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. + + Support: Core + maxLength: 253 + minLength: 1 + type: string + namespace: + description: |- + Namespace is the namespace of the referent. When unspecified, this refers + to the local namespace of the Route. + + Note that there are specific rules for ParentRefs which cross namespace + boundaries. Cross-namespace references are only valid if they are explicitly + allowed by something in the namespace they are referring to. For example: + Gateway has the AllowedRoutes field, and ReferenceGrant provides a + generic way to enable any other kind of cross-namespace reference. + + + ParentRefs from a Route to a Service in the same namespace are "producer" + routes, which apply default routing rules to inbound connections from + any namespace to the Service. + + ParentRefs from a Route to a Service in a different namespace are + "consumer" routes, and these routing rules are only applied to outbound + connections originating from the same namespace as the Route, for which + the intended destination of the connections are a Service targeted as a + ParentRef of the Route. + + + Support: Core + maxLength: 63 + minLength: 1 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?$ + type: string + port: + description: |- + Port is the network port this Route targets. It can be interpreted + differently based on the type of parent resource. + + When the parent resource is a Gateway, this targets all listeners + listening on the specified port that also support this kind of Route(and + select this Route). It's not recommended to set `Port` unless the + networking behaviors specified in a Route must apply to a specific port + as opposed to a listener(s) whose port(s) may be changed. When both Port + and SectionName are specified, the name and port of the selected listener + must match both specified values. + + + When the parent resource is a Service, this targets a specific port in the + Service spec. When both Port (experimental) and SectionName are specified, + the name and port of the selected port must match both specified values. + + + Implementations MAY choose to support other parent resources. + Implementations supporting other types of parent resources MUST clearly + document how/if Port is interpreted. + + For the purpose of status, an attachment is considered successful as + long as the parent resource accepts it partially. For example, Gateway + listeners can restrict which Routes can attach to them by Route kind, + namespace, or hostname. If 1 of 2 Gateway listeners accept attachment + from the referencing Route, the Route MUST be considered successfully + attached. If no Gateway listeners accept attachment from this Route, + the Route MUST be considered detached from the Gateway. + + Support: Extended + format: int32 + maximum: 65535 + minimum: 1 + type: integer + sectionName: + description: |- + SectionName is the name of a section within the target resource. In the + following resources, SectionName is interpreted as the following: + + * Gateway: Listener name. When both Port (experimental) and SectionName + are specified, the name and port of the selected listener must match + both specified values. + * Service: Port name. When both Port (experimental) and SectionName + are specified, the name and port of the selected listener must match + both specified values. + + Implementations MAY choose to support attaching Routes to other resources. + If that is the case, they MUST clearly document how SectionName is + interpreted. + + When unspecified (empty string), this will reference the entire resource. + For the purpose of status, an attachment is considered successful if at + least one section in the parent resource accepts it. For example, Gateway + listeners can restrict which Routes can attach to them by Route kind, + namespace, or hostname. If 1 of 2 Gateway listeners accept attachment from + the referencing Route, the Route MUST be considered successfully + attached. If no Gateway listeners accept attachment from this Route, the + Route MUST be considered detached from the Gateway. + + Support: Core + maxLength: 253 + minLength: 1 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$ + type: string + required: + - name + type: object + conditions: + description: Conditions describes the status of the Policy with + respect to the given Ancestor. + items: + description: Condition contains details for one aspect of + the current state of this API Resource. + properties: + lastTransitionTime: + description: |- + lastTransitionTime is the last time the condition transitioned from one status to another. + This should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable. + format: date-time + type: string + message: + description: |- + message is a human readable message indicating details about the transition. + This may be an empty string. + maxLength: 32768 + type: string + observedGeneration: + description: |- + observedGeneration represents the .metadata.generation that the condition was set based upon. + For instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date + with respect to the current state of the instance. + format: int64 + minimum: 0 + type: integer + reason: + description: |- + reason contains a programmatic identifier indicating the reason for the condition's last transition. + Producers of specific condition types may define expected values and meanings for this field, + and whether the values are considered a guaranteed API. + The value should be a CamelCase string. + This field may not be empty. + maxLength: 1024 + minLength: 1 + pattern: ^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$ + type: string + status: + description: status of the condition, one of True, False, + Unknown. + enum: + - "True" + - "False" + - Unknown + type: string + type: + description: type of condition in CamelCase or in foo.example.com/CamelCase. + maxLength: 316 + pattern: ^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$ + type: string + required: + - lastTransitionTime + - message + - reason + - status + - type + type: object + maxItems: 8 + minItems: 1 + type: array + x-kubernetes-list-map-keys: + - type + x-kubernetes-list-type: map + controllerName: + description: |- + ControllerName is a domain/path string that indicates the name of the + controller that wrote this status. This corresponds with the + controllerName field on GatewayClass. + + Example: "example.net/gateway-controller". + + The format of this field is DOMAIN "/" PATH, where DOMAIN and PATH are + valid Kubernetes names + (https://kubernetes.io/docs/concepts/overview/working-with-objects/names/#names). + + Controllers MUST populate this field when writing status. Controllers should ensure that + entries to status populated with their ControllerName are cleaned up when they are no + longer necessary. + maxLength: 253 + minLength: 1 + pattern: ^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$ + type: string + required: + - ancestorRef + - controllerName + type: object + maxItems: 16 + type: array + required: + - ancestors + type: object + required: + - spec + type: object + served: true storage: true subresources: status: {} diff --git a/site/content/reference/api.md b/site/content/reference/api.md index f74d7f984..3053999c6 100644 --- a/site/content/reference/api.md +++ b/site/content/reference/api.md @@ -10,6 +10,9 @@ NGINX Gateway API Reference
  • gateway.nginx.org/v1alpha1
    • +
  • +gateway.nginx.org/v1alpha2 +

    • gateway.nginx.org/v1alpha1

    @@ -2019,6 +2022,365 @@ Examples of invalid names: some-$value, quoted-“value”-name, unescap

    +

    gateway.nginx.org/v1alpha2

    +

    +

    Package v1alpha2 contains API Schema definitions for the +gateway.nginx.org API group.

    +

    +Resource Types: + +

    ObservabilityPolicy + +

    +

    +

    ObservabilityPolicy is a Direct Attached Policy. It provides a way to configure observability settings for +the NGINX Gateway Fabric data plane. Used in conjunction with the NginxProxy CRD that is attached to the +GatewayClass parametersRef.

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +apiVersion
    +string    		 + +gateway.nginx.org/v1alpha2 + +
    +kind
    +string +    		ObservabilityPolicy
    +metadata
    + + +Kubernetes meta/v1.ObjectMeta + + +    		 +Refer to the Kubernetes API documentation for the fields of the +metadata field. +
    +spec
    + + +ObservabilityPolicySpec + + +    		 +

    Spec defines the desired state of the ObservabilityPolicy.

    +
    +
    + + + + + + + + + +
    +tracing
    + + +Tracing + + +    		 +(Optional) +

    Tracing allows for enabling and configuring tracing.

    +
    +targetRefs
    + + +[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference + + +    		 +

    TargetRefs identifies the API object(s) to apply the policy to. +Objects must be in the same namespace as the policy. +Support: HTTPRoute, GRPCRoute.

    +
    +
    +status
    + + +sigs.k8s.io/gateway-api/apis/v1alpha2.PolicyStatus + + +    		 +

    Status defines the state of the ObservabilityPolicy.

    +
    +

    ObservabilityPolicySpec + +

    +

    +(Appears on: +ObservabilityPolicy) +

    +

    +

    ObservabilityPolicySpec defines the desired state of the ObservabilityPolicy.

    +

    + + + + + + + + + + + + + + + + + +
    FieldDescription
    +tracing
    + + +Tracing + + +    		 +(Optional) +

    Tracing allows for enabling and configuring tracing.

    +
    +targetRefs
    + + +[]sigs.k8s.io/gateway-api/apis/v1alpha2.LocalPolicyTargetReference + + +    		 +

    TargetRefs identifies the API object(s) to apply the policy to. +Objects must be in the same namespace as the policy. +Support: HTTPRoute, GRPCRoute.

    +
    +

    SpanAttribute + +

    +

    +(Appears on: +Tracing) +

    +

    +

    SpanAttribute is a key value pair to be added to a tracing span.

    +

    + + + + + + + + + + + + + + + + + +
    FieldDescription
    +key
    + +string + +    		 +

    Key is the key for a span attribute. +Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’

    +
    +value
    + +string + +    		 +

    Value is the value for a span attribute. +Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’

    +
    +

    TraceContext +(string alias)

    +

    +

    +(Appears on: +Tracing) +

    +

    +

    TraceContext specifies how to propagate traceparent/tracestate headers.

    +

    + + + + + + + + + + + + + + + + +
    ValueDescription

    "extract"

    TraceContextExtract uses an existing trace context from the request, so that the identifiers +of a trace and the parent span are inherited from the incoming request.

    +

    "ignore"

    TraceContextIgnore skips context headers processing.

    +

    "inject"

    TraceContextInject adds a new context to the request, overwriting existing headers, if any.

    +

    "propagate"

    TraceContextPropagate updates the existing context (combines extract and inject).

    +
    +

    TraceStrategy +(string alias)

    +

    +

    +(Appears on: +Tracing) +

    +

    +

    TraceStrategy defines the tracing strategy.

    +

    + + + + + + + + + + + + +
    ValueDescription

    "parent"

    TraceStrategyParent enables tracing and only records spans if the parent span was sampled.

    +

    "ratio"

    TraceStrategyRatio enables ratio-based tracing, defaulting to 100% sampling rate.

    +
    +

    Tracing + +

    +

    +(Appears on: +ObservabilityPolicySpec) +

    +

    +

    Tracing allows for enabling and configuring OpenTelemetry tracing.

    +

    + + + + + + + + + + + + + + + + + + + + + + + + + + + + + +
    FieldDescription
    +strategy
    + + +TraceStrategy + + +    		 +

    Strategy defines if tracing is ratio-based or parent-based.

    +
    +ratio
    + +int32 + +    		 +(Optional) +

    Ratio is the percentage of traffic that should be sampled. Integer from 0 to 100. +By default, 100% of http requests are traced. Not applicable for parent-based tracing. +If ratio is set to 0, tracing is disabled.

    +
    +context
    + + +TraceContext + + +    		 +(Optional) +

    Context specifies how to propagate traceparent/tracestate headers. +Default: https://nginx.org/en/docs/ngx_otel_module.html#otel_trace_context

    +
    +spanName
    + +string + +    		 +(Optional) +

    SpanName defines the name of the Otel span. By default is the name of the location for a request. +If specified, applies to all locations that are created for a route. +Format: must have all ‘“’ escaped and must not contain any ‘$’ or end with an unescaped ‘\’ +Examples of invalid names: some-$value, quoted-“value”-name, unescaped

    +
    +spanAttributes
    + + +[]SpanAttribute + + +    		 +(Optional) +

    SpanAttributes are custom key/value attributes that are added to each span.

    +
    +

    Generated with gen-crd-api-reference-docs

    From 3a0391280d9ded9a4ad6b566e9a4bbddbbf92d25 Mon Sep 17 00:00:00 2001 From: Saloni Date: Mon, 11 Nov 2024 11:25:26 -0800 Subject: [PATCH 2/2] update API version for examples --- apis/v1alpha1/observabilitypolicy_types.go | 2 +- config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml | 2 +- deploy/crds.yaml | 2 +- docs/proposals/observability.md | 4 ++-- site/content/how-to/monitoring/tracing.md | 2 +- tests/suite/manifests/tracing/policy-multiple.yaml | 2 +- tests/suite/manifests/tracing/policy-single.yaml | 2 +- 7 files changed, 8 insertions(+), 8 deletions(-) diff --git a/apis/v1alpha1/observabilitypolicy_types.go b/apis/v1alpha1/observabilitypolicy_types.go index c4d49930f..3762bec62 100644 --- a/apis/v1alpha1/observabilitypolicy_types.go +++ b/apis/v1alpha1/observabilitypolicy_types.go @@ -7,7 +7,7 @@ import ( // +genclient // +kubebuilder:object:root=true -// +kubebuilder:deprecatedversion:warning="The 'v1alpha1' version of ObservabilityPolicy API is deprecated, please migrate to 'v1alpha2'" +// +kubebuilder:deprecatedversion:warning="The 'v1alpha1' version of ObservabilityPolicy API is deprecated, please migrate to 'v1alpha2'." // +kubebuilder:subresource:status // +kubebuilder:resource:categories=nginx-gateway-fabric,scope=Namespaced // +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` diff --git a/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml b/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml index a38a25e92..db8bfff40 100644 --- a/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml +++ b/config/crd/bases/gateway.nginx.org_observabilitypolicies.yaml @@ -24,7 +24,7 @@ spec: type: date deprecated: true deprecationWarning: The 'v1alpha1' version of ObservabilityPolicy API is deprecated, - please migrate to 'v1alpha2' + please migrate to 'v1alpha2'. name: v1alpha1 schema: openAPIV3Schema: diff --git a/deploy/crds.yaml b/deploy/crds.yaml index a0fafd598..2a5836f1b 100644 --- a/deploy/crds.yaml +++ b/deploy/crds.yaml @@ -843,7 +843,7 @@ spec: type: date deprecated: true deprecationWarning: The 'v1alpha1' version of ObservabilityPolicy API is deprecated, - please migrate to 'v1alpha2' + please migrate to 'v1alpha2'. name: v1alpha1 schema: openAPIV3Schema: diff --git a/docs/proposals/observability.md b/docs/proposals/observability.md index 67cee1b93..9aaeb9329 100644 --- a/docs/proposals/observability.md +++ b/docs/proposals/observability.md @@ -46,7 +46,7 @@ The `ObservabilityPolicy` API is a CRD that is a part of the `gateway.nginx.org` Below is the Golang API for the `ObservabilityPolicy` API: ```go -package v1alpha1 +package v1alpha2 import ( metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" @@ -148,7 +148,7 @@ type SpanAttribute struct { Below is an example YAML version of an `ObservabilityPolicy`: ```yaml -apiVersion: gateway.nginx.org/v1alpha1 +apiVersion: gateway.nginx.org/v1alpha2 kind: ObservabilityPolicy metadata: name: example-observability-policy diff --git a/site/content/how-to/monitoring/tracing.md b/site/content/how-to/monitoring/tracing.md index 739faa117..0922772d8 100644 --- a/site/content/how-to/monitoring/tracing.md +++ b/site/content/how-to/monitoring/tracing.md @@ -267,7 +267,7 @@ To enable tracing for the coffee HTTPRoute, create the following policy: ```yaml kubectl apply -f - <