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

»Deploy

A deploy takes a previously built artifact and stages it onto the target deployment platform. The target deployment platform is pluggable and can be Docker, Kubernetes, Nomad, EC2, and more.

"Stage" in this context means that the application should be ready to receive traffic, but is not yet open to public traffic. For example, the application should not be added to the load balancer, DNS should not be updated, etc. While it is staged, the deployment is accessible via the deployment URL or other internal means.

Note: Not all platforms support the concept of "staging" a deployment or this behavior may not be desirable. Waypoint does not enforce this requirement and some deployment plugins may not support it.

A deploy is triggered during a waypoint up or using the dedicated waypoint deploy command.

»Configuration

The deploy is configured using the deploy stanza within an app:

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

»Target Deployment Platforms

To deploy your app with Waypoint, you will need to select which platform to use. A deployment platform is a runtime for your app. It could be a container runtime capable of running a docker image or it could be a virtual machine platform. The deployment platform must be compatible with the app artifact output format from build.

You can currently use Waypoint to deploy your app to any of these platforms.

  • Kubernetes
  • HashiCorp Nomad
  • AWS EC2
  • AWS ECS
  • AWS Lambda
  • Google Cloud Run
  • Azure Container Instances

You may use the Kubernetes plugin to target any Kubernetes instance. For example, AWS EKS, Azure AKS, Google GKE, and Kubernetes for Docker Desktop.

»How to Add a Deployment Platform to Waypoint

You can also create a plugin to extend Waypoint with your own deployment platform. If you would like to add a plugin for a platform currently not in Waypoint, please file a GitHub Issue for the project.

»Automatic Release

By default, waypoint deploy automatically performs a release.

This is because this is often the most expected behavior of a deploy since traditionally deploy and release were inseparable. We consider separating deploy and release steps a best practice so we encourage Waypoint users to disable this behavior as soon as they're comfortable.

This behavior can be disabled by using the -release=false flag with waypoint deploy:

$ waypoint deploy -release=false
...
$ waypoint deploy -release=false
...

A future Waypoint version will allow this to be disabled in the project configuration file.

»Private Registries

Deployment platforms that pull an app container image from a private registry need configuration to authenticate to a private registry.

»Kubernetes with a Private Registry

For Kubernetes, reference authenticate to private container registries with a kubernetes secret. If you named the secret example-registry-secret, then you can reference the secret in Waypoint like:

...
  deploy {
    use "kubernetes" {
      image_secret = "example-registry-secret"
    }
  }
...
...
  deploy {
    use "kubernetes" {
      image_secret = "example-registry-secret"
    }
  }
...

»Docker with a Private Registry

When deploying to Docker with a private image, Waypoint will use authentication from the registry stanza or "out of band" Docker authentication configured directly with Docker.

»Nomad with a Private Registry

The Waypoint Nomad plugin does not currently support configuring the auth stanza in the Nomad task configuration.

»Other Platforms with a Private Registry

Platform plugins such as AWS ECS, Azure ACI, and GCP Cloud Run often inherently support private registries.

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