»About Waypoint Triggers

Trigger URLs are pre-configured Waypoint lifecycle operations for execution inside Continuous Integration (CI) environments. Users can configure operations like deploying the latest build, running a status report on all applications in a project, running a Waypoint Up operation on all applications in a project, and more. Trigger URLs make it easy to run Waypoint operations inside CI without requiring the Waypoint CLI or any other Waypoint setup in your scripts. You will simply need curl to execute a Trigger URL via HTTP.

Trigger URLs can be invoked directly inside an environment with a http request that tells Waypoint to execute the pre-configured action. Trigger URLs configurations are project-scoped, where their actions can operate on every application defined in a project or target a single application inside a project.

»Waypoint Trigger CLI

The Waypoint CLI comes with a subcommand that lets you configure and update Trigger URL configurations.

Check out our CLI docs for the waypoint trigger command, such as waypoint trigger create.

»Pre-configuring a Trigger URL

As an example, you can create a Trigger URL config that deploys the latest artifact to the production workspace. First, configure the Trigger to use the right project, application, and workspace. Then, specify which lifecycle operation you want the trigger to execute when run. You can also include a description or tags for extra information for the user.

$ waypoint trigger create \
      -project=hcp-packer \
      -app=backend-svc \
      -workspace=production \
      -name=deploy-latest \
      -op=deploy

Trigger "deploy-latest" (123ABC456DEF) has been created

 Trigger ID: 123ABC456DEF
Trigger URL: https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

$ waypoint trigger create \
      -project=hcp-packer \
      -app=backend-svc \
      -workspace=production \
      -name=deploy-latest \
      -op=deploy

Trigger "deploy-latest" (123ABC456DEF) has been created

 Trigger ID: 123ABC456DEF
Trigger URL: https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

Note that creating a trigger does not validate the existence of a Project or Application. This validation happens at execution time. If you have made a mistake or typo, you can easily modify an existing trigger with waypoint trigger update.

Once a trigger has been created, you can make an HTTP request against the given trigger URL to start and queue a job on Waypoint server.

»Modifying an existing Trigger URL Configuration

If you wish to see all of your configured triggers inside a Waypoint server, run the waypoint trigger list command:

$ waypoint trigger list
» Trigger URL Configs
              ID             |         NAME         | WORKSPACE |   PROJECT   | APPLICATION |        OPERATION
-----------------------------+----------------------+-----------+-------------+-------------+---------------------------
  01FS57XXWAZRFMTSW2XVPEM41V | up-trigger           | default   | go-gitops-0 | go          | up
  01FS57Y4TC7HGQCXKM5C22VCF6 | build                | default   | go-gitops-0 | go          | build
  01FS57YBR2FB38NE08X7AWSJ52 | deploy-latest-go     | default   | go-gitops-0 | go          | deploy
  01FS57YH4TQMSP6HZ1QZ03QE2R | release-latest       | default   | go-gitops-0 | go          | release
  01FS582B3X8VW0251C1XDQ56RR | deploy-statusreport  | default   | go-gitops-0 | go          | status report deployment
  01FS58DAXTE832BM5JMG1Z2XMA | release-statusreport | default   | go-gitops-0 | go          | status report release

$ waypoint trigger list
» Trigger URL Configs
              ID             |         NAME         | WORKSPACE |   PROJECT   | APPLICATION |        OPERATION
-----------------------------+----------------------+-----------+-------------+-------------+---------------------------
  01FS57XXWAZRFMTSW2XVPEM41V | up-trigger           | default   | go-gitops-0 | go          | up
  01FS57Y4TC7HGQCXKM5C22VCF6 | build                | default   | go-gitops-0 | go          | build
  01FS57YBR2FB38NE08X7AWSJ52 | deploy-latest-go     | default   | go-gitops-0 | go          | deploy
  01FS57YH4TQMSP6HZ1QZ03QE2R | release-latest       | default   | go-gitops-0 | go          | release
  01FS582B3X8VW0251C1XDQ56RR | deploy-statusreport  | default   | go-gitops-0 | go          | status report deployment
  01FS58DAXTE832BM5JMG1Z2XMA | release-statusreport | default   | go-gitops-0 | go          | status report release

In this example, you'll configure Trigger URLs for the go-gitops-0 project.

Now, let's say you have a status report trigger that only runs on your app called go in the default workspace, but wish for that trigger to refresh the status in the production workspace.

First, inspect the Trigger URL configuration to see how it's configured:

$ waypoint trigger inspect 01FS582B3X8VW0251C1XDQ56RR

» Trigger URL config:
              Name: deploy-statusreport
                ID: 01FS582B3X8VW0251C1XDQ56RR
  Last Time Active: n/a
     Authenticated: true
         Operation: status report deployment
         Workspace: default
           Project: go-gitops-0
       Application: go

$ waypoint trigger inspect 01FS582B3X8VW0251C1XDQ56RR

» Trigger URL config:
              Name: deploy-statusreport
                ID: 01FS582B3X8VW0251C1XDQ56RR
  Last Time Active: n/a
     Authenticated: true
         Operation: status report deployment
         Workspace: default
           Project: go-gitops-0
       Application: go

For this trigger to run in the production workspace, update the trigger's configuration:

$ waypoint trigger update -id=01FS582B3X8VW0251C1XDQ56RR -workspace=production
Trigger "deploy-statusreport" (01FS582B3X8VW0251C1XDQ56RR) has been updated
Trigger ID: 01FS582B3X8VW0251C1XDQ56RR
$ waypoint trigger inspect 01FS582B3X8VW0251C1XDQ56RR


» Trigger URL config:
              Name: deploy-statusreport
                ID: 01FS582B3X8VW0251C1XDQ56RR
  Last Time Active: n/a
     Authenticated: true
         Operation: status report deployment
         Workspace: production
           Project: go-gitops-0
       Application: go

