XTelemetryPolicy
gateway.networking.x-k8s.io / v1alpha1
apiVersion: gateway.networking.x-k8s.io/v1alpha1
kind: XTelemetryPolicy
metadata:
name: example
apiVersion
string
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
kind
string
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
metadata
object
spec object required
Spec defines the desired state of TelemetryPolicy.
targetRefs []object required
TargetRefs identifies the gateways to which this policy applies (GEP-713).
When configured, the telemetry settings defined in this policy are applied
uniformly to the referenced resources. In the absence of targetRefs, the policy is
invalid and will not be accepted.
TargetRefs must be distinct.
Support: Core for Gateway
minItems:
1maxItems:
16
group
string required
Group is the group of the referent. For example, "gateway.networking.k8s.io".
When unspecified or empty string, core API group is inferred.
pattern:
^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$maxLength:
253
kind
string required
Kind is kind of the referent. For example "HTTPRoute" or "Service".
pattern:
^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$minLength:
1maxLength:
63
name
string required
Name is the name of the referent.
minLength:
1maxLength:
253tracing object
Tracing defines the configuration for distributed tracing.
When configured, distributed tracing spans are generated and exported. In the
absence of this configuration, tracing behavior is determined by implementation
defaults.
Support: Extended
Feature Name: TelemetryPolicyTracing
attributes []object
Attributes is a list of custom key-value pairs (or variables) attached to every span.
When configured, these attributes are injected into every generated tracing span.
In the absence of attributes, only standard proxy-defined attributes are emitted.
Support: Extended
attributeKey
string
AttributeKey refers to a standard OpenTelemetry attribute.
For example: "http.response.status_code" or "http.request.method".
This is required if SourceType is "Attribute".
See: https://opentelemetry.io/docs/specs/semconv/
pattern:
^[a-z0-9_.-]+$minLength:
1maxLength:
256
headerName
string
HeaderName specifies the HTTP header to extract the value from.
This is required if SourceType is "Header".
pattern:
^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$minLength:
1maxLength:
256
literalValue
string
LiteralValue specifies a static string value to attach.
This is required if SourceType is "Literal".
minLength:
1maxLength:
1024
name
string required
Name is the key of the attribute as it will appear in the output
(i.e., as a span tag).
pattern:
^[a-zA-Z0-9_.:/-]+$minLength:
1maxLength:
256
sourceType
string required
SourceType specifies where the attribute value comes from.
Valid values are "Header", "Literal", or "Attribute".
enum:
Header, Literal, Attribute
mode
string
Mode explicitly controls if tracing is enabled. Valid values are "Enabled", "Disabled",
"ImplementationDefault".
In the absence of this field, it defaults to "ImplementationDefault".
Support: Core (within TelemetryPolicy feature)
enum:
Enabled, Disabled, ImplementationDefaultparentBasedSampling object
ParentBasedSampling configures whether to respect the sampling decision of the parent span.
* When Mode is "Enabled", the proxy will respect the upstream trace parent's sampling
decision.
* When Mode is "Disabled", the proxy ignores the upstream trace parent's sampling
decision and applies its own local sampling rate decision.
* When Mode is "ImplementationDefault" or absent, the implementation's default behavior
is used.
Support: Extended
Feature Name: TelemetryPolicyParentBasedSampling
mode
string
Mode explicitly controls if parent-based sampling is enabled. Valid values are "Enabled",
"Disabled", "ImplementationDefault".
In the absence of this field, it defaults to "ImplementationDefault".
Support: Extended
enum:
Enabled, Disabled, ImplementationDefaultsamplingRate object
SamplingRate is the sampling rate to apply when parent-based sampling is active.
This acts as a downsampling governor. It allows an operator to say: "I want to
respect the parent's decision, but only for 50% of those requests". Even if a
parent is already marked as "Sampled", this allows the Gateway to apply a secondary
filter so that it can respect the parent's intent while still controlling the volume
of spans reported.
When Mode is "Enabled" and this field is absent, a 100% sampling rate
({numerator: 100, denominator: 100}) is used.
Support: Extended
denominator
integer
format:
int32minimum:
1
numerator
integer required
format:
int32minimum:
0provider object
Provider specifies the tracing collector or backend endpoint receiving OTLP spans.
When configured, spans generated by the Gateway proxy are exported to this destination.
This field is required when Mode is "Enabled", and must not be set otherwise.
Support: Core (within Tracing feature)
backendRef object required
BackendRef is a reference to a Kubernetes Service or other supported
backend that receives OTLP traces.
When configured, tracing data is exported to the referenced backend.
Cross-namespace references are only valid if they are explicitly allowed
by ReferenceGrant in the target namespace.
If the reference is invalid (e.g., the Service does not exist, has an
unsupported Group or Kind, or is a cross-namespace reference not permitted
by a ReferenceGrant), the implementation MUST set the "ResolvedRefs"
condition on the Policy status to "status: False", with Reason
"BackendNotFound", "InvalidKind", or "RefNotPermitted" as appropriate.
TLS configuration for the connection to the backend is managed by the referenced
object. For example, if the BackendRef points to a Service, a BackendTLSPolicy
can be attached to configure TLS. Alternatively, the referenced backend could be a
custom resource (e.g., XBackend) that natively manages TLS.
Support: Core
group
string
Group is the group of the referent. For example, "gateway.networking.k8s.io".
When unspecified or empty string, core API group is inferred.
pattern:
^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$maxLength:
253
kind
string
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)
pattern:
^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$minLength:
1maxLength:
63
name
string required
Name is the name of the referent.
minLength:
1maxLength:
253
namespace
string
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
pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$minLength:
1maxLength:
63
port
integer
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:
int32minimum:
1maximum:
65535headers []object
Headers specifies a list of custom headers to be added to the telemetry
export requests (e.g., for authentication).
Support: Extended
maxItems:
16
name
string required
Name is the name of the HTTP Header to be matched. Name matching MUST be
case-insensitive. (See https://tools.ietf.org/html/rfc7230#section-3.2).
If multiple entries specify equivalent header names, the first entry with
an equivalent name MUST be considered for a match. Subsequent entries
with an equivalent header name MUST be ignored. Due to the
case-insensitivity of header names, "foo" and "Foo" are considered
equivalent.
pattern:
^[A-Za-z0-9!#$%&'*+\-.^_\x60|~]+$minLength:
1maxLength:
256
value
string required
Value is the value of HTTP Header to be matched.
Must consist of printable US-ASCII characters, optionally separated
by single tabs or spaces. See: https://tools.ietf.org/html/rfc7230#section-3.2
pattern:
^[!-~]+([\t ]?[!-~]+)*$minLength:
1maxLength:
4096samplingRate object
SamplingRate specifies the base probability of sampling new traces.
The sampling probability is represented as a fraction.
For example, a Numerator of 5 and Denominator of 100 represents a 5% sampling rate.
* If configured, only the specified percentage of new traces will be initiated.
* In the absence of this field, an implementation-defined default is used.
Support: Extended
denominator
integer
format:
int32minimum:
1
numerator
integer required
format:
int32minimum:
0
serviceName
string
ServiceName is the "service.name" attribute of the OpenTelemetry resource.
If absent, the implementation's default service name will be used.
Support: Extended
Feature Name: TelemetryPolicyTracing
pattern:
^[a-zA-Z0-9_.:/-]+$minLength:
1maxLength:
253
spanName
string
SpanName defines a custom name for the OTel span. By default, the name
is implementation-specific.
Support: Extended
Feature Name: TelemetryPolicyTracing
pattern:
^[a-zA-Z0-9_.:/-]+( [a-zA-Z0-9_.:/-]+)*$minLength:
1maxLength:
256status object
Status defines the observed state of TelemetryPolicy.
ancestors []object required
For Policy Status API conventions, see:
https://gateway-api.sigs.k8s.io/geps/gep-713/#the-status-stanza-of-policy-objects
Ancestors is a list of ancestor resources (specifically Gateway resources)
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.
For TelemetryPolicy, the ancestor MUST be the Gateway resource
referenced in spec.targetRefs.
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.
maxItems:
16ancestorRef object required
AncestorRef corresponds with a ParentRef in the spec that this
PolicyAncestorStatus struct describes the status of.
group
string
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
pattern:
^$|^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$maxLength:
253
kind
string
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.
pattern:
^[a-zA-Z]([-a-zA-Z0-9]*[a-zA-Z0-9])?$minLength:
1maxLength:
63
name
string required
Name is the name of the referent.
Support: Core
minLength:
1maxLength:
253
namespace
string
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
pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?$minLength:
1maxLength:
63
port
integer
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:
int32minimum:
1maximum:
65535
sectionName
string
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
pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*$minLength:
1maxLength:
253conditions []object required
Conditions describes the status of the Policy with respect to the given Ancestor.
minItems:
1maxItems:
8
lastTransitionTime
string required
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
message
string required
message is a human readable message indicating details about the transition.
This may be an empty string.
maxLength:
32768
observedGeneration
integer
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:
int64minimum:
0
reason
string required
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.
pattern:
^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$minLength:
1maxLength:
1024
status
string required
status of the condition, one of True, False, Unknown.
enum:
True, False, Unknown
type
string required
type of condition in CamelCase or in foo.example.com/CamelCase.
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])$maxLength:
316
controllerName
string required
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.
pattern:
^[a-z0-9]([-a-z0-9]*[a-z0-9])?(\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*\/[A-Za-z0-9\/\-._~%!$&'()*+,;=:]+$minLength:
1maxLength:
253No matches. Try .spec.targetRefs for an exact path