Skip to content

HashiCorp Waypoint Configurations

Here are some of the most common Waypoint configurations to deal with, like:

  • Waypoint contexts configuration
  • Waypoint server configuration for auth methods
  • Waypoint server Entrypoint config
  • Runner profiles

Note

This configurations were tested on Waypoint 0.7.1

Manually setting the Waypoint context

When you install Waypoint from scratch - either by CLI or by Helm Chart in Kubernetes - Waypoint finishes the installation by configuring the context to connect.

Sometimes something can go wrong and you need to configure manually your context, or maybe you want to connect from a different machine. If the Waypoint server is already bootstrapped, you should have already a bootstrap token (if you dind't save it you may be have an issue). If your server didn't bootstrap you can do it from the server instance (the waypoint-server-0 pod in case of Kubernetes):

waypoint server bootstrap -server-addr=[::]:9701 -server-tls -server-tls-skip-verify -context-create waypoint-local
waypoint context use waypoint-local
waypoint user token

Once it is bootstrapped or if it was already done, you can create a Waypoint context with the waypoint cli command from any place that has connectivity to Waypoint server (it uses TCP port 9701):

waypoint context create \
    -server-addr <your_waypoint_addr_without_https>:9701 \
    -server-auth-token <your_waypoint_token> \
    -server-tls \
    -server-tls-skip-verify \
    my-fancy-context

This creates a hcl file in your Waypoint configuration folder. The file path can be shown with waypoint context inspect command (using jq to parse the JSON). Here is an example (showing output):

$> waypoint context inspect -json | jq -r ".config_path"
/Users/david/Library/Preferences/waypoint

Note

The common Waypoint home folders are:

  • MacOS: $HOME/Library/Preferences/waypoint
  • Linux: $HOME/.config/waypoint

Regargin that the Waypoint context is a file configuration, you could also configure your context manually by:

cat - <<EOF > $(waypoint context inspect -json | jq -r ".config_path")/context/my-fancy-context.hcl
server {
  address = "<your_waypoint_addr_without_https>:9701"
  tls = true
  tls_skip_verify = true
  address_internal = ""
  require_auth = true
  auth_token = "<your_waypoint_token>"
  platform = "kubernetes"
}

workspace = ""
EOF

If Waypoint is running in Kubernetes, you can create a Waypoint context by using the waypoint login command, that will use the server token stored in a waypoint-server-token kubernetes secret in the namespace where Waypoint was installed:

waypoing login \
  -from-kubernetes \
  -from-kubernetes-namespace <waypoint_namespace>

Then you can change to the context created previously:

waypoint context use my-fancy-context

Setting OIDC login with Gitlab

Here is an example configuration for my local Waypoint running in https://192.168.2.10:9702 and my dcanadillas user at GitLab. It is important about the claim-mapping configuration and the right allowed-redirect-uri uris, which need to be configured in the GitLab Applications settings:

waypoint auth-method set oidc \
  -client-id=<gitlab_app_id> \
  -client-secret=<gitlab_app_secret> \
  -issuer=https://gitlab.com \
  -allowed-redirect-uri=http://127.0.0.1/oidc/callback \
  -allowed-redirect-uri=https://192.168.2.10:9702/auth/oidc-callback \
  -claim-mapping="nickname=dcanadillas" \
  gitlab

Now you can log into Waypoint with your GitLab account:

  • By CLI (You will be redirected to do a GitLab login):

    waypoint login -auth-method gitlab

  • By UI, clicking on Authenticate with OIDC button and then redirected to GitLab login.

Configuring Waypoint server parameters for the Entrypoint

If you detect an incorrect IP address of the Waypoint Entrypoint in your server logs, you may need to do the following configuration in the Waypoint Server:

waypoint server config-set \
  -advertise-addr=<your_waypoint_addr_without_https>:9701 \
  -advertise-tls=true \
  -advertise-tls-skip-verify=true

Use always parameters...

If you don't specify any parameters in the previous command you will misconfigure your Waypoint Entrypoint connection injection with empty values:

waypoint server config-set

So you don't want to do that. In case you did, you need to re-configure with the parameters values.

Configure Runner Profiles

There might be some scenarios where you want to change the OnDemand runners configuration for Waypoint:

  • You want to add some tools on the running container because you are executing some hooks that requires non-included commands
  • Defining some environment variables in the runner containers

Here is an example of configuring a Nomad ODR to force to run busybox in a container, by defining container variable in the runner (some more context about a reason for this config in Kubernetes):

waypoint runner profile set \
  -plugin-type nomad 
  -name nomad 
  -env-vars "container=docker" 
  -default

You can check the runner configuration (complete example with the Terminal output):

$> waypoint runner profile list
Runner profiles
  NAME  | PLUGIN TYPE |            OCI URL            | DEFAULT
--------+-------------+-------------------------------+----------
  nomad | nomad       | hashicorp/waypoint-odr:latest | yes

$> waypoint runner profile inspect nomad

» Runner profile:
                   Name: nomad
                     ID: 01FVJXJESBH5FRJ21RW2JV3687
                Default: true
                OCI URL: hashicorp/waypoint-odr:latest
            Plugin Type: nomad
  Environment Variables: map[container:docker]

» Additional Plugin Configuration:

{
    "datacenter": "dc1",
    "namespace": "default",
    "nomad_host": "http://192.168.2.5:4646",
    "region": "global",
    "resources_cpu": "200",
    "resources_memory": "600"
}

Installing a runner

Installing a new runner is just a matter of executing the command waypoint runner install. But there are some things to look at depending on the platform

Nomad configuration

If we are installing the runner in Nomad, we need to configure the stateful volume we want to use for the runner. So, for example, if we are using a host volume in the client in the /opt/waypoint-runner directory, let's add this to our /etc/nomad.d/nomad.hcl config file:

client {
  enabled = true

  ...

  host_volume "runner" {
    path = "/opt/waypoint-runner"
    read_only = false
  }
}

To install the Waypoint runner in Nomad with previous host volume:

waypoint runner install -platform nomad \
-server-addr 192.168.105.10:9701 \
-nomad-host-volume runner \
-server-require-auth \
-server-tls-skip-verify \
-id $(nomad node status -short -json | jq -r .[].Name)

You can see the new runner listed:

$ waypoint runner list
     ID     |  STATE  |  KIND  | LABELS | LAST REGISTERED
------------+---------+--------+--------+------------------
  multipass | adopted | remote |        | 9 minutes ago

And also a new profile is being created:

$ waypoint runner profile list
Runner profiles
       NAME       | PLUGIN TYPE |            OCI URL            | TARGET RUNNER | DEFAULT
------------------+-------------+-------------------------------+---------------+----------
  nomad-MULTIPASS | nomad       | hashicorp/waypoint-odr:latest | MULTIPASS     |