»Waypoint Server in Production

Waypoint is still a very new project and we're collecting information for a more detailed guide on how to run Waypoint in production. We will fill in this page soon. In the mean time, we appreciate any feedback in GitHub issues or our discussion forum on your experiences.

»Ports Used

Waypoint requires two different ports:

  • HTTP API (Default 9702, TCP) - This is used to serve the web UI and the web UI API client. If the web UI is not used, this port can be blocked or disabled.

  • gRPC API (Default 9701, TCP) - This is used for the gRPC API. This is consumed by the CLI, Entrypoint, and Runners. This port must be reachable by all deployments using the Entrypoint.

Both of these ports require TCP, but the connections are always TLS protected. Non-TLS connections are not allowed on either port.

»Network Topology

Waypoint Servers expect to have ample bandwidth available for all client connections, particularly entrypoints. Entrypoints must have access to the server for features such as logs, exec, etc. to work.

The most bandwidth-heavy feature is the log shipping of applications. The servers should have access to enough bandwidth for all appliation instances to stream their logs to it.

Waypoint Servers are not highly latency sensitive; bandwidth is much more important than latency. We recommend a latency of at most a few seconds to avoid heartbeating issues in some cases (but any heartbeats in the system are typically dozens of seconds or more).

»Resources (RAM, CPU, etc.)

We are still determining the recommended requirements for these resources.

The Waypoint server stores all application log buffers in memory. These buffers are limited to ~600 Kilobytes per application instance. Therefore, a recommended formula for determining memory requirements is: 128 MB plus 1 MB per application instance. This will give your server plenty of RAM.

An "application instance" is a single running instance of your application. For example, if you deploy a Kubernetes application with 5 replicas, then that would be 5 application instances (even though it is only one "deployment").

»TLS

Waypoint requires TLS for all inbound connections. TLS cannot be disabled. By default, Waypoint will generate a self-signed certificate on startup.

Servers that are run manually (not installed using waypoint install) can specify custom TLS certificates using the -tls-cert-file and -tls-key-file flags on the waypoint server run command. These flags should point to a PEM-encoded certificate file and private key, respectively.

»Limitations

»TLS Certs

The Waypoint server is always protected with TLS, but there is currently no way to specify a custom TLS cert. Instead, the Waypoint server will always create a self-signed TLS cert on startup. A future version of Waypoint very soon will fix this limitation.

A workaround for this today is to front the Waypoint server with a TCP load balancer that terminates TLS with your desired TLS certificate. The backend connection must use the self-signed TLS connection to the Waypoint server.