June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Infrastructure
    • terraform
    • packer
  • Networking
    • consul
  • Security
    • vault
    • boundary
  • Applications
    • nomad
    • waypoint
    • vagrant
  • HashiCorp Cloud Platform

    A fully managed platform to automate infrastructure on any cloud with HashiCorp products.

    • consul
    • terraform
    • vault
    • packerbeta
    Visit cloud.hashicorp.com
  • Overview
  • Tutorials
  • Docs
  • CLI
  • Plugins
  • Community
GitHub
Download
    • v0.8.x (latest)
    • v0.7.x
    • v0.6.x
    • v0.5.x
    • v0.4.x
    • v0.3.x
    • v0.2.x
    • v0.1.x
    • Overview
      • Overview
      • Helm
      • Heroku, Vercel, etc.
      • Kubernetes
  • Getting Started
    • Overview
    • Compatibility Promise
    • Protocol Version Table
    • Release Notifications
      • Overview
      • Upgrade to 0.2.0

    • Install
    • Externally Built Images
    • Building Container Images
    • Helm Deployment
    • YAML-Free Deployment
    • YAML Directory Deployment
    • Resource Status
    • ConfigMaps and Secrets

    • Overview
    • Git Integration
    • Remote Operations
    • Overview
    • Build
    • Deploy
    • Release
    • Hooks
    • Labels
    • Workspace and Label Scoping
    • Overview
      • Overview
      • Input Variables
      • External Data
      • artifact
      • deploy
      • entrypoint
      • labels
      • path
      • workspace
      • Overview
      • Full Reference
      • Templating
      • Overview
      • Expressions
      • JSON Syntax
    • app
    • build
    • config
    • deploy
    • hook
    • plugin
    • registry
    • release
    • runner
    • url
    • use
    • variable
  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
    • Overview
      • Overview
      • OIDC
      • Overview
      • Maintenance
      • Production
      • Security
    • Express Server Install
    • Overview
    • Configuration
    • Profiles
    • On-Demand Runner
    • Additional Runners
  • Workspaces
  • Plugins
  • Triggers

    • Overview
      • Overview
      • Registering Plugin Components
      • Handling Configuration
      • Implementing the Builder Interface
      • Compiling the Plugin
      • Creating an Example Application
      • Testing the Plugin
    • Initializing the SDK
    • Passing Values Between Components
      • Overview
      • Authenticator
      • Configurable
      • ConfigurableNotify
      • Builder
      • Registry
      • Platform
      • ReleaseManager
      • Destroy
      • Status
      • Default Parameters
      • Overview
    • Overview
    • Disable
    • Overview
    • GitHub Actions
    • GitLab CI/CD
    • CircleCI
    • Jenkins
  • Troubleshooting
  • Glossary

    • Overview
    • Architecture
    • Operation Execution
  • Roadmap
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.

github logoEdit this page

Using Waypoint

The best way to understand what Waypoint can enable for your projects is to give it a try.

Waypoint tutorials
Waypoint documentation
Tutorial

Get Started - Kubernetes

Build, deploy, and release applications to a Kubernetes cluster.

View
Tutorial

Introduction to Waypoint

Waypoint enables you to publish any application to any platform with a single file and a single command.

View

Waypoint is maintained by HashiCorp, Inc.

View Code of Conduct
DocumentationCLI ReferenceTutorialsIntegrations
All systems normal