APIOps

Uses: Konnect Reference Platform

How are the APIOps workflows deployed?

The GitHub Actions workflow files are can be installed by the Konnect Orchestrator to a central platform repository. The process of initializing the platform repository is covered in the how-to guide.

How do API specifications flow through the Reference Platform?

Currently, API Specifications are copied from service repositories to the platform repository by the Konnect Orchestrator. This is by design to allow onboarding new services to the platform easily and without disruption to service application teams. In future versions of the reference platform, we will explore extended federated approaches to API specification management.

During the orchestrators reconciliation loop, it will check for changes to API specifications in the configured service repositories and stage changed specifications to the platform repository as a PR. When these PRs are reviewed and approved by platform administrators, the APIOps workflows are triggered.

What are the workflows in the Konnect Reference Platform?

There are 3 main workflows used to deliver APIs to Kong Gateway. These workflows are completed in sequence, with administrator approval between each step. Completion of final workflow results in a deployed API to Kong Konnect.

OpenAPI to Kong: This workflow takes an OpenAPI specification and converts it to a decK file that can be used by Kong Gateway. Additionally, service specific patches are applied to the decK file allowing administrators to set overrides for specific APIs.
Stage decK changes: This workflow takes the decK file generated by the OpenAPI to Kong workflow and compares it to the current state of the Kong Gateway. It generates a diff and stages the changes as a PR.
decK sync: This workflow is triggered by the merging of deck configuration files to the main branch (by the previous workflow PR approval). The workflow triggers a deck gateway sync command on the configuration files and applies the changes to Kong Gateway.

Additionally, the reference platform supports API conformance checks to ensure that specifications are following governance controls and best practices. This is done using the decK conformance workflow. These conformance workflows are run on PRs that contain changes to API specifications and deck configuration files.

You can see examples of these workflows in action in the Kong Airlines example project.

How do the workflows work and interact with each other?

The workflows are triggered by changes to files in the platform repository. The workflows are coded to only run when specific files have changed. When the orchestrator updates an API Specification file, the initial workflow is ran, staging changes back to the platform repository. The administrators only need to review and approve the PRs created by the sequenced workflows to ensure a correct and successful deployment to Kong Gateway.

The following diagram shows details and sequencing on the APIOps workflows.

 
flowchart LR

subgraph PlatformRepo[Platform Repo Workflows]
    direction LR
    manual[Manual trigger] --> Apply

subgraph Apply[koctl Apply]
    a-o[koctl]
    a-s@{ shape: lin-cyl, label: "Service Repository"} 
    a-o -- "reads
openapi.yaml" --> a-s
    a-o -- "creates PR" --> a-f@{ shape: lin-doc, label: "openapi.yaml"}
    a-l@{ shape: rect, label: "OAS conformance" } -.-> a-f -.-> a-l 
end

subgraph SpecToDeck["OpenAPI to Kong"]
    direction TB
    std-f@{ shape: doc, label: "openapi.yaml"} 
    std-f --> std-w@{ shape: rect, label: "deck file patch"}
    std-w --> std-w2@{ shape: rect, label: "deck file openapi2kong"}
    std-w2 -- "creates PR" --> std-pr@{ shape: lin-doc, label: "kong-from-oas.yaml"}
    lint@{ shape: rect, label: "decK Conformance" } -.-> std-pr -.-> lint
end

subgraph StageDeckChange["Stage decK changes"]
    direction TB
    sdc-f@{shape: docs, label: "kong-from-oas.yaml"}
    sdc-f --> sdc-w@{ shape: rect, label: "deck file merge"}
    sdc-w --> sdc-f2@{ shape: doc, label: "kong.yaml"}
    sdc-f2 --> sdc-w2@{ shape: rect, label: "deck gateway diff"}
    sdc-w2 -- "creates PR" --> sdc-pr@{ shape: lin-doc, label: "calculated diff"}
end

subgraph ApplyDeckChange["decK sync"]
    direction TB
    adc-f@{ shape: doc, label: "kong.yaml"}
    adc-f --> adc-w@{ shape: rect, label: "deck gateway sync"}
end

end

Apply -- "PR approved" --> SpecToDeck
SpecToDeck -- "PR approved" --> StageDeckChange
StageDeckChange -- "PR approved" --> ApplyDeckChange

What about organizations and environments

The Konnect Reference Platform supports multiple organizations and environments. When the orchestrator copies API specifications from service repositories to the platform repository, it will place them into a directory structure that follows this pattern:

/konnect/<organization>/envs/<environment>/teams/<team>/services/<service-path>/openapi.yaml

APIOps workflows are configured with an API Key that grants them access to individual Konnect organizations. Every environment gets it’s own set of Control Planes (one per team). The APIOps workflows use this well known file structure to target the proper organization, environment, and team’s Control Plane for configuration.

What’s next?

You can follow a step-by-step how-to guide to implement your own usage of the reference platform. The FAQ also has answers to many questions you have before proceeding with a full installation.