New Interested in participating in the HCP Waypoint Private Beta Program? Apply here
  • 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
      • Upgrade to 0.3.0
      • Upgrade to 0.4.0
      • Upgrade to 0.5.0
      • Upgrade to 0.6.0
      • Upgrade to 0.7.0
      • Upgrade to 0.8.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
      • Tokens
      • 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
      • ConfigSourcer
      • 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

»config Stanza

Placementconfig
app -> config

The config stanza configures application configuration. Application configuration sets environment variables or writes files for your application. Application configuration can use static values or by synced with an external system. Application configuration can be set via the waypoint.hcl file using the config stanza as well as via the CLI.

To learn about application configuration more broadly please also read the application configuration docs. The dedicated application configuration section goes into more detail about how application configuration works with Waypoint. This page is specifically about the config stanza in the waypoint.hcl file and does not cover the application configuration system more broadly.

»Project vs. App Scope

The config stanza can appear at the project (root) level or within an app. Configuration set at the project level is used for all applications and merged with any app-scoped configuration. Configuration set within an app stanza is only set for that application. If there are any conflicting values, the app-scoped value overrides the project-scoped value.

The example below shows configuration set at both the project and app scope. In this case, these will be merged and the app will have both the THEME and PORT environment variables set.

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

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

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

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

  # ...
}

»Further Scoping: Workspaces and Labels

In both the project and app scope, a configuration can be further scoped to only exist in a specific workspace or label set for a deployment. For more information, see the workspace and label-scoping documentation.

»Syncing

Changes to config in the waypoint.hcl file take effect only during the scenarios listed below:

  1. waypoint up - A full build, deploy, release will resync configuration.
  2. waypoint deploy - This is useful when you want to redeploy but don't want to rebuild the application.
  3. waypoint config sync - This is useful when you want to update the configuration but don't want to redeploy the application.

When the configuration is synced, any values set in the file will overwrite values that may have been set manually via the CLI. Any configuration set in the CLI that was not set in the configuration file will remain unchanged.

Synced configuration impacts all versions of a deployed application. All deployed applications will subsequently be restarted or signaled if configuration values changed.

»config Parameters

»Optional

  • env (map<string>ConfigValue: {}) - Environment variables to set for the deployed application. See the ConfigValue section below on more details on valid values for this map.

  • file (map<string>string: {}) - Files to write at runtime for the deployed application. The key is the path to write the file and the value is the file contents. If the path is relative, it is relative to the working directory of the deployment. The value is usually paired with templating functions. See the configuration file documentation for more information.

  • file_change_signal (string: "USR2") - The signal to send to the deployed application when a configuration file changes.

  • internal (map<string>ConfigValue: {}) - Internal variables use the same syntax as env but are not exposed directly to the application. Instead, these values may be referenced using config.internal.NAME within env values or file values. See the internal values documentation for more information.

  • workspace (config) - Define workspace-scoped configuration. The label for the stanza is the name of a workspace to exactly match.

  • label (config) - Define label-scoped configuration. The label for the stanza is a label selector.

»ConfigValue

A ConfigValue type is used to configure the value of a configuration key such as within env.

»Primitive Values

A configuration value can be set to a primitive value such as a string or number. This will be coerced into a string and set as a static configuration value. In the example below, we set the PORT environment variable using a static value:

config {
  env = {
    PORT = 8080
  }
}
config {
  env = {
    PORT = 8080
  }
}

»Dynamic Value

A configuration value can be sourced from an external system using the dynamic function. This function creates a ConfigValue and can only be used within a config stanza or as a default value for an input variable. In the example below, we synchronize a value with a Kubernetes ConfigMap:

config {
  env = {
    PORT = dynamic("kubernetes", {
      name = "my-app" # ConfigMap name
      key  = "port"
    })
  }
}
config {
  env = {
    PORT = dynamic("kubernetes", {
      name = "my-app" # ConfigMap name
      key  = "port"
    })
  }
}

And in another example, we use dynamic to source a value for a variable:

variable "image_name" {
  type    = string
  default = dynamic("terraform-cloud", {
    organization = "foocorp"
    workspace    = "images"
    output       = "name"
  })
}
variable "image_name" {
  type    = string
  default = dynamic("terraform-cloud", {
    organization = "foocorp"
    workspace    = "images"
    output       = "name"
  })
}
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