Application Configuration

Waypoint can configure your application by setting environment variables and writing files. Both the environment variables and files can use values sourced from external systems such as Kubernetes ConfigMaps, HashiCorp Vault, Amazon Parameter Store, etc.

Application configuration can be set two ways. First, it may be set using the config stanza in the waypoint.hcl file. You may also use the waypoint config CLI command, but this can only be used for environment variables.

When configuration values change, Waypoint will automatically restart your application.

This functionality requires the Waypoint entrypoint.

Setting Configuration via the CLI

Static configuration are values that are set directly using waypoint config set. They are "static" because they are set with a predetermined value directly on the Waypoint server.

$ waypoint config set DATABASE_URL="postgresql://example.com:5432"

This will make the DATABASE_URL environment variable present with the given value for all deployed applications. For already-deployed applications, Waypoint will restart running applications when configuration changes.

Project Scope

waypoint config set will set variables by default scoped to the project. This means that all applications within your project will have the environment variable set.

Application Scope

You may use the -app flag to scope a variable to a specific application. For this scope, only a specific application in the project will have the configuration set.

$ waypoint config set -app web PORT=8080

Setting Configuration via waypoint.hcl

Configuration can also be set directly in the waypoint.hcl file using the config stanza. The example below achieves the same thing as the waypoint config set example in the section above.

config {
  env = {
    DATABASE_URL = "postgresql://example.com:5432"
  }
}

Configuration specified in the waypoint.hcl file has a number of benefits:

• The configuration is made available immediately during all lifecycle operations (such as waypoint up, waypoint deploy, etc.).

• The configuration is persisted as code and can be committed to version control.

• The configuration can make use of functions and variables to compute the keys and values.

Updating the Configuration of Existing Deployments

Changes to configuration within the waypoint.hcl file take effect whenever a new deploy occurs (such as via a waypoint up or waypoint deploy). Existing deployments can be updated without a new deploy by using the waypoint config sync CLI command.

When configuration changes take effect, any changes will affect all deployments of that project or application. Practically, this means if you change a configuration value in the waypoint.hcl file and run waypoint up, the new deployment as well as any previous deployments that are still running will be updated with the new configuration value.

Project vs. Application Scope

The config stanza is valid at the project level and within app stanzas. This can be used to specify whether a configuration is at the project or application scope. You can also mix both together and they will be merged. The example below will set THEME for all apps and set PORT only for the "frontend" app.

config {
  env = {
    THEME = "rainbow"
  }
}

app "frontend" {
  config {
    env = {
      PORT = 8080
    }
  }

  # ...
}

For conflicting keys, the app-scope value will be used. If in the above example the app-scoped config set a THEME value, that value would be used instead of the project-scoped value.

Unsetting Configuration

To delete a configuration variable, use the CLI to set it to an empty string:

$ waypoint config set DATABASE_URL=

This works for configuration set via the CLI as well as waypoint.hcl. This also works for static as well as dynamic configuration values.

Syncing with External Systems

Waypoint can sync application configuration values with external systems such as Kubernetes ConfigMaps, HashiCorp Vault, Amazon Parameter Store, and more. To learn more about this, see the documentation page on dynamic configuration values.

Application Restart Behavior

Waypoint will automatically restart your running applications whenever a configuration change is detected for that application. Waypoint restarts your application with the following steps:

1. The SIGTERM signal is sent to your application process. This signal can be trapped to perform last minute cleanup and shutdown.

2. Waypoint will wait up to 30 seconds for your application to gracefully exit.

3. After 30 seconds, Waypoint will send the SIGKILL signal to your application process group. This will kill the application process as well as any subprocesses it may have started. This signal is not able to be trapped and your application will be killed immediately.