Additional Runners

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.

With self managed Waypoint servers, the waypoint install command installs and manages a single Waypoint static runner.

Additional static runners can be added using waypoint runner install, which automates the process of creating resources in Kubernetes, Nomad, ECS, or Docker to execute a static runner.

In the case that none of these work for you, you can configure a static runner manually as well.

Installing a Static Runner Automatically

Waypoint supports deploying a static runner to multiple platforms with one command. Depending on the platform, different configurations can be provided to control how the runner is deployed in a platform. By default, the server will adopt the static runner and create a new runner profile for it after it reports to the server.

To install a static runner, use the waypoint runner install command. Below is an example of using that command to install a Waypoint static runner to Docker:

$ waypoint runner install -platform=docker -docker-runner-network=waypoint -server-addr=waypoint-server:9701 -server-tls-skip-verify=true
✓ Connecting to: waypoint-server:9701
✓ Runner 01G5F2R0EKY0J8WW4W8HRGZVN1 installed successfully
✓ Runner profile docker-01G5F2R0EKY0J8WW4W8HRGZVN1 created successfully.
✓ Waypoint runner installed and started!
✓ Runner detected by server
✓ Runner 01G5F2R0EKY0J8WW4W8HRGZVN1 adopted successfully.

Other example commands for the platforms Waypoint supports in server install are below. If you customized any of the values during install, substitute your own values for the defaults.

Docker:

$ waypoint runner install -platform=docker -server-addr=waypoint-server:9701 -docker-runner-network=waypoint -server-tls-skip-verify

Kubernetes:

$ waypoint runner install -platform=kubernetes -server-addr=waypoint-server:9701 -server-tls-skip-verify

ECS:

$ waypoint runner install -platform=ecs -ecs-cluster=waypoint -ecs-region=<AWS_REGION> -server-addr=<AWS_NLB_NAME>.elb.<AWS_REGION>.amazonaws.com:9701 -server-tls-skip-verify

Nomad:

$ waypoint runner install -platform=nomad -server-addr=localhost:9701 -nomad-host-volume=waypoint-runner -server-tls-skip-verify

Officially Supported Runner Platforms

Currently, Waypoint supports installing runners on the following platforms:

Kubernetes
Nomad
Amazon ECS
Docker

Manually Running a Static Runner

The instructions below are only if you're installing additional static runners manually. It's recommended that you utilize the the automated static runner installation if possible.

The primary reason you'd need to install a new static runner manually is because the environment it will run in can't be captured by the above automation.

Under normal circumstances, on-demand runners should be the mechanism used to provide additional capacity within an installation, not additional static runners.

Waypoint Runner Agent

To run a static runner, use the waypoint runner agent command:

$ WAYPOINT_SERVER_ADDR=<server addr> \
  WAYPOINT_SERVER_TLS=true \
  WAYPOINT_SERVER_TOKEN=<auth token> \
  waypoint runner agent


» Runner configuration:
  Server address: waypoint.example.com:9701

» Runner logs:

...

The environment variables specify how to connect to the server:

WAYPOINT_SERVER_ADDR should be the address to the Waypoint server that the runner can reach. The port should be for the gRPC API, and is typically 9701.
WAYPOINT_SERVER_TLS should be set to a truthy value (e.g. "1") if the server is listening on TLS.
WAYPOINT_SERVER_TLS_SKIP_VERIFY should be set to a truthy value (e.g. "1") if the TLS cert is invalid and can be safely ignored, such as in a development environment.
WAYPOINT_SERVER_TOKEN should be an auth token the runner can use to communicate to the server. You can generate a new auth token using waypoint user token.

If the runner process remains running and doesn't show any errors, the runner is now registered with the server and can now be used.