A new platform for documentation and tutorials is launching soon.
We are migrating Waypoint documentation into HashiCorp Developer, our new developer experience.
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.
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.
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:
Download the appropriate
waypoint-entrypointbinary 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.
Put the single binary Waypoint entrypoint anywhere in your deployment image, such as
/usr/local/binon Unix-like systems.
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.
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 (
- Logs (
- Instance tracking
More features that require the entrypoint may be introduced in the future.
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.
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
The default log level for entrypoint logs is
DEBUG. You may change the
log level by setting the
WAYPOINT_LOG_LEVEL environment variable to
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.
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.
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.
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.