How to translate an ingress using websockets to gateway API?

[kbsquared]

Is there an example somewhere of how to use NGF to host websockets? I've been looking for one and can not find it.

With NGINX Plus ingress controller we're using the following annotations, these are what I need to chase down the equivalent for...

nginx.org/proxy-read-timeout: 200s
nginx.org/proxy-set-headers: "true"
nginx.org/redirect-to-https: "true"
nginx.org/websocket-services: servicea,serviceb

Any examples or guidance would be wonderful and might help others as well.

Thank you.

[sjberman]

Hi @kbsquared, to set up HTTPS redirection, you can see an example using a requestRedirect filter in an HTTPRoute in this guide.

You can then send a request with the "Upgrade: websocket" header set, which should allow traffic to be sent to your websocket service. If you also need to set other websocket headers likeSec-WebSocket-Key and Sec-WebSocket-Version, you can set those using a requestHeaderModifier filter, see this guide. The Upgrade header cannot be set in a filter, it must be set in the client request.

Timeouts are not yet supported in a native API policy, so you can use the SnippetsFilter API as a workaround for now.

Let me know if this helps out!

[sjberman]

The Upgrade and Connection headers can't be set in the header filters, NGF sets those values.

We automatically set the Upgrade header to $http_upgrade (which is the value of the Upgrade header provided by the client). The connection header is set to upgrade if $http_upgrade is set, otherwise it's set to close.

So you should not need to define any of these (nor can you) in the filters.

Otherwise I think the route looks good, just remove those header filters.

[sjberman]

I'll create an issue to document how we support websocket services (assuming that this process ends up working for you).

[kbsquared]

I need to do a lot of testing but at a cursory glance it seems to be working. Now for the timeout...

The guide you pointed me too for the snippet filters doesn't show the proxy-read-timeout example. I looked through the API docs linked in the guide to see if I could figure out how to list this and I'm not having any luck.

Thank you for the offer for the documentation. It might be nice to try and go through some of the more common ingress controllers/annotations and come up with a how to guide on how to translate them.

I thank you so much for your assistance.

[sjberman]

Happy to help, and this type of feedback around use cases always helps us improve our documentation so we know what users need!

Regarding the snippets filter, I think you could define one as simply as:

apiVersion: gateway.nginx.org/v1alpha1
kind: SnippetsFilter
metadata:
  name: proxy-read-timeout
spec:
  snippets:
    - context: http.server.location
      value: proxy_read_timeout 200s;

and attach it to each HTTPRoute rule similar to the example in that guide. The idea behind the SnippetsFilter is basically giving the ability to inject literal nginx config into a specific place.

[kbsquared]

Thank you so much for the help.

Just so you know, I never would have figured out how to do that. From the guide you linked I ended up at the API doc trying to find something that would tell me the context for the proxy_read_timeout and it wasn't listed on the page.

This - https://docs.nginx.com/nginx-gateway-fabric/reference/api/

Led me here - https://nginx.org/en/docs/http/ngx_http_core_module.html#location

Not sure how I would have found this information out without you. Thanks again, now I'm off to test!

[sjberman]

Glad I could help. And thank you for the feedback.

It's hard to account for all the possible nginx directives that could be used, which is why we introduced the SnippetsFilter API to allow users to inject nginx config that isn't available in any first-class policy or API.

It would probably be useful for us to have a doc on how to convert from NGINX Ingress Controller configuration to NGINX Gateway Fabric configuration (when possible).

[sjberman]

There is a tool (https://github.com/kubernetes-sigs/ingress2gateway) that is being developed that should be able to convert basic ingress configuration to Gateway API configuration, however it doesn't yet support NGINX Ingress Controller annotation conversions.