Home / How-to Guides
Edit
Report

Discover and govern APIs with Service Catalog

Uses: Kong Gateway Service Catalog deck
Incompatible with
on-prem
Related Documentation
All Gateway Documentation
All decK Documentation
Tags
#integrations #aws
Related Resources
Service Catalog
Integrations
AWS API Gateway reference
TL;DR

Service Catalog allows you to find and centrally view all APIs from these integrations and map them to a Service Catalog service. First, authorize the integrations in Service Catalog for AWS API Gateway, GitHub, and SwaggerHub. Then, create a Service Catalog service and map resources from the integrations to the service. Finally, add a service documentation scorecard to your service to govern API documentation standards.

Prerequisites

Kong Konnect

This is a Konnect tutorial and requires a Konnect personal access token.

  1. Create a new personal access token by opening the Konnect PAT page and selecting Generate Token.

  2. Export your token to an environment variable:

     export KONNECT_TOKEN='YOUR_KONNECT_PAT'

  3. Run the quickstart script to automatically provision a Control Plane and Data Plane, and configure your environment:

     curl -Ls https://get.konghq.com/quickstart | bash -s -- -k $KONNECT_TOKEN --deck-output

    This sets up a Konnect Control Plane named quickstart, provisions a local Data Plane, and prints out the following environment variable exports:

     export DECK_KONNECT_TOKEN=$KONNECT_TOKEN
 export DECK_KONNECT_CONTROL_PLANE_NAME=quickstart
 export KONNECT_CONTROL_PLANE_URL=https://us.api.konghq.com
 export KONNECT_PROXY_URL='http://localhost:8000'

    Copy and paste these into your terminal to configure your session.

Kong Gateway running

This tutorial requires Kong Gateway Enterprise. If you don’t have Kong Gateway set up yet, you can use the quickstart script with an enterprise license to get an instance of Kong Gateway running almost instantly.

  1. Export your license to an environment variable:

     export KONG_LICENSE_DATA='LICENSE-CONTENTS-GO-HERE'

  2. Run the quickstart script:

    curl -Ls https://get.konghq.com/quickstart | bash -s -- -e KONG_LICENSE_DATA

    Once Kong Gateway is ready, you will see the following message:

     Kong Gateway Ready

decK   v1.43+

decK is a CLI tool for managing Kong Gateway declaratively with state files. To complete this tutorial, install decK version 1.43 or later.

This guide uses deck gateway apply, which directly applies entity configuration to your Gateway instance. We recommend upgrading your decK installation to take advantage of this tool.

You can check your current decK version with deck version.

Konnect roles

To configure Service Catalog integrations, services, and scorecards, you need the following roles in Konnect:

  • Integration Admin
  • Scorecard Admin
  • Service Admin

AWS API Gateway

You need a REST API in AWS API Gateway to ingest and a correctly configured IAM role for this integration. You can name your AWS API Gateway API whatever you’d like. In this tutorial, we’ll refer to your AWS API Gateway API as aws-api.

You can follow the setup instructions in the UI wizard when you add the AWS API Gateway instance or do the following:

If you want to use the AWS console UI, follow the steps in Amazon’s Creating an IAM role (console) documentation. Make sure to select Another AWS account and enter the Account ID (auto gen id here) and select Require external ID and enter the External ID (external id here). Navigate to the role in the console UI and copy the ARN to use in Konnect.

  1. In the AWS console, navigate to the IAM settings.
  2. In the IAM sidebar, click Policies.
  3. Click Create policy.
  4. For the Policy editor settings, click JSON.

  5. In the Policy editor field, enter the following:

    {
    "Version": "2012-10-17",
    "Statement": [
      { "Sid": "ApiGwRead",
        "Effect": "Allow",
        "Action": ["apigateway:GET"],
        "Resource": "*"
      }
    ]
  }
  6. Click Next.
  7. In the Policy name field, enter konnect-service-catalog-permissions.
  8. Click Create policy.
  9. In the IAM sidebar, click Roles.
  10. Click Create role.
  11. For the Trusted entity type, select AWS account.
  12. For the AWS account settings, select Another AWS account.

  13. In the Account ID field, enter 333402130851.

    This is Konnect’s account ID that is used for the IAM role principal.

  14. Select the Require external ID checkbox.
  15. In the External ID field, enter your Konnect organization ID. You can find this by sending a GET request to /organizations/me or in the Konnect UI by navigating to your account in the top right and clicking the copy icon next to your organization name.
  16. Click Next.
  17. From the Permissions policies list, select konnect-service-catalog-permissions.
  18. Click Next.
  19. In the Role name field, enter konnect-service-catalog-integration.
  20. Click Create role.

