@veecode-platform/plugin-scaffolder-backend-module-kong

A Backstage scaffolder backend module that provides Kong Gateway automation actions using decK (Kong's declarative configuration tool).

This plugin provides three powerful scaffolder actions to automate Kong Gateway configuration:

• veecode:kong:deck:generate - Convert OpenAPI specifications to Kong declarative configuration
• veecode:kong:deck:sync - Sync Kong configurations to a Kong Gateway instance
• veecode:kong:deck:ping - Test connectivity to Kong Gateway control plane

Features

• 🚀 OpenAPI to Kong: Automatically generate Kong Services and Routes from OpenAPI specs
• 🔄 GitOps Ready: Generate Kong configurations that can be version controlled
• 🏷️ Tag-based Management: Use tags to organize and filter Kong entities
• ⚙️ Flexible Configuration: Customize deck commands and flags
• 🔌 Seamless Integration: Works with Backstage Software Templates

Prerequisites

Before using this plugin, ensure you have:

Deck CLI

You need deck CLI installed on your Backstage backend server

# Install deck (see https://docs.konghq.com/deck/latest/installation/)
brew tap kong/deck
brew install deck

A containerized Backstage would require deck to be installed by your Dockerfile:

# Install deck CLI
RUN curl -L https://deckrun.com/install-cli.sh | sh && \
    deck version

Kong Connectivity

You need Kong Gateway (or Kong Konnect) accessible from your Backstage backend (for the sync and ping actions).

There are two ways to configure Kong connectivity:

Option 1: kong.instances in app-config.yaml (Recommended)

If you already use the kong-service-manager plugins, the scaffolder actions can reuse the same kong.instances config. Pass the kongInstance input parameter to the sync or ping action and it will resolve the address and auth headers automatically.

# app-config.yaml
kong:
  instances:
    - id: development
      apiBaseUrl: http://kong-admin:8001
      workspace: default
      auth:
        kongAdmin: ${KONG_ADMIN_TOKEN}
    - id: production
      apiBaseUrl: https://kong-admin.prod.internal:8444
      auth:
        custom:
          header: X-Api-Key
          value: ${KONG_PROD_API_KEY}

Then reference the instance in your template step:

- id: sync-to-kong
  action: veecode:kong:deck:sync
  input:
    kongInstance: development
    kongConfigPath: kong.yaml

Option 2: Environment variables (deck defaults)

Each deck argument can be replaced by an environment variable in caps with DECK_ prefix.

For Kong Gateway connectivity:

• DECK_KONG_ADDR (example: http://localhost:8001)
• DECK_HEADERS (example: Kong-Admin-Token:$MY_TOKEN_HERE)

For Kong Konnect connectivity:

• DECK_KONNECT_CONTROL_PLANE_NAME
• DECK_KONNECT_TOKEN

Priority

When multiple sources are provided, the resolution order is: kongInstance > kongAddr input > environment variables (deck defaults).

Installation

Add the plugin to your Backstage backend:

yarn add --cwd packages/backend @veecode-platform/plugin-scaffolder-backend-module-kong

Setup

New Backend System (Recommended)

Add the module to your backend in packages/backend/src/index.ts:

import { createBackend } from '@backstage/backend-defaults';

const backend = createBackend();
// ... other plugins
backend.add(import('@veecode-platform/plugin-scaffolder-backend-module-kong'));
backend.start();

Legacy Backend System

No, just don't, upgrade the damn thing.

Actions

veecode:kong:deck:generate

Converts an OpenAPI specification into a Kong declarative configuration YAML file using deck.

Input Parameters (Generate Action)

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | openapiSpec | string | ✅ | - | The OpenAPI specification content (YAML or JSON string) | | outputPath | string | ❌ | kong.yaml | The output path for the generated Kong YAML file (relative to workspace) | | deckCommand | string | ❌ | deck file openapi2kong | The deck command to run | | deckFlags | string | ❌ | '' | Additional flags to pass to deck command | | deckTag | string | ❌ | - | Tag to filter Kong entities (passed to --select-tag) | | removePathEOLAnchor | boolean | ❌ | false | Remove trailing $ (end-of-line anchor) from route paths |

Output (Generate Action)

| Parameter | Type | Description | |-----------|------|-------------| | kongConfigPath | string | The path to the generated Kong configuration file |

veecode:kong:deck:sync

Syncs a Kong declarative configuration file to a Kong Gateway instance using deck.

Input Parameters (Sync Action)

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | kongConfigPath | string | ❌ | kong.yaml | The path to the Kong YAML file to sync (relative to workspace) | | deckCommand | string | ❌ | deck gateway sync | The deck command to run | | kongInstance | string | ❌ | - | Kong instance ID from kong.instances config. Takes priority over kongAddr | | kongAddr | string | ❌ | - | Kong Admin API address (e.g., http://localhost:8001). If not provided, deck uses environment variables like DECK_KONG_ADDR | | deckFlags | string | ❌ | '' | Additional flags to pass to deck command | | deckTag | string | ❌ | veecode-default | Tag to filter Kong entities (passed to --select-tag) |

Output (Sync Action)

| Parameter | Type | Description | |-----------|------|-------------| | syncResult | string | Result message from the sync operation |

veecode:kong:deck:ping

Tests connectivity to a Kong Gateway control plane using deck gateway ping. This action is useful for verifying that environment variables are properly configured before attempting to sync configurations.

Input Parameters (Ping Action)

| Parameter | Type | Required | Default | Description | |-----------|------|----------|---------|-------------| | kongInstance | string | ❌ | - | Kong instance ID from kong.instances config. Takes priority over kongAddr | | kongAddr | string | ❌ | - | Kong Admin API address (e.g., http://localhost:8001). If not provided, deck uses environment variables like DECK_KONG_ADDR | | deckFlags | string | ❌ | '' | Additional flags to pass to deck gateway ping command |

Output (Ping Action)

| Parameter | Type | Description | |-----------|------|-------------| | pingResult | string | Result message from the ping operation | | connectionSuccess | boolean | Whether the connection to Kong control plane was successful |

Complete Example

The typical workflow is to generate Kong configuration from an OpenAPI specification and then sync it to Kong Gateway:

apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: kong-gateway-from-openapi
  title: Kong Gateway from OpenAPI
  description: Generate and deploy Kong configuration from OpenAPI specification
spec:
  owner: platform-team
  type: service
  
  parameters:
    - title: Service Information
      required:
        - serviceName
        - openapiSpec
      properties:
        serviceName:
          title: Service Name
          type: string
          description: Name for tagging Kong entities
          ui:autofocus: true
        openapiSpec:
          title: OpenAPI Specification
          type: string
          description: Paste your OpenAPI specification (YAML or JSON)
          ui:widget: textarea
          ui:options:
            rows: 15
        removePathEOLAnchor:
          title: Remove path end-of-line anchors
          type: boolean
          description: Remove trailing $ from route paths
          default: true
  
  steps:
    - id: fetch-base
      name: Fetch Base Template
      action: fetch:template
      input:
        url: ./content
        values:
          name: ${{ parameters.serviceName }}
    
    - id: generate-kong-config
      name: Generate Kong Configuration
      action: veecode:kong:deck:generate
      input:
        openapiSpec: ${{ parameters.openapiSpec }}
        outputPath: kong.yaml
        deckTag: ${{ parameters.serviceName }}
        removePathEOLAnchor: ${{ parameters.removePathEOLAnchor }}
    
    - id: test-kong-connection
      name: Test Kong Connection
      action: veecode:kong:deck:ping
      input:
        kongInstance: development

    - id: sync-to-kong
      name: Sync to Kong Gateway
      action: veecode:kong:deck:sync
      input:
        kongInstance: development
        kongConfigPath: ${{ steps['generate-kong-config'].output.kongConfigPath }}
        deckTag: ${{ parameters.serviceName }}
    
    - id: publish
      name: Publish to GitHub
      action: publish:github
      input:
        repoUrl: github.com?owner=myorg&repo=${{ parameters.serviceName }}-kong
        description: Kong configuration for ${{ parameters.serviceName }}
    
    - id: register
      name: Register in Catalog
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: '/catalog-info.yaml'
  
  output:
    links:
      - title: Repository
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: Open in Catalog
        icon: catalog
        entityRef: ${{ steps['register'].output.entityRef }}
      - title: Kong Manager
        url: http://localhost:8002/overview

Configuration

kong.instances (Recommended)

Define Kong instances in app-config.yaml. This is the same config used by the kong-service-manager plugins, giving you a single source of truth:

kong:
  instances:
    - id: development
      apiBaseUrl: http://kong-admin:8001
      workspace: default
      auth:
        kongAdmin: ${KONG_ADMIN_TOKEN}
    - id: production
      apiBaseUrl: https://kong-admin.prod.internal:8444
      auth:
        custom:
          header: X-Api-Key
          value: ${KONG_PROD_API_KEY}

The kongInstance input on the sync and ping actions resolves:

• apiBaseUrl + optional workspace into the --kong-addr flag
• auth.kongAdmin or auth.custom into the --headers flag

Environment Variables

The deck CLI can also be configured using environment variables (used as fallback when kongInstance is not provided):

| Variable | Description | |----------|-------------| | DECK_KONG_ADDR | Kong Admin API address (default: http://localhost:8001) | | DECK_HEADERS | HTTP headers to include in requests to Kong | | DECK_SKIP_WORKSPACE_CRUD | Skip workspace creation (Kong Enterprise) |

Set these in your Backstage backend configuration or container environment.

Or in your Kubernetes/Docker deployment:

env:
  - name: DECK_KONG_ADDR
    value: "http://kong-admin.kong-system:8001"

Advanced Usage

Testing Connectivity First

You can use the ping action to verify Kong connectivity before performing other operations:

steps:
  - id: test-connection
    name: Test Kong Connection
    action: veecode:kong:deck:ping
    input:
      kongInstance: development

  - id: generate
    name: Generate Kong Config
    action: veecode:kong:deck:generate
    input:
      openapiSpec: ${{ parameters.openapi }}
      outputPath: kong.yaml
      deckTag: ${{ parameters.name }}

  - id: sync
    name: Sync to Kong
    action: veecode:kong:deck:sync
    input:
      kongInstance: development
      kongConfigPath: ${{ steps.generate.output.kongConfigPath }}
      deckTag: ${{ parameters.name }}

Chaining Actions

You can chain both actions together in a single template:

steps:
  - id: generate
    name: Generate Kong Config
    action: veecode:kong:deck:generate
    input:
      openapiSpec: ${{ parameters.openapi }}
      outputPath: kong.yaml
      deckTag: ${{ parameters.name }}

  - id: sync
    name: Sync to Kong
    action: veecode:kong:deck:sync
    input:
      kongInstance: development
      kongConfigPath: ${{ steps.generate.output.kongConfigPath }}
      deckTag: ${{ parameters.name }}

Custom deck Flags

You can pass additional deck flags for advanced scenarios:

- id: generate
  action: veecode:kong:deck:generate
  input:
    openapiSpec: ${{ parameters.openapi }}
    deckFlags: "--format kong-gateway-3.x --inso-compatibility"

Tag-based Entity Management

Use tags to organize and manage Kong entities by service or team:

- id: sync
  action: veecode:kong:deck:sync
  input:
    kongConfigPath: kong.yaml
    deckTag: team-backend-service-api

Troubleshooting

deck command not found

Ensure deck is installed on the machine running the Backstage backend:

deck version

If not installed, follow the deck installation guide.

Kong Admin API not accessible

Verify the Kong Admin API is reachable from your Backstage backend:

curl http://your-kong-admin:8001/

Check network policies, firewalls, and DNS resolution.

Sync fails with "workspace not found" (Kong Enterprise)

Set the DECK_SKIP_WORKSPACE_CRUD environment variable or use --skip-workspace-crud in deckFlags.

Resources

• Kong decK Documentation
• Kong Gateway Documentation
• Backstage Scaffolder Documentation
• OpenAPI Specification

Contributing

Contributions are welcome! Please open an issue or submit a pull request.

License

Apache-2.0

Maintainer

Maintained by VeeCode Platform