Migrating applications from NGINX Ingress to Gwin

Written by

Updated at December 29, 2025

Mapping table of Ingress NGINX and Gwin annotations
Switch workload to the Gwin controller

Yandex Application Load Balancer allows you to create and manage load balancers in Yandex Managed Service for Kubernetes clusters using the Gwin controller. Installed in a cluster, the Gwin controller automatically deploys L7 load balancers based on the configuration of your Kubernetes resources.

To migrate applications from the NGINX Ingress Controller to Gwin, follow these steps:

Install the Gwin controller in your cluster.
Migrate custom annotations from the NGINX Ingress controller to the Gwin controller using the mapping table.
Switch the workload over to the Gwin controller.

Mapping table of Ingress NGINX and Gwin annotations

The table gives abbreviated annotation names for NGINX and Gwin. Full annotation names start with nginx.ingress.kubernetes.io/ for NGINX, and gwin.yandex.cloud/ for Gwin.

NGINX	Gwin	Description
Redirection
`force-ssl-redirect` `ssl-redirect`	redirect.{name}.replaceScheme	Redirects to another protocol (HTTP/HTTPS)
`permanent-redirect` `temporal-redirect` `app-root`	redirect.{name}.replaceScheme redirect.{name}.replaceHost redirect.{name}.replacePort redirect.{name}.path.replacePath redirect.{name}.path.replacePrefix redirect.{name}.removeQuery redirect.{name}.responseCode	Redirect to another address Gwin specifies `redirect.{name}.responseCode = "301"` for permanent redirection and `redirect.{name}.responseCode = "302"` for temporary redirection
`rewrite-target`	rules.prefixRewrite rules.hostRewrite.auto rules.hostRewrite.replace rules.http.regexRewrite.regex rules.http.regexRewrite.substitute	Rewrites URLs at the proxy level without changing the address in the browser
Backend configuration
`backend-protocol`	rules.backends.http.useHTTP2 rules.backends.tls.sni rules.backends.tls.trustedCA.id rules.backends.tls.trustedCA.bytes	Establishes the connection protocol between the load balancer and backends
Client authentication
`auth-type` `auth-secret` `auth-secret-type` `auth-realm` `auth-tls-secret` `auth-tls-verify-depth` `auth-tls-verify-client` `auth-tls-error-page` `auth-tls-pass-certificate-to-upstream` `auth-tls-match-cn`	{resource}.rbac.principals.{principal-group}.{principal}.{rule-type}	In NGINX, authentication is performed via HTTP (Basic/Digest) or TLS certificates, whereas in Gwin, using the role-based access control (RBAC) system. RBAC manages access to routes and hosts based on request attributes.
Binding a session to a backend
`affinity` `affinity-mode` `affinity-canary-behavior` `session-cookie-name` `session-cookie-path` `session-cookie-domain` `session-cookie-change-on-failure` `session-cookie-samesite` `session-cookie-conditional-samesite-none`	rules.sessionAffinity.header.name rules.sessionAffinity.cookie.name rules.sessionAffinity.cookie.ttl rules.sessionAffinity.sourceIP	NGINX allows session binding via cookies; Gwin does the same via cookies, headers, or IP addresses
Backend certificate verification
`proxy-ssl-secret` `proxy-ssl-verify` `proxy-ssl-verify-depth` `proxy-ssl-ciphers` `proxy-ssl-name` `proxy-ssl-protocols`	rules.backends.tls.sni rules.backends.tls.trustedCA.id rules.backends.tls.trustedCA.bytes	NGINX sets up certificate verification through SSL; Gwin uses TLS
Connection timeouts
`proxy-connect-timeout` `proxy-send-timeout` `proxy-read-timeout` `proxy-next-upstream` `proxy-next-upstream-timeout` `proxy-next-upstream-tries` `proxy-request-buffering`	rules.timeout rules.idleTimeout	In Gwin, you set a general backend response timeout and an idle timeout
Rate limit
`global-rate-limit` `global-rate-limit-window` `global-rate-limit-key` `global-rate-limit-ignored-cidrs`	hosts.rateLimit.allRequests.perSecond hosts.rateLimit.allRequests.perMinute hosts.rateLimit.requestsPerIP.perSecond hosts.rateLimit.requestsPerIP.perMinute	Sets the maximum number of requests you can send within a time interval
Logging
`enable-access-log`	logs.logGroupID logs.logs.disable logs.discardRule.{name}.httpCodes logs.discardRule.{name}.httpCodeIntervals logs.discardRule.{name}.grpcCodes logs.discardRule.{name}.discardPercent	Enables logging In Gwin, you can also configure logging parameters
Other
`custom-http-errors`	directResponse.{name}.responseCode directResponse.{name}.responseBody.text	Specifies the error code and response text
`proxy-http-version`	rules.backends.http.useHTTP2	Determines the HTTP version for backend interaction
`limit-rps`	hosts.rateLimit.requestsPerIP.perSecond	Sets the number of requests from one IP per second
`proxy-cookie-domain` `proxy-cookie-path`	rules.modifyResponseHeaders.append.{header-name} rules.modifyResponseHeaders.rename.{old-header-name} rules.modifyResponseHeaders.replace.{header-name} rules.modifyResponseHeaders.remove	Set response headers
`load-balance`	rules.backends.balancing.mode	Sets the load balancing algorithm

Switch workload to the Gwin controller

Creating new resources in the cluster

Apply the updated YAML manifests using the following command: kubectl apply -f <YAML_file_or_folder>.

This will create a new load balancer without removing the existing one.
Make sure all resources were successfully created by checking their status with the kubectl get command.

Checking that your load balancing is correct

Test the new load balancer to ensure it functions correctly:

Get the IP address of your new load balancer:
- Retrieve the Ingress resource status using the kubectl get Ingress command.
- In the management console, do the following:
  - Go to the Managed Service for Kubernetes cluster page.
  - In the left-hand panel, select Network.
  - Navigate to the Ingress tab.
Make sure routing behaves as expected by testing the availability of your app's HTTP/HTTPS endpoints.
Make sure backend health checks report all backends as healthy.
Check the logs for errors and review the load balancer metrics for any signs of performance issues.

Redirecting traffic to the new load balancer

Update your domain DNS records to point to the new load balancer's IP address, thereby redirecting traffic.
Monitor app metrics during the traffic switchover.
Make sure the app's features remain fully accessible after the traffic redirection.

Deleting the resources you no longer need

Delete your old NGINX Ingress resources, i.e., original ingress controllers, backend groups, etc.
Remove any unused load balancers or TLS certificates.

Migrating applications from NGINX Ingress to Gwin

Mapping table of Ingress NGINX and Gwin annotationsMapping table of Ingress NGINX and Gwin annotations

Switch workload to the Gwin controllerSwitch workload to the Gwin controller

Creating new resources in the clusterCreating new resources in the cluster

Checking that your load balancing is correctChecking that your load balancing is correct

Redirecting traffic to the new load balancerRedirecting traffic to the new load balancer

Deleting the resources you no longer needDeleting the resources you no longer need