• HashiCorp Developer

  • HashiCorp Cloud Platform
  • Terraform
  • Packer
  • Consul
  • Vault
  • Boundary
  • Nomad
  • Waypoint
  • Vagrant
Waypoint
  • Install
  • Tutorials
  • Documentation
  • CLI
  • Plugins
  • Try Cloud(opens in new tab)
  • Sign up
Waypoint Home

Documentation

Skip to main content
  • Documentation
  • Getting Started


  • URL Service
  • Logs
  • Exec
    • Overview
    • Dynamic Values
    • Files
    • Internal Values
    • Workspace and Label Scoping
  • Workspaces
  • Plugins
  • Triggers

  • Troubleshooting
  • Glossary

  • Roadmap

  • Resources

  • Tutorial Library
  • Community Forum
    (opens in new tab)
  • Support
    (opens in new tab)
  • GitHub
    (opens in new tab)
  1. Developer
  2. Waypoint
  3. Documentation
  4. App Configuration
  5. Workspace and Label Scoping
  • Waypoint
  • v0.9.x
  • v0.8.x
  • v0.7.x
  • v0.6.x
  • v0.5.x
  • v0.4.x
  • v0.3.x
  • v0.2.x
  • v0.1.x

ยปWorkspace and Label Scoping

Waypoint allows you to set different configuration values for specific workspaces or labels. For example, you might set a database URL for staging different from production using workspaces, or you might use labels to set different addresses for different regions or any other metadata.

By default, Waypoint application configuration is exposed to the application in every scenario. By using the additional scoping constraints described in this document, you can limit what configuration values are set in what situations.

Workspace Scoping

You can use workspace scoping to expose configuration only in specific, exact workspaces:

config {
  env = {
    "DB_ADDR" = "dev.example.com"
  }

  workspace "production" {
    env = {
      "DB_ADDR" = "prod.example.com"
    }
  }
}

In this example, the DB_ADDR environment variable will be set to "prod.example.com" only in the "production" workspace. Within the workspace stanza, you can use all available configuration parameters such as env, internal, files, etc.

Note: Values aren't inherited from the global scope. For example, you cannot set an internal variable at the root and access it within the workspace stanza. You must redeclare any internal variables used.

Non-Exact Workspace Matching

The workspace stanza does not support non-exact workspace matching. However, you can use the label stanza documented below to do this. All workspaces automatically are exposed via the waypoint/workspace label and label selectors support Consul style matching operators such as contains, matches, etc. For example, you could match all workspaces that contain "dev" this way:

config {
  env = {
    "DB_ADDR" = "dev.example.com"
  }

  label "waypoint/workspace contains \"dev\"" {
    env = {
      "DB_ADDR" = "prod.example.com"
    }
  }
}

Label Scoping

You can use the label stanza to expose configuration only in specific label contexts:

config {
  env = {
    "DB_ADDR" = "dev.example.com"
  }

  label "env == production and region == us-east-1" {
    env = {
      "DB_ADDR" = "prod.example.com"
    }
  }
}

This will only expose the "prod.example.com" value for the DB_ADDR environment variable if the labels of the deployment match the given selector.

Warning! This is an advanced use case. Most cases can be satisfied using the workspace stanza which is much simpler to understand and debug. Under the covers, the workspace stanza is functionally equivalent to a label selector of waypoint/workspace == <name>.

Inheritance

Based on the structural syntax of workspace and label selectors, it may appear that there is some ability to reference or inherit "parent" configuration values, such as internal values. This is not possible.

For example, given the following configuration:

config {
  internal = {
    "db_host" = "example.com"
  }

  env = {
    "DB_ADDR" = "dev@${config.internal.db_host}"
  }

  workspace "production" {
    # THIS DOES NOT WORK!
    env = {
      "DB_ADDR" = "prod@${config.internal.db_host}"
    }
  }
}

This does not work. The environment variable value inside the workspace stanza does not have access to the internal variables in the root config stanza. Any workspace or label stanzas must redeclare internal variables that are commonly used.

Edit this page on GitHub

On this page

  1. Workspace and Label Scoping
  2. Workspace Scoping
  3. Label Scoping
  4. Inheritance
Give Feedback(opens in new tab)
  • Certifications
  • System Status
  • Terms of Use
  • Security
  • Privacy
  • Trademark Policy
  • Trade Controls
  • Give Feedback(opens in new tab)