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

»Labels

Labels are key/value pairs that can be specified by the user and attached to Waypoint operations. Labels can be used to specify any information that may be useful for the user, but are not directly interpreted by Waypoint itself. For example, this can be used for organizational information (team=widget), process information (scanned=true), etc.

»Specifying Labels

»Operation Labels

Labels can be attached to any of the major lifecycle stages using the labels attribute, as shown below.

app "web" {
  build {
    labels = {
      "region" = "tokyo"
    }

    // ... normal build fields
  }
}
app "web" {
  build {
    labels = {
      "region" = "tokyo"
    }

    // ... normal build fields
  }
}

This would attach the label region=tokyo to all the "build" operations and this would be visible in the UI and accessible via the API.

Operation labels can also be specified using the CLI during any operation by specifying the -label flag. This flag can be repeated multiple times to specify multiple labels. The example below specifies a couple labels that will be applied to the build step only for this invocation.

$ waypoint build -label a=1 -label b=2
$ waypoint build -label a=1 -label b=2

»Project and App Labels

Labels can also be specified at both the project and app scope. These labels are inherited by all operations within the project and application.

labels = {
  global = "true"
}

app "web" {
  labels = {
    "app-only" = "true"
  }

  // ... operations
}
labels = {
  global = "true"
}

app "web" {
  labels = {
    "app-only" = "true"
  }

  // ... operations
}

»Predefined Labels

Labels starting with waypoint/ are reserved for Waypoint rather than user specification. It is an error to try to set any labels starting with waypoint/ and Waypoint will not allow it. We call these "system labels". The full set of system labels is listed below:

  • waypoint/workspace - The current workspace of the operation.

»Using Labels

»Labels Variable

The complete label set for the current operation is always available using the labels variable within the waypoint.hcl file. The linked documentation shares various examples of how this might be useful, but one example might be that you want to also store all the labels as annotations within a platform such as Kubernetes:

app "web" {
  deploy {
    use "kubernetes" {
      annotations = { for k, v in labels: "waypoint/${k}" => v }
    }
  }
}
app "web" {
  deploy {
    use "kubernetes" {
      annotations = { for k, v in labels: "waypoint/${k}" => v }
    }
  }
}

»Filtering with Selectors

Labels can be used in various places in Waypoint for filtering by using "label selectors." Label selectors are boolean expressions (result in a "true" or "false"). An example of where filtering can be used is application configuration.

The full label selector syntax is documented below.

Note: Labels have powerful but limited functionality at present. We plan for more features to utilize labels in the future but expect their usage beyond simple informational tasks to remain advanced concepts.

»Label Selector Syntax

The full syntax for label selectors is documented below.

The list below shows all the operators that can be used for a single value, such as equality, inequality, string or list containment, regular expression matching, etc.

// Equality & Inequality checks
<Selector> == "<Value>"
<Selector> != "<Value>"

// Emptiness checks
<Selector> is empty
<Selector> is not empty

// Contains checks or Substring Matching
"<Value>" in <Selector>
"<Value>" not in <Selector>
<Selector> contains "<Value>"
<Selector> not contains "<Value>"

// Regular Expression Matching
<Selector> matches "<Value>"
<Selector> not matches "<Value>"
// Equality & Inequality checks
<Selector> == "<Value>"
<Selector> != "<Value>"

// Emptiness checks
<Selector> is empty
<Selector> is not empty

// Contains checks or Substring Matching
"<Value>" in <Selector>
"<Value>" not in <Selector>
<Selector> contains "<Value>"
<Selector> not contains "<Value>"

// Regular Expression Matching
<Selector> matches "<Value>"
<Selector> not matches "<Value>"

Multiple such expressions can be composed using and, or, and parentheses:

// Logical Or - evaluates to true if either sub-expression does
<Expression 1> or <Expression 2>

// Logical And - evaluates to true if both sub-expressions do
<Expression 1 > and <Expression 2>

// Logical Not - evaluates to true if the sub-expression does not
not <Expression 1>

// Grouping - Overrides normal precedence rules
( <Expression 1> )

// Inspects data to check for a match
<Matching Expression 1>
// Logical Or - evaluates to true if either sub-expression does
<Expression 1> or <Expression 2>

// Logical And - evaluates to true if both sub-expressions do
<Expression 1 > and <Expression 2>

// Logical Not - evaluates to true if the sub-expression does not
not <Expression 1>

// Grouping - Overrides normal precedence rules
( <Expression 1> )

// Inspects data to check for a match
<Matching Expression 1>
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