Deploy an Application to Kubernetes

30min
Waypoint

Let's use Waypoint to deploy applications onto Kubernetes. This tutorial will give you a very quick overview of how Waypoint works.

Prerequisites

In order to complete this tutorial, you will need access to a running Kubernetes cluster, such as one running in a public cloud, in Docker Desktop, or in kind.

You'll need to install the waypoint binary locally, and clone the examples repository (detailed in the next section).

Clone the examples repository

This walkthrough uses an example NodeJS application to show you how to build, deploy and release an application using Waypoint.

This example app is part of the Waypoint Examples applications. You will need a local clone of this repository on your computer to complete this walkthrough.

Clone the Waypoint Examples repository and navigate to the Kubernetes NodeJS example directory.

$ git clone https://github.com/hashicorp/waypoint-examples.git

Change into the subdirectory for the Kubernetes project. This project uses NodeJS but the following instructions will work with any language that can be built with a cloud native buildpack.

$ cd waypoint-examples/kubernetes/nodejs

Create a Kubernetes environment

You can use any current Kubernetes distribution with Waypoint. Set your KubeConfig with the KUBECONFIG environment variable to allow access to the cluster.

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

To enable Kubernetes on your local machine, navigate to the Preferences screen and select the check box labeled "Enable Kubernetes".

MacOS

Then click the "Apply & Restart" button. After a few moments, Docker Desktop will restart with and active Kubernetes cluster. You can verify your local configuration by running any command against kubectl.

$  kubectl get all

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/kubernetes   ClusterIP   10.96.0.1    <none>        443/TCP   24m

Kind is a tool for running a local Kubernetes cluster.

Create a cluster with the create command.

$ kind create cluster

The create command will also configure kubectl to use the new cluster for operations.

Verify the existence of the new cluster by running get clusters.

$ kind get clusters

This tutorial can be run against the AWS Elastic Kubernetes Service and the Elastic Container Registry.

The easiest way to get started is by provisioning an EKS cluster with our Terraform EKS tutorial.

Once you have completed the "Configure kubectl" section in the EKS tutorial, you will be properly configured to run commands with kubectl against the cluster. Return to this guide to continue using Waypoint.

Note

The Terraform tutorial uses us-east-2 for the example, but this tutorial uses us-east-1. The examples will still work, but be sure to modify any commands to use the appropriate region.

Verify that you have a running Kubernetes cluster by checking the EKS console before continuing.

EKS Console

You can also verify your local configuration by running a command against kubectl.

$ kubectl get all

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/kubernetes   ClusterIP   172.20.0.1   <none>        443/TCP   57m

Next, create an ECR registry named waypoint-example (or any other available name).

ECR Form

Verify that you have a running container registry by checking the ECR console and can see the registry.

ERC Successfully Created

This tutorial can be run against a GCP GKE cluster and the Google Container Registry.

The easiest way to set up a cluster is to follow our GKE tutorial.

Once you have completed the "Configure kubectl" section in the GKE tutorial, you will be properly configured to run commands with kubectl against the cluster. Return to this guide to continue using Waypoint.

Or, you can visit the GKE console and create a cluster. Any size will work, including the "My first cluster" quick start.

GCP Kubernetes Console

You can verify your local configuration by running any command against kubectl.

$ kubectl get all

NAME                 TYPE        CLUSTER-IP   EXTERNAL-IP   PORT(S)   AGE
service/kubernetes   ClusterIP   172.20.0.1   <none>        443/TCP   57m

The Google Container Registry will be available to your application as part of the cluster setup process but you must configure push and pull access from your machine as Waypoint uses your local Google Cloud credentials to deploy your application.

Run the auth configure-docker command to register gcloud as the credential helper. Confirm the process with Y when prompted. This allows Waypoint to interact with the Google Container Registry.

