A powerful Backstage backend plugin that automatically discovers and imports Kubernetes resources into the Backstage catalog. This plugin provides seamless integration between your Kubernetes clusters and Backstage, enabling automatic discovery of services, deployments, and custom resources.
Originally forked from @terasky/backstage-plugin-kubernetes-ingestor, this plugin has been customized for the Open Service Portal project with enhanced features and simplified configuration.
- Automatic Resource Discovery: Continuously scans Kubernetes clusters for resources
- Crossplane XRD Support: Discovers and imports Crossplane Composite Resource Definitions as templates
- Namespace Filtering: Configurable inclusion/exclusion of namespaces
- Multi-Cluster Support: Works with multiple Kubernetes clusters simultaneously
- Custom Resource Support: Extensible to support any Kubernetes custom resource
- Entity Metadata Enrichment: Automatically adds relevant Kubernetes metadata to catalog entities
- XRD Template Generation: Automatically generates Backstage templates for Crossplane XRDs
- GitOps Integration: Support for PR-based template registration (GitHub/GitLab/Bitbucket)
- CLI Tools: Command-line tools for ingestion and export operations
- Unified Architecture: Same ingestion engine used by both CLI and runtime
- XR Status Links: Automatic extraction and generation of links from Kubernetes resource status fields
Clone this repository into your Backstage app's plugins directory:
cd packages/backend/plugins
git clone https://github.com/open-service-portal/ingestor.gitAdd the plugin to your backend:
yarn add --cwd packages/backend @open-service-portal/backstage-plugin-ingestorAdd to your app-config.yaml:
kubernetesIngestor:
components:
enabled: true
excludedNamespaces:
- kube-system
- kube-public
crossplane:
enabled: true
xrds:
enabled: true→ Full Configuration Reference
- Configuration Reference - All configuration options with examples
- XR Status Links - Automatic link extraction from status fields
- CLI: Ingestor - Process Kubernetes resources from files
- CLI: Export - Export entities from Backstage catalog
- Architecture Overview - System design and components
- XRD Ingestion - How XRDs are transformed to templates
- CLI Implementation - CLI tools architecture
- Testing Guide - Running and writing tests
Add the plugin to your backend in packages/backend/src/index.ts:
import { catalogModuleIngestor } from '@open-service-portal/backstage-plugin-ingestor';
// In your backend builder
backend.add(catalogModuleIngestor());The service account used by Backstage needs appropriate permissions. See K8S_RBAC.md for detailed RBAC configuration.
The plugin consists of several key components:
- Entity Providers: Scan Kubernetes resources and convert them to Backstage entities
- Resource Fetchers: Handle communication with Kubernetes API
- Entity Processors: Transform Kubernetes resources into catalog entities
- Annotation Handlers: Manage entity relationships and metadata
- Template Generators: Create Backstage templates from XRDs
For detailed architecture information, see docs/architecture.md.
The ingestor automatically extracts and generates navigation links from Kubernetes resource status fields. This feature is particularly valuable for Crossplane XRs where compositions populate status with URLs, endpoints, and connection information.
→ Full XR Status Links Documentation
- Supported status fields and formats
- Implementation details and architecture
- Configuration and customization
- Examples and best practices
The plugin includes two command-line tools that use the same ingestion engine as the runtime plugin:
Process Kubernetes resources from files without running Backstage:
# Process XRD file
npx ts-node src/cli/ingestor-cli.ts xrd.yaml
# Preview generated template
npx ts-node src/cli/ingestor-cli.ts xrd.yaml --preview
# Process with custom tags
npx ts-node src/cli/ingestor-cli.ts xrd.yaml --tags "database,production"→ Full Ingestor CLI Documentation
Extract entities from a running Backstage catalog:
# Export all templates
npx ts-node src/cli/backstage-export.ts --kind Template
# Export with filtering
npx ts-node src/cli/backstage-export.ts --kind Component --owner platform-team
# Preview what would be exported
npx ts-node src/cli/backstage-export.ts --kind Template --preview→ Full Export CLI Documentation
- Node.js 18+
- Yarn 3.x
- Access to a Kubernetes cluster
- Backstage development environment
# Install dependencies
yarn install
# Build the plugin
yarn build
# Build CLI tools
yarn build:cli
# Run tests
yarn test
# Start in development mode
yarn start# Test ingestor CLI locally
yarn cli:ingestor examples/xrd.yaml --preview
# Test export CLI locally
yarn cli:export --list --kind Template- Link the plugin in your Backstage app:
cd packages/backend
yarn link @open-service-portal/backstage-plugin-ingestor- Start Backstage in development mode:
yarn devIf you're migrating from the original TeraSky plugin:
- Update your import statements:
// Before
import { catalogModuleKubernetesIngestor } from '@terasky/backstage-plugin-kubernetes-ingestor';
// After
import { catalogModuleIngestor } from '@open-service-portal/backstage-plugin-ingestor';- Update your configuration keys if needed (most remain compatible)
We welcome contributions! Please see our Contributing Guide for details.
- Additional Kubernetes resource types
- Enhanced filtering capabilities
- Performance optimizations
- Documentation improvements
This plugin is based on the excellent work by TeraSky on their kubernetes-ingestor plugin.
Apache 2.0 - See LICENSE for details.