> ## Documentation Index
> Fetch the complete documentation index at: https://ryvn.ai/docs/llms.txt
> Use this file to discover all available pages before exploring further.

# Ingress networking (deprecated)

> What still works for Kubernetes Ingress on Ryvn, what doesn't, and how to move to ports, domains, and Routes

> [!WARNING]
>
> Ingress networking is deprecated. For new work, use `spec.networking` on server installations and
> [Routes](https://ryvn.ai/docs/networking/routes.md) in Helm charts. See [Networking](https://ryvn.ai/docs/networking/overview.md).

Ryvn used to expose installations through Kubernetes Ingress resources that ingress-nginx served. The Kubernetes
community [retired ingress-nginx](https://kubernetes.io/blog/2025/11/11/ingress-nginx-retirement/) in March 2026, so
Ryvn environments move off it. Ports, domains, and Routes are now the way to expose an installation.

An existing Ingress keeps working. For compatibility, Ryvn environments provide two ingress classes: `external-nginx`
for the public network and `internal-nginx` for the internal network. A compatibility layer serves an Ingress that
uses one of these classes, and most Ingress resources need no changes. An Ingress with any other class is not
affected.

## Does this affect you?

| You have | What to do |
| - | - |
| A server installation with a **Networking mode** and no NGINX annotations | Nothing. It keeps working. For new work, see [what to use instead](#what-to-use-instead). |
| A server installation with `nginx.ingress.kubernetes.io/*` annotations | Check each annotation in the [annotation support](#annotation-support) list. |
| A Helm chart that creates an Ingress | Check the rendered Ingress: its annotations and its [spec fields](#helm-chart-notes). |

A server installation uses Ingress networking when its **Settings > Networking** tab shows a **Networking mode**. A
Helm chart installation uses it when the chart creates an Ingress.

If a chart depends on something that isn't supported, override its values, use another chart version, or expose the
chart [with a Route](https://ryvn.ai/docs/networking/routes.md#third-party-charts).

## What to use instead

Networking modes are a dashboard setting, and ports replace them. In the installation's **Settings > Networking** tab,
list the ports your app listens on and choose which ones are public.

| Networking mode | With ports |
| - | - |
| Public | Make the port [public](https://ryvn.ai/docs/networking/overview.md#public-the-internet). |
| Internal | Nothing to set. Every port has an [internal address](https://ryvn.ai/docs/networking/overview.md#internal-your-vpc-and-connected-networks). |
| Private | Nothing to set. Every installation is reachable [inside the environment](https://ryvn.ai/docs/networking/overview.md#private-inside-the-environment). |

In YAML, `spec.networking` and Routes replace the Ingress configuration:

| Ingress configuration | Replacement |
| - | - |
| `config.ingress` on a server installation | [`spec.networking`](https://ryvn.ai/docs/iac/installations/server#networking) |
| An Ingress in a Helm chart | A [Route](https://ryvn.ai/docs/networking/routes.md) |
| Your own domain as an Ingress host | A domain on the port or the Route. See [Domains and TLS](https://ryvn.ai/docs/networking/domains-and-tls.md). |
| Auth annotations | `security.externalAuth` on a Route. See [external auth](https://ryvn.ai/docs/networking/routes.md#external-auth). |

## Annotation support

Every annotation name on this page starts with `nginx.ingress.kubernetes.io/`.

| Annotation | Status | Notes |
| - | - | - |
| `force-ssl-redirect`, `ssl-redirect` | Works | The redirect [keeps a trailing slash](#https-redirects-and-trailing-slashes). |
| `proxy-read-timeout`, `proxy-send-timeout` | Changed | One deadline for the whole request. See [Timeouts](#timeouts). |
| `proxy-connect-timeout` | Works | Defaults to 60 seconds. Applies to the Service, not to one Ingress. See [Timeouts](#timeouts). |
| `backend-protocol` | Changed | `HTTP` and `GRPC` only. See [Backend protocol](#backend-protocol). |
| `rewrite-target` | Changed | Literal paths only, such as `/`. Capture groups such as `/$1` are rejected. |
| `use-regex` | Works | |
| `whitelist-source-range`, `allowlist-source-range` | Works | IP allowlist. If both are set, they must have the same value. |
| `denylist-source-range` | Works | IP denylist. |
| `use-forwarded-headers`, `proxy-http-version`, `x-forwarded-proto` | No effect | Already the default behavior. Safe to leave in place. |
| `use-http2` | No effect | HTTP/2 is used where it applies. |
| `proxy-body-size` | No effect | No body size limit. Set the limit in your app. See [Body size](#body-size). |
| `proxy-buffering` and the other buffer annotations | No effect | Requests and responses stream. See [Buffering](#buffering). |
| `grpc-backend` | Unsupported | Use `backend-protocol: GRPC`. See [gRPC](#grpc). |
| Snippet annotations | Rejected | See [Snippets](#snippets). |
| Auth annotations | Rejected | Use external auth on a Route. See [Basic and external auth](#auth). |
| Client certificate annotations (`auth-tls-*`) | Rejected | Let your app terminate TLS with [TLS passthrough](https://ryvn.ai/docs/networking/overview.md#tls-passthrough). |
| ModSecurity annotations | Rejected | Ryvn doesn't provide a WAF. |

Ryvn doesn't admit an Ingress that sets a rejected annotation on one of its ingress classes.

An Ingress with an allowlist or a denylist can't have a wildcard host such as `*.example.com`. Ryvn rejects it, so
list each hostname.

## Behavior differences

### HTTPS redirects and trailing slashes

ingress-nginx removes a trailing slash when it redirects HTTP to HTTPS. The compatibility layer keeps the path as
requested.

| Request | ingress-nginx | Compatibility layer |
| - | - | - |
| `http://app.example.com/docs/` | `https://app.example.com/docs` | `https://app.example.com/docs/` |
| `http://app.example.com/docs/page/` | `https://app.example.com/docs/page` | `https://app.example.com/docs/page/` |

This affects only requests that end in `/`. A request for `/docs` on an Ingress path `/docs/` still redirects to
`/docs/`. If your app treats `/docs` and `/docs/` as different routes, test both.

### Timeouts

`proxy-read-timeout` and `proxy-send-timeout` both set one deadline for the whole request. If you set both, the larger
value wins.

On ingress-nginx, the read timeout is an idle timeout: the timer restarts each time your app sends data. On the
compatibility layer, it limits the total time of the request. A response that streams one chunk every 45 seconds runs
without end under a 60 second idle timeout, but stops after 60 seconds under a 60 second deadline.

This matters for long-lived HTTP connections: server-sent events, long polling, and large downloads. A large value
such as `86400` still works, but it counts from the start of the request.

`proxy-connect-timeout` defaults to 60 seconds, the same as ingress-nginx, and a value of `0` is ignored. If several
Ingress resources point at the same Service, set the same value on each. Conflicting values are dropped, and the
Service falls back to 60 seconds.

Timeout annotations don't apply to a [gRPC](#grpc) Ingress.

### Buffering

The compatibility layer streams requests and responses to your app and doesn't hold them in a buffer, so these
annotations have no effect:

* `nginx.ingress.kubernetes.io/proxy-buffering`
* `nginx.ingress.kubernetes.io/proxy-buffer-size`
* `nginx.ingress.kubernetes.io/proxy-buffers-number`
* `nginx.ingress.kubernetes.io/proxy-busy-buffers-size`
* `nginx.ingress.kubernetes.io/proxy-busy-buffers`
* `nginx.ingress.kubernetes.io/proxy-request-buffering`
* `nginx.ingress.kubernetes.io/client-body-buffer-size`
* `nginx.ingress.kubernetes.io/large-client-header-buffers`

Most apps see no difference. An app can notice if it relied on NGINX to absorb traffic for it: a server that stalls
when a request body arrives slowly, an app that sends very large response headers, or one that can't handle a partial
body. Handle the stream in your app, or run a buffering layer next to it.

## Not supported

### Snippets

A snippet injects arbitrary NGINX configuration, which is a security risk and makes routing hard to predict. Ryvn
rejects an Ingress that sets one of these annotations:

* `nginx.ingress.kubernetes.io/configuration-snippet`
* `nginx.ingress.kubernetes.io/server-snippet`
* `nginx.ingress.kubernetes.io/auth-snippet`
* `nginx.ingress.kubernetes.io/stream-snippet`

If a snippet blocks your move, [contact Ryvn support](https://ryvn.ai/docs/support/contact-us.md).

### Basic and external auth

Ryvn rejects an Ingress that sets an auth annotation:

* Basic auth: `nginx.ingress.kubernetes.io/auth-type`, `auth-secret`, `auth-secret-type`, `auth-realm`
* External auth: `nginx.ingress.kubernetes.io/auth-url`, `auth-signin`, `auth-signin-redirect-param`,
  `auth-response-headers`, `auth-request-redirect`, `auth-method`, `auth-proxy-set-headers`
* Global auth: `nginx.ingress.kubernetes.io/enable-global-auth`, `satisfy`

To check requests with your own auth service, use [external auth](https://ryvn.ai/docs/networking/routes.md#external-auth) on a Route. For
basic auth, or for an app with no auth of its own, Ryvn can help you run an auth proxy such as
[OAuth2 Proxy](https://oauth2-proxy.github.io/oauth2-proxy/) in front of the installation.
[Contact Ryvn support](https://ryvn.ai/docs/support/contact-us.md).

### Body size

`nginx.ingress.kubernetes.io/proxy-body-size` has no effect. The compatibility layer sets no limit on the request
body, so large requests reach your app. If you relied on the limit, for example to cap uploads, set it in your app:

* [Express.js](https://expressjs.com/en/api.html#express.json): the `limit` option on `express.json()` and
  `express.urlencoded()`.
* [Next.js Pages Router API routes](https://nextjs.org/docs/pages/building-your-application/routing/api-routes):
  `config.api.bodyParser.sizeLimit`. App Router Route Handlers have no equivalent, so cap the body as you read it.
* [Django](https://docs.djangoproject.com/en/stable/ref/settings/#data-upload-max-memory-size):
  `DATA_UPLOAD_MAX_MEMORY_SIZE` and `FILE_UPLOAD_MAX_MEMORY_SIZE`.
* [Flask](https://flask.palletsprojects.com/en/stable/patterns/fileuploads/): `app.config['MAX_CONTENT_LENGTH']`.
* [Spring Boot](https://docs.spring.io/spring-boot/reference/web/servlet.html#web.servlet.multipart):
  `spring.servlet.multipart.max-request-size` and `max-file-size`.
* [Go `net/http`](https://pkg.go.dev/net/http#MaxBytesReader): wrap the request body with `http.MaxBytesReader`.

### gRPC

`nginx.ingress.kubernetes.io/grpc-backend` is not supported. Use `nginx.ingress.kubernetes.io/backend-protocol: GRPC`.

A gRPC Ingress ignores the HTTP-only annotations, such as the timeout and redirect annotations.

### Backend protocol

`nginx.ingress.kubernetes.io/backend-protocol` supports `HTTP` and `GRPC`. `HTTPS` and `GRPCS`, which use TLS to your
app, are not supported, and neither are `AUTO_HTTP` and `FCGI`. `use-http2` is not needed, because HTTP/2 is used
where it applies.

### Ingress spec fields

A few Ingress fields behave differently on the compatibility layer:

* `backend.resource` is not supported. Use `backend.service`.
* `spec.defaultBackend` catches unmatched paths only for hosts in `spec.rules`. Requests for other hosts are rejected.
* `pathType: ImplementationSpecific` is a literal `Prefix` match.

## Configure an Ingress

These are the steps for installations that still use Ingress networking.

> [accordion] Server: networking modes
>
> Every server that uses Ingress networking has a networking mode, which sets where it is reachable:
>
> | Mode | Reachable from |
> | - | - |
> | Public | The internet |
> | Internal | Your VPC and connected networks |
> | Private | Other installations in the environment |
>
> A public server gets a TLS certificate that Ryvn issues and renews, and can serve a custom domain.

> [accordion] Server: add a custom domain
>
> 1. Open your installation in the Ryvn dashboard and go to **Settings** > **Networking**.
> 2. Switch to **Public** networking mode. Wait about 10 seconds for the installation to connect to the public
>    load balancer.
> 3. Enter your domain name in the custom domain field and click **Save**. Convert Unicode domains to Punycode
>    first. For example, `ëxample.com` becomes `xn--xample-ova.com`.
> 4. Copy the load balancer hostname or IP shown below the custom domain field. At your DNS provider, create a
>    CNAME record for your domain with that value. Some providers name this record ALIAS or ANAME.
> 5. Back in Ryvn, click **Connect**. Ryvn verifies domain ownership and creates a TLS certificate.
> 6. Check that your domain is reachable over HTTPS.

> [accordion] Helm chart: ingress values and a custom domain
>
> Each environment has two cert-manager issuers for the ingress classes: `external-issuer` for public domains and
> `internal-issuer` for internal domains.
>
> 1. Go to your installation's **Settings** > **Helm Values** and set the chart's `ingress` values:
>
>    ```yaml theme={null}
>    ingress:
>      enabled: true
>      className: external-nginx
>      annotations:
>        cert-manager.io/cluster-issuer: external-issuer
>      hosts:
>        - host: myapp.example.com
>          paths:
>            - path: /
>              pathType: Prefix
>      tls:
>        - secretName: myapp-tls
>          hosts:
>            - myapp.example.com
>    ```
>
>    For an internal domain, use `className: internal-nginx` and `cert-manager.io/cluster-issuer: internal-issuer`.
>
> 2. Click **Save** to deploy the changes.
>
> 3. Get the load balancer hostname from your installation's **Resources** tab. Find the Ingress resource and copy
>    its address.
>
> 4. At your DNS provider, create a CNAME record for your domain with that value. For a root domain such as
>    `example.com`, use an ALIAS or ANAME record if your provider supports them. Otherwise use A records with the
>    load balancer IPs.
>
> When the DNS record resolves, your app is reachable at the custom domain over HTTPS.

> [accordion] Helm chart: use the environment's domain
>
> Use template variables instead of a hardcoded `ryvn.run` domain:
>
> ```yaml theme={null}
> ingress:
>   enabled: true
>   className: external-nginx
>   annotations:
>     cert-manager.io/cluster-issuer: external-issuer
>   hosts:
>     - host: myapp.{{ .ryvn.env.state.public_domain.name }}
>       paths:
>         - path: /
>           pathType: Prefix
>   tls:
>     - secretName: myapp-tls
>       hosts:
>         - myapp.{{ .ryvn.env.state.public_domain.name }}
> ```
>
> This resolves to your environment's public domain. If the environment has a
> [custom root domain](https://ryvn.ai/docs/networking/domains-and-tls.md#custom-root-domain), the templates use it with no changes.

> [accordion] Troubleshooting a custom domain
>
> If a custom domain doesn't reach your app, check that its DNS record resolves to the load balancer:
>
> ```bash theme={null}
> dig myapp.example.com CNAME
> dig myapp.example.com A
> ```
>
> To rule out a stale local cache, query a public resolver directly:
>
> ```bash theme={null}
> dig myapp.example.com @1.1.1.1
> ```

## Get help

If an Ingress depends on something that isn't supported, [contact Ryvn support](https://ryvn.ai/docs/support/contact-us.md) or use your
shared Slack channel.