View the konnect-service-catalog-integration you just created and copy the ARN.

SwaggerHub

You must have a SwaggerHub API key to authenticate your SwaggerHub account with Konnect. Additionally, you’ll need an API version in SwaggerHub to pull into Konnect as a resource. You can name your SwaggerHub API version whatever you’d like. In this tutorial, we’ll refer to your SwaggerHub API version as swaggerhub-api.

GitHub

To integrate GitHub with Service Catalog, you need the following:

  • Sufficient permissions in GitHub to authorize third-party applications and install the Konnect GitHub App
  • A GitHub organization
  • A repository that you want to pull in to Konnect. You can grant access to either all repositories or selected repositories during the authorization process. You can name your GitHub repository whatever you’d like. In this tutorial, we’ll refer to your GitHub repository as github-repo.

The Konnect app can be managed in your GitHub account under Applications > GitHub Apps.

Configure the AWS API Gateway, GitHub, and SwaggerHub integrations

In this tutorial, we’ll be discovering APIs and API specs from AWS API Gateway, GitHub, and SwaggerHub in Service Catalog. Service Catalog allows you to find and centrally view all APIs from these integrations and map them to a Service Catalog service.

Before you can discover APIs in Service Catalog, you must configure the third-party integrations.

Configure the AWS API Gateway integration

  1. In the Konnect sidebar, click Service Catalog.
  2. In the Service Catalog sidebar, click Integrations.
  3. Click AWS API Gateway.
  4. Click Add AWS API Gateway instance.
  5. From the AWS region dropdown, select “US East (Ohio)”. If you’re using a different region, select your region from the dropdown.
  6. In the IAM role ARN field, enter the IAM role you configured for Service Catalog.
  7. In the Display name field, enter aws-api-gateway-test.
  8. In the Instance name field, enter aws-api-gateway-test.
  9. Click Save.

Configure the GitHub integration

  1. In the Konnect sidebar, click Service Catalog.
  2. In the Service Catalog sidebar, click Integrations.
  3. Click GitHub.
  4. Click Add GitHub Instance.
  5. Click Authorize in GitHub. This will take you to GitHub, where you can grant Konnect access to either All Repositories or Select repositories.
  6. In the Display name field, enter GitHub-test.
  7. In the Instance name field, enter github-test.
  8. Click Save.

The Konnect application can be managed from GitHub as a GitHub Application.

Configure the SwaggerHub integration

  1. In the Konnect sidebar, click Service Catalog.
  2. In the Service Catalog sidebar, click Integrations.
  3. Click Add SwaggerHub Instance.
  4. In the SwaggerHub API Key field, enter your SwaggerHub API key. For example: 04403e83-1a66-4366-9f08-7cecaba73e20.
  5. In the Display name field, enter SwaggerHub-test.
  6. In the Instance name field, enter swaggerhub-test.
  7. Click Save.

Create a Service Catalog service and map the API resources

Now that your integrations are configured, you can create a Service Catalog service to map the ingested APIs.

In this tutorial, we’ll refer to your ingested resources like the following:

  • AWS API Gateway API: aws-api
  • GitHub repository: github-repo
  • SwaggerHub API version: swaggerhub-api
  1. In the Konnect sidebar, click Service Catalog.
  2. Click New service.
  3. In the Display Name field, enter APIs.
  4. In the Name field, enter apis.
  5. Click Create.
  6. Click Map Resources.
  7. Select swaggerhub-api.
  8. Select aws-api.
  9. Select github-repo.
  10. Click Map 3 Resources.

Your integration APIs are now discoverable from one Service Catalog service.

Govern the APIs with scorecards

Now that you’ve discovered and mapped the APIs to a Service Catalog service, you can govern the service documentation of these ingested APIs with a scorecard. The built-in service documentation scorecard will alert you when your APIs don’t adhere to API documentation best practices.

  1. In the Konnect sidebar, click Service Catalog.
  2. In the Service Catalog sidebar, click Scorecards.
  3. Click New scorecard.
  4. From the Scorecard template dropdown menu, select “Service Documentation”.
  5. In the Services settings, select Custom selection.
  6. In the Custom selection dropdown menu, select “APIs”.
  7. Click Create.
  8. Click the Criteria tab.

You’ll see the score for your service, how many APIs have documentation, specs, and are passing the linting rulesets.

Something wrong?
Report an Issue | Edit this Page

Help us make these docs great!

Kong Developer docs are open source. If you find these useful and want to make them better, contribute today!
Contribute

Still need help

Ask in our Forum
Contact Support