$ gcloud auth configure-docker
Adding credentials for all GCR repositories.
WARNING: A long list of credential helpers may cause delays running 'docker build'. We recommend passing the registry name to configure only the registry you are using.
After update, the following will be written to your Docker config file located at [/Users/[USER]/.docker/config.json]:
 {
  "credHelpers": {
    "gcr.io": "gcloud",
    "us.gcr.io": "gcloud",
    "eu.gcr.io": "gcloud",
    "asia.gcr.io": "gcloud",
    "staging-k8s.gcr.io": "gcloud",
    "marketplace.gcr.io": "gcloud"
  }
}

Do you want to continue (Y/n)?  Y

Docker configuration file updated.

Install the Waypoint server

Now that you have created a Kubernetes environment, install the Waypoint server on it with the install command. The -accept-tos flag confirms that you accept the terms of service for our application URL service.

$ waypoint install --platform=kubernetes -accept-tos

service/waypoint created
statefulset.apps/waypoint-server created

You can verify that the cluster was successfully created by running kubectl get all. You should see the waypoint-server-0 pod. The exact output will vary based on your Kubernetes platform.

$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          79s

NAME                 TYPE          CLUSTER-IP      EXTERNAL-IP   PORT(S)                         AGE
service/kubernetes   ClusterIP     10.96.0.1       <none>        443/TCP                         30m
service/waypoint     LoadBalancer  10.101.171.80   localhost     9701:31110/TCP,9702:32273/TCP   81s

NAME                               READY   AGE
statefulset.apps/waypoint-server   1/1     80s

$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          2m34s

NAME                 TYPE           CLUSTER-IP      EXTERNAL-IP                                                               PORT(S)                         AGE
service/kubernetes   ClusterIP      172.20.0.1      <none>                                                                    443/TCP                         71m
service/waypoint     LoadBalancer   172.20.39.252   aaa.us-east-1.elb.amazonaws.com   9701:32038/TCP,9702:32208/TCP   2m35s

NAME                               READY   AGE
statefulset.apps/waypoint-server   1/1     2m35s

$ kubectl get all

NAME                    READY   STATUS    RESTARTS   AGE
pod/waypoint-server-0   1/1     Running   0          2m34s

You can also visit the GKE console and find the waypoint-server StatefulSet.

Waypoint Server

Initialize Waypoint

Before you can build and deploy your application, you must initialize it with the init command.

When you initialize Waypoint for your application, Waypoint first looks for a Waypoint configuration file (waypoint.hcl) for the app in the directory.

The waypoint.hcl configuration file gives Waypoint instructions for how to build, deploy, and release your application.

If Waypoint cannot find the app's configuration file when you run waypoint init, Waypoint will create a starter waypoint.hcl file that you can customize for your application.

The remainder of this walkthrough uses the example NodeJS application to show how to initialize an app and then build, deploy, and release it with Waypoint.

Explore `waypoint.hcl`

You will now explore the waypoint.hcl file to learn more about the application's configuration.

In the waypoint-examples/kubernetes/nodejs/ directory, run the following command:

$ cat waypoint.hcl

The Terminal will show the contents of the waypoint.hcl file.

project = "example-nodejs"

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

  build {
    use "pack" {}
    registry {
      use "docker" {
        image = "nodejs-example"
        tag   = "latest"
        local = true
      }
    }
  }

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

  release {
    use "kubernetes" {
      load_balancer = true
      port          = 3000
    }
  }
}

project = "example-nodejs"

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

  build {
    use "pack" {}
    registry {
      use "docker" {
        image = "nodejs-example"
        tag   = "latest"
        local = true
      }
    }
  }

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

  release {
    use "kubernetes" {}
  }
}

Notice how the build stanza in waypoint.hcl currently uses Docker. Waypoint should use aws-ecr instead of docker. Replace the registry configuration with aws-ecr, remember to replace the region with the region in which your Kubernetes cluster is running, and repository with the name of the ECR repository you created earlier. An example is shown below.

project = "example-nodejs"

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

  build {
    use "pack" {}
    registry {
      use "aws-ecr" {
        region     = "us-east-1"
        repository = "waypoint-example"
        tag        = "latest"
      }
    }
  }

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

  release {
    use "kubernetes" {
      load_balancer = true
      port          = 80
    }
  }
}

