»Runner Configuration

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.

»Environment Variables

»Via the CLI

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

$ 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  |           |

$ waypoint config get -runner
   SCOPE  |    NAME               | VALUE | WORKSPACE | LABELS
----------+-----------------------+-------+-----------+---------
  global  | AWS_ACCESS_KEY_ID     | abcd  |           |
  global  | AWS_SECRET_ACCESS_KEY | 1234  |           |

You can use the -scope flag paired with flags such as -project, -label-scope, and -workspace-scope 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-scope=dev NOMAD_TOKEN=abc123

$ waypoint config set -runner -workspace-scope=prod NOMAD_TOKEN=def456

$ waypoint config get -runner
   SCOPE  |    NAME     |                VALUE                 | WORKSPACE | LABELS
----------+-------------+--------------------------------------+-----------+---------
  project | NOMAD_TOKEN | abc123                               | dev       |
  project | NOMAD_TOKEN | def456                               | prod      |

$ waypoint config set -runner -workspace-scope=dev NOMAD_TOKEN=abc123

$ waypoint config set -runner -workspace-scope=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.

»Via the waypoint.hcl File

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...
}

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.

»Files

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...
}

config {
  runner {
    file = {
      "config/config.json" = "file contents"
    }
  }

  // App config is here...
}

»Dynamic Values

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}"
    }
  }
}

// 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}"
    }
  }
}

»Runner profiles

To modify the way that Waypoint launches on-demand runners, see runner profiles.