VirtualServer and VirtualServerRoute Resources
The VirtualServer and VirtualServerRoute resources are new load balancing configuration, introduced in release 1.5 as an alternative to the Ingress resource. The resources enable use cases not supported with the Ingress resource, such as traffic splitting and advanced content-based routing. The resources are implemented as Custom Resources.
This document is the reference documentation for the resources. To see additional examples of using the resources for specific use cases, go to the examples-of-custom-resources folder in our GitHub repo.
The VirtualServer resource defines load balancing configuration for a domain name, such as example.com. Below is an example of such configuration:
apiVersion: k8s.nginx.org/v1kind: VirtualServermetadata:name: cafespec:host: cafe.example.comtls:secret: cafe-secretupstreams:- name: teaservice: tea-svcport: 80- name: coffeeservice: coffee-svcport: 80routes:- path: /teaaction:pass: tea- path: /coffeeaction:pass: coffee- path: ~ ^/decaf/.*\\.jpg$action:pass: coffee- path: = /green/teaaction:pass: teaFieldDescriptionTypeRequiredhostThe host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as my-app or hello.example.com. Wildcard domains like *.example.com are not allowed.The host value needs to be unique among all Ingress and VirtualServer resources. See also Handling Host and Listener Collisions.stringYestlsThe TLS termination configuration.[tls](#virtualservertlsNopoliciesA list of policies.[]policyNoupstreamsA list of upstreams.[]upstreamNoroutesA list of routes.[]routeNoingressClassNameSpecifies which Ingress controller must handle the VirtualServer resource.stringNohttp-snippetsSets a custom snippet in the http context.stringNoserver-snippetsSets a custom snippet in server context. Overrides the server-snippets ConfigMap key.stringNoThe tls field defines TLS configuration for a VirtualServer. For example:
secret: cafe-secretredirect:enable: trueFieldDescriptionTypeRequiredsecretThe name of a secret with a TLS certificate and key. The secret must belong to the same namespace as the VirtualServer. The secret must be of the type kubernetes.io/tls and contain keys named tls.crt and tls.key that contain the certificate and private key as described here. If the secret doesn’t exist or is invalid, NGINX will break any attempt to establish a TLS connection to the host of the VirtualServer.stringNoredirectThe redirect configuration of the TLS for a VirtualServer.tls.redirectNoThe redirect field configures a TLS redirect for a VirtualServer:
enable: truecode: 301basedOn: schemeFieldDescriptionTypeRequiredenableEnables a TLS redirect for a VirtualServer. The default is False.booleanNocodeThe status code of a redirect. The allowed values are: 301\ , 302\ , 307\ , 308.The default is 301.intNobasedOnThe attribute of a request that NGINX will evaluate to send a redirect. The allowed values are scheme (the scheme of the request) or x-forwarded-proto (the X-Forwarded-Proto header of the request). The default is scheme.stringNoThe policy field references a Policy resource by its name and optional namespace. For example:
FieldDescriptionTypeRequirednameThe name of a policy. If the policy doesn’t exist or invalid, NGINX will respond with an error response with the 500 status code.stringYesnamespaceThe namespace of a policy. If not specified, the namespace of the VirtualServer resource is used.stringNoThe route defines rules for matching client requests to actions like passing a request to an upstream. For example:
path: /teaaction:pass: teaFieldDescriptionTypeRequiredpathThe path of the route. NGINX will match it against the URI of a request. Possible values are: a prefix (\ /\ , /path\ ), an exact match (\ =/exact/match\ ), a case insensitive regular expression (\ ~*^/Bar.*\\.jpg\ ) or a case sensitive regular expression (\ ~^/foo.*\\.jpg\ ). In the case of a prefix (must start with /\ ) or an exact match (must start with =\ ), the path must not include any whitespace characters, {\ , } or ;. In the case of the regex matches, all double quotes " must be escaped and the match can’t end in an unescaped backslash \. The path must be unique among the paths of all routes of the VirtualServer. Check the location directive for more information.stringYespoliciesA list of policies. The policies override the policies of the same type defined in the spec of the VirtualServer. See Applying Policies for more details.[]policyNoactionThe default action to perform for a request.actionNosplitsThe default splits configuration for traffic splitting. Must include at least 2 splits.[]splitNomatchesThe matching rules for advanced content-based routing. Requires the default action or splits.Unmatched requests will be handled by the default action or splits.matchesNorouteThe name of a VirtualServerRoute resource that defines this route. If the VirtualServerRoute belongs to a different namespace than the VirtualServer, you need to include the namespace. For example, tea-namespace/tea.stringNoerrorPagesThe custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code.[]errorPageNolocation-snippetsSets a custom snippet in the location context. Overrides the location-snippets ConfigMap key.stringNo* – a route must include exactly one of the following: action, splits, or route.
The VirtualServerRoute resource defines a route for a VirtualServer. It can consist of one or multiple subroutes. The VirtualServerRoute is an alternative to Mergeable Ingress types.
In the example below, the VirtualServer cafe from the namespace cafe-ns defines a route with the path /coffee, which is further defined in the VirtualServerRoute coffee from the namespace coffee-ns.
VirtualServer:
apiVersion: k8s.nginx.org/v1kind: VirtualServermetadata:name: cafenamespace: cafe-nsspec:host: cafe.example.comupstreams:- name: teaservice: tea-svcport: 80routes:- path: /teaaction:pass: tea- path: /coffeeroute: coffee-ns/coffeeVirtualServerRoute:
apiVersion: k8s.nginx.org/v1kind: VirtualServerRoutemetadata:name: coffeenamespace: coffee-nsspec:host: cafe.example.comupstreams:- name: latteservice: latte-svcport: 80- name: espressoservice: espresso-svcport: 80subroutes:- path: /coffee/latteaction:pass: latte- path: /coffee/espressoaction:pass: espressoNote that each subroute must have a path that starts with the same prefix (here /coffee), which is defined in the route of the VirtualServer. Additionally, the host in the VirtualServerRoute must be the same as the host of the VirtualServer.
FieldDescriptionTypeRequiredhostThe host (domain name) of the server. Must be a valid subdomain as defined in RFC 1123, such as my-app or hello.example.com. Wildcard domains like *.example.com are not allowed. Must be the same as the host of the VirtualServer that references this resource.stringYesupstreamsA list of upstreams.[]upstreamNosubroutesA list of subroutes.[]subrouteNoingressClassNameSpecifies which Ingress controller must handle the VirtualServerRoute resource. Must be the same as the ingressClassName of the VirtualServer that references this resource.string_NoThe subroute defines rules for matching client requests to actions like passing a request to an upstream. For example:
path: /coffeeaction:pass: coffeeFieldDescriptionTypeRequiredpathThe path of the subroute. NGINX will match it against the URI of a request. Possible values are: a prefix (\ /\ , /path\ ), an exact match (\ =/exact/match\ ), a case insensitive regular expression (\ ~*^/Bar.*\\.jpg\ ) or a case sensitive regular expression (\ ~^/foo.*\\.jpg\ ). In the case of a prefix, the path must start with the same path as the path of the route of the VirtualServer that references this resource. In the case of an exact or regex match, the path must be the same as the path of the route of the VirtualServer that references this resource. In the case of a prefix or an exact match, the path must not include any whitespace characters, {\ , } or ;.In the case of the regex matches, all double quotes " must be escaped and the match can’t end in an unescaped backslash \. The path must be unique among the paths of all subroutes of the VirtualServerRoute.stringYespoliciesA list of policies. The policies override all policies defined in the route of the VirtualServer that references this resource. The policies also override the policies of the same type defined in the spec of the VirtualServer. See Applying Policies for more details.[]policyNoactionThe default action to perform for a request.actionNosplitsThe default splits configuration for traffic splitting. Must include at least 2 splits.[]splitNomatchesThe matching rules for advanced content-based routing. Requires the default action or splits.Unmatched requests will be handled by the default action or splits.matchesNoerrorPagesThe custom responses for error codes. NGINX will use those responses instead of returning the error responses from the upstream servers or the default responses generated by NGINX. A custom response can be a redirect or a canned response. For example, a redirect to another URL if an upstream server responded with a 404 status code.[]errorPageNolocation-snippetsSets a custom snippet in the location context. Overrides the location-snippets of the VirtualServer (if set) or the location-snippets ConfigMap key.stringNo* – a subroute must include exactly one of the following: action or splits.
The upstream defines a destination for the routing configuration. For example:
name: teaservice: tea-svcsubselector:version: canaryport: 80lb-method: round_robinfail-timeout: 10smax-fails: 1max-conns: 32keepalive: 32connect-timeout: 30sread-timeout: 30ssend-timeout: 30snext-upstream: "error timeout non_idempotent"next-upstream-timeout: 5snext-upstream-tries: 10client-max-body-size: 2mtls:enable: trueNote: The WebSocket protocol is supported without any additional configuration.
FieldDescriptionTypeRequirednameThe name of the upstream. Must be a valid DNS label as defined in RFC 1035. For example, hello and upstream-123 are valid. The name must be unique among all upstreams of the resource.stringYesserviceThe name of a service. The service must belong to the same namespace as the resource. If the service doesn’t exist, NGINX will assume the service has zero endpoints and return a 502 response for requests for this upstream. For NGINX Plus only, services of type ExternalName are also supported (check the prerequisites\ ).stringYessubselectorSelects the pods within the service using label keys and values. By default, all pods of the service are selected. Note: the specified labels are expected to be present in the pods when they are created. If the pod labels are updated, the Ingress Controller will not see that change until the number of the pods is changed.map[string]stringNouse-cluster-ipEnables using the Cluster IP and port of the service instead of the default behavior of using the IP and port of the pods. When this field is enabled, the fields that configure NGINX behavior related to multiple upstream servers (like lb-method and next-upstream) will have no effect, as the Ingress Controller will configure NGINX with only one upstream server that will match the service Cluster IP.booleanNoportThe port of the service. If the service doesn’t define that port, NGINX will assume the service has zero endpoints and return a 502 response for requests for this upstream. The port must fall into the range 1..65535.uint16Yeslb-methodThe load balancing method. To use the round-robin method, specify round_robin. The default is specified in the lb-method ConfigMap key.stringNofail-timeoutThe time during which the specified number of unsuccessful attempts to communicate with an upstream server should happen to consider the server unavailable. See the fail_timeout parameter of the server directive. The default is set in the fail-timeout ConfigMap key.stringNomax-failsThe number of unsuccessful attempts to communicate with an upstream server that should happen in the duration set by the fail-timeout to consider the server unavailable. See the max_fails parameter of the server directive. The default is set in the max-fails ConfigMap key.intNomax-connsThe maximum number of simultaneous active connections to an upstream server. See the max_conns parameter of the server directive. By default there is no limit. Note: if keepalive connections are enabled, the total number of active and idle keepalive connections to an upstream server may exceed the max_conns value.intNokeepaliveConfigures the cache for connections to upstream servers. The value 0 disables the cache. See the keepalive directive. The default is set in the keepalive ConfigMap key.intNoconnect-timeoutThe timeout for establishing a connection with an upstream server. See the proxy_connect_timeout directive. The default is specified in the proxy-connect-timeout ConfigMap key.stringNoread-timeoutThe timeout for reading a response from an upstream server. See the proxy_read_timeout directive.The default is specified in the proxy-read-timeout ConfigMap key.stringNosend-timeoutThe timeout for transmitting a request to an upstream server. See the proxy_send_timeout directive. The default is specified in the proxy-send-timeout ConfigMap key.stringNonext-upstreamSpecifies in which cases a request should be passed to the next upstream server. See the proxy_next_upstream directive. The default is error timeout.stringNonext-upstream-timeoutThe time during which a request can be passed to the next upstream server. See the proxy_next_upstream_timeout directive. The 0 value turns off the time limit. The default is 0.stringNonext-upstream-triesThe number of possible tries for passing a request to the next upstream server. See the proxy_next_upstream_tries directive. The 0 value turns off this limit. The default is 0.intNoclient-max-body-sizeSets the maximum allowed size of the client request body. See the client_max_body_size directive. The default is set in the client-max-body-size ConfigMap key.stringNotlsThe TLS configuration for the Upstream.tlsNohealthCheckThe health check configuration for the Upstream. See the health_check directive. Note: this feature is supported only in NGINX Plus.healthcheckNoslow-startThe slow start allows an upstream server to gradually recover its weight from 0 to its nominal value after it has been recovered or became available or when the server becomes available after a period of time it was considered unavailable. By default, the slow start is disabled. See the slow_start parameter of the server directive. Note: The parameter cannot be used along with the random\ , hash or ip_hash load balancing methods and will be ignored.stringNoqueueConfigures a queue for an upstream. A client request will be placed into the queue if an upstream server cannot be selected immediately while processing the request. By default, no queue is configured. Note: this feature is supported only in NGINX Plus.queueNobufferingEnables buffering of responses from the upstream server. See the proxy_buffering directive. The default is set in the proxy-buffering ConfigMap key.booleanNobuffersConfigures the buffers used for reading a response from the upstream server for a single connection.buffersNobuffer-sizeSets the size of the buffer used for reading the first part of a response received from the upstream server. See the proxy_buffer_size directive. The default is set in the proxy-buffer-size ConfigMap key.stringNoThe buffers field configures the buffers used for reading a response from the upstream server for a single connection:
See the proxy_buffers directive for additional information.
FieldDescriptionTypeRequirednumberConfigures the number of buffers. The default is set in the proxy-buffers ConfigMap key.intYessizeConfigures the size of a buffer. The default is set in the proxy-buffers ConfigMap key.stringYesThe queue field configures a queue. A client request will be placed into the queue if an upstream server cannot be selected immediately while processing the request:
See queue directive for additional information.
Note: This feature is supported only in NGINX Plus.
FieldDescriptionTypeRequiredsizeThe size of the queue.intYestimeoutThe timeout of the queue. A request cannot be queued for a period longer than the timeout. The default is 60s.stringNoThe Healthcheck defines an active health check. In the example below we enable a health check for an upstream and configure all the available parameters:
name: teaservice: tea-svcport: 80healthCheck:enable: truepath: /healthzinterval: 20sjitter: 3sfails: 5passes: 5port: 8080tls:enable: trueconnect-timeout: 10sread-timeout: 10ssend-timeout: 10sheaders:- name: Hostvalue: my.servicestatusMatch: "! 500"Note: This feature is supported only in NGINX Plus.
FieldDescriptionTypeRequiredenableEnables a health check for an upstream server. The default is false.booleanNopathThe path used for health check requests. The default is /.stringNointervalThe interval between two consecutive health checks. The default is 5s.stringNojitterThe time within which each health check will be randomly delayed. By default, there is no delay.stringNofailsThe number of consecutive failed health checks of a particular upstream server after which this server will be considered unhealthy. The default is 1.integerNopassesThe number of consecutive passed health checks of a particular upstream server after which the server will be considered healthy. The default is 1.integerNoportThe port used for health check requests. By default, the port of the upstream is used. Note: in contrast with the port of the upstream, this port is not a service port, but a port of a pod.integerNotlsThe TLS configuration used for health check requests. By default, the tls field of the upstream is used.upstream.tlsNoconnect-timeoutThe timeout for establishing a connection with an upstream server. By default, the connect-timeout of the upstream is used.stringNoread-timeoutThe timeout for reading a response from an upstream server. By default, the read-timeout of the upstream is used.stringNosend-timeoutThe timeout for transmitting a request to an upstream server. By default, the send-timeout of the upstream is used.stringNoheadersThe request headers used for health check requests. NGINX Plus always sets the Host\ , User-Agent and Connection headers for health check requests.[]headerNostatusMatchThe expected response status codes of a health check. By default, the response should have status code 2xx or 3xx. Examples: "200"\ , "! 500"\ , "301-303 307". See the documentation of the match directive.stringNoThe SessionCookie field configures session persistence which allows requests from the same client to be passed to the same upstream server. The information about the designated upstream server is passed in a session cookie generated by NGINX Plus.
In the example below, we configure session persistence with a session cookie for an upstream and configure all the available parameters:
name: teaservice: tea-svcport: 80sessionCookie:enable: truename: srv_idpath: /expires: 1hdomain: .example.comhttpOnly: falsesecure: trueSee the sticky directive for additional information. The session cookie corresponds to the sticky cookie method.
Note: This feature is supported only in NGINX Plus.
FieldDescriptionTypeRequiredenableEnables session persistence with a session cookie for an upstream server. The default is false.booleanNonameThe name of the cookie.stringYespathThe path for which the cookie is set.stringNoexpiresThe time for which a browser should keep the cookie. Can be set to the special value max\ , which will cause the cookie to expire on 31 Dec 2037 23:55:55 GMT.stringNodomainThe domain for which the cookie is set.stringNohttpOnlyAdds the HttpOnly attribute to the cookie.booleanNosecureAdds the Secure attribute to the cookie.booleanNoThe header defines an HTTP Header:
name: Hostvalue: example.comFieldDescriptionTypeRequirednameThe name of the header.stringYesvalueThe value of the header.stringNoThe action defines an action to perform for a request.
In the example below, client requests are passed to an upstream coffee:
path: /coffee action:pass: coffeeFieldDescriptionTypeRequiredpassPasses requests to an upstream. The upstream with that name must be defined in the resource.stringNoredirectRedirects requests to a provided URL.action.redirectNoreturnReturns a preconfigured response.action.returnNoproxyPasses requests to an upstream with the ability to modify the request/response (for example, rewrite the URI or modify the headers).action.proxyNo* – an action must include exactly one of the following: pass, redirect, return or proxy.
The redirect action defines a redirect to return for a request.
In the example below, client requests are passed to a url http://www.nginx.com:
redirect:url: http://www.nginx.comcode: 301FieldDescriptionTypeRequiredurlThe URL to redirect the request to. Supported NGINX variables: $scheme\ , $http_x_forwarded_proto\ , $request_uri\ , $host. Variables must be enclosed in curly braces. For example: ${host}${request_uri}.stringYescodeThe status code of a redirect. The allowed values are: 301\ , 302\ , 307\ , 308. The default is 301.intNoThe return action defines a preconfigured response for a request.
In the example below, NGINX will respond with the preconfigured response for every request:
return:code: 200type: text/plainbody: "Hello World\n"FieldDescriptionTypeRequiredcodeThe status code of the response. The allowed values are: 2XX, 4XX or 5XX. The default is 200.intNotypeThe MIME type of the response. The default is text/plain.stringNobodyThe body of the response. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: Request is ${request_uri}\n.stringYes* – Supported NGINX variables: $request_uri, $request_method, $request_body, $scheme, $http_, $args, $arg_, $cookie_, $host, $request_time, $request_length, $nginx_version, $pid, $connection, $remote_addr, $remote_port, $time_iso8601, $time_local, $server_addr, $server_port, $server_name, $server_protocol, $connections_active, $connections_reading, $connections_writing and $connections_waiting.
The proxy action passes requests to an upstream with the ability to modify the request/response (for example, rewrite the URI or modify the headers).
In the example below, the request URI is rewritten to /, and the request and the response headers are modified:
proxy:upstream: coffeerequestHeaders:pass: trueset:- name: My-Headervalue: Value- name: Client-Certvalue: ${ssl_client_escaped_cert}responseHeaders:add:- name: My-Headervalue: Value- name: IC-Nginx-Versionvalue: ${nginx_version}always: truehide:- x-internal-versionignore:- Expires- Set-Cookiepass:- ServerrewritePath: /FieldDescriptionTypeRequiredupstreamThe name of the upstream which the requests will be proxied to. The upstream with that name must be defined in the resource.stringYesrequestHeadersThe request headers modifications.action.Proxy.RequestHeadersNoresponseHeadersThe response headers modifications.action.Proxy.ResponseHeadersNorewritePathThe rewritten URI. If the route path is a regular expression (starts with ~), the rewritePath can include capture groups with $1-9. For example $1 for the first group, and so on. For more information, check the rewrite example.stringNoThe RequestHeaders field modifies the headers of the request to the proxied upstream server.
FieldDescriptionTypeRequiredpassPasses the original request headers to the proxied upstream server. See the proxy_pass_request_header directive for more information. Default is true.boolNosetAllows redefining or appending fields to present request headers passed to the proxied upstream servers. See the proxy_set_header directive for more information.[]headerNoThe header defines an HTTP Header:
name: My-Headervalue: My-ValueIt is possible to override the default value of the Host header, which the Ingress Controller sets to $host:
name: Hostvalue: example.comFieldDescriptionTypeRequirednameThe name of the header.stringYesvalueThe value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ${scheme}.stringNo* – Supported NGINX variables: $request_uri, $request_method, $request_body, $scheme, $http_, $args, $arg_, $cookie_, $host, $request_time, $request_length, $nginx_version, $pid, $connection, $remote_addr, $remote_port, $time_iso8601, $time_local, $server_addr, $server_port, $server_name, $server_protocol, $connections_active, $connections_reading, $connections_writing, $connections_waiting, $ssl_cipher, $ssl_ciphers, $ssl_client_cert, $ssl_client_escaped_cert, $ssl_client_fingerprint, $ssl_client_i_dn, $ssl_client_i_dn_legacy, $ssl_client_raw_cert, $ssl_client_s_dn, $ssl_client_s_dn_legacy, $ssl_client_serial, $ssl_client_v_end, $ssl_client_v_remain, $ssl_client_v_start, $ssl_client_verify, $ssl_curves, $ssl_early_data, $ssl_protocol, $ssl_server_name, $ssl_session_id, $ssl_session_reused, $jwt_claim_ (NGINX Plus only) and $jwt_header_ (NGINX Plus only).
The ResponseHeaders field modifies the headers of the response to the client.
FieldDescriptionTypeRequiredhideThe headers that will not be passed* in the response to the client from a proxied upstream server. See the proxy_hide_header directive for more information.boolNopassAllows passing the hidden header fields* to the client from a proxied upstream server. See the proxy_pass_header directive for more information.[]stringNoignoreDisables processing of certain headers** to the client from a proxied upstream server. See the proxy_ignore_headers directive for more information.[]stringNoaddAdds headers to the response to the client.[]addHeaderNo* – Default hidden headers are: Date, Server, X-Pad and X-Accel-....
** – The following fields can be ignored: X-Accel-Redirect, X-Accel-Expires, X-Accel-Limit-Rate, X-Accel-Buffering, X-Accel-Charset, Expires, Cache-Control, Set-Cookie and Vary.
The addHeader defines an HTTP Header with an optional always field:
name: My-Headervalue: My-Valuealways: trueFieldDescriptionTypeRequirednameThe name of the header.stringYesvalueThe value of the header. Supports NGINX variables*. Variables must be enclosed in curly brackets. For example: ${scheme}.stringNoalwaysIf set to true, add the header regardless of the response status code**. Default is false. See the add_header directive for more information.boolNo* – Supported NGINX variables: $request_uri, $request_method, $request_body, $scheme, $http_, $args, $arg_, $cookie_, $host, $request_time, $request_length, $nginx_version, $pid, $connection, $remote_addr, $remote_port, $time_iso8601, $time_local, $server_addr, $server_port, $server_name, $server_protocol, $connections_active, $connections_reading, $connections_writing, $connections_waiting, $ssl_cipher, $ssl_ciphers, $ssl_client_cert, $ssl_client_escaped_cert, $ssl_client_fingerprint, $ssl_client_i_dn, $ssl_client_i_dn_legacy, $ssl_client_raw_cert, $ssl_client_s_dn, $ssl_client_s_dn_legacy, $ssl_client_serial, $ssl_client_v_end, $ssl_client_v_remain, $ssl_client_v_start, $ssl_client_verify, $ssl_curves, $ssl_early_data, $ssl_protocol, $ssl_server_name, $ssl_session_id, $ssl_session_reused, $jwt_claim_ (NGINX Plus only) and $jwt_header_ (NGINX Plus only).
** – If always is false, the response header is added only if the response status code is any of 200, 201, 204, 206, 301, 302, 303, 304, 307 or 308.
The split defines a weight for an action as part of the splits configuration.
In the example below NGINX passes 80% of requests to the upstream coffee-v1 and the remaining 20% to coffee-v2:
splits:- weight: 80action:pass: coffee-v1- weight: 20action:pass: coffee-v2FieldDescriptionTypeRequiredweightThe weight of an action. Must fall into the range 1..99. The sum of the weights of all splits must be equal to 100.intYesactionThe action to perform for a request.actionYesThe match defines a match between conditions and an action or splits.
In the example below, NGINX routes requests with the path /coffee to different upstreams based on the value of the cookie user:
user=john -> coffee-futureuser=bob -> coffee-deprecatedIf the cookie is not set or not equal to either john or bob, NGINX routes to coffee-stablepath: /coffeematches:- conditions:- cookie: uservalue: johnaction:pass: coffee-future- conditions:- cookie: uservalue: bobaction:pass: coffee-deprecatedaction:pass: coffee-stableIn the next example, NGINX routes requests based on the value of the built-in $request_method variable, which represents the HTTP method of a request:
all POST requests -> coffee-postall non-POST requests -> coffeepath: /coffeematches:- conditions:- variable: $request_methodvalue: POSTaction:pass: coffee-postaction:pass: coffeeFieldDescriptionTypeRequiredconditionsA list of conditions. Must include at least 1 condition.[]conditionYesactionThe action to perform for a request.actionNosplitsThe splits configuration for traffic splitting. Must include at least 2 splits.[]splitNo* – a match must include exactly one of the following: action or splits.
The condition defines a condition in a match.
FieldDescriptionTypeRequiredheaderThe name of a header. Must consist of alphanumeric characters or -.stringNocookieThe name of a cookie. Must consist of alphanumeric characters or _.stringNoargumentThe name of an argument. Must consist of alphanumeric characters or _.stringNovariableThe name of an NGINX variable. Must start with $. See the list of the supported variables below the table.stringNovalueThe value to match the condition against. How to define a value is shown below the table.stringYes* – a condition must include exactly one of the following: header, cookie, argument or variable.
Supported NGINX variables: $args, $http2, $https, $remote_addr, $remote_port, $query_string, $request, $request_body, $request_uri, $request_method, $scheme. Find the documentation for each variable here.
The value supports two kinds of matching:
Case-insensitive string comparison. For example:john – case-insensitive matching that succeeds for strings, such as john, John, JOHN.!john – negation of the case-incentive matching for john that succeeds for strings, such as bob, anything, '' (empty string).Matching with a regular expression. Note that NGINX supports regular expressions compatible with those used by the Perl programming language (PCRE). For example:~^yes – a case-sensitive regular expression that matches any string that starts with yes. For example: yes, yes123.!~^yes – negation of the previous regular expression that succeeds for strings like YES, Yes123, noyes. (The negation mechanism is not part of the PCRE syntax).~*no$ – a case-insensitive regular expression that matches any string that ends with no. For example: no, 123no, 123NO.Note: a value must not include any unescaped double quotes (") and must not end with an unescaped backslash (\). For example, the following are invalid values: some"value, somevalue\.
The errorPage defines a custom response for a route for the case when either an upstream server responds with (or NGINX generates) an error status code. The custom response can be a redirect or a canned response. See the error_page directive for more information.
path: /coffeeerrorPages:- codes: [502, 503]redirect:code: 301url: https://nginx.org- codes: [404]return:code: 200body: "Original resource not found, but success!"FieldDescriptionTypeRequiredcodesA list of error status codes.[]intYesredirectThe redirect action for the given status codes.errorPage.RedirectNoreturnThe canned response action for the given status codes.errorPage.ReturnNo* – an errorPage must include exactly one of the following: return or redirect.
The redirect defines a redirect for an errorPage.
In the example below, NGINX responds with a redirect when a response from an upstream server has a 404 status code.
codes: [404]redirect:code: 301url: ${scheme}://cafe.example.com/error.htmlFieldDescriptionTypeRequiredcodeThe status code of a redirect. The allowed values are: 301\ , 302\ , 307\ , 308.The default is 301.intNourlThe URL to redirect the request to. Supported NGINX variables: $scheme\ and $http_x_forwarded_proto. Variables must be enclosed in curly braces. For example: ${scheme}.stringYesThe return defines a canned response for an errorPage.
In the example below, NGINX responds with a canned response when a response from an upstream server has either 401 or 403 status code.
codes: [401, 403]return:code: 200type: application/jsonbody: |{\"msg\": \"You don't have permission to do this\"}headers:- name: x-debug-original-statusesvalue: ${upstream_status}FieldDescriptionTypeRequiredcodeThe status code of the response. The default is the status code of the original response.intNotypeThe MIME type of the response. The default is text/html.stringNobodyThe body of the response. Supported NGINX variable: $upstream_status \ . Variables must be enclosed in curly braces. For example: ${upstream_status}.stringYesheadersThe custom headers of the response.errorPage.Return.HeaderNoThe header defines an HTTP Header for a canned response in an errorPage:
name: x-debug-original-statusesvalue: ${upstream_status}FieldDescriptionTypeRequirednameThe name of the header.stringYesvalueThe value of the header. Supported NGINX variable: $upstream_status \ . Variables must be enclosed in curly braces. For example: ${upstream_status}.stringNoYou can use the usual kubectl commands to work with VirtualServer and VirtualServerRoute resources, similar to Ingress resources.
For example, the following command creates a VirtualServer resource defined in cafe-virtual-server.yaml with the name cafe:
$ kubectl apply -f cafe-virtual-server.yamlvirtualserver.k8s.nginx.org "cafe" createdYou can get the resource by running:
$ kubectl get virtualserver cafeNAME STATE HOST IPPORTSAGEcafe Valid cafe.example.com 12.13.23.123[80,443] 3mIn the kubectl get and similar commands, you can also use the short name vs instead of virtualserver.
Working with VirtualServerRoute resources is analogous. In the kubectl commands, use virtualserverroute or the short name vsr.
Snippets allow you to insert raw NGINX config into different contexts of NGINX configuration. In the example below, we use snippets to configure several NGINX features in a VirtualServer:
apiVersion: k8s.nginx.org/v1kind: VirtualServermetadata:name: cafenamespace: cafespec:http-snippets: |limit_req_zone $binary_remote_addr zone=mylimit:10m rate=1r/s;proxy_cache_path /tmp keys_zone=one:10m;host: cafe.example.comtls:secret: cafe-secretserver-snippets: |limit_req zone=mylimit burst=20;upstreams:- name: teaservice: tea-svcport: 80- name: coffeeservice: coffee-svcport: 80routes:- path: /tealocation-snippets: |proxy_cache one;proxy_cache_valid 200 10m;action:pass: tea- path: /coffeeaction:pass: coffeeSnippets are intended to be used by advanced NGINX users who need more control over the generated NGINX configuration.
However, because of the disadvantages described below, snippets are disabled by default. To use snippets, set the enable-snippets command-line argument.
Disadvantages of using snippets:
Complexity. To use snippets, you will need to:Understand NGINX configuration primitives and implement a correct NGINX configuration.Understand how the IC generates NGINX configuration so that a snippet doesn’t interfere with the other features in the configuration.Decreased robustness. An incorrect snippet makes the NGINX config invalid which will lead to a failed reload. This will prevent any new configuration updates, including updates for the other VirtualServer and VirtualServerRoute resources until the snippet is fixed.Security implications. Snippets give access to NGINX configuration primitives and those primitives are not validated by the Ingress Controller. For example, a snippet can configure NGINX to serve the TLS certificates and keys used for TLS termination for Ingress and VirtualServer resources.To help catch errors when using snippets, the Ingress Controller reports config reload errors in the logs as well as in the events and status field of VirtualServer and VirtualServerRoute resources. Additionally, a number of Prometheus metrics show the stats about failed reloads – controller_nginx_last_reload_status and controller_nginx_reload_errors_total.
Note that during a period when the NGINX config includes an invalid snippet, NGINX will continue to operate with the latest valid configuration.
Two types of validation are available for VirtualServer and VirtualServerRoute resources:
Structural validation by the kubectl and Kubernetes API server.Comprehensive validation by the Ingress Controller.Structural ValidationThe custom resource definitions for VirtualServer and VirtualServerRoute include structural OpenAPI schema which describes the type of every field of those resources.
If you try to create (or update) a resource that violates the structural schema (for example, you use a string value for the port field of an upstream), kubectl and Kubernetes API server will reject such a resource:
Example of kubectl validation:$ kubectl apply -f cafe-virtual-server.yamlerror: error validating "cafe-virtual-server.yaml": error validating data: ValidationError(VirtualServer.spec.upstreams[0].port): invalid type for org.nginx.k8s.v1.VirtualServer.spec.upstreams.port: got "string", expected "integer"; if you choose to ignore these errors, turn validation off with --validate=falseExample of Kubernetes API server validation:$ kubectl apply -f cafe-virtual-server.yaml --validate=falseThe VirtualServer "cafe" is invalid: []: Invalid value: map[string]interface {}{ ... }: validation failure list:spec.upstreams.port in body must be of type integer: "string"If a resource is not rejected (it doesn’t violate the structural schema), the Ingress Controller will validate it further.
Comprehensive ValidationThe Ingress Controller validates the fields of the VirtualServer and VirtualServerRoute resources. If a resource is invalid, the Ingress Controller will reject it: the resource will continue to exist in the cluster, but the Ingress Controller will ignore it.
You can check if the Ingress Controller successfully applied the configuration for a VirtualServer. For our example cafe VirtualServer, we can run:
$ kubectl describe vs cafe. . .Events:TypeReasonAge FromMessage-------------------------NormalAddedOrUpdated16s nginx-ingress-controllerConfiguration for default/cafe was added or updatedNote how the events section includes a Normal event with the AddedOrUpdated reason that informs us that the configuration was successfully applied.
If you create an invalid resource, the Ingress Controller will reject it and emit a Rejected event. For example, if you create a VirtualServer cafe with two upstream with the same name tea, you will get:
$ kubectl describe vs cafe. . .Events:Type ReasonAge FromMessage---- ---------------------WarningRejected12s nginx-ingress-controllerVirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"Note how the events section includes a Warning event with the Rejected reason.
Additionally, this information is also available in the status field of the VirtualServer resource. Note the Status section of the VirtualServer:
$ kubectl describe vs cafe. . .Status:External Endpoints:Ip:12.13.23.123Ports: [80,443]Message:VirtualServer default/cafe is invalid and was rejected: spec.upstreams[1].name: Duplicate value: "tea"Reason: RejectedState:InvalidThe Ingress Controller validates VirtualServerRoute resources in a similar way.
Note: If you make an existing resource invalid, the Ingress Controller will reject it and remove the corresponding configuration from NGINX.
You can customize the NGINX configuration for VirtualServer and VirtualServerRoutes resources using the ConfigMap. Most of the ConfigMap keys are supported, with the following exceptions:
proxy-hide-headersproxy-pass-headershstshsts-max-agehsts-include-subdomainshsts-behind-proxyredirect-to-httpsssl-redirectNEXT: DB2® Connect : A remote client fails to connect to a DB2 ...
![[Solved] Can't connect to MySql server on localhost (10061) (View topic) * Apache OpenOffice Community Forum](http://website-google-hk.oss-cn-hongkong.aliyuncs.com/drawing/26/2022-3-1/7051.jpeg "[Solved] Can't connect to MySql server on localhost (10061) (View topic) * Apache OpenOffice Community Forum")