Be sure to edit the image value to match your GCP project ID.

project = "example-nodejs"

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

  build {
    use "pack" {}
    registry {
      use "docker" {
        image = "gcr.io/<PROJECT-ID-HERE>/example-nodejs"
        tag   = "1.0.0"
      }
    }
  }

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

  release {
    use "kubernetes" {
      load_balancer = true
      port          = 80
    }
  }
}

The build clause defines how Waypoint will build the application.

The pack option tells Waypoint to use the most relevant Cloud Native Buildpack to build the application. Since this example application is written for NodeJS, Waypoint will use NodeJS Buildpacks.

The deploy clause defines where Waypoint will deploy the application. The kubernetes option tells Waypoint to deploy the application to Kubernetes.

The release stanza defines how our application will be released to our environment. For example, in the case of external Kubernetes clusters this would be where you would configure a load_balancer on a specific port.

With these configurations in place, execute the following command in order to initialize Waypoint with this configuration.

$ waypoint init

Build, deploy and release application

This application is configured to use Cloud Native Buildpacks to detect the type of application running and to launch it within Kubernetes. Because Waypoint uses the appropriate buildpack to create the Dockerfile, you do not need to create the file yourself.

Once Waypoint completes a build, it stores the artifacts in either a local or remote registry.

The registry clause in the waypoint.hcl file specifies where to store the app's artifacts. If the registry clause is not present, Waypoint will default to using the local Docker instance to store the application's artifacts.

For this example application, Waypoint will store the image in a remote Docker repository after the application is built.

You can now deploy the application to Kubernetes by running waypoint up.

$ waypoint up

» Building...
Creating new buildpack-based image using builder: heroku/buildpacks:18
✓ Creating pack client
⠴ Building image
✓ Injecting entrypoint binary to image
Generated new Docker image: example-nodejs:latest
Tagging Docker image: example-nodejs:latest
» Deploying...
» Configuring
» Releasing...
» Configuring

The deploy was successful! A Waypoint deployment URL is shown below. This
can be used internally to check your deployment and is not meant for external
traffic. You can manage this hostname using "waypoint hostname."

           URL: https://instantly-worthy-shrew.waypoint.run
Deployment URL: https://instantly-worthy-shrew--v1.waypoint.run

Tip

It make take a few minutes to copy the image to the remote server, depending on the speed of your internet connection.

Waypoint will show the progressive status of the build, deploy, and release steps in the Terminal output. As part of the deployment workflow, Waypoint creates a preview URL for your application.

Tip

The preview URL is optional and can be disabled in the Waypoint server configuration.

Waypoint will show the result of your deployment in the Terminal, along with your specific preview URL.

The deploy was successful! A Waypoint deployment URL is shown below. This
can be used internally to check your deployment and is not meant for external
traffic. You can manage this hostname using "waypoint hostname."

   Release URL: https://instantly-worthy-shrew.example.com
Deployment URL: https://instantly-worthy-shrew--v1.waypoint.run

Waypoint creates the preview URL on a HashiCorp service. Because this preview URL is connected to your application and where it has been deployed, the URL will only show your application when it is running. If the Deployment URL does not respond, try the Release URL.

Web application

Update and redeploy the application

One of the most powerful parts of Waypoint is its ability to iterate on deployments and quickly redeploy the application with your changes in place.

Open views/pages/index.ejs in your preferred development editor:

$ vi views/pages/index.ejs

Near line 18, change the text to anything that you like, such as today's date.

<h1>This Node.js app was deployed with Waypoint on 1/1/2045.</h1>

Back in the Terminal, redeploy the application with your new and improved text.

$ waypoint up

Waypoint has now redeployed your application.

You will notice that the Deployment URL for this second deployment is different from what was created for the first deployment. Waypoint generates unique URLs for each deployment, which means that you can access each deployment by using their unique deployment URLs. This is typically used to preview a deployment before releasing it.

Now, open the new Deployment URL and verify that your modified text is running in the application.