A new platform for documentation and tutorials is launching soon.

We are migrating Waypoint documentation into HashiCorp Developer, our new developer experience.

Join Now
Type '/' to Search

»Waypoint Architecture

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. Most commonly, the CLI acts as a runner, but it is possible to run dedicated runners. This isn't shown in the diagram above.

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

This is only an issue if remote runners are being used. In the most common case, the CLI acts as a runner and this is not a possible failure mode.

»CLI

The CLI is not an online system.