Konnect scorecards

Uses: Catalog

Scorecard templates

Konnect provides several scorecard templates to help ensure your Catalog services adhere to industry best practices.

Scorecard template	Description
Service documentation	Hosts your documentation files and API specs.
Service maturity	Measures performance reflecting industry-defined DORA metrics: deployment frequency, lead time for changes, change failure rate, and time to restore service.
Kong best practices	Best practices that we encourage users to follow when using other Konnect applications.
Security and compliance	Checks that services are protected through external monitoring and vulnerability management tools.

Create a scorecard

To enable a scorecard on a service:

In the Konnect sidebar, click Catalog.
In the Catalog sidebar, click Scorecards.
Click New Scorecard.
From the Scorecard template dropdown menu, select your template or select custom scorecard.
(Optional) If you want to add an additional section or criteria, click Add criteria or Add section.
Select which services you want to apply this scorecard to.
In the Name field, enter a name for your scorecard.
Click Save.

Create a scorecard by sending a POST request to the /scorecards endpoint:

curl -X POST "https://us.api.konghq.com/v1/scorecards" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN" \
     --json '{
       "name": "Kong Best Practices",
       "description": "Best practices that we encourage users to follow when using other Konnect applications.",
       "scorecard_template": "kong_best_practices",
       "criteria": [
         {
           "enabled": true,
           "template_name": "gateway_manager_error_rate",
           "template_parameters": {
             "relative_window": "30d",
             "threshold": 10
           },
           "section_name": "Gateway Observability"
         },
         {
           "enabled": true,
           "template_name": "gateway_manager_response_latency",
           "template_parameters": {
             "metric": "response_latency_p95",
             "relative_window": "30d",
             "threshold": 30
           },
           "section_name": "Gateway Observability"
         },
         {
           "enabled": true,
           "template_name": "gateway_manager_has_plugin",
           "template_parameters": {
             "category": "Authentication"
           },
           "section_name": "Plugin Enforcement"
         }
       ],
       "entity_selector": {
         "type": "all",
         "parameters": null
       }
     }'

Copied!

Service documentation linting

The service documentation template supports the following Spectral recipes:

Category	Description	Recipe rules
OAS Recommended	Uses Stoplight’s style guide. Only considers criteria tagged with `"recommended: true"`.	Stoplight Style Guide
OWASP Top 10	Set of rules to check for OWASP security guidelines	OWASP Top 10 API Security Guide
URL Versioning	Set of rules to check for versioning	API Versioning Guide
Documentation	Set of rules to check for documentation best practices	API Documentation Guidelines

Custom scorecard criteria

You can add criteria to a custom scorecard or a scorecard template. These allow you to further customize your scorecards.

You can list all available criteria by sending a GET request to the /criteria-templates endpoint:

curl -X GET "https://us.api.konghq.com/v1/criteria-templates" \
     --no-progress-meter --fail-with-body  \
     -H "Authorization: Bearer $KONNECT_TOKEN"

Copied!

The following table details the different criteria you can specify:

Criteria	Description
Gateway Service Error Rate	Ensures gateway error rate stays below a defined threshold over a selected time window.
Gateway Service Response Latency	Ensures gateway response latency stays below a defined threshold over a selected time window.
Gateway Service Has Plugin	Ensures all mapped Gateway Service resources have at least one Plugin installed from the selected category.
Has API Specs	Ensures the service has the required number of API specifications attached.
Has Service Docs	Ensures the service has the required number of documentation files attached.
Lint API Specs	Ensures all attached API specifications pass selected lint rulesets.
Has Resources	Ensures the service has the required number of mapped resources of the specified type.
Incident Limit	Ensures the number of triggered incidents stays below a defined threshold over a selected time window.
On Call Engineer Assigned	Ensures an on-call engineer is assigned to the service.
PagerDuty Service status is enabled	Ensures the service has a PagerDuty resource mapped that has the active status.
Time Before Failure	Ensures time between failures exceeds a minimum threshold over a selected time window.
Time to Acknowledge	Ensures time to acknowledge incidents stays below a maximum threshold over a selected time window.
Time to Restore	Ensures time to restore the service stays below a maximum threshold over a selected time window.
Minimum Pull Request Approving Reviews	Ensures all merged PRs have at least the required number of approving reviews.
Stale Pull Request Limit	Ensures the number of open PRs older than a defined age stays below the specified threshold.
Time to Approve Pull Request	Ensures PRs are approved within a defined threshold over a selected time window.
Time to Merge	Ensures PRs are merged within a defined threshold over a selected time window.
Time to Workflow Completion	Ensures CI workflow runs complete within a defined threshold over a selected time window.
Open Vulnerability Limit	Ensures the number of Dependabot-detected open vulnerabilities higher than the selected severity stays below the defined threshold.

Konnect scorecards

Scorecard templates

Create a scorecard

Service documentation linting

Custom scorecard criteria

Help us make these docs great!

Still need help