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 Entrypoint

Waypoint uses an entrypoint binary to enable features such as application configuration, logs, exec, and more. In most cases, Waypoint will automatically inject and configure the entrypoint binary during the build phase. The image below shows a high-level architecture diagram of the entrypoint in a Docker image.

Entrypoint Overview

The entrypoint binary injection and usage is not required and can be disabled. This will also disable features such as logs, exec, etc. for that application. See disabling the entrypoint for more information.

»Installation

For builders that produce Docker images, the entrypoint is automatically injected into the container image.

For other types of builds, the entrypoint must be manually installed. To manually install the entrypoint:

  1. Download the appropriate waypoint-entrypoint binary for the platform your application will run on. This is not your desktop operating system but the operating system your app will be deployed to.

  2. Put the single binary Waypoint entrypoint anywhere in your deployment image, such as /usr/local/bin on Unix-like systems.

  3. Configure your application startup to run the entrypoint first rather than your application. If you booted your application as node app.js, change that to waypoint-entrypoint /usr/bin/node app.js

Builder-specific documentation for entrypoint injection will be written soon. The instructions above are the most generic and we understand they may be complicated to apply to your builder.

»Functionality

The features listed below require the entrypoint. If you choose to disable the entrypoint, the features below will not work. The entrypoint can be disabled on a per-project or per-application basis, so you can choose to opt-out of the functionality below for only some of your applications.

  • URL Service
  • Application configuration
  • Exec (waypoint exec)
  • Logs (waypoint logs)
  • Instance tracking

More features that require the entrypoint may be introduced in the future.

»Resource Requirements

The Waypoint entrypoint introduces some small amount of overhead to your deployments.

The primary resource requirement for the entrypoint is a small amount of RAM. The CPU impact is negligible since the entrypoint mostly sits idle. No disk access is required at all. We haven't yet measured the exact usage but plan to soon.

The entrypoint primarily sits idle waiting on network traffic. The entrypoint will only "wake up" from blocking on network traffic when it receives new application configuration, a request for exec, an inbound request from the URL service, etc.

»Logging

The entrypoint itself emits logs about its own behavior. These logs are in addition to the logs emitted by the deployed application. We differentiate between the two by calling one "entrypoint logs" and the other "application logs".

Entrypoint logs are also streamed and can be viewed via waypoint logs. If waypoint logs is not working, the entrypoint logs are also emitted to stderr. This is primarily for debugging purposes in case the entrypoint is not functioning properly.

The default log level for entrypoint logs is DEBUG. You may change the log level by setting the WAYPOINT_LOG_LEVEL environment variable to one of: TRACE, DEBUG, INFO, WARN, ERROR (values further to the left are more verbose than those to the right). This environment variable may be set at build time, using deployment plugin configuration, or via the waypoint config CLI.

Note: The WAYPOINT_LOG_LEVEL environment variable must be set within the runtime environment of your deployment, not on your local machine. This is a common error when attempting to change entrypoint log levels.

»Failure Behavior

The Waypoint entrypoint is designed to be resilient to failure scenarios that it introduces.

»Server Unavailable on Startup

If the Waypoint server connection cannot be established on startup within 5 seconds, Waypoint will "fail open" by starting the child process immediately. Waypoint will continue to retry to connect to the server in the background.

This behavior allows Waypoint to start the child process no matter what.

If you're using application configuration, the configuration will not be available to the application in this failure case. This may cause the application startup to fail.

»Server Connection Lost

If the Waypoint server connection is lost at any point during runtime, the child process is unaffected. Waypoint will retry to establish a connection in the background.

While the connection is lost, any entrypoint related functionality will stop working. Initial application configuration will be retained, but further application configuration changes will have no effect until the connection can be reestablished.

During this time, logs will be dropped. The application logs during the period when the connection was lost will not become available again. Once the connection is re-estalished, new logs from that point forward will be sent to the server.

»Security

The Waypoint entrypoint does not open any network listeners. It does not proxy any network connections to your application except for the URL service (which is an outbound connection, not inbound). When a user visits your application using your release URL (such as directly via a Kubernetes Service for example), the traffic is routed directly to the application.

The Waypoint entrypoint does maintain a long-running outbound connection to the Waypoint server as well as the Waypoint URL service (if enabled). Most importantly for security, the Waypoint server can initiate an exec call to arbitrarily execute commands within the context of your application. Therefore it is important that the server is well secured.

The Waypoint entrypoint connects to the Waypoint server using a token that can only retrieve and set entrypoint-related information for that specific deployment. It cannot trigger new deploys, list existing deploys, etc. Therefore, if the environment the entrypoint is running in is compromised in any way, it poses a minimal risk to Waypoint as a whole.

The Waypoint entrypoint can be completely disabled if that is desired. This will disable all entrypoint-related functionality including app config, logs, exec, etc. You may also disable specific features instead of the entire entrypoint.

Many improvements are planned to improve the security of the entrypoint. We plan on restricting the commands that can be used with exec, we plan on supporting more fine-grained feature enable/disable flags, etc.

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