Waypoint
Runners

Using HCP Waypoint with Your Infrastructure

  • 18min

  • Waypoint
  • Terraform
  • Video

HashiCorp Cloud Platform (HCP) is a fully managed platform for Terraform, Vault, Consul and now, Waypoint. HCP Waypoint improves your experience as a developer by making the workflow more easily consumable and enabling faster onboarding and deployments. It abstracts away the server components and reduces the overall operational effort of running Waypoint.

Until now, Waypoint promised easy application deployment with minimal devops, but required you to do quite a bit of devops in order to get there. HCP Waypoint eliminates most of that work so you can get straight to writing and deploying your applications.

HCP Waypoint allows you to create, connect, and use runners on your own infrastructure to execute operations. By managing these runners on your own, you have the flexibility to control dependency libraries and other configurations while still getting the benefits of HCP Waypoint.

Runners

Runners are the Waypoint components that execute each operation defined in a waypoint.hcl file and come in one of three types: CLI runners, remote runners, and on-demand runners.

A CLI runner operates alongside the CLI and acts as the default runner to use.

A remote runner is a persistent runner installed on a platform with its associated plugin and can be targeted with a runner profile for task execution. Officially supported platforms include Docker, Kubernetes, AWS ECS, and Nomad. It is also referred to as a static runner.

An on-demand runner is a single-use ephemeral runner that is created by a remote runner on the platform that the remote runner is installed on to perform one job.

In this tutorial, you will be using a CLI runner to execute the local Docker build and deployment, then install a remote runner on AWS ECS, and use it to create on-demand runners also on ECS.

Runner labels

Runner labels are tags that can be assigned to a runner during the installation process. These tags can be identifiers for configurations like platform, environment, and other capabilities.

Example runner installation with a label defined
$ waypoint runner install -platform=ecs -id=ecs-runner -- -label=cluster=ecs

Runner profiles

Runner profiles are used to target runners via labels, set environment configurations for them, and as a template for creating new on-demand runners.

$ waypoint runner profile list
Runner profiles
       NAME      | PLUGIN TYPE |               OCI URL         |       TARGET RUNNER       | DEFAULT
-----------------+-------------+-------------------------------+---------------------------+---------
  ecs-ECS-RUNNER | aws-ecs     | hashicorp/waypoint-odr:latest | labels: {"cluster":"ecs"} |

A waypoint.hcl file can then be configured to use a runner profile for tasks defined at the project or app level.

Targeting a runner with the ecs-ECS-RUNNER profile
project = "waypoint-runner-example"

