HashiCorp Developer AI Private beta now available Sign up today
Waypoint
Waypoint Home

Deploy an Application to Kubernetes

Warning

This content is part of the legacy version of Waypoint that is no longer actively maintained. For additional information on the new vision of Waypoint, check out this blog post and the HCP Waypoint documentation.

In this tutorial, you will learn how Waypoint works by deploying and running an application on Kubernetes.

Prerequisites

For this tutorial, you will need:

You will create a Kubernetes cluster in this tutorial and depending on where you want to run it, you'll also need one of the following:

Clone the example repository

The example repository contains application code and Waypoint configuration files for building, deploying, and releasing the application with Waypoint.

Clone the example repository.

$ git clone https://github.com/hashicorp-education/learn-waypoint-get-started.git

Navigate to the example-app directory.

$ cd kubernetes/example-app

Set up DockerHub configuration

When running Waypoint on non-local infrastructure, an external image repository is necessary for storing and retrieving built images. In this tutorial, you will use DockerHub as an external image repository but other ones work as long as you properly configure authentication through the auth configuration of the registry block in the Docker plugin.

To access DockerHub for pushing and pulling images, Waypoint requires authentication credentials. It supports credential definitions in the waypoint.hcl file and "out of band" authentication by reading configurations set locally by a docker login either through the Docker CLI or Docker Desktop. In this tutorial, you will be providing DockerHub token credentials through environment variables.

Navigate to DockerHub, log in, and create an access token by visiting the security settings page and clicking the New Access Token button. Give the token a description, select the Read, Write, Delete permission option from the dropdown, and click the Generate button.

Create an access token on DockerHub

Copy the token value and export it as an environment variable.

$ export REGISTRY_PASSWORD=<YOUR_TOKEN>

Then, export your DockerHub username.

$ export REGISTRY_USERNAME=<YOUR_USERNAME>

Create a Kubernetes environment

Waypoint can run on any Kubernetes cluster including locally with Docker Desktop and major cloud provider distributions like Amazon EKS (Elastic Kubernetes Service) and Google GKE (Google Kubernetes Engine).

Docker Desktop has a built-in feature for running a local Kubernetes cluster.

To enable Kubernetes on your local machine, open the Docker Desktop application, navigate to the Preferences screen, click on the Kubernetes option in the left navigation, check the Enable Kubernetes check box, and click the Apply & Restart button.

Docker Desktop application on MacOS

Docker Desktop application on Windows

After a few moments, Docker Desktop will restart with an active Kubernetes cluster. The kubectl context will be set as part of the process.

Verify connectivity and that the correct context is set.

$  kubectl cluster-info
Kubernetes control plane is running at https://kubernetes.docker.internal:6443
CoreDNS is running at https://kubernetes.docker.internal:6443/api/v1/namespaces/kube-system/services/kube-dns:dns/proxy

To further debug and diagnose cluster problems, use 'kubectl cluster-info dump'.

Set up Waypoint

HCP Waypoint is a HashiCorp-managed service that helps you to manage your application lifecycle without maintaining a Waypoint server and associated infrastructure. It allows to you automate and simplify the process of deploying your web applications into your infrastructure.

Waypoint runs as a server and a client, whether run on HCP Waypoint or locally. For this tutorial, you can choose to use HCP Waypoint for the server and your Kubernetes cluster for the client or run Waypoint entirely on your cluster.

Both methods create a Waypoint context that contains information about the server and authentication for connecting to it from the Waypoint CLI. This is how the CLI knows the address of the server when you run other Waypoint commands.

Tip

Since Waypoint can run on any Kubernetes cluster, you can use the same install command regardless of whether your cluster is on AWS, GCP, Docker Desktop, or elsewhere. However, note that some of the output from the commands in this tutorial may differ from yours depending on the location of your cluster.

Set up an HCP organization and project

Sign in to your HCP account and create an HCP organization by following the steps in the Create an organization page. Then, create an HCP project by following the steps in the Create a project page.

Enable HCP Waypoint

Click on the Waypoint option from the left navigation.

HCP UI with the Waypoint option highlighted

Then, click on the Activate Waypoint button in the top right of the page.

HCP Waypoint UI with the Activate Waypoint button highlighted

A dialog appears to confirm that Waypoint has been activated.

HCP Waypoint UI a dialog showing that Waypoint has been activated

Set up HCP Waypoint context

Click the Manage button on the top right of the page, click on the clipboard icon to copy the waypoint context create command, and run it in your terminal. Your Waypoint CLI can now communicate with HCP Waypoint.

HCP Waypoint UI with the Manage button clicked and copy button highlighted

HCP Waypoint works with your local installation of the Waypoint CLI and does not require any additional runners as it uses the one that is part of the CLI. Installing and connecting a static runner to HCP Waypoint allows you to automate your workflow with GitOps and use dynamic configuration sourcing without requiring interaction with your CLI.

