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
    • 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
      • 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
      • 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

The Waypoint website is being redesigned to help you find what you are looking for more effectively.

Type '/' to Search

»Workspace and Label Scoping

You can specify alternate configurations for lifecycle operations based on the current workspace or labels. This can be used to change configurations between environments such as development, staging, production or by specific metadata like region.

This documentation page will use the deploy operation for examples, but the scoping stanzas may be used by all lifecycle stages and is not limited to only the deploy stage. The basic example below will deploy to the "default" Kubernetes namespace no matter what workspace or set of labels are in use:

app "my-app" {
  deploy {
    use "kubernetes" {}
  }
}
app "my-app" {
  deploy {
    use "kubernetes" {}
  }
}

Note: Scoping is just one way to alter configuration depending on workspaces or labels. In particular, it is useful for whole configuration differences: where the configuration is wholly different between workspaces or labels. For smaller differences, you may want to look at alternative methods such as conditionals. See partial configuration changes.

»Workspace Scoping

We can use workspaces as one way to model environments such as staging, production, etc. And we might use multiple Kubernetes namespaces as a way to separate these stages. The example below uses the "default" namespace by default, but uses the "production" namespace if the workspace is also "production":

app "my-app" {
  deploy {
    use "kubernetes" {}

    workspace "production" {
      use "kubernetes" {
        namespace = "production"
      }
    }
  }
}
app "my-app" {
  deploy {
    use "kubernetes" {}

    workspace "production" {
      use "kubernetes" {
        namespace = "production"
      }
    }
  }
}

Note that we could go further and completely change the plugin in use as well. Perhaps we are testing a migration to Nomad if we're in the "new-platform" workspace:

app "my-app" {
  deploy {
    use "kubernetes" {}

    workspace "production" {
      use "kubernetes" {
        namespace = "production"
      }
    }

    workspace "new-platform" {
      use "nomad" {
        // nomad configuration here
      }
    }
  }
}
app "my-app" {
  deploy {
    use "kubernetes" {}

    workspace "production" {
      use "kubernetes" {
        namespace = "production"
      }
    }

    workspace "new-platform" {
      use "nomad" {
        // nomad configuration here
      }
    }
  }
}

»Label Scoping

The label stanza can be used to configure operations based on label selectors.

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>.

For example, perhaps we have a different configuration depending on if the region label is set for operations. (This label must be manually set. See labels.)

app "my-app" {
  deploy {
    use "kubernetes" {}

    label "region == us-east" {
      use "kubernetes" {
        // us-east configs
      }
    }

    label "region == us-west" {
      // In us-west we're still migrating from bare ec2
      use "aws-ec2" {}
    }
  }
}
app "my-app" {
  deploy {
    use "kubernetes" {}

    label "region == us-east" {
      use "kubernetes" {
        // us-east configs
      }
    }

    label "region == us-west" {
      // In us-west we're still migrating from bare ec2
      use "aws-ec2" {}
    }
  }
}

Mixing: label and workspace stanzas can be used together. See multiple match ordering to determine the behavior when there are multiple matches.

»Scoped Registry Configuration

The registry configuration can be scoped as well, but only within the root build stanza. This does not limit the functionality of scoping registry configuration at all.

For example, the following specifies a custom build and registry configuration for the "production" workspace. Note that we don't use registry within the workspace-scoped build configuration. We still use registry within the top-level build and apply a duplicate workspace stanza.

app "my-app" {
  build {
    use "docker" {}

    registry {
      use "docker" {
        local = true
      }

      workspace "production" {
        use "docker" {}
      }
    }

    // Alternate build configuration for production.
    workspace "production" {
      use "pack" {}
    }
  }
}
app "my-app" {
  build {
    use "docker" {}

    registry {
      use "docker" {
        local = true
      }

      workspace "production" {
        use "docker" {}
      }
    }

    // Alternate build configuration for production.
    workspace "production" {
      use "pack" {}
    }
  }
}

»Multiple Match Ordering

If multiple workspace and/or label stanzas are used, there may be scenarios where multiple are valid choices for the current operation. In this scenario, the following rules are used. The first matching rule halts the lookup.

  1. An exact match workspace matches over any label.

  2. The longest label selector string by byte count (ignoring preceding or trailing whitespace) matches before shorter label selector strings.

»Partial Configuration Changes

The workspace and label stanzas are particularly powerful for whole configuration differences. If only one field is changing between workspaces, copying the entire configuration between the different stanzas will become error prone, aesthetically displeasing, and verbose. For single fields, you should use other features.

Important: The workspace and label stanzas do not inherit any values from the "default" stanza. You must respecify ALL configurations. (For example, you can't set the Kubernetes namespace in the default deploy stanza and then omit it in a workspace-scoped stanza; it must be duplicated).

»Map Lookup

One option is to use a map lookup as a way to change behavior. For example, if we are only changing the namespace for Kubernetes based on the workspace, we can do the following:

app "my-app" {
  deploy {
    use "kubernetes" {
      namespace = {
        "default"    = "default"
        "production" = "prod"
      }[workspace.name]
    }
  }
}
app "my-app" {
  deploy {
    use "kubernetes" {
      namespace = {
        "default"    = "default"
        "production" = "prod"
      }[workspace.name]
    }
  }
}

This is admittedly not obvious. To explain: we are creating an HCL map with the {} syntax and then doing a lookup using [] keyed on the workspace variable.

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