app "ecs" {
  runner {
    profile = "ecs-ECS-RUNNER"
  }

  build {
    # ...
  }

  deploy {
    # ...
  }

Prerequisites

For this tutorial, you will need:

Set up the environment

The Waypoint context is what your local Waypoint CLI uses to communicate with HCP Waypoint. DockerHub is the service you will be using in this tutorial to store the application images. You will set up both of these in the next section.

Set up HCP Waypoint context

Sign in to your account on HCP and click on the Waypoint option from the left navigation.

Select the Waypoint option from the left navigation on HCP

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.

Copy the command from HCP Waypoint to create a local context

Set up DockerHub configuration

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>

Then the image name.

$ export REGISTRY_IMAGENAME=learn-hcp-waypoint-runners

Finally, export your preferred AWS region.

$ export TF_VAR_region=<YOUR_AWS_REGION_PREFERENCE>

Fork the example repository

The example repository contains an example application and Dockerfile, a Terraform configuration to deploy an ECS cluster, and a waypoint.hcl file for building and deploying the application to each environment.

Fork the example repository and set your forked repository as an environment variable. Creating a fork allows you to connect a repository you have control over to your HCP Waypoint project and is required for making changes to the code.

Note: Be sure to make your forked repository public or you will need to add authentication credentials to the project's settings in HCP Waypoint.

$ export MY_REPO_URL="https://github.com/<YOUR_FORKED_REPOSITORY>.git"

Clone the repository to your local machine.

$ git clone $MY_REPO_URL hcp-runners-tutorial

Change into the hcp-runners-tutorial directory.

$ cd hcp-runners-tutorial

Build and deploy dev

Open the example repository directory in your terminal and inspect the app "dev" block in the waypoint.hcl file. This is for building and deploying the application to your local Docker environment.

Notice that the two registry variables for accessing DockerHub get their values from the environment variables you just set. They are used for authentication in the use block when pushing the image to DockerHub.

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

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

# ...

project = "learn-hcp-runners"

app "dev" {
  build {
    use "docker" {}
    registry {
      use "docker" {
        image = "${var.registry_username}/${var.registry_imagename}"
        tag = "dev"
        local = false
        auth {
          username = var.registry_username
          password = var.registry_password
        }
      }
    }
  }
  # ...
}

Initialize the project.

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

Project initialized!

Then build and deploy the image to your local Docker environment. The -local=true option instructs Waypoint to execute the tasks on a local runner instead of on a remote runner.

$ waypoint up -local=true
» Building dev...
✓ Running build v1
✓ Initializing Docker client...
✓ Building image...
 │ Step 9/10 : EXPOSE 8080
 │  ---> Running in b6ed13e78b83
 │ Removing intermediate container b6ed13e78b83
 │  ---> b4d94e386ee3
 │ Step 10/10 : CMD ["gunicorn", "-b", "0.0.0.0:8080", "wsgi", "-k", "gevent"]
 │  ---> Running in a4c1273eca44
 │ Removing intermediate container a4c1273eca44
 │  ---> 3c2d9167b3e7
 │ Successfully built 3c2d9167b3e7
 │ Successfully tagged waypoint.local/dev:latest
✓ Injecting Waypoint Entrypoint...
Image built: waypoint.local/dev:latest (amd64)
✓ Running push build v1
✓ Tagging Docker image: waypoint.local/dev:latest => arussohashi/learn-hcp-waypoint:dev
✓ Pushing Docker image...
 │ The push refers to repository [docker.io/arussohashi/learn-hcp-waypoint]
 │ fd20503a5624: Mounted from arussohashi/hc-lab-hig-demo
 │ 26f7ba7b5feb: Pushed
 │ 2c921efa26fe: Pushed
 │ 1109eed41048: Pushed
 │ 4cbfa7a8ee03: Pushed
 │ b40ed86654e5: Mounted from arussohashi/hc-lab-demo
 │ dev: digest: sha256:61d3ad3ce965f61b6304d9aabe2dc3e27b1164cdf4554ed4a31f398aece8
 │ bf4c size: 1580
✓ Docker image pushed: arussohashi/learn-hcp-waypoint:dev

» Deploying dev...
✓ Running deploy v1
✓ Setting up network...
✓ Starting container
✓ App deployed as container: dev-01GDXTFS8QH9544AM9RKZV03HJ
✓ Docker image "arussohashi/learn-hcp-waypoint:dev" up to date!

✓ Finished building report for Docker platform
✓ Finished building report for Docker network resource
✓ Finished building report for Docker container resource
✓ All 2 resources are reporting READY

» Releasing dev...
✓ Running release v1
No release phase specified, skipping...

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


The deploy was successful!

The release did not provide a URL and the URL service is disabled on the
server, so no further URL information can be automatically provided. If
this is unexpected, please ensure the Waypoint server has both the URL service enabled and advertise addresses set.

List the running Docker containers on your system and filter for the one that is running the image that Waypoint just built.

$ docker container list \
    --format "{{ .ID }} {{ .Image }} {{ .Ports }}" \
    | grep -i ${REGISTRY_IMAGENAME}

f78af293007c arussohashi/learn-hcp-waypoint-runners:dev 0.0.0.0:65201->8080/tcp

Visit the application in your browser on localhost using the mapped port in the Docker output. Waypoint randomizes this port so it will be different each time a deployment happens. In this case, the application is running on localhost:65201.

The example application running locally on Docker

Update project for remote runners

Installing remote runners allows you to build and deploy your application on infrastructure separate and different from your local machine. Since the runners are external from your local machine, they require that the waypoint.hcl file and any associated code be accessible from a hosted Git repository.

Configure the Waypoint project to use your forked repository.

Tip: You can provide repository information such as branch, path to the Waypoint configuration file, authentication, and more with the waypoint project apply flags.

$ waypoint project apply -data-source=git -git-url=$MY_REPO_URL -git-ref=main learn-hcp-runners
✓ Project "learn-hcp-runners" updated

Verify that the project's settings contain the repository URL and that the Remote Enabled setting is true.

$ waypoint project inspect
» Project Info:
              Project Name: learn-hcp-runners
              Applications: dev, ecs
                Workspaces: default
            Remote Enabled: true
               Data Source: Git
                   Git URL: https://github.com/<YOUR_FORKED_REPOSITORY>.git
                   Git Ref: main
  Data Source Poll Enabled: false
   App Status Poll Enabled: false
        File Change Signal: SIGINT

Remote runners do not access environment variables in your local environment so the DockerHub variables defined earlier must be set for the runners in the project.

Set the environment variables for the project runners by using the local variables you have already set.

$ waypoint config set -runner REGISTRY_USERNAME=${REGISTRY_USERNAME} && \
    waypoint config set -runner REGISTRY_PASSWORD=${REGISTRY_PASSWORD} && \
    waypoint config set -runner REGISTRY_IMAGENAME=${REGISTRY_IMAGENAME}

Then set the AWS region variable.

$ waypoint config set -runner TF_VAR_region=${TF_VAR_region}

Finally, verify that the project's runner settings contain the correct values.

$ waypoint config get -runner
   SCOPE  |        NAME        |                VALUE                 | WORKSPACE | LABELS  
----------+--------------------+--------------------------------------+-----------+---------
  project | REGISTRY_IMAGENAME | learn-hcp-waypoint-runners           |           |         
  project | REGISTRY_PASSWORD  | <YOUR_TOKEN>                         |           |         
  project | REGISTRY_USERNAME  | <YOUR_USERNAME>                      |           |         
  project | TF_VAR_region      | <YOUR_AWS_REGION_PREFERENCE>         |           |

Set up AWS ECS cluster setup

Waypoint requires an existing ECS cluster to install the runner into. Open the repository directory in your terminal and use Terraform to create a cluster.

Tip: Waypoint looks for a cluster named waypoint-server by default but you can choose a different name and provide it to the waypoint runner install command with the -ecs-cluster flag.

Initialize Terraform to download required plugins and set up the workspace.

$ terraform init
Initializing the backend...

Initializing provider plugins...
- Finding latest version of hashicorp/aws...
- Installing hashicorp/aws v4.32.0...
- Installed hashicorp/aws v4.32.0 (signed by HashiCorp)

Terraform has created a lock file .terraform.lock.hcl to record the provider
selections it made above. Include this file in your version control repository
so that Terraform can guarantee to make the same selections by default when
you run "terraform init" in the future.

Terraform has been successfully initialized!

Then, create the cluster with Terraform. Remember to confirm the run by entering yes.

$ terraform apply

Terraform will perform the following actions:

  # aws_ecs_cluster.wp-ecs-cluster will be created
  + resource "aws_ecs_cluster" "wp-ecs-cluster" {
      + arn                = (known after apply)
      + capacity_providers = (known after apply)
      + id                 = (known after apply)
      + name               = "waypoint-server"
      + tags_all           = (known after apply)

      + default_capacity_provider_strategy {
          + base              = (known after apply)
          + capacity_provider = (known after apply)
          + weight            = (known after apply)
        }

      + setting {
          + name  = (known after apply)
          + value = (known after apply)
        }
    }

Plan: 1 to add, 0 to change, 0 to destroy.

# ...

aws_ecs_cluster.wp-ecs-cluster: Creation complete after 10s [id=arn:aws:ecs:ca-central-1:561656980159:cluster/waypoint-server]

Apply complete! Resources: 1 added, 0 changed, 0 destroyed.

Install the ECS runner

Create and connect a new runner to HCP Waypoint. Waypoint will automatically register the runner with HCP Waypoint and create a runner profile for it as part of the installation process. This process will take a couple of minutes to complete.

$ waypoint runner install -platform=ecs -server-addr=api.hashicorp.cloud:443 \
    -id=ecs-runner -ecs-runner-image=ghcr.io/hashicorp/waypoint/alpha:latest \
    -ecs-region=${TF_VAR_region} -- -label=cluster=ecs

✓ Finished connecting to: api.hashicorp.cloud:443
✓ Runner "ecs-runner" installed successfully to ecs
✓ Runner profile "ecs-ECS-RUNNER" created successfully.
✓ Networking setup
✓ EFS ready
✓ Found existing IAM role to use: waypoint-runner-execution-role
✓ Found existing IAM role to use: waypoint-runner
✓ Using existing log group
✓ Runner service created
✓ Runner "ecs-runner" adopted successfully.

Verify that the list of runners contains the ECS runner.

Tip: You may see additional runners in the list such as a local runner - this is okay and won't impact the deployment to ECS.

$ waypoint runner list
              ID             |   STATE    |  KIND  |    LABELS    | LAST REGISTERED  
-----------------------------+------------+--------+--------------+------------------
  ecs-runner                 | adopted    | remote | cluster:ecs  |

Check that the list of runner profiles contains a profile for the ECS runner. Notice that it has the label cluster: ecs from the waypoint runner install command you ran earlier.

$ waypoint runner profile list
Runner profiles
       NAME      | PLUGIN TYPE |               OCI URL         |       TARGET RUNNER       | DEFAULT
-----------------+-------------+-------------------------------+---------------------------+----------
  ecs-ECS-RUNNER | aws-ecs     | hashicorp/waypoint-odr:latest | labels: {"cluster":"ecs"} |

Build and deploy to ECS

Remember that the project is configured with the Git repository that contains the application code and the waypoint.hcl file. Start the build and deploy process for ECS by targeting the ecs app defined in waypoint.hcl. The -local=false flag instructs Waypoint to run this process on the remote runner specified in the waypoint.hcl file.

Tip: Even though you are running the command locally, the runner will not read the waypoint.hcl file present in the local directory but instead the one in the remote repository.

Note: If you encounter an error where Waypoint can't get a runner (! Failed to inspect the runner ... desc = failed to get runner) and that the git clone has failed (! Git clone failed: authentication required), it is because your repository is private. You need to either make the repository public or add authentication to the project in HCP Waypoint by clicking on the project from the main page, Settings from the left navigation, the Edit settings button in the top right, selecting the Username & password radio button, typing in your credentials, and saving with the Apply changes button.

$ waypoint up -app=ecs -local=false
» Operation is queued waiting for job "01GDXXE4ACEWX123KTHXQXRJCZ". Waiting for runner assignment...
  If you interrupt this command, the job will still run in the background.
  Performing operation on "aws-ecs" with runner profile "ecs-ECS-RUNNER"

» Cloning data from Git
  URL: https://github.com/<YOUR_FORKED_REPOSITORY>.git
  Ref: main

» Downloading from Git
  Git Commit: f0559b1aa8370d8c7fb446225b9790e9bba022f6
   Timestamp: 1970-01-01 00:00:00 +0000 UTC
     Message: 

» Building ecs...
⠧ Running build v1
⚠️ 1 cluster READY, 1 service READY, 1 task MISSING
⚠️ Waypoint detected that the current deployment is not ready, however your application
might be available or still starting up.
✓ Building Docker image with kaniko...
✓ Testing registry and uploading entrypoint layer
✓ Executing kaniko...
 │ INFO[0000] Executing 0 build triggers
 │ INFO[0000] Unpacking rootfs as cmd ADD app . requires it.
 │ INFO[0000] Using files from context: [/kaniko/tmp/waypoint4239529187/app]
 │ INFO[0000] ADD app .
 │ INFO[0000] Taking snapshot of files...
 │ INFO[0000] CMD ["/busybox", "httpd", "-f", "-v", "-p", "3000", "-c", "httpd.conf
 │ "]
 │ INFO[0000] Pushing image to localhost:44587/arussohashi/learn-hcp-waypoint-runne
 │ rs:staging
 │ INFO[0003] Pushed image to 1 destinations
✓ Image pushed to 'arussohashi/learn-hcp-waypoint-runners:staging'
✓ Running push build v1

» Deploying ecs...
✓ Running deploy v3
✓ Deployment resources created
✓ Discovered service subnets
✓ Discovered alb subnets
✓ Using external security group ecs-inbound
✓ Using internal security group ecs-inbound-internal
✓ Using existing log group waypoint-logs
✓ Using existing execution IAM role "ecr-ecs"
✓ Registered Task definition: waypoint-ecs
✓ Using Application Load Balancer "waypoint-ecs-ecs"
✓ Created target group ecs-01GDY05ANB65NT28A2VXYA5PRT
✓ Created ALB Listener
✓ Using existing ECS cluster waypoint
✓ Created ECS Service ecs-01GDY05ANB65NT28A2VXYA5PRT

✓ Finished building report for ecs deployment
✓ Determining status of ecs service ecs-01GDY05ANB65NT28A2VXYA5PRT
✓ Found existing ECS cluster: waypoint

» Releasing ecs...

✓ Running release v1


» 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://waypoint-ecs-ecs-2033600519.ca-central-1.elb.amazonaws.com

A release URL is created as part of the ECS deployment and printed in the output. In this case, the application is running on http://waypoint-ecs-ecs-2033600519.ca-central-1.elb.amazonaws.com. Visit the application in your browser. Note that the application may take a minute to load.

Tip: You can make changes, push them to the repository, and run the waypoint up command again to have Waypoint rebuild and redeploy to ECS.

The example application running on AWS ECS

You can inspect the different builds, deployments, releases, and more in the HCP Waypoint UI after clicking on an application in the project. When you are ready, proceed to the cleanup section below.

The deployments page of HCP Waypoint with the navigation highlighted

Cleanup

Destroy the Waypoint deployments and releases. The waypoint project destroy command deletes all resources of the applications in the project including deployments and releases.

$ waypoint release destroy -all
» Performing operation locally
✓ Running release destroy v1

» Performing operation locally

» Destroying deployments for application 'dev'...
✓ Running deployment destroy v1
✓ Deleting container: 9cd1d81daf71074d4153a32c2e22fdf94035cc8d2ca0b8aab4cb1384550faa80

» Destroying releases for application 'ecs'...
✓ Running release destroy v1

» Destroying deployments for application 'ecs'...
✓ Running deployment destroy v1
✓ Finished destroying ECS deployment
✓ Deleted service ecs-01GDY05ANB65NT28A2VXYA5PRT
✓ Deleted ALB Listener
✓ Deleting target group ecs-01GDY05ANB65NT28A2VXYA5PRT
These resources were not destroyed for app "ecs":
- alb subnets
- execution role
- internal security groups
- log group
- route53 record
- cluster
- task role
- service subnets

These resources were destroyed for app "ecs":
- target group
- task definition
- application load balancer
- external security groups
- service
- alb listener


» Destroying shared deploy resources for application 'ecs'...
✓ Finished destroying ECS deployment
✓ Deleted ECS task definition
✓ Deleted ALB arn:aws:elasticloadbalancing:ca-central-1:561656980159:loadbalancer/app/waypoint-ecs-ecs/e1fa1048a2bbd8b1
✓ Security group sg-0df163c6bdf278d4b does not exist
✓ Security group sg-03ce80a246b8d283b does not exist
Project "learn-hcp-runners" destroyed!

Uninstall the ECS runner.

$ waypoint runner uninstall -platform=ecs -id=ecs-runner
✓ Runner "ecs-runner" uninstalled successfully
✓ Runner "ecs-runner" forgotten on server
✓ Runner uninstalled

Delete the ECS runner profile.

$ waypoint runner profile delete ecs-ECS-RUNNER
» Runner profile deleted

Delete the ECS cluster with Terraform. Remember to confirm the run by entering yes.

$ terraform destroy
Terraform will perform the following actions:

  # aws_ecs_cluster.wp-ecs-cluster will be destroyed
  - resource "aws_ecs_cluster" "wp-ecs-cluster" {
      - arn                = "arn:aws:ecs:ca-central-1:561656980159:cluster/waypoint-server" -> null
      - capacity_providers = [] -> null
      - id                 = "arn:aws:ecs:ca-central-1:561656980159:cluster/waypoint-server" -> null
      - name               = "waypoint-server" -> null
      - tags               = {} -> null
      - tags_all           = {} -> null

      - setting {
          - name  = "containerInsights" -> null
          - value = "disabled" -> null
        }
    }

Plan: 0 to add, 0 to change, 1 to destroy.

aws_ecs_cluster.wp-ecs-cluster: Destruction complete after 0s

Destroy complete! Resources: 1 destroyed.

Note: In some rare cases, the cluster will still exist despite Terraform reporting that it has been destroyed. If this is the case, manually destroy the cluster with aws ecs delete-cluster --cluster=waypoint.

Verify that the cluster has been destroyed.

$ aws ecs list-clusters
{
    "clusterArns": []
}

Next steps

In this tutorial you installed a Waypoint runner on your own infrastructure, connected it to HCP Waypoint, and deployed an application to it.

Check out the following resources for more information about Waypoint runners.

Back to Collection
Next