A new platform for documentation and tutorials is launching soon.

We are migrating Waypoint documentation into HashiCorp Developer, our new developer experience.

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

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.