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 (conflict with global settings is an error)
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 (conflict with global settings is an error)
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.
Use when the load balancer must connect to its targets over TLS.
If you only need “TLS as is” (no SNI and no backend certificate verification), provide an empty tls: {} section.
Health check TLS settings work the same way, but are configured separately.
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 |