June 20-22 Announcing HashiConf Europe full schedule: keynotes, sessions, labs & more Register Now
  • Infrastructure
    • terraform
    • packer
  • Networking
    • consul
  • Security
    • vault
    • boundary
  • Applications
    • nomad
    • waypoint
    • vagrant
  • HashiCorp Cloud Platform

    A fully managed platform to automate infrastructure on any cloud with HashiCorp products.

    • consul
    • terraform
    • vault
    • packerbeta
    Visit cloud.hashicorp.com
  • Overview
  • Tutorials
  • Docs
  • CLI
  • Plugins
  • Community
GitHub
Download
    • Overview
      • Overview
      • Helm
      • Heroku, Vercel, etc.
      • Kubernetes
  • Getting Started
    • Overview
    • Compatibility Promise
    • Protocol Version Table
    • Release Notifications
      • Overview
      • Upgrade to 0.2.0

    • Install
    • Externally Built Images
    • Building Container Images
    • Helm Deployment
    • YAML-Free Deployment
    • YAML Directory Deployment
    • Resource Status
    • ConfigMaps and Secrets

    • Overview
    • Git Integration
    • Remote Operations
    • Overview
    • Build
    • Deploy
    • Release
    • Hooks
    • Labels
    • Workspace and Label Scoping
    • Overview
      • Overview
      • Input Variables
      • External Data
      • artifact
      • deploy
      • entrypoint
      • labels
      • path
      • workspace
      • Overview
      • Full Reference
      • Templating
      • Overview
      • Expressions
      • JSON Syntax
    • app
    • build
    • config
    • deploy
    • hook
    • plugin
    • registry
    • release
    • runner
    • url
    • use
    • variable
  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
    • Overview
      • Overview
      • OIDC
      • Overview
      • Maintenance
      • Production
      • Security
    • Express Server Install
    • Overview
    • Configuration
    • Profiles
    • On-Demand Runner
    • Additional Runners
  • Workspaces
  • Plugins
  • Triggers

    • Overview
      • Overview
      • Registering Plugin Components
      • Handling Configuration
      • Implementing the Builder Interface
      • Compiling the Plugin
      • Creating an Example Application
      • Testing the Plugin
    • Initializing the SDK
    • Passing Values Between Components
      • Overview
      • Authenticator
      • Configurable
      • ConfigurableNotify
      • Builder
      • Registry
      • Platform
      • ReleaseManager
      • Destroy
      • Status
      • Default Parameters
      • Overview
    • Overview
    • Disable
    • Overview
    • GitHub Actions
    • GitLab CI/CD
    • CircleCI
    • Jenkins
  • Troubleshooting
  • Glossary

    • Overview
    • Architecture
    • Operation Execution
  • Roadmap
Type '/' to Search

»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 AWS_ACCESS_KEY_ID=abcd AWS_SECRET_ACCESS_KEY=1234
$ waypoint config set -runner AWS_ACCESS_KEY_ID=abcd AWS_SECRET_ACCESS_KEY=1234

This will expose these environment variables on every runner (including the CLI when it runs operations 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
$ waypoint config get -runner

Security note: These configuration values are stored as plaintext in the Waypoint server. 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-scope to set runner variables that are only available within certain scoped situations. Variables are otherwise server global by default.

»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 files to be available within runners 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...
}

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 since we assume single-use runners.

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

github logoEdit this page

Using Waypoint

The best way to understand what Waypoint can enable for your projects is to give it a try.

Waypoint tutorials
Waypoint documentation
Tutorial

Get Started - Kubernetes

Build, deploy, and release applications to a Kubernetes cluster.

View
Tutorial

Introduction to Waypoint

Waypoint enables you to publish any application to any platform with a single file and a single command.

View

Waypoint is maintained by HashiCorp, Inc.

View Code of Conduct
DocumentationCLI ReferenceTutorialsIntegrations
All systems normal