layout | page_title | description |
---|---|---|
docs |
Runner Configuration |
Waypoint utilizes "runners" to execute Waypoint operations remotely. Runners can be configured to have environment variables and files exposed during certain project operations. |
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.
Runners may require additional configuration such as cloud credentials, Docker registry credentials, etc. Waypoint enables runners to be configured with environment variables and files at runtime, either globally or specific to certain environments.
You can set environment variables using waypoint config
with the -runner
flag:
$ waypoint config set -runner -scope=global AWS_ACCESS_KEY_ID=abcd AWS_SECRET_ACCESS_KEY=1234
This will expose these environment variables on every runner (including
a CLI runner when an operation runs locally). To unset any variables, assign it to
an empty value. You may view the set of runner configuration values using
waypoint config get
:
$ waypoint config get -runner
SCOPE | NAME | VALUE | WORKSPACE | LABELS
----------+-----------------------+-------+-----------+---------
global | AWS_ACCESS_KEY_ID | abcd | |
global | AWS_SECRET_ACCESS_KEY | 1234 | |
~> Security note: HCP Waypoint stores these values encrypted within its backend using HashiCorp Vault. If that's unsatisfactory, you can set the environment variables manually when manually running the runner.
~> Security note: On a self hosted Waypoint server, these configuration values are stored as plaintext in the Waypoint server data file. If you do not want to store any secrets on the Waypoint server, you must set the environment variables manually when manually running the runner.
You can use the -scope
flag paired with flags such as -project
,
-label-scope
, and -workspace
to set runner variables that are only
available within certain scoped situations. Unscoped variables are globally sent to
all runners.
Consider an example where you're using a dev
and a prod
workspace in Waypoint.
These workspaces match up to your dev
and prod
environments.
For this example, let's assume that you use Nomad (with an ACL-enabled cluster), and
your dev
and prod
environments are separated into different namespaces by the name names. These two different workspaces need to be configured by Waypoint to deploy
to the proper environments in Nomad.
To accomplish this, you would set your runner config to use workspace-scoped
config: a Nomad token with permissions to submit jobs to the dev
namespace
is used for the dev
Waypoint workspace, and another token with permissions to
submit jobs to the prod
namespace for the prod
Waypoint workspace. Here's what
that could look like:
$ waypoint config set -runner -workspace=dev NOMAD_TOKEN=abc123
$ waypoint config set -runner -workspace=prod NOMAD_TOKEN=def456
$ waypoint config get -runner
SCOPE | NAME | VALUE | WORKSPACE | LABELS
----------+-------------+--------------------------------------+-----------+---------
project | NOMAD_TOKEN | abc123 | dev |
project | NOMAD_TOKEN | def456 | prod |
With configurations set in this way, operations executed in a given workspace will
use the NOMAD_TOKEN
configured for the corresponding environment automatically.
Environment variables for runners can also be set via the waypoint.hcl
file. This uses the same syntax as the config
stanza:
config {
runner {
// All config in here is exposed only on runners.
env = {
AWS_ACCESS_KEY_ID = "abcd"
}
}
// App config is here...
}
This configuration is scoped only to the project or application of
the waypoint.hcl
file.
Using the waypoint.hcl
file, you can configure data to be stored in files
that are available to runners when running operations for that project or application.
You cannot configure files to be available globally to the server. This behaves similarly to
application configuration files.
config {
runner {
file = {
"config/config.json" = "file contents"
}
}
// App config is here...
}
-> Note: The user that is running the runner must have permission to write to the given file paths. File paths are not cleaned up after the runner operation completes as this feature presume On-demand runners are in use, as they are the most common production deployment setup.
When using the waypoint.hcl
format, runners may make use of
dynamic values to source configuration
from external sources. The runner
stanza also has access to
internal values for composing multiple
values together.
Note that runner variables only have access to internal variables
specified within the runner
stanza. Variables specified at the app-level
config
stanza are not inherited.
For example, the following is not valid:
// This is invalid!
config {
internal = {
"db_host" = "localhost"
"db_user" = "admin"
}
runner {
// This does not work because the "internal" variables were only
// specified at the app-level, not the runner level.
env = {
"DB_ADDR" = "${config.internal.db_user}@${config.internal.db_host}"
}
}
}
To modify the way that Waypoint launches on-demand runners, see runner profiles.