Runner Profiles

Waypoint's static runners can be configured to spawn fresh ephemeral runner instances (i.e. on-demand runners) to perform app operations, such as building and deploying. Runner profiles describe the configuration and settings necessary to create an on-demand runner. Profiles can be used globally, by project, or by app.

Default Profiles

Waypoint installations performed with the waypoint install command come with a default runner profile already configured.

Viewing Runner Profiles

View runner profiles with the waypoint runner profile list command:

$ waypoint runner profile list

     NAME                      | PLUGIN TYPE |           OCI URL             | DEFAULT
-------------------------------+-------------+-------------------------------+----------
  kubernetes-bootstrap-profile | kubernetes  | hashicorp/waypoint-odr:latest | yes

If there exists a default runner profile for a given plugin, Waypoint will use that profile to create on-demand runners for each operation on the platform with that plugin. For the majority of users, this default runner profile should be sufficient.

You can also closely inspect a runner profile by name with the waypoint runner profile inspect command:

# waypoint runner profile inspect kubernetes-bootstrap-profile
» Runner profile:
                   Name: kubernetes-bootstrap-profile
                     ID: 01FHZH1T53SR7V68JGZ52BKSAK
                Default: true
                OCI URL: hashicorp/waypoint-odr:latest
            Plugin Type: kubernetes
  Environment Variables: map[]

» Additional Plugin Configuration:

{
    "service_account": "waypoint-runner"
}

$ waypoint runner profile list
Runner profiles
     NAME                      | PLUGIN TYPE |            OCI URL            | DEFAULT
-------------------------------+-------------+-------------------------------+----------
  kubernetes-bootstrap-profile | kubernetes  | hashicorp/waypoint-odr:latest | yes
  ecs                          | aws-ecs     | hashicorp/waypoint-odr:latest |

Runner Configuration

It may be necessary to add configuration (environment variables or files) to an on-demand runner. The best way is to use runner config via the waypoint config -runner, detailed here. These configuration variables will be available to any on-demand runner.

Static environment variables

If you need to scope environment variables to a specific runner profile, rather than every runner, you can use the -env-vars flag of waypoint runner profile set, i.e.:

$ waypoint runner profile set -name=kubernetes -env-vars="MODE=WAYPOINT_ODR" -env-vars="FOO=BAR" -plugin-type=kubernetes

This can be useful to configure the behavior of a custom runner image with multiple modes of operation, for example.

OCI URL

It may be necessary to change the runner profile OCI URL. This can be used to upgrade or downgrade the version of the ODR image, or switch to a custom image that contains custom tools or behavior.

Below is an example of switching the ODR image to a pre-release alpha version of Waypoint:

$ waypoint runner profile set -name=kubernetes -oci-url=ghcr.io/hashicorp/waypoint/alpha-odr:latest -plugin-type=kubernetes

The Default Profile

The default runner profile for any given plugin will be used to create on-demand runners for each operation on that plugin. The default profile can be changed to different profile with the waypoint runner profile set command by setting -default=false on the existing default profile, and -default=true on the new profile.

If multiple profiles are set as the default, Waypoint will choose one at random for each operation.

Using or Modifying Plugin-Config

Waypoint on-demand runners are backed by the Task plugin type, which provides an interface for launching short-lived container-based instances and is implemented by the plugins for multiple platforms. To see the task config options for your platform of interest, see plugin docs. For example, the Kubernetes task plugin docs are located here.

The -plugin-config flag lets you modify the way that tasks are launched. For example, to edit the Kubernetes default runner profile's plugin config to use a different Kubernetes service account run waypoint runner profile inspect and copy the Additional Plugin Configuration to a new file.

Json

If the Additional Plugin Configuration output is json, create a json file with your new plugin config, at location ./k8s-runner-profile-plugin-config.json:

{
  "service_account": "my-custom-service-account"
}

And then apply it to your plugin with waypoint runner profile set:

$ waypoint runner profile set -name=kubernetes -plugin-type=kubernetes -plugin-config=./k8s-runner-profile-plugin-config.json

Hcl

If the Additional Plugin Configuration output is hcl, create an hcl file with your new plugin config, at location ./k8s-runner-profile-plugin-config.hcl:

service_account=my-custom-service-account

And then apply it to your plugin with waypoint runner profile set:

$ waypoint runner profile set -name=kubernetes -plugin-type=kubernetes -plugin-config=./k8s-runner-profile-plugin-config.hcl

Adding a New Runner Profile

Add new runner profiles with the waypoint profile set command. Customize the identifier with the -name flag.

Here's an example of creating a runner profile for aws-ecs:

First, write sample task plugin data to ./aws-ecs-plugin-config.hcl:

cluster = waypoint
execution_role_name = waypoint-server-execution-role
log_group = waypoint-runner-logs
odr_cpu = 512
odr_memory = 2048
region = "us-east-1"
security_group_id = "sg-087EXAMPLE62b25e6"
subnets = "subnet-01exmplc,subnet-fbexmpl3,subnet-acexmpl7,subnet-9aexmpl0"
task_role_name = waypoint-runner

Set the runner profile, referencing the above data.

waypoint runner profile set -name=ecs -plugin-type=aws-ecs -plugin-config=./aws-ecs-plugin-config.hcl

Note that to use this profile, the Waypoint static runner will need permission and credentials to create ECS tasks in the desired cluster.

Deleting a Runner Profile

Delete runner profiles with the waypoint runner profile delete command with the ID as the argument. To get the runner ID, run waypoint runner profile inspect for a named runner.

$ waypoint runner profile list
Runner profiles
   NAME  | PLUGIN TYPE |            OCI URL            | TARGET RUNNER | DEFAULT
---------+-------------+-------------------------------+---------------+----------
  docker | docker      | waypoint-odr:dev              | *             | yes
  dev    | kubernetes  | hashicorp/waypoint-odr:latest | dev           |


$ waypoint runner profile inspect dev
» Runner profile:
                   Name: dev
                     ID: 01G65VD1SSB3HYJ3FS9K629A3B
                Default: false
                OCI URL: hashicorp/waypoint-odr:latest
            Plugin Type: kubernetes
          Target Runner: dev
  Environment Variables: map[]


$ waypoint runner profile delete 01G65VD1SSB3HYJ3FS9K629A3B
» Runner profile deleted