Skip to main content
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 for the traffic. An installation can be reachable on three networks: How you configure networking depends on the service type. A server installation lists its ports under spec.networking in its installation YAML, or in its Settings > Networking tab in the Ryvn Dashboard. A Helm chart installation adds a Route to the chart. Each example on this page shows both.
This page applies to environments that Ryvn provisions. On an existing cluster 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. An installation’s ports are reachable at a cluster DNS name. The form to use depends on the namespace of the client: <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.
List the ports your app listens on under spec.networking.

Limit connections

No policy limits connections between installations by default. To control which destinations an installation can reach, add a network policy.

Encrypt connections

To encrypt traffic between installations and verify the identity at both ends, enable traffic encryption (mTLS) 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. Internal addresses are in the environment’s internal domain, such as internal.production.acme-7fk2q.ryvn.run.
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.
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. Public addresses are in the environment’s public domain, such as production.acme-7fk2q.ryvn.run.
Set public: true on the port. The web installation is then at https://web.production.acme-7fk2q.ryvn.run, and keeps its internal address.
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.

Find the addresses

The installation’s Settings > Networking tab in the Ryvn Dashboard lists its addresses. With the CLI, describe the installation:
The Endpoints section shows each address, its network, and its state:
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. 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.
Add the domain to the port’s domains.
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 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.
List the domain on both installations, and give the api installation a path on it.
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.
Set tls.mode: passthrough on the domain. The port must be public.
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 instead. See Ingress networking for what the compatibility layer supports.

Next steps

  • Routes: every Route option, third-party charts, and troubleshooting.
  • Domains and TLS: DNS records for your own domains, and TLS certificates.
  • Network policy: limit which destinations an installation can reach.