Waypoint Server in Production
Warning
This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.
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).
Note: we recognize that constant log shipping by all deployed
applications to a single server is not desirable long term behavior and
will not scale to larger deployments. We have plans to aleviate this need
in the future. For now, you may disable entrypoint features or write logs
to anywhere other than stdout and stderr to avoid this challenge.
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.
TLS Rotation
Waypoint servers specified with the -tls-cert-file and -tls-key-file
parameters will detect any file changes and automatically reload the
TLS cert without impacting any active connections. Therefore, the easiest
way to rotate certificates is to overwrite the existing TLS PEM files.