Waypoint Architecture

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 has many different components that interact with each other. This page documents all of these components: what they do, how they work with each other, when they're required, etc.

High-Level Overview

The diagram below shows a typical single-platform deployment of Waypoint.

Architecture Overview

Note: some of the components are optional by sacrificing functionality. It is possible to operate Waypoint without entrypoints, but you'll lose all entrypoint-required functionality.

The primary components of Waypoint are:

Server - The Waypoint server is a long-running, central service that serves the Waypoint API. This API is consumed by the CLI, entrypoint, and other consumers. This is the only component in Waypoint that stores state. Learn more about servers here.
CLI - The waypoint CLI acts as a client of the server API. It does not store any state locally except for connection information to the server.
Entrypoint - The Waypoint Entrypoint is built-in to the deployments to enable functionality such as logs, exec, the URL service, and more. It creates an outbound connection to the server to enable this functionality.
Runner - A Waypoint runner executes operations such as build, deploy, etc. There are two kinds of runners:
- Static Runner - A static runner is a long-lived runner that is very likely set up when a team begins using Waypoint.
- On-Demand Runner - An on-demand runner is launched per operation within a container platform.

Failure Behavior

The components of Waypoint are designed to be resilient to failures of the other components.

Server

If the server is down:

The CLI and UI will not be able to perform any operations. Builds, deploys, etc. cannot be run.
Existing running deployments with an entrypoint will not be affected. They will keep running successfully and attempt to reconnect to the server. Logs during this downtime will be lost. Exec sessions cannot be opened.
Restarting deployments with an entrypoint may not be affected. If the entrypoint cannot talk to the server on startup, it will still start the subprocess. If you use application configuration, this configuration will not be present until the server comes back online. This may cause your application to fail to start.
Deployments without an entrypoint are completely unaffected whether they are running or not currently.

Entrypoint

The entrypoint is designed to not affect the child process during failures. Any failures in the entrypoint will be logged but will not cause the entrypoint to exit. Errors such as failure to connect to a Waypoint server will retry in the background.

Runner

If a dedicated runner is down, then the capacity of the server to execute remote operations will be diminished. If no runners exist, jobs will queue. Operations include build, deploy, release, etc.

If there are no static runners configured in the system or the user has specified -local=true, then the CLI will spawn a runner itself.

See CLI acts as a runner for more details.

CLI

The CLI is not an online system.