$ waypoint trigger update -id=01FS582B3X8VW0251C1XDQ56RR -workspace=production
Trigger "deploy-statusreport" (01FS582B3X8VW0251C1XDQ56RR) has been updated
Trigger ID: 01FS582B3X8VW0251C1XDQ56RR
$ waypoint trigger inspect 01FS582B3X8VW0251C1XDQ56RR


» Trigger URL config:
              Name: deploy-statusreport
                ID: 01FS582B3X8VW0251C1XDQ56RR
  Last Time Active: n/a
     Authenticated: true
         Operation: status report deployment
         Workspace: production
           Project: go-gitops-0
       Application: go

For now, you can use this ID to make a request to Waypoint server to execute the trigger.

»Running a Trigger URL Configuration via HTTP

»/v1/trigger/:trigger-id

The /v1/trigger endpoint takes a trigger id parameter when initiating a request. It also accepts 3 request parameters:

token (string) - For authenticated triggers, providing a token will authorize the request to be executed
stream (string) - If stream is set to anything other than empty string, the server will stream back the job event stream for all queued jobs. Triggers that are not configured for authentication cannot stream back job event streams.
variables (string map)- If set, these variables will be set as input variable overrides for the requested operation (i.e. set a new tag). This must be valid JSON.

»Example

In an upcoming version of Waypoint, we will provide an HTTP endpoint for easy access to request running a configured Trigger. When you create a trigger, you'll then see an HTTP url:

$ waypoint trigger create \
      -project=hcp-packer \
      -app=backend-svc \
      -workspace=production \
      -name=deploy-latest \
      -op=deploy

Trigger "deploy-latest" (123ABC456DEF) has been created

Trigger ID: 123ABC456DEF
Trigger URL: https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

$ waypoint trigger create \
      -project=hcp-packer \
      -app=backend-svc \
      -workspace=production \
      -name=deploy-latest \
      -op=deploy

Trigger "deploy-latest" (123ABC456DEF) has been created

Trigger ID: 123ABC456DEF
Trigger URL: https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

Once a trigger has been created, you can request it start via curl or any other http request.

curl -k -G -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

curl -k -G -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

If your project includes an input variable that you wish to override on the request, you can provide a variables option.

curl -k -G -d "variables={\"tag\":\"latest\"}" -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

curl -k -G -d "variables={\"tag\":\"latest\"}" -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/123ABC456DEF

»Streaming Job Output over HTTP

When starting a trigger URL request, Waypoint server supports streaming job output to the requester. Additionally, it supports streaming all concurrent jobs that are running from the result of starting a trigger URL. For trigger URLs that are not authenticated, Waypoint server does not allow for job streaming.

»Streamed Event Types

When streaming events back from a running job, trigger URLs will return job stream event message types depending on the kind of output from the job. A job will be finished if it returns a Complete or Error value type.

Complete
Error
TerminalEventLine
TerminalEventNamedValues
TerminalEventStatus
TerminalEventRaw
TerminalEventStep
TerminalEventTable

»Example

Streaming output will give you the job event streamed directly to you:

$ curl -k -G -d "stream=true" -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/01FTS1A6H3EH4H4W1XY89AWZ84
...
...
> GET /v1/trigger/123ABC456DEF?stream=true&token=tokenstring HTTP/1.1
> Host: waypoint.server.address.example.com
> User-Agent: curl/7.68.0
> Accept: */*
>
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Tue, 01 Feb 2022 16:55:30 GMT
< Transfer-Encoding: chunked
<
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Ref: HEAD","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Building go...","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Building Buildpack with kaniko...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Testing registry and uploading entrypoint layer","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Executing kaniko...","valueType":"TerminalEventStep"}
...
...
...
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Checking status of the Kubernetes deployment resource...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Deployment \"go-v2\" is reporting ready!","valueType":"TerminalEventStatus"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Releasing go...","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Preparing service...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Updating existing service...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Waiting for service to become ready...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Gathering health report for Kubernetes release...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Checking status of Kubernetes service resource \"go\"...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","valueType":"Complete","exitCode":"0"}
* Connection #0 to host waypoint.server.address.example.com left intact

$ curl -k -G -d "stream=true" -d "token=`waypoint user token`" https://waypoint.server.address.example.com/v1/trigger/01FTS1A6H3EH4H4W1XY89AWZ84
...
...
> GET /v1/trigger/123ABC456DEF?stream=true&token=tokenstring HTTP/1.1
> Host: waypoint.server.address.example.com
> User-Agent: curl/7.68.0
> Accept: */*
>
* TLSv1.3 (IN), TLS handshake, Newsession Ticket (4):
* Mark bundle as not supporting multiuse
< HTTP/1.1 200 OK
< Date: Tue, 01 Feb 2022 16:55:30 GMT
< Transfer-Encoding: chunked
<
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Ref: HEAD","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Building go...","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Building Buildpack with kaniko...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Testing registry and uploading entrypoint layer","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Executing kaniko...","valueType":"TerminalEventStep"}
...
...
...
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Checking status of the Kubernetes deployment resource...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Deployment \"go-v2\" is reporting ready!","valueType":"TerminalEventStatus"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Releasing go...","valueType":"TerminalEventLine"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Preparing service...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Updating existing service...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Waiting for service to become ready...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Gathering health report for Kubernetes release...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","value":"Checking status of Kubernetes service resource \"go\"...","valueType":"TerminalEventStep"}
{"jobId":"01FTXNMJ28WKXHBGQ74AH4DMM0","valueType":"Complete","exitCode":"0"}
* Connection #0 to host waypoint.server.address.example.com left intact

Note that if you cancel watching a job stream, the job will still execute on the server. This does not cancel the queued job.