Waypoint Entrypoint

Waypoint uses an entrypoint binary to enable features such as application configuration, logs, exec, and more. In most cases if building containers, 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.

Installation

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

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.

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.