Externally Built Images

The Waypoint workflow includes the ability to perform the build step directly, but users may also use Waypoint with externally built artifacts such as from CI pipelines. This is particularly common if you're adopting Waypoint for existing applications (versus net new use cases).

Configuring Waypoint to Use an Existing Image

The docker-pull builder was designed so that Waypoint can use pre-built Docker images. These images can be built anyway you want: manually, CI pipelines, 3rd party sources, etc.

The example below shows how we can use an image that was already built. In this case, Waypoint does nothing: it just notes that this is the image you want to use. It doesn't verify that it can access this image and doesn't modify the image in any way. This enables the deploy plugin in the next step to use this pre-existing image.

build {
  use "docker-pull" {
    image = "gcr.io/my-project/my-image"
    tag   = "abcd1234"
    disable_entrypoint = true
  }
}

A more realistic example would likely use input variables or functions to dynamically specify the correct image.

Input Variables to Specify the Image Tag

Input variables can be used to specify parameters for configuring the image to use, as shown below. This is a more realistic example because this allows a step in a system such as a CI to specify to Waypoint what the desired image tag is for deployment.

variable "image_tag" {
  type = string
}

app "my-app" {
  build {
    use "docker-pull" {
      image = "gcr.io/my-project/my-image"
      tag   = var.image_tag
      disable_entrypoint = true
    }
  }
}

This variable can then be used in many ways. If a CI is executing Waypoint, the most likely way is via a flag:

$ waypoint build -var image_tag=$TAG my-project/my-app

Git Functions to Specify the Image Tag

Another approach to specifying the image tag, particularly in a GitOps-oriented workflow, would be to use Git functions.

The example below specifies that the tag should always match the current Git commit hash. This assumes your external system is building an image for every commit. You can also use functions such as gitreftag to get the current tag.

app "my-app" {
  build {
    use "docker-pull" {
      image = "gcr.io/my-project/my-image"
      tag   = gitrefhash()
      disable_entrypoint = true
    }
  }
}

Invoking Waypoint when Using External Images

When using externally built images, Waypoint should be invoked after the image is already created. The approach to do this depends on how your build system is configured and how (or if) your team uses Git.

Invoking from CI

The first approach is to not use repository polling with Waypoint, because Waypoint may run before your CI system builds the image. Instead, the CI system can manually invoke the Waypoint operation once the image is built.

To do this, the CI must be configured with connection environment variables: WAYPOINT_SERVER_ADDR, WAYPOINT_SERVER_TOKEN, etc. Then, after the image is built, trigger a deploy:

$ waypoint up <project>/<app>

You may specify variables and other flags to the up command. The <project>/<app> syntax will force a remote operation so the up will happen remotely. This will block while the operation is happening.

Invoking from Git

Another approach is to continue using Git to trigger deploys. In this approach, your project Git settings should be configured to watch a specific branch that is only merged to when you're ready to deploy.

For example, you can have a production branch (or it may just be your main branch) that you only merge to after your CI system ran tests and built the resulting image.

This requires a different style of Git discipline and may not fit all teams.

Waypoint Entrypoint with External Image Builds

The Waypoint Entrypoint is an optional component that enables features such as waypoint exec, log streaming, instance tracking, and more. When using externally built Docker images, you must also manually inject the entrypoint. This is optional! Waypoint does not require the entrypoint to perform deploys.

To setup the entrypoint, the simplest approach is to use Docker multi-stage builds:

FROM hashicorp/waypoint:latest AS waypoint

# Your main build:
FROM yourbaseimage

COPY --from=waypoint /usr/bin/waypoint-entrypoint /waypoint-entrypoint

# Replace "<EXISTING>" with your existing entrypoint (if any)
ENTRYPOINT ["/waypoint-entrypoint", <EXISTING>]

Note that injecting the entrypoint is safe even if you don't use Waypoint. If the entrypoint doesn't have the proper environment variables set (by Waypoint itself, not as part of the build), then the entrypoints acts as if it doesn't exist: it executes its child process and does nothing. This lets you start injecting the entrypoint even if you're still only experimenting with Waypoint.