|
| 1 | +/* |
| 2 | +Copyright 2025 The Kubernetes Authors. |
| 3 | +
|
| 4 | +Licensed under the Apache License, Version 2.0 (the "License"); |
| 5 | +you may not use this file except in compliance with the License. |
| 6 | +You may obtain a copy of the License at |
| 7 | +
|
| 8 | + http://www.apache.org/licenses/LICENSE-2.0 |
| 9 | +
|
| 10 | +Unless required by applicable law or agreed to in writing, software |
| 11 | +distributed under the License is distributed on an "AS IS" BASIS, |
| 12 | +WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| 13 | +See the License for the specific language governing permissions and |
| 14 | +limitations under the License. |
| 15 | +*/ |
| 16 | + |
| 17 | +package v1alpha1 |
| 18 | + |
| 19 | +import ( |
| 20 | + metav1 "k8s.io/apimachinery/pkg/apis/meta/v1" |
| 21 | +) |
| 22 | + |
| 23 | +// +genclient |
| 24 | +// +kubebuilder:object:root=true |
| 25 | +// +kubebuilder:subresource:status |
| 26 | +// +kubebuilder:storageversion |
| 27 | +// +kubebuilder:resource:categories=gateway-api,shortName=btrafficpolicy |
| 28 | +// +kubebuilder:printcolumn:name="Age",type=date,JSONPath=`.metadata.creationTimestamp` |
| 29 | +// |
| 30 | +// BackendTrafficPolicy is a Direct Attached Policy. |
| 31 | +// +kubebuilder:metadata:labels="gateway.networking.k8s.io/policy=Direct" |
| 32 | + |
| 33 | +// BackendTrafficPolicy defines the configuration for how traffic to a |
| 34 | +// target backend should be handled. |
| 35 | +type BackendTrafficPolicy struct { |
| 36 | + // Support: Extended |
| 37 | + // |
| 38 | + // +optional |
| 39 | + |
| 40 | + metav1.TypeMeta `json:",inline"` |
| 41 | + metav1.ObjectMeta `json:"metadata,omitempty"` |
| 42 | + |
| 43 | + // Spec defines the desired state of BackendTrafficPolicy. |
| 44 | + Spec BackendTrafficPolicySpec `json:"spec"` |
| 45 | + |
| 46 | + // Status defines the current state of BackendTrafficPolicy. |
| 47 | + Status PolicyStatus `json:"status,omitempty"` |
| 48 | +} |
| 49 | + |
| 50 | +// BackendTrafficPolicyList contains a list of BackendTrafficPolicies |
| 51 | +// +kubebuilder:object:root=true |
| 52 | +type BackendTrafficPolicyList struct { |
| 53 | + metav1.TypeMeta `json:",inline"` |
| 54 | + metav1.ListMeta `json:"metadata,omitempty"` |
| 55 | + Items []BackendTrafficPolicy `json:"items"` |
| 56 | +} |
| 57 | + |
| 58 | +// BackendTrafficPolicySpec define the desired state of BackendTrafficPolicy |
| 59 | +// Note: there is no Override or Default policy configuration. |
| 60 | +type BackendTrafficPolicySpec struct { |
| 61 | + // TargetRefs identifies API object(s) to apply this policy to. |
| 62 | + // Currently, Backends (A grouping of like endpoints such as Service, |
| 63 | + // ServiceImport, or any implementation-specific backendRef) are the only |
| 64 | + // valid API target references. |
| 65 | + // |
| 66 | + // Currently, a TargetRef can not be scoped to a specific port on a |
| 67 | + // Service. |
| 68 | + // |
| 69 | + // +listType=map |
| 70 | + // +listMapKey=group |
| 71 | + // +listMapKey=kind |
| 72 | + // +listMapKey=name |
| 73 | + // +kubebuilder:validation:MinItems=1 |
| 74 | + // +kubebuilder:validation:MaxItems=16 |
| 75 | + TargetRefs []LocalPolicyTargetReference `json:"targetRefs"` |
| 76 | + |
| 77 | + // RetryConstraint defines the configuration for when to allow or prevent |
| 78 | + // further retries to a target backend, by dynamically calculating a 'retry |
| 79 | + // budget'. This budget is calculated based on the percentage of incoming |
| 80 | + // traffic composed of retries over a given time interval. Once the budget |
| 81 | + // is exceeded, additional retries will be rejected. |
| 82 | + // |
| 83 | + // For example, if the retry budget interval is 10 seconds, there have been |
| 84 | + // 1000 active requests in the past 10 seconds, and the allowed percentage |
| 85 | + // of requests that can be retried is 20% (the default), then 200 of those |
| 86 | + // requests may be composed of retries. Active requests will only be |
| 87 | + // considered for the duration of the interval when calculating the retry |
| 88 | + // budget. Retrying the same original request multiple times within the |
| 89 | + // retry budget interval will lead to each retry being counted towards |
| 90 | + // calculating the budget. |
| 91 | + // |
| 92 | + // Configuring a RetryConstraint in BackendTrafficPolicy is compatible with |
| 93 | + // HTTPRoute Retry settings for each HTTPRouteRule that targets the same |
| 94 | + // backend. While the HTTPRouteRule Retry stanza can specify whether a |
| 95 | + // request will be retried, and the number of retry attempts each client |
| 96 | + // may perform, RetryConstraint helps prevent cascading failures such as |
| 97 | + // retry storms during periods of consistent failures. |
| 98 | + // |
| 99 | + // After the retry budget has been exceeded, additional retries to the |
| 100 | + // backend MUST return a 503 response to the client. |
| 101 | + // |
| 102 | + // Additional configurations for defining a constraint on retries MAY be |
| 103 | + // defined in the future. |
| 104 | + // |
| 105 | + // Support: Extended |
| 106 | + // |
| 107 | + // +optional |
| 108 | + // <gateway:experimental> |
| 109 | + RetryConstraint *RetryConstraint `json:"retryConstraint,omitempty"` |
| 110 | + |
| 111 | + // SessionPersistence defines and configures session persistence |
| 112 | + // for the backend. |
| 113 | + // |
| 114 | + // Support: Extended |
| 115 | + // |
| 116 | + // +optional |
| 117 | + SessionPersistence *SessionPersistence `json:"sessionPersistence,omitempty"` |
| 118 | +} |
| 119 | + |
| 120 | +// RetryConstraint defines the configuration for when to retry a request. |
| 121 | +type RetryConstraint struct { |
| 122 | + // BudgetPercent defines the maximum percentage of active requests that may |
| 123 | + // be made up of retries. |
| 124 | + // |
| 125 | + // Support: Extended |
| 126 | + // |
| 127 | + // +optional |
| 128 | + // +kubebuilder:default=20 |
| 129 | + // +kubebuilder:validation:Minimum=0 |
| 130 | + // +kubebuilder:validation:Maximum=100 |
| 131 | + BudgetPercent *int `json:"budgetPercent,omitempty"` |
| 132 | + |
| 133 | + // BudgetInterval defines the duration in which requests will be considered |
| 134 | + // for calculating the budget for retries. |
| 135 | + // |
| 136 | + // Support: Extended |
| 137 | + // |
| 138 | + // +optional |
| 139 | + // +kubebuilder:default="10s" |
| 140 | + // +kubebuilder:validation:XValidation:message="budgetInterval can not be greater than one hour or less than one second",rule="!(duration(self) < duration('1s') || duration(self) > duration('1h'))" |
| 141 | + BudgetInterval *Duration `json:"budgetInterval,omitempty"` |
| 142 | + |
| 143 | + // MinRetryRate defines the minimum rate of retries that will be allowable |
| 144 | + // over a specified duration of time. |
| 145 | + // |
| 146 | + // The effective overall minimum rate of retries targeting the backend |
| 147 | + // service may be much higher, as there can be any number of clients which |
| 148 | + // are applying this setting locally. |
| 149 | + // |
| 150 | + // This ensures that requests can still be retried during periods of low |
| 151 | + // traffic, where the budget for retries may be calculated as a very low |
| 152 | + // value. |
| 153 | + // |
| 154 | + // Support: Extended |
| 155 | + // |
| 156 | + // +optional |
| 157 | + // +kubebuilder:default={count: 10, interval: "1s"} |
| 158 | + MinRetryRate *RequestRate `json:"minRetryRate,omitempty"` |
| 159 | +} |
0 commit comments