This tutorial uses only the CLI runner and does not include runner installation. You can read more about the runner installation process on the runner install page.

Initialize Waypoint for the Application

You must initialize and configure Waypoint for your application before beginning the build, deploy, and release workflow.

During the initialization process, Waypoint searches for a waypoint.hcl configuration file for the application in the current directory. This configuration file gives Waypoint instructions for how to build, deploy, and release your application. If Waypoint cannot find the configuration file when waypoint init is run, it will create a waypoint.hcl file that you can then customize for your application.

Review the waypoint.hcl file

Open the waypoint.hcl file.

kubernetes/example-app/waypoint.hcl
variable "registry_username" {
  type = string
  default = ""
  env = ["REGISTRY_USERNAME"]
}

variable "registry_password" {
  type = string
  sensitive = true
  default = ""
  env = ["REGISTRY_PASSWORD"]
}

project = "kubernetes-nodejs"

app "kubernetes-nodejs-web" {
  labels = {
    "service" = "kubernetes-nodejs-web",
    "env"     = "dev"
  }

  build {
    use "pack" {}
    registry {
       use "docker" {
        image = "${var.registry_username}/kubernetes-nodejs-web"
        tag   = "1"
        local = false
        auth {
          username = var.registry_username
          password = var.registry_password
        }
      }
    }
  }

  deploy {
    use "kubernetes" {
      probe_path = "/"
    }
  }

  release {
    use "kubernetes" {
      // Sets up a load balancer to access released application
      load_balancer = true
      port          = 3000
    }
  }
}

The variable blocks define the Docker registry username and password environment variables set earlier.

The app block defines the name of the application in Waypoint and contains the build, deploy, and release configuration blocks.

The labels block defines labels for the application. These are intended to contain information such as organizational or process data useful to the user but not directly interpreted by Waypoint.

The use option within the build, deploy, and release blocks specifies which plugin to use during those specific phases of the workflow.

The build block defines how Waypoint will build the application and produce an artifact.

  • Since the use "pack" option in this example is empty, Waypoint uses the default configuration for the Cloud Native Buildpacks plugin, which selects the most relevant pack to build the application.
  • The registry option specifies image registry information. In this example, the image contains the username for DockerHub and an auth block with credentials for pushing to that registry. The image attribute must include the fully qualified name unless you are using DockerHub.

The deploy block defines how Waypoint will deploy the application.

  • In this example, the probe_path attribute of the Kubernetes plugin instructs Waypoint to run a health check on the application at the path /.

The release block defines how Waypoint releases the application. In this example, the release block uses the Kubernetes plugin and creates a load balancer that listens on port 3000.

Waypoint URL service

The Waypoint URL service is a service hosted by HashiCorp that generates publically accessible URLs for your applications on Waypoint. The URLs are connected to your application and their deployment locations so the URLs will only resolve when the deployment is running.

These preview URLs are optional and can be disabled in the Waypoint server configuration when running a server manually with waypoint server run. You can also disable preview URLs on a per-app basis with the url block if the service is enabled on the server.

Disable the URL service for a specific app
project = "example-project"

app "example-application" {
  url {
    auto_hostname = false
  }
  
  # ...
}

Initialize Waypoint

Initialize Waypoint for the example application.

$ waypoint init
✓ Configuration file appears valid
✓ Connection to Waypoint server was successful
✓ Project "kubernetes-nodejs" and all apps are registered with the server.
✓ Project "kubernetes-nodejs" pipelines are registered with the server.

Project initialized!

You may now call 'waypoint up' to deploy your project or
commands such as 'waypoint build' to perform steps individually.

Build and Deploy

With the initialization complete, use the waypoint up command to instruct Waypoint to build, deploy, and release your application.

Run waypoint up

Waypoint uses Cloud Native Buildpacks to automatically detect the type of application and uses the applicable buildpack to create the build artifact.

Once Waypoint completes the build, it stores the artifacts in a registry. The registry block contains the configuration for where Waypoint should store those artifacts. By default, Waypoint stores Docker artifacts locally with Docker Desktop unless the registry block contains additional configuration.

Start the Waypoint workflow.

$ waypoint up

Waypoint will start the process and output the following.

✓ Running build v1
Creating new buildpack-based image using builder: heroku/buildpacks:20
✓ Creating pack client
✓ Building image
 │ [exporter] Reusing layer 'buildpacksio/lifecycle:process-types'
 │ [exporter] Adding label 'io.buildpacks.lifecycle.metadata'
 │ [exporter] Adding label 'io.buildpacks.build.metadata'
 │ [exporter] Adding label 'io.buildpacks.project.metadata'
 │ [exporter] Setting default process type 'web'
 │ [exporter] Saving kubernetes-nodejs-web...
 │ [exporter] *** Images (18a50cd83fe5):
 │ [exporter]       kubernetes-nodejs-web
 │ [exporter] Reusing cache layer 'heroku/nodejs-engine:dist'
 │ [exporter] Reusing cache layer 'heroku/nodejs-npm:toolbox'
