> ## 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.

# Networking

> How installations connect inside an environment, and how to expose them to your VPC or the internet

Networking in a Ryvn environment works the way it does in a Kubernetes cluster. Installations reach each other over
the environment's private network through Kubernetes Services. On top of that, Ryvn runs the load balancers, creates
the DNS records, and issues the TLS certificates that expose an installation outside the environment. It also
collects [network metrics](https://ryvn.ai/docs/observability/metrics.md#network-metrics) for the traffic.

An installation can be reachable on three networks:

| Network | Reachable from | Example address |
| - | - | - |
| Private | Other installations in the environment | `http://api:8080` |
| Internal | Your VPC and connected networks | `https://api.internal.production.acme-7fk2q.ryvn.run` |
| Public | The internet | `https://api.production.acme-7fk2q.ryvn.run` |

How you configure networking depends on the service type. A [server](https://ryvn.ai/docs/deploy/service-types/server.md) installation lists
its ports under `spec.networking` in its [installation YAML](https://ryvn.ai/docs/iac/installations/server.md#networking), or in its
**Settings > Networking** tab in the [Ryvn Dashboard](https://control.ryvn.app). A
[Helm chart](https://ryvn.ai/docs/deploy/service-types/chart.md) installation adds a [Route](https://ryvn.ai/docs/networking/routes.md) to the chart. Each example
on this page shows both.

> [!NOTE]
>
> This page applies to environments that Ryvn provisions. On an [existing cluster](https://ryvn.ai/docs/provision/existing-cluster.md) that
> you connect to Ryvn, you run your own load balancers, DNS, and certificates.

## Private: inside the environment

By default, every installation in an environment can connect to every other installation, like pods in a Kubernetes
cluster. These addresses work only inside the environment.

```mermaid theme={null}
---
title: "Environment: production"
---
%%{init: {'flowchart': {'rankSpacing': 40}}}%%
flowchart TB
    subgraph ns["Namespace: production"]
        direction LR
        web["web"] -- "http://api:8080" ----> api["api"]
    end
    subgraph data["Namespace: data"]
        redis["redis"]
    end
    ns -- "redis.data.svc.cluster.local:6379" --> data
```

An installation's ports are reachable at a cluster DNS name. The form to use depends on the
[namespace](https://ryvn.ai/docs/guides/namespaces.md) of the client:

| Client is in | Address |
| - | - |
| The same namespace | `<name>:<port>` |
| A different namespace | `<name>.<namespace>.svc.cluster.local:<port>` |

`<name>` is the installation's name for a server, and the Service's name for a Helm chart. Installations run in the
environment's namespace unless you set another one, so the short form works in most environments.

> [tab] Server
>
> List the ports your app listens on under `spec.networking`.
>
> ```yaml theme={null}
> # api installation
> spec:
>   networking:
>     ports:
>       - number: 8080
> ```

> [tab] Helm chart
>
> A chart defines its own Kubernetes Services, so there is nothing to configure in Ryvn.
>
> ```yaml theme={null}
> # templates/service.yaml
> apiVersion: v1
> kind: Service
> metadata:
>   name: api
> spec:
>   selector:
>     app.kubernetes.io/name: api
>   ports:
>     - name: http
>       port: 8080
> ```

### Limit connections

No policy limits connections between installations by default. To control which destinations an installation can
reach, add a [network policy](https://ryvn.ai/docs/networking/network-policy.md).

### Encrypt connections

To encrypt traffic between installations and verify the identity at both ends, enable
[traffic encryption (mTLS)](https://ryvn.ai/docs/networking/traffic-encryption.md) on a namespace. It is off by default.

## Expose an installation outside the environment

Each environment has two load balancers that Ryvn deploys and manages: an internal one for your VPC and connected
networks, and a public one for the internet. Each load balancer sends connections to a gateway that Ryvn runs inside
the environment. The gateway terminates TLS and routes each request to an installation by hostname and path.

When you expose a port, Ryvn adds it to a gateway, creates the DNS record, and issues and renews the TLS certificate.

### Internal: your VPC and connected networks

Use the internal network for clients that are in your network but outside the environment, such as a VM in the same
VPC, a workload in a peered VPC, or a laptop on your VPN. Requests stay off the public internet.

```mermaid theme={null}
%%{init: {'flowchart': {'wrappingWidth': 480, 'rankSpacing': 18, 'padding': 9, 'subGraphTitleMargin': {'top': 4, 'bottom': 16}}}}%%
flowchart TB
    subgraph vpc["Your VPC and connected networks"]
        direction TB
        vm["Sandbox VM"]
        address(["https://api.internal.production.acme-7fk2q.ryvn.run"])
        subgraph env["Environment: production"]
            direction LR
            ilb["Internal load balancer"] --> igw["Gateway"] --> api["api"]
        end
    end
    vm --> address --> env
```

Internal addresses are in the environment's internal domain, such as `internal.production.acme-7fk2q.ryvn.run`.

> [tab] Server
>
> Every port under `spec.networking` gets an internal address, with nothing more to configure. The `api`
> installation is at `https://api.internal.production.acme-7fk2q.ryvn.run`.
>
> When an installation has more than one port, the other ports' addresses include the port name, such as
> `api--metrics.internal.production.acme-7fk2q.ryvn.run`.

> [tab] Helm chart
>
> Add a [Route](https://ryvn.ai/docs/networking/routes.md) with `internal` exposure and a name in the internal domain. `to` is the Service
> that receives the requests and one of its ports, by name or number.
>
> ```yaml theme={null}
> # templates/route.yaml
> apiVersion: networking.ryvn.app/v1alpha1
> kind: Route
> metadata:
>   name: api
> spec:
>   exposure: [internal]
>   domains: [api.internal.production.acme-7fk2q.ryvn.run]
>   rules:
>     - to: [{ name: api, port: http }]
> ```

The internal domain resolves only inside the environment's VPC. For clients in a connected network, make the domain
resolvable there too, for example with DNS forwarding.

### Public: the internet

Use the public network for anything clients reach over the internet, such as a web app, a public API, or a webhook
endpoint. Ryvn serves the address over HTTPS and redirects HTTP to HTTPS.

```mermaid theme={null}
%%{init: {'flowchart': {'wrappingWidth': 480, 'rankSpacing': 28, 'padding': 9, 'subGraphTitleMargin': {'top': 4, 'bottom': 16}}}}%%
flowchart TB
    client["Browser"]
    address(["https://web.production.acme-7fk2q.ryvn.run"])
    subgraph env["Environment: production"]
        direction LR
        plb["Public load balancer"] --> pgw["Gateway"] --> web["web"]
    end
    client --> address --> env
```

Public addresses are in the environment's public domain, such as `production.acme-7fk2q.ryvn.run`.

> [tab] Server
>
> Set `public: true` on the port. The `web` installation is then at `https://web.production.acme-7fk2q.ryvn.run`,
> and keeps its internal address.
>
> ```yaml theme={null}
> # web installation
> spec:
>   networking:
>     ports:
>       - number: 3000
>         public: true
> ```

> [tab] Helm chart
>
> Add a [Route](https://ryvn.ai/docs/networking/routes.md) with `public` exposure and a name in the public domain.
>
> ```yaml theme={null}
> # templates/route.yaml
> apiVersion: networking.ryvn.app/v1alpha1
> kind: Route
> metadata:
>   name: web
> spec:
>   exposure: [public]
>   domains: [web.production.acme-7fk2q.ryvn.run]
>   rules:
>     - to: [{ name: web, port: http }]
> ```

In a chart, read the environment's domains from the installation config instead of hardcoding them, and list both
networks in `exposure` to serve a Route on both. See
[Routes](https://ryvn.ai/docs/networking/routes.md#set-the-hostname-for-each-environment).

### Find the addresses

The installation's **Settings > Networking** tab in the [Ryvn Dashboard](https://control.ryvn.app) lists its
addresses. With the CLI, describe the installation:

```bash theme={null}
ryvn describe installation web -e production
```

The `Endpoints` section shows each address, its network, and its state:

```text theme={null}
Endpoints:
  - https://web.production.acme-7fk2q.ryvn.run
    Exposure: public
    Port:     http (3000)
    State:    Active
  - https://web.internal.production.acme-7fk2q.ryvn.run
    Exposure: internal
    Port:     http (3000)
    State:    Active
```

An address that isn't `Active` yet shows a `Reason` line that says what it waits for.

## Supported protocols

On the private network, installations can use any TCP or UDP protocol. Internal and public addresses carry HTTP,
and can pass TLS connections through to your app.

| Protocol | Private | Internal and public | Notes |
| - | :-: | :-: | - |
| HTTP/1.1 and WebSocket | ✓ | ✓ | |
| HTTP/2 and gRPC | ✓ | ✓ | Set the port's protocol, as described below. |
| TLS that your app terminates | ✓ | ✓ | With [TLS passthrough](#tls-passthrough), port 443. |
| Other TCP, such as a database protocol | ✓ | ✗ | |
| UDP | ✓ | ✗ | Helm charts only. A server installation's ports are TCP. |

For gRPC and other apps that serve HTTP/2 without TLS, set the port's protocol so the gateway connects to your app
over HTTP/2. On a server installation, set `protocol: http2` on the port. In a Helm chart, set `appProtocol: kubernetes.io/h2c` on
the Service port.

## Custom domains

Serve an installation on a domain you own, such as `app.example.com`. Ryvn issues and renews the domain's certificate.

> [tab] Server
>
> Add the domain to the port's `domains`.
>
> ```yaml theme={null}
> # web installation
> spec:
>   networking:
>     ports:
>       - number: 3000
>         public: true
>         domains:
>           - app.example.com
> ```

> [tab] Helm chart
>
> List the domain in the `domains` of the [Route](https://ryvn.ai/docs/networking/routes.md).
>
> ```yaml theme={null}
> # templates/route.yaml
> spec:
>   exposure: [public]
>   domains: [app.example.com]
>   rules:
>     - to: [{ name: web, port: http }]
> ```

Ryvn then shows the DNS records to create at your DNS provider, in the installation's **Settings > Networking** tab
and in `ryvn describe installation`. See [Domains and TLS](https://ryvn.ai/docs/networking/domains-and-tls.md) for the records, and for
replacing `ryvn.run` with your own domain for a whole environment.

## Path-based routing

Put several installations behind one domain, each under its own path. A common setup serves a web app at
`app.example.com` and its API at `app.example.com/api`.

> [tab] Server
>
> List the domain on both installations, and give the `api` installation a path on it.
>
> ```yaml theme={null}
> # web installation
> spec:
>   networking:
>     ports:
>       - number: 3000
>         public: true
>         domains:
>           - app.example.com
> ```
>
> ```yaml theme={null}
> # api installation
> spec:
>   networking:
>     ports:
>       - number: 8080
>         public: true
>         domains:
>           - hostname: app.example.com
>             path: /api
>             replacePrefix: /
> ```

> [tab] Helm chart
>
> Add a rule for each path to the [Route](https://ryvn.ai/docs/networking/routes.md). Services from different installations can share a
> domain too: give each chart its own Route with the same domain and its own paths.
>
> ```yaml theme={null}
> # templates/route.yaml
> spec:
>   exposure: [public]
>   domains: [app.example.com]
>   rules:
>     - path: /
>       to: [{ name: web, port: http }]
>     - path: /api
>       replacePrefix: /
>       to: [{ name: api, port: http }]
> ```

Requests for `/api` and the paths under it go to `api`, and all other requests go to `web`. When several paths match,
the longest one wins. `replacePrefix` replaces the matched path before the request reaches your app, so
`app.example.com/api/users` reaches `api` as `/users`. Ryvn adds the original prefix in an `X-Forwarded-Prefix`
header.

## TLS passthrough

By default, Ryvn terminates TLS for you. The gateway inside the environment serves the domain's certificate and
forwards the decrypted request to your app. Use TLS passthrough when your app must terminate TLS itself, for example
because it verifies client certificates (mTLS). The gateway then forwards the encrypted connection to your app
without decrypting it.

> [tab] Server
>
> Set `tls.mode: passthrough` on the domain. The port must be public.
>
> ```yaml theme={null}
> # api installation
> spec:
>   networking:
>     ports:
>       - number: 8443
>         public: true
>         domains:
>           - hostname: api.example.com
>             tls:
>               mode: passthrough
> ```

> [tab] Helm chart
>
> Set `tls.mode: passthrough` on the [Route](https://ryvn.ai/docs/networking/routes.md).
>
> ```yaml theme={null}
> # templates/route.yaml
> spec:
>   exposure: [public]
>   domains: [api.example.com]
>   tls:
>     mode: passthrough
>   rules:
>     - to: [{ name: api, port: 8443 }]
> ```

Clients connect on port 443, and Ryvn forwards the connection to your app's port. Ryvn doesn't issue a certificate
for a passthrough domain, so your app must serve a valid certificate for it and renew it. Because Ryvn can't read the
requests, a passthrough domain can't have paths, and only one port can use it.

## Charts that create an Ingress

Many third-party Helm charts expose themselves with a Kubernetes Ingress. For compatibility, Ryvn environments
provide two ingress classes: `external-nginx` for the public network and `internal-nginx` for the internal network.
An Ingress that uses one of these classes keeps working, with host and path routing and the most common NGINX
annotations.

The recommended way is to turn the Ingress off and [use a Route](https://ryvn.ai/docs/networking/routes.md#third-party-charts) instead. See
[Ingress networking](https://ryvn.ai/docs/networking/migration-guides/ingress-networking.md) for what the compatibility layer supports.

## Next steps

* [Routes](https://ryvn.ai/docs/networking/routes.md): every Route option, third-party charts, and troubleshooting.
* [Domains and TLS](https://ryvn.ai/docs/networking/domains-and-tls.md): DNS records for your own domains, and TLS certificates.
* [Network policy](https://ryvn.ai/docs/networking/network-policy.md): limit which destinations an installation can reach.
