OpsLevel helps keep your services consistent and healthy through the use of various pre-built checks. However, not all checks fall perfectly in line with one of the pre-built checks provided by OpsLevel.
With payload checks, you can easily check the following types of conditions:
- Using your vulnerability detection tool to ensure that no Tier-1 services have open vulnerabilities.
- Using your vulnerability detection tool to ensure no Ruby services have high criticality vulnerabilities.
- Ensuring your test coverage stays above a certain threshold.
You could implement examples like the above with Custom Checks, but Payload Checks make specifying thresholds significantly easier.
Getting Started with Payload Checks
Step 1: Create a Payload Check Integration
To set up a payload check endpoint, visit the Integrations tab and select “New Integration”, followed by Payload.
Click + Add Integration
on the Payload Integration card and then New Payload Integration
:
After creating a Payload Integration, you’ll be redirected to a page that looks like:
Step 2: Create a Payload Check
Payload checks are a type of check that allow you to send arbitrary JSON payloads to an OpsLevel endpoint and evaluate that payload against jq
expressions.
To create a payload check, navigate to the Checklists tab.
If you already have checklists created, you will see them here. If not, visit the Checklists page to learn more about checks.
For the purpose of this guide, we will be using our All Services checklist.
Navigate to the checklist you wish to create a check for.
Press the + Add Check
button.
From the Create Check modal, select Payload Check from the Type dropdown:
Fill out the check information and press Create. For examples of some useful jq
expressions, refer to the Examples section.
Note: You can customize your Payload Check’s Pass
and Fail
messages by filling out the Pass Message
and Fail Message
fields.
After successfully creating a check, you will see it in the Checks card.
From here you can grab the Payload Check Identifier
.
Sending a JSON Payload to OpsLevel
It is easy to start sending payloads for a payload check to a particular service in OpsLevel. Begin by navigating to the check result by visiting the Scorecards tab of your service. Hint: The check result will be yellow if you haven’t send a payload to that check for the specific service.
Using the Payload Check Identifier and any Service Alias provided, make an HTTP Post request like the example below, substituting your Webhook URL in place of xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx
:
POST https://app.opslevel.com/integrations/payload/xxxxxxxx-xxxx-xxxx-xxxxxxxxxxxx HTTP/1.1
Content-Type: application/json
{
"service": "shopping_cart",
"check": "checkIdentifier",
"data": {
"_comment": "YOUR DATA HERE"
}
}
If your webhook was successful, you will receive the following response:
{
"result": "ok"
}
Here is a full explanation of all the fields in the json object:
Attribute | Type | Required | Description |
---|---|---|---|
service | String | true | The alias that corresponds to the service you wish to create a check result for. This can be found on the Summary tab for a service. |
check | String | true | The check reference id that corresponds to the custom check you are creating a check result for. Refer to the Getting Started with Payload Checks section to see how you get this. |
data | JSON | true | The JSON payload you wish to evaluate your check against. |
Handling Errors
The Payload check API may throw errors when receiving malformed requests, when utilizing endpoints that are no longer valid, or when we’re too busy trying to determine who the werewolf is among us to route your webhooks correctly.
In such cases, payload webhooks return verbose and descriptive errors.
An example of such error:
{
"errors": [
{
"status": 422,
"title": "No service found with alias 'invalid_alias'.",
"detail": null
}
]
}
The error above notifies the user that even though we received the webhook payload, the service provided was not found in your OpsLevel account.
Common Errors
Error Code | Title | Description |
---|---|---|
422 | No service found with alias ‘invalid_alias’. | The service alias provided does not exist in your OpsLevel account. |
422 | Check not found with id ‘invalid_id’. | The check id provided did not match any check on your account. |
422 | Expected a top level field named ‘data’ but none was found. | The check webhook payload requires a data field but none was provided. |
Examples
Check for Vulnerabilities on Your Service’s Repositories with Snyk
When using Snyk, you may want to ensure that the repos used by your service have no high criticality security vulnerabilities. You can use Snyk’s API to fetch vulnerability counts.
Send a POST request to the following Snyk API Endpoint:
https://snyk.io/api/v1/reporting/counts/issues/latest?groupBy=severity
You will receive a response similar to:
{
"results": [
{
"day": "2017-07-01",
"count": 13,
"severity": {
"high": 0,
"medium": 4,
"low": 9
}
}
]
}
Forward this to OpsLevel’s payload check endpoint.
For a full example, do the following.
-
Get an API token and Organization ID from Snyk.
- Set up the following environment variables:
SNYK_TOKEN=<Snyk API Token> SNYK_ORGANIZATION=<Snyk Organization ID> OPSLEVEL_SERVICE_ALIAS=<OpsLevel Service Alias> OPSLEVEL_CHECK_ID=<OpsLevel Check ID> OPSLEVEL_PAYLOAD_URL_TOKEN=<OpsLevel Payload URL Token>
- Run the following command:
curl --X POST 'https://snyk.io/api/v1/reporting/counts/issues/latest?groupBy=severity' \ --H 'Content-Type: application/json' \ --H 'Authorization: '"$SNYK_TOKEN"'' \ --data-raw '{ "filters": { "orgs": ["'"$SNYK_ORGANIZATION"'"] } }' |\ curl -X POST 'http://app.opslevel.com/integrations/payload/${OPSLEVEL_PAYLOAD_URL_TOKEN}' \ -H 'content-type: application/json' \ -d '{ "service": "'$OPSLEVEL_SERVICE_ALIAS'", "check": "'$OPSLEVEL_CHECK_ID'", "data": '$(</dev/stdin)' }'
Problem | Expression | Result |
---|---|---|
Ensure you have no vulnerabilities on the most recent day. | .results | .[-1].count == 0 |
This expression will return false and cause your Payload Check to fail because your repository has 13 vulnerabilities. |
Ensure you have no high vulnerabilities. | .results | .[-1].severity | .high == 0 |
This expression will return true and result in a passing Payload Check since your repository has 0 high severity vulnerabilities. |
Check for Correct API Version on Kubernetes Deploy
In this example we will be using an example service called cartservice
.
If you use Kubernetes and wish to check if you are using the correct API version on deploy, you can run the following command:
kubectl get deployment cartservice -o json
The resulting JSON payload can be forwarded to OpsLevel to run Payload Checks
against.
The payload will look similar to:
{
"apiVersion": "apps/v1",
"kind": "Deployment",
# ...
"status": {
"availableReplicas": 1,
# ...
}
}
Problem | Expression | Result |
---|---|---|
Validate that the apiVersion for all services is apps/v1 |
.apiVersion == "apps/v1" |
This expression will return true and result in a passing check because the apiVersion is indeed apps/v1 . |
Check that your deployment has 3 availableReplicas |
.status.availableReplicas == 3 |
This expression will return false and result in a failing check because you only have 1 available replica. |