✓ Injecting entrypoint binary to image

» Performing operation locally

Generated new Docker image: kubernetes-nodejs-web:latest
✓ Running push build v1
✓ Tagging Docker image: kubernetes-nodejs-web:latest => kubernetes-nodejs-web:1.0.0
✓ Docker image pushed: kubernetes-nodejs-web:1.0.0

» Deploying kubernetes-nodejs-web...
✓ Running deploy v1
✓ Kubernetes client connected to https://kubernetes.docker.internal:6443 with namespace default
✓ Creating deployment...
✓ Expected "http" port "3000" for app "kubernetes-nodejs-web-v1"
✓ Deployment successfully rolled out!
✓ Finished building report for Kubernetes platform
✓ Finished building report for Kubernetes deployment resource
✓ Deployment "kubernetes-nodejs-web-v1" is reporting ready!

✓ Finished building report for Kubernetes platform
✓ Finished building report for Kubernetes deployment resource
✓ Deployment "kubernetes-nodejs-web-v1" is reporting ready!

» Releasing kubernetes-nodejs-web...
✓ Running release v1
✓ Kubernetes client connected to https://kubernetes.docker.internal:6443 with namespace default
✓ Creating service...
✓ Service is ready!
✓ Finished building report for Kubernetes platform
✓ Finished building report for Kubernetes service resource

✓ Finished building report for Kubernetes platform
✓ Finished building report for Kubernetes service resource

» Variables used:
  VARIABLE | VALUE | TYPE | SOURCE  
-----------+-------+------+---------


The deploy was successful! This deploy was done in-place so the deployment
URL may match a previous deployment.

   Release URL: http://localhost

Waypoint shows the progress of the build, deploy, and release steps in the output but does not contain deployment URLs as the URL service is disabled when using HCP Waypoint.

Open the release URL in your web browser.

The example application showing deployment text

Update and Redeploy the App

One of the most powerful parts of Waypoint is that it allows you to quickly iterate on and redeploy changes to your application.

Open index.ejs in your text editor and update the deployment message in the <h1> tag. Save the file.

kubernetes/example-app/views/pages/index.ejs
<section class="content">
  <div class="language-icon">
    <img src="/language.svg" alt="Node.js Icon" />
  </div>
  <h1>This Node.js app was updated and redeployed with Waypoint!</h1>
  <p>
    Try making a change to this text locally and run <code>waypoint up</code> again to see it.
  </p>
  <p>
    Read the <a href="https://waypointproject.io/docs">documentation</a> for more about Waypoint.
  </p>
</section>

Navigate back to your terminal and restart the workflow.

$ waypoint up

Waypoint will start the process and output the following.

» Building kubernetes-nodejs-web...
â ¦ Running build v2
Creating new buildpack-based image using builder: heroku/buildpacks:20
✓ Creating pack client
✓ Building image

# ...

Generated new Docker image: kubernetes-nodejs-web:latest
✓ Running push build v2
✓ Tagging Docker image: kubernetes-nodejs-web:latest => kubernetes-nodejs-web:1.0.0
✓ Docker image pushed: kubernetes-nodejs-web:1.0.0

# ...

✓ Docker image pushed: 561656980159.dkr.ecr.us-east-2.amazonaws.com/waypoint-example:latest

» Deploying kubernetes-nodejs-web...
✓ Running deploy v2

# ...

✓ Deployment "kubernetes-nodejs-web-v2" is reporting ready!

» Releasing kubernetes-nodejs-web...
✓ Running release v2

# ...

The deploy was successful! This deploy was done in-place so the deployment
URL may match a previous deployment.

   Release URL: http://localhost

Open the deployment's release URL in your web browser. In this example, the release URL for v2 is the same as the v1 deployment but the URL now points to the v2 deployment.

The updated example application with new text

Next Steps

In this tutorial, you learned about Waypoint and the application workflow, set up a Waypoint server and client on Kubernetes, and built, deployed, updated, and redeployed an application.

Learn how to deploy applications to other platforms with Waypoint by checking out the Docker and Nomad tutorials.

Continue on to the next tutorial by clicking on the Next button below. You will learn how to interact with a running application container and browse the Waypoint web UI.

Be sure to follow the steps in the Destroy the Deployment from Kubernetes tutorial when you are ready to uninstall the Waypoint components and clean up your Kubernetes cluster. It comes after the next tutorial about using the Waypoint web UI.

Edit this page on GitHub