RoutePolicy
- Cheatsheet
- RoutePolicySpec
- LocalObjectReference
- LabelSelector
- LabelSelectorRequirement
- Route
- RouteRule
- Backend
- HTTPBackend
- GRPCBackend
- StreamBackend
- LoadBalancingConfig
- HealthCheck
- HealthcheckHTTP
- HealthcheckGRPC
- HealthcheckStream
- HealthCheckTransportSettings
- BackendTLS
- BackendTLSTrustedCA
- SessionAffinity
- SessionAffinityConnection
- SessionAffinityCookie
- SessionAffinityHeader
- ALBRoute
- RouteALBHTTP
- VirtualHost
- RateLimit
- RateLimitLimit
- HostRewrite
- RegexMatchAndSubstitute
- RoutePolicyStatus
RoutePolicy is a Gwin custom resource for configuring route-level policies in Yandex Application Load Balancer. It allows you to define backend settings, routing configuration, virtual host options, and security policies that apply to HTTPRoute, GRPCRoute, and TLSRoute resources.
- Cheatsheet
- RoutePolicySpec
- LocalObjectReference
- LabelSelector
- LabelSelectorRequirement
- Route
- RouteRule
- BackendGroup
- Backend
- HTTPBackend
- GRPCBackend
- StreamBackend
- LoadBalancingConfig
- HealthCheck
- HealthcheckHTTP
- HealthcheckGRPC
- HealthcheckStream
- HealthCheckTransportSettings
- BackendTLS
- BackendTLSTrustedCA
- SessionAffinity
- SessionAffinityConnection
- SessionAffinityCookie
- SessionAffinityHeader
- ALBRoute
- RouteALBHTTP
- HostRewrite
- RegexMatchAndSubstitute
- VirtualHost
- RateLimit
- RateLimitLimit
- RBAC
- AndPrincipals
- Principal
- HeaderPrincipal
- IPPrincipal
- RoutePolicyStatus
Cheatsheet
Примечание
Specification provided below is not valid configuration.
It's just demonstration of all RoutePolicy fields.
apiVersion: gwin.yandex.cloud/v1
kind: RoutePolicy
metadata:
name: example-route-policy
namespace: example-ns
spec:
# Target Route resources
targetRefs:
- group: gateway.networking.k8s.io
kind: HTTPRoute
name: example-http-route
- group: gateway.networking.k8s.io
kind: GRPCRoute
name: example-grpc-route
# Or use label selector
selector:
matchLabels:
app: my-routes
matchExpressions:
- key: environment
operator: In
values: ["production", "staging"]
# Route policy configuration
policy:
# Common rules settings (applies to all rules)
rules:
# Backend group configuration
backends:
http:
useHTTP2: true # enable HTTP/2 to backends
grpc: {} # gRPC-specific settings
stream:
enableProxy: true # enable proxy protocol
keepConnectionsOnHostHealthFailure: false # drop failed connections
balancing:
mode: "ROUND_ROBIN" # load balancing algorithm
localityAwareRouting: 80 # prefer same zone
strictLocality: false # allow cross-zone routing
panicThreshold: 50 # panic mode threshold
# Health checks
hc:
timeout: "5s" # health check timeout
interval: "10s" # check interval
healthyThreshold: 2 # checks to mark healthy
unhealthyThreshold: 3 # checks to mark unhealthy
port: 8080 # health check port
http:
path: "/health" # HTTP health check path
host: "health.example.com" # Host header
useHTTP2: false # use HTTP/1.1 for checks
expectedStatuses: [200, 202] # healthy status codes
grpc:
serviceName: "health.HealthService" # gRPC service
stream:
send: "PING" # TCP check data to send
receive: "PONG" # expected TCP response
# Health check transport settings
transportSettings:
plaintext: true # use plaintext for health checks
tls:
sni: "health.example.com" # SNI for health check TLS
trustedCA:
id: "health-cert-123" # health check TLS cert ID
# Backend TLS configuration
tls:
sni: "backend.example.com" # SNI for TLS
trustedCA:
id: "cert-123456" # cloud certificate ID
# Session affinity
sessionAffinity:
connection:
sourceIP: true # IP-based affinity
cookie:
name: "session" # cookie name
ttl: "3600s" # cookie lifetime
header:
name: "X-Session-ID" # header-based affinity
# Route timeouts
timeout: "60s" # overall connection timeout
idleTimeout: "300s" # idle connection timeout
# Rate limiting for routes
rateLimit:
allRequests:
perSecond: 100 # route-level rate limit for all requests
perMinute: 6000 # route-level rate limit for all requests
requestsPerIP:
perSecond: 10 # route-level rate limit per IP
perMinute: 600 # route-level rate limit per IP
# Host rewriting
hostRewrite:
auto: true # automatically rewrite host to backend target
replace: "backend.example.com" # static host replacement
# HTTP specific settings
http:
upgradeTypes: ["websocket"] # supported upgrade protocols
regexRewrite:
regex: "^/service/([^/]+)(/.*)$" # regex pattern for path rewriting
substitute: "\\2/instance/\\1" # substitution with capture groups
# Security
securityProfileID: "security-profile-1" # WAF profile for routes
rbac:
action: "ALLOW" # default RBAC action
principals:
admin:
check-token:
header:
name: "authorization"
exact: "Bearer admin123"
check-ip:
ip:
remoteIp: "10.0.0.0/8"
# Specific rule settings (overrides common settings)
rule:
api-rule: # rule name from HTTPRoute
backends:
balancing:
mode: "LEAST_REQUEST" # per-rule balancing
...
# Common hosts settings (applies to all hosts)
hosts:
securityProfileID: "host-security-profile-1" # WAF profile for hosts
rateLimit:
allRequests:
perSecond: 100 # global rate limit
perMinute: 6000 # global rate limit
requestsPerIP:
perSecond: 10 # per-IP rate limit
perMinute: 600 # per-IP rate limit
rbac:
action: "DENY" # host-level RBAC action
principals:
blocked:
bad-ip:
ip:
remoteIp: "192.168.1.0/24"
# Specific host settings (overrides common settings)
host:
"api.example.com": # specific hostname
securityProfileID: "api-host-security" # per-host WAF
...
status:
conditions:
- type: "Ready"
status: "True"
reason: "PolicyApplied"
attachedRoutes: 5
| Field | Description |
|---|---|
| metadata | ObjectMeta Standard Kubernetes metadata. |
| spec | RoutePolicySpec Route policy specification. |
| status | RoutePolicyStatus Route policy status. |
RoutePolicySpec
RoutePolicySpec defines the desired state of RoutePolicy.
Appears in: RoutePolicy
| Field | Description |
|---|---|
| targetRefs | []LocalObjectReference References to Route resources (HTTPRoute, GRPCRoute, TLSRoute) that this policy should apply to. |
| selector | LabelSelector Label selector for Route resources that this policy should apply to. |
| policy | Route Route policy configuration. |
LocalObjectReference
Reference to a local Kubernetes object.
Appears in: RoutePolicySpec
| Field | Description |
|---|---|
| group | string API group of the target resource. Example: gateway.networking.k8s.io |
| kind | string Kind of the target resource. Example: HTTPRoute |
| name | string Name of the target resource. Example: example-http-route |
LabelSelector
Label selector for selecting resources by labels.
Appears in: RoutePolicySpec
| Field | Description |
|---|---|
| matchLabels | map[string]string Map of key-value pairs for exact label matching. Example: app: my-routes |
| matchExpressions | []LabelSelectorRequirement List of label selector requirements. |
LabelSelectorRequirement
Label selector requirement for advanced label matching.
Appears in: LabelSelector
| Field | Description |
|---|---|
| key | string Label key that the selector applies to. Example: environment |
| operator | string Operator for the requirement. Options: In, NotIn, Exists, DoesNotExist. Example: In |
| values | []string Array of string values for In and NotIn operators. Example: ["production", "staging"] |
Route
Route policy configuration that applies to routing rules and virtual hosts.
Appears in: RoutePolicySpec
| Field | Description |
|---|---|
| rules | RouteRule Common rules settings that apply to all route rules. |
| rule | map[string]RouteRule Specific rules settings where key is the rule name. |
| hosts | VirtualHost Common hosts settings that apply to all virtual hosts. |
| host | map[string]VirtualHost Specific hosts settings where key is the hostname. |
RouteRule
Route rule configuration that combines backend group and route settings.
Appears in: Route
| Field | Description |
|---|---|
| backends | Backend Backend configuration settings. |
| sessionAffinity | SessionAffinity Session affinity configuration for the backend group. |
| timeout | string Overall timeout for HTTP connection between load balancer and backend. Default: 60s. Example: 60s |
| idleTimeout | string Idle timeout for HTTP connection. Example: 300s |
| rateLimit | RateLimit Rate limit configuration applied for route. |
| hostRewrite | HostRewrite Host header rewriting configuration. |
| http | RouteALBHTTP HTTP specific route options. |
| securityProfileID | string Security profile ID for route-level protection. Example: security-profile-1 |
| rbac | RBAC RBAC access control configuration. |
Backend
Backend configuration for protocol-specific settings, load balancing, health checks, and TLS.
Appears in: RouteRule
| Field | Description |
|---|---|
| http | HTTPBackend HTTP specific backend settings. |
| grpc | GRPCBackend gRPC specific backend settings. |
| stream | StreamBackend TCP stream specific backend settings. |
| balancing | LoadBalancingConfig Load balancing configuration for the backend. |
| hc | HealthCheck Health check configuration. |
| tls | BackendTLS TLS settings for backend connections. |
HTTPBackend
HTTP specific backend settings.
Appears in: Backend
| Field | Description |
|---|---|
| useHTTP2 | bool Enables HTTP/2 usage in connections between load balancer nodes and backend targets. Default: false. Example: true |
GRPCBackend
gRPC specific backend settings.
Appears in: Backend
Reserved for future gRPC-specific settings.
StreamBackend
TCP stream specific backend settings.
Appears in: Backend
| Field | Description |
|---|---|
| enableProxy | bool If set, proxy protocol will be enabled for this backend. Example: true |
| keepConnectionsOnHostHealthFailure | bool If a backend host becomes unhealthy, keep connections to the failed host. Example: false |
LoadBalancingConfig
Load balancing configuration for backends.
Appears in: Backend
| Field | Description |
|---|---|
| panicThreshold | int Threshold for panic mode (percentage). If healthy backends drop below this threshold, traffic routes to all backends. Set to 0 to disable panic mode. Example: 50 |
| localityAwareRouting | int Percentage of traffic sent to backends in the same availability zone. Remaining traffic is divided equally between other zones. Example: 90 |
| strictLocality | bool Send traffic only to backends in the same availability zone. If true, localityAwareRouting is ignored. Example: false |
| mode | string Load balancing mode. Options: ROUND_ROBIN, LEAST_REQUEST, RANDOM, RING_HASH, MAGLEV_HASH. Example: ROUND_ROBIN |
HealthCheck
Health check configuration for monitoring backend health.
Appears in: Backend
| Field | Description |
|---|---|
| timeout | string Health check timeout — time allowed for the target to respond. Example: 5s |
| interval | string Base interval between consecutive health checks. Example: 10s |
| healthyThreshold | int Number of consecutive successful checks to mark target as healthy. Default: 0 (1 check required). Example: 2 |
| unhealthyThreshold | int Number of consecutive failed checks to mark target as unhealthy. Default: 0 (1 check required). Example: 3 |
| port | int Port used for health checks. If not specified, backend port is used. Example: 8080 |
| http | HealthcheckHTTP HTTP-specific health check settings. |
| grpc | HealthcheckGRPC gRPC-specific health check settings. |
| stream | HealthcheckStream TCP stream-specific health check settings. |
| transportSettings | HealthCheckTransportSettings Optional transport protocol for health checks. |
HealthcheckHTTP
HTTP-specific health check settings.
Appears in: HealthCheck
| Field | Description |
|---|---|
| host | string Value for the HTTP/1.1 Host header or HTTP/2 :authority pseudo-header. Example: health.example.com |
| path | string HTTP path used in requests to targets. Example: /health |
| useHTTP2 | bool Enables HTTP/2 usage in health checks. Default: false. Example: true |
| expectedStatuses | []int List of HTTP response statuses considered healthy. Default: [200]. Example: [200, 202, 204] |
HealthcheckGRPC
gRPC-specific health check settings.
Appears in: HealthCheck
| Field | Description |
|---|---|
| serviceName | string Name of the gRPC service to be checked. If not specified, overall health is checked. Example: health.v1.HealthService |
HealthcheckStream
TCP stream-specific health check settings.
Appears in: HealthCheck
| Field | Description |
|---|---|
| send | string Message sent to targets during TCP data transfer. If not specified, no data is sent. Example: PING |
| receive | string Data that must be contained in received messages for successful health check. If not specified, no messages are expected. Example: PONG |
HealthCheckTransportSettings
Transport protocol settings for health checks.
Appears in: HealthCheck
| Field | Description |
|---|---|
| plaintext | bool Use plaintext protocol for health checks. Set to true to force HTTP health checks even for HTTPS backends. Example: true |
| tls | BackendTLS TLS settings for health checks. Use when health checks require different TLS configuration than backend. |
BackendTLS
TLS settings for backend connections.
Appears in: Backend, HealthCheckTransportSettings
| Field | Description |
|---|---|
| sni | string Server Name Indication (SNI) string for TLS connections. Example: backend.example.com |
| trustedCA | BackendTLSTrustedCA Validation context for TLS connections. |
BackendTLSTrustedCA
Trusted CA configuration for TLS validation.
Appears in: BackendTLS
| Field | Description |
|---|---|
| id | string Cloud certificate ID. Example: fpq6gvvm6piu******** |
| bytes | string X.509 certificate contents in PEM format. Example: -----BEGIN CERTIFICATE-----\n...\n-----END CERTIFICATE----- |
SessionAffinity
Session affinity configuration for routing requests from the same client to the same backend.
Appears in: RouteRule
| Field | Description |
|---|---|
| connection | SessionAffinityConnection Connection-based session affinity (by client IP). |
| cookie | SessionAffinityCookie Cookie-based session affinity. |
| header | SessionAffinityHeader HTTP header-based session affinity. |
SessionAffinityConnection
Connection-based session affinity configuration.
Appears in: SessionAffinity
| Field | Description |
|---|---|
| sourceIP | bool Use client IP address for session affinity. Example: true |
SessionAffinityCookie
Cookie-based session affinity configuration.
Appears in: SessionAffinity
| Field | Description |
|---|---|
| name | string Name of the cookie used for session affinity. Example: session-cookie |
| ttl | string Maximum age of generated session cookies. Set to 0 for session cookies (deleted on client restart). If not set, balancer only uses incoming cookies. Example: 3600s |
SessionAffinityHeader
HTTP header-based session affinity configuration.
Appears in: SessionAffinity
| Field | Description |
|---|---|
| name | string Name of the HTTP header field used for session affinity. Example: X-Session-ID |
ALBRoute
Application Load Balancer route configuration.
Appears in: RouteRule
| Field | Description |
|---|---|
| timeout | string Overall timeout for HTTP connection between load balancer and backend. Default: 60s. Example: 60s |
| idleTimeout | string Idle timeout for HTTP connection. Example: 300s |
| http | RouteALBHTTP HTTP specific route options. |
| securityProfileID | string Security profile ID for route-level protection. Example: security-profile-1 |
| rbac | RBAC RBAC access control configuration. |
RouteALBHTTP
HTTP-specific route configuration.
Appears in: ALBRoute, RouteRule
| Field | Description |
|---|---|
| upgradeTypes | []string Supported values for HTTP Upgrade header. Example: ["websocket"] |
| regexRewrite | RegexMatchAndSubstitute Path rewriting using regular expressions. |
VirtualHost
Virtual host configuration for rate limiting and access control.
Appears in: Route
| Field | Description |
|---|---|
| securityProfileID | string Security profile ID for host-level protection. Example: host-security-profile-1 |
| rbac | RBAC RBAC access control configuration. |
| rateLimit | RateLimit Rate limit configuration applied for a whole virtual host. |
RateLimit
Rate limit configuration applied to virtual hosts.
Appears in: VirtualHost
| Field | Description |
|---|---|
| allRequests | RateLimitLimit Rate limit configuration applied to all incoming requests. |
| requestsPerIP | RateLimitLimit Rate limit configuration applied separately for each set of requests grouped by client IP address. |
RateLimitLimit
Rate limit configuration with time-based limits.
Appears in: RateLimit
| Field | Description |
|---|---|
| perMinute | int Limit value specified with per minute time unit. Example: 6000 |
| perSecond | int Limit value specified with per second time unit. Example: 100 |
HostRewrite
Host header rewriting configuration for HTTP/1.1 Host headers and HTTP/2 :authority pseudo-headers.
Appears in: RouteRule
| Field | Description |
|---|---|
| auto | bool Automatically replaces the host with that of the target backend. Example: true |
| replace | string Static host replacement value. Example: backend.example.com |
RegexMatchAndSubstitute
Regular expression-based path rewriting configuration for HTTP routes.
Appears in: RouteALBHTTP
| Field | Description |
|---|---|
| regex | string Regular expression pattern to match portions of the path for rewriting. Example: ^/service/([^/]+)(/.*)$ |
| substitute | string Substitution string for path rewriting with capture group support. Pattern ^/service/([^/]+)(/.*)$ with substitution \\2/instance/\\1 transforms /service/foo/v1/api to /v1/api/instance/foo. Example: \\2/instance/\\1 |
RoutePolicyStatus
RoutePolicyStatus defines the observed state of RoutePolicy.
Appears in: RoutePolicy
| Field | Description |
|---|---|
| conditions | []Condition Current state conditions of the route policy. |
| attachedRoutes | int32 Number of currently attached routes. |
RBAC
RBAC (Role-Based Access Control) configuration for controlling access to routes and hosts.
Appears in: RouteRule, ALBRoute, VirtualHost
| Field | Description |
|---|---|
| action | string Action to take when principals match. Options: ALLOW, DENY. Example: ALLOW |
| principals | map[string]AndPrincipals Map of principal groups where each group contains multiple principals combined with AND logic. |
AndPrincipals
Map of principals that are combined with AND logic within a group.
Appears in: RBAC
| Field | Description |
|---|---|
| key | Principal Principal identifier mapped to principal configuration. |
Principal
Principal configuration for RBAC matching.
Appears in: AndPrincipals
| Field | Description |
|---|---|
| header | HeaderPrincipal Header-based principal matching. |
| ip | IPPrincipal IP-based principal matching. |
| any | bool Match any request. Example: true |
HeaderPrincipal
Header-based principal matching configuration.
Appears in: Principal
| Field | Description |
|---|---|
| name | string Name of the header to match. Example: authorization |
| regex | string Regular expression pattern for header value matching. Example: ^Bearer .* |
| exact | string Exact header value match. Example: Bearer admin123 |
| prefix | string Header value prefix match. Example: Bearer |
IPPrincipal
IP-based principal matching configuration.
Appears in: Principal
| Field | Description |
|---|---|
| remoteIp | string IP address or CIDR block for matching client IP. Example: 10.0.0.0/8 |