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
    • v0.8.x (latest)
    • v0.7.x
    • v0.6.x
    • v0.5.x
    • v0.4.x
    • v0.3.x
    • v0.2.x
    • v0.1.x
    • 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

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

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