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.
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.
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.
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.
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
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.
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.