gateway-api 0.21.0

// WARNING: generated by kopium - manual changes will be overwritten
// kopium command: kopium --schema=derived --derive=JsonSchema --derive=Default --derive=PartialEq --docs -f -
// kopium version: 0.22.5

#[allow(unused_imports)]
mod prelude {
    pub use k8s_openapi::apimachinery::pkg::apis::meta::v1::Condition;
    pub use kube::CustomResource;
    pub use schemars::JsonSchema;
    pub use serde::{Deserialize, Serialize};
}
use self::prelude::*;

/// Spec defines the desired state of BackendTrafficPolicy.
#[derive(CustomResource, Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
#[kube(
    group = "gateway.networking.x-k8s.io",
    version = "v1alpha1",
    kind = "XBackendTrafficPolicy",
    plural = "xbackendtrafficpolicies"
)]
#[kube(namespaced)]
#[kube(status = "XBackendTrafficPolicyStatus")]
#[kube(derive = "Default")]
#[kube(derive = "PartialEq")]
pub struct XBackendTrafficPolicySpec {
    /// RetryConstraint defines the configuration for when to allow or prevent
    /// further retries to a target backend, by dynamically calculating a 'retry
    /// budget'. This budget is calculated based on the percentage of incoming
    /// traffic composed of retries over a given time interval. Once the budget
    /// is exceeded, additional retries will be rejected.
    ///
    /// For example, if the retry budget interval is 10 seconds, there have been
    /// 1000 active requests in the past 10 seconds, and the allowed percentage
    /// of requests that can be retried is 20% (the default), then 200 of those
    /// requests may be composed of retries. Active requests will only be
    /// considered for the duration of the interval when calculating the retry
    /// budget. Retrying the same original request multiple times within the
    /// retry budget interval will lead to each retry being counted towards
    /// calculating the budget.
    ///
    /// Configuring a RetryConstraint in BackendTrafficPolicy is compatible with
    /// HTTPRoute Retry settings for each HTTPRouteRule that targets the same
    /// backend. While the HTTPRouteRule Retry stanza can specify whether a
    /// request will be retried, and the number of retry attempts each client
    /// may perform, RetryConstraint helps prevent cascading failures such as
    /// retry storms during periods of consistent failures.
    ///
    /// After the retry budget has been exceeded, additional retries to the
    /// backend MUST return a 503 response to the client.
    ///
    /// Additional configurations for defining a constraint on retries MAY be
    /// defined in the future.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "retryConstraint")]
    pub retry_constraint: Option<XBackendTrafficPolicyRetryConstraint>,
    /// SessionPersistence defines and configures session persistence
    /// for the backend.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "sessionPersistence")]
    pub session_persistence: Option<XBackendTrafficPolicySessionPersistence>,
    /// TargetRefs identifies API object(s) to apply this policy to.
    /// Currently, Backends (A grouping of like endpoints such as Service,
    /// ServiceImport, or any implementation-specific backendRef) are the only
    /// valid API target references.
    ///
    /// Currently, a TargetRef cannot be scoped to a specific port on a
    /// Service.
    #[serde(rename = "targetRefs")]
    pub target_refs: Vec<XBackendTrafficPolicyTargetRefs>,
}

/// RetryConstraint defines the configuration for when to allow or prevent
/// further retries to a target backend, by dynamically calculating a 'retry
/// budget'. This budget is calculated based on the percentage of incoming
/// traffic composed of retries over a given time interval. Once the budget
/// is exceeded, additional retries will be rejected.
///
/// For example, if the retry budget interval is 10 seconds, there have been
/// 1000 active requests in the past 10 seconds, and the allowed percentage
/// of requests that can be retried is 20% (the default), then 200 of those
/// requests may be composed of retries. Active requests will only be
/// considered for the duration of the interval when calculating the retry
/// budget. Retrying the same original request multiple times within the
/// retry budget interval will lead to each retry being counted towards
/// calculating the budget.
///
/// Configuring a RetryConstraint in BackendTrafficPolicy is compatible with
/// HTTPRoute Retry settings for each HTTPRouteRule that targets the same
/// backend. While the HTTPRouteRule Retry stanza can specify whether a
/// request will be retried, and the number of retry attempts each client
/// may perform, RetryConstraint helps prevent cascading failures such as
/// retry storms during periods of consistent failures.
///
/// After the retry budget has been exceeded, additional retries to the
/// backend MUST return a 503 response to the client.
///
/// Additional configurations for defining a constraint on retries MAY be
/// defined in the future.
///
/// Support: Extended
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicyRetryConstraint {
    /// Budget holds the details of the retry budget configuration.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub budget: Option<XBackendTrafficPolicyRetryConstraintBudget>,
    /// MinRetryRate defines the minimum rate of retries that will be allowable
    /// over a specified duration of time.
    ///
    /// The effective overall minimum rate of retries targeting the backend
    /// service may be much higher, as there can be any number of clients which
    /// are applying this setting locally.
    ///
    /// This ensures that requests can still be retried during periods of low
    /// traffic, where the budget for retries may be calculated as a very low
    /// value.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "minRetryRate")]
    pub min_retry_rate: Option<XBackendTrafficPolicyRetryConstraintMinRetryRate>,
}

/// Budget holds the details of the retry budget configuration.
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicyRetryConstraintBudget {
    /// Interval defines the duration in which requests will be considered
    /// for calculating the budget for retries.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub interval: Option<String>,
    /// Percent defines the maximum percentage of active requests that may
    /// be made up of retries.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub percent: Option<i64>,
}

/// MinRetryRate defines the minimum rate of retries that will be allowable
/// over a specified duration of time.
///
/// The effective overall minimum rate of retries targeting the backend
/// service may be much higher, as there can be any number of clients which
/// are applying this setting locally.
///
/// This ensures that requests can still be retried during periods of low
/// traffic, where the budget for retries may be calculated as a very low
/// value.
///
/// Support: Extended
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicyRetryConstraintMinRetryRate {
    /// Count specifies the number of requests per time interval.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub count: Option<i64>,
    /// Interval specifies the divisor of the rate of requests, the amount of
    /// time during which the given count of requests occur.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub interval: Option<String>,
}

/// SessionPersistence defines and configures session persistence
/// for the backend.
///
/// Support: Extended
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicySessionPersistence {
    /// AbsoluteTimeout defines the absolute timeout of the persistent
    /// session. Once the AbsoluteTimeout duration has elapsed, the
    /// session becomes invalid.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "absoluteTimeout")]
    pub absolute_timeout: Option<String>,
    /// CookieConfig provides configuration settings that are specific
    /// to cookie-based session persistence.
    ///
    /// Support: Core
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "cookieConfig")]
    pub cookie_config: Option<XBackendTrafficPolicySessionPersistenceCookieConfig>,
    /// IdleTimeout defines the idle timeout of the persistent session.
    /// Once the session has been idle for more than the specified
    /// IdleTimeout duration, the session becomes invalid.
    ///
    /// Support: Extended
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "idleTimeout")]
    pub idle_timeout: Option<String>,
    /// SessionName defines the name of the persistent session token
    /// which may be reflected in the cookie or the header. Users
    /// should avoid reusing session names to prevent unintended
    /// consequences, such as rejection or unpredictable behavior.
    ///
    /// Support: Implementation-specific
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "sessionName")]
    pub session_name: Option<String>,
    /// Type defines the type of session persistence such as through
    /// the use of a header or cookie. Defaults to cookie based session
    /// persistence.
    ///
    /// Support: Core for "Cookie" type
    ///
    /// Support: Extended for "Header" type
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "type")]
    pub r#type: Option<XBackendTrafficPolicySessionPersistenceType>,
}

/// CookieConfig provides configuration settings that are specific
/// to cookie-based session persistence.
///
/// Support: Core
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicySessionPersistenceCookieConfig {
    /// LifetimeType specifies whether the cookie has a permanent or
    /// session-based lifetime. A permanent cookie persists until its
    /// specified expiry time, defined by the Expires or Max-Age cookie
    /// attributes, while a session cookie is deleted when the current
    /// session ends.
    ///
    /// When set to "Permanent", AbsoluteTimeout indicates the
    /// cookie's lifetime via the Expires or Max-Age cookie attributes
    /// and is required.
    ///
    /// When set to "Session", AbsoluteTimeout indicates the
    /// absolute lifetime of the cookie tracked by the gateway and
    /// is optional.
    ///
    /// Defaults to "Session".
    ///
    /// Support: Core for "Session" type
    ///
    /// Support: Extended for "Permanent" type
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "lifetimeType")]
    pub lifetime_type: Option<XBackendTrafficPolicySessionPersistenceCookieConfigLifetimeType>,
}

/// CookieConfig provides configuration settings that are specific
/// to cookie-based session persistence.
///
/// Support: Core
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, PartialEq)]
pub enum XBackendTrafficPolicySessionPersistenceCookieConfigLifetimeType {
    Permanent,
    Session,
}

/// SessionPersistence defines and configures session persistence
/// for the backend.
///
/// Support: Extended
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, PartialEq)]
pub enum XBackendTrafficPolicySessionPersistenceType {
    Cookie,
    Header,
}

/// 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.
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicyTargetRefs {
    /// Group is the group of the target resource.
    pub group: String,
    /// Kind is kind of the target resource.
    pub kind: String,
    /// Name is the name of the target resource.
    pub name: String,
}

/// Status defines the current state of BackendTrafficPolicy.
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicyStatus {
    /// 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.
    pub ancestors: Vec<XBackendTrafficPolicyStatusAncestors>,
}

/// 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.
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicyStatusAncestors {
    /// AncestorRef corresponds with a ParentRef in the spec that this
    /// PolicyAncestorStatus struct describes the status of.
    #[serde(rename = "ancestorRef")]
    pub ancestor_ref: XBackendTrafficPolicyStatusAncestorsAncestorRef,
    /// Conditions describes the status of the Policy with respect to the given Ancestor.
    pub conditions: Vec<Condition>,
    /// 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.
    #[serde(rename = "controllerName")]
    pub controller_name: String,
}

/// AncestorRef corresponds with a ParentRef in the spec that this
/// PolicyAncestorStatus struct describes the status of.
#[derive(Serialize, Deserialize, Clone, Debug, JsonSchema, Default, PartialEq)]
pub struct XBackendTrafficPolicyStatusAncestorsAncestorRef {
    /// 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
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub group: Option<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.
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub kind: Option<String>,
    /// Name is the name of the referent.
    ///
    /// Support: Core
    pub name: 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
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub namespace: Option<String>,
    /// 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
    #[serde(default, skip_serializing_if = "Option::is_none")]
    pub port: Option<i32>,
    /// 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
    #[serde(default, skip_serializing_if = "Option::is_none", rename = "sectionName")]
    pub section_name: Option<String>,
}