Automating Execution of Waypoint

Warning

This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.

Your team may want to automate the execution of Waypoint as your build and deployment tool, based on triggers such as a commit to a VCS provider, a chat-based workflow, or on-demand in a specific environment.

The best option for automating execution is to use Waypoint's native Git integration. This will watch a Git repository and run a waypoint up whenever a change is detected. This is the recommended approach.

You may also choose to run the waypoint CLI in an environment other than a local developer macine, and this is perfectly fine. For example, if you currently have a deployment tool or script that runs on a remote machine based on a trigger, you could, in place of that, run Waypoint by invoking it in the existing script or system to gradually adopt it.

The recommended way to run Waypoint remotely is through the Waypoint Git integration. We recommend trying that approach first and only scripting the waypoint CLI if that approach does not work for you.

Environment Variables

In a remote execution environment, as with a local workstation, the Waypoint binary will need access to the Waypoint server. Locally, it is recommended that developers create contexts to store information about the remote Waypoint server. In a remote environment, this may make less sense given the environments are often ephemeral. In this scenario, we recommend using environment variables to configure the server.

Below is a list of commonly used environment variables for remote execution. These variables configure the Waypoint CLI for communication with the Waypoint server.

WAYPOINT_SERVER_TOKEN. Must be set to a Waypoint token, created with waypoint user token
WAYPOINT_SERVER_ADDR. The address to the Waypoint server gRPC address. This must be accessible from the network that the client is running on.
WAYPOINT_SERVER_TLS. Should be set to a truthy value (e.g. "1") to configure the client to use TLS when connecting to the server.
WAYPOINT_SERVER_TLS_SKIP_VERIFY. Current must be set to a truthy value (e.g. "1") to disable TLS verification when communicating with the server.

The Waypoint server token is sensitive and should be treated as a password and protected accordingly.

Init

The waypoint init command is still required in remote environments, and must be run in the environment ahead of other Waypoint commands such as up. This command can be run multiple times safely.

In a scenario where you are running build, deploy, and release in discrete steps, it may make sense to run init once followed by those commands, or if each of the commands are run in ephemeral or potentially ephemeral environments, to ensure init is called each time. A helpful side-effect of init is that it will validate the Waypoint configuration, connection to the server, and will ensure that everything is set-up to properly execute the operation. Any remote system executing this command should make the output easily accessible to users upon failure.

Output Formatting

If Waypoint detects that the terminal does not support interactivity it will output a simpler "non-interactive" output mode. This output is easier to consume in a CI/CD systems logging views, or through log archiving systems. This is automatic and does not need to be explicitly configured, but can be forced by setting the environment variable WAYPOINT_PLAIN to a truthy value (e.g. "1").

Workspaces

When automating Waypoint, it is important to keep in mind that all commands will use the default workspace unless otherwise specified.

In a scenario where there are multiple developers triggering remote execution of Waypoint, it may be important to consider the effect this could have while all working out of the default workspace.

For example, if integrating with a VCS system such as GitHub, an additional branch may have a new feature that you would not want released in the default workspace, but that same developer will want to validate their work in a deployment, and possibly a released deployment, depending on the platform.

In this scenario, it is best to use additional workspaces. These can be configured, as they are locally, at invocation time from the CLI. A common pattern for this might be to utilize a git branch in a name of a workspace.

For example:

$ waypoint up -workspace $(git symbolic-ref HEAD)

This would run a build in a new workspace (eg. refs/heads/f-new-feature) and deploy and release against resources not used in the default workspace.

Labels

In order to determine the source of a build or other operation, it can be very useful to utilize labels. Often, these environments might provide labels that can be useful to annotate an operation with.

Labels can be specified as arguments to the main operation commands.

For example:

$ waypoint deploy -label git_sha=$GITHUB_SHA -label build_id=$BUILD_ID -label build_hostname=$(hostname)

Locking

Waypoint locks operations based on a tuple of (project, app, workspace). If multiple operations are created (eg. waypoint build) they will automatically queue.