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

»Building Container Images

Waypoint incorporates a first-class build step that can be used to build your container images and other artifacts. This page will focus on container (or Docker) images, since these are the primary deployment artifact that Kubernetes uses.

Often one of the first challenges when setting up a new application is answering two questions: how do I build my application? and how do I get the result of my build plumbed into my deployment configuration? Waypoint solves both of these by incorporating configuration for both build and deploys into the waypoint.hcl file.

The built-in build functionality is optional. If you have an external process already setup to build your images, you can use externally-built images. Waypoint just needs to know about some sort of artifact, whether it is responsible for building it or not.

This page will focus on Dockerfile-based builds because these are the most popular and also take into account applications that you may have written prior to Waypoint. However, Waypoint supports many more methods of building container images. Documentation on other methods along with examples can be found on the build lifecycle page.

»Docker Builder (Dockerfile)

The most popular way to build container images today is using a manually written Dockerfile. Waypoint can also build images from Dockerfiles using the docker builder. This also is the easiest way to get started with Waypoint with existing applications, since most existing applications for Kubernetes have Dockerfiles.

If you don't know Docker, or don't want to write a Dockerfile, take a look at the pack builder. This uses buildpacks to autodetect your app language and build a container image.

The example below uses the Docker builder:

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

This will use a Dockerfile in the same directory as your waypoint.hcl file. You can test this using the Waypoint CLI by running waypoint build. This command will perform the build only, so it can be used for testing. The waypoint build command should be run in the same directory as your project (with the waypoint.hcl).

Waypoint will automatically run your build remotely if you have a git repo configured for your project and a runner and runner profile configured. If you want to force a build to happen locally, use the -local flag.

# let waypoint choose to run your build remotely if possible (recommended):
$ waypoint build
...

# or, force it to run locally on your development machine:
$ waypoint build -local
...
# let waypoint choose to run your build remotely if possible (recommended):
$ waypoint build
...

# or, force it to run locally on your development machine:
$ waypoint build -local
...

»Docker Secrets

A common requirement within Dockerfiles is to be able to access private information, whether that be via SSH, some API token, or any other mechanism. Because Waypoint image builds happen remotely, they don't have access to your local machine's secrets. The recommended approach to ensure secrets can be accessed everywhere (locally and remote) is to use Waypoint input variables paired with Docker build arguments.

Why not Docker Secrets? Unfortunately, Docker Secrets aren't supported because Kaniko does not support them. We use Kaniko as the underlying technology to perform Docker builds within your Kubernetes cluster.

The example below shows how we can access a private GitHub repository using a GitHub Personal Access Token (PAT). We show both the waypoint.hcl and the Dockerfile used to build a Go application, as an example.

variable "github_token" {
  type = string
  env  = ["GITHUB_TOKEN"]
}

app "my-app" {
  build {
    use "docker" {
      disable_entrypoint = true
      build_args = {
        GITHUB_TOKEN = var.github_token
      }
    }
  }
}
variable "github_token" {
  type = string
  env  = ["GITHUB_TOKEN"]
}

app "my-app" {
  build {
    use "docker" {
      disable_entrypoint = true
      build_args = {
        GITHUB_TOKEN = var.github_token
      }
    }
  }
}
FROM golang:1.17-alpine AS builder

# Configure Git
ARG GITHUB_TOKEN
RUN apk add --no-cache git
RUN git config --global url."https://${GITHUB_TOKEN}:x-oauth-basic@github.com/".insteadOf "https://github.com/"

# Build Go app
RUN mkdir -p /src
WORKDIR /src
COPY . .
RUN go mod download
RUN go build -o /app .

FROM scratch

COPY --from=builder /app /app

ENTRYPOINT ["/app"]
FROM golang:1.17-alpine AS builder

# Configure Git
ARG GITHUB_TOKEN
RUN apk add --no-cache git
RUN git config --global url."https://${GITHUB_TOKEN}:x-oauth-basic@github.com/".insteadOf "https://github.com/"

# Build Go app
RUN mkdir -p /src
WORKDIR /src
COPY . .
RUN go mod download
RUN go build -o /app .

FROM scratch

COPY --from=builder /app /app

ENTRYPOINT ["/app"]

To invoke this, you can set the github_token input variable many different ways. For long term use, the recommended location to set the variable is via the web UI. However, for testing, you can use the CLI:

$ waypoint build -var github_token=$MYTOKEN <project>/<app>
$ waypoint build -var github_token=$MYTOKEN <project>/<app>

»Container Registry

After getting builds working, the next step is usually to push that container image to a container registry. Waypoint supports a registry stanza for specifying a container registry for your image. To specify a Docker registry compatiable registry, use the docker registry:

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

    registry {
      use "docker" {
        image = "docker.io/my-org/my-app"
        tag   = gitrefpretty()
        username = "myusername"
        password = "mytoken"
      }
    }
  }
}
app "my-app" {
  build {
    use "docker" {}

    registry {
      use "docker" {
        image = "docker.io/my-org/my-app"
        tag   = gitrefpretty()
        username = "myusername"
        password = "mytoken"
      }
    }
  }
}

This example would push the built container image to Docker Hub, but any compatible registry such as Quay, AWS ECR, etc. would work. For now, hardcode your credentials as we've done in the example above and run waypoint build to verify it works. This should push your image now.

»Hiding Credentials

In a real production use-case, you should not put your container registry credentials directly in the waypoint.hcl file. Instead, you should use input variables to parameterize them. Input variables can be configured to read from environment variables so you can use well known environment variables (such as AWS_ACCESS_KEY), too.

For remote runners, they can get access to input variables either by setting the variables in the web UI, or by setting runner configuration.

»Local vs. Remote Builds

Waypoint can run builds locally where you run the waypoint CLI, or remotely in your Kubernetes cluster in pods that are launched on demand. By default, Waypoint will automatically run your operations remotely when certain conditions are met. Builds triggered by Git polling or the UI also happen remotely.

To build Docker images within Kubernetes, Waypoint uses Kaniko. Waypoint sets up and invokes Kaniko for you, so you don't need to be familiar with it. All you need to know is that Kaniko supports almost all modern Dockerfile syntax, and it lets you do container image builds without any special privileges in your Kubernetes cluster.

Remote builds are recommended. If you want to force a build to happen locally, use the -local flag.

$ waypoint build -local
$ waypoint build -local
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