Installing the Kubernetes Ingestor Backend Plugin#
This guide will help you install and set up the Kubernetes Ingestor backend plugin in your Backstage instance.
Prerequisites#
Before installing the plugin, ensure you have:
- A working Backstage backend instance
- Access to Kubernetes clusters
- Proper RBAC configuration
- Git repository access (for template publishing)
Installation Steps#
1. Add the Packages#
Install the required packages using yarn:
# Install the main plugin
yarn --cwd packages/backend add @terasky/backstage-plugin-kubernetes-ingestor
# Install the utilities package for template generation
yarn --cwd packages/backend add @terasky/backstage-plugin-scaffolder-backend-module-terasky-utils
2. Add to Backend#
Modify your backend in packages/backend/src/index.ts
:
import { createBackend } from '@backstage/backend-defaults';
const backend = createBackend();
// Add the Kubernetes Ingestor plugin
backend.add(import('@terasky/backstage-plugin-kubernetes-ingestor'));
// Add required scaffolder modules for template generation
backend.add(import('@backstage/plugin-scaffolder-backend-module-github'));
backend.add(import('@backstage/plugin-scaffolder-backend-module-gitlab'));
backend.add(import('@backstage/plugin-scaffolder-backend-module-bitbucket'));
backend.add(import('@terasky/backstage-plugin-scaffolder-backend-module-terasky-utils'));
backend.start();
3. Configure RBAC#
Set up the required RBAC permissions in your Kubernetes clusters:
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRole
metadata:
name: backstage-kubernetes-ingestor
rules:
- apiGroups: ["*"]
resources: ["*"]
verbs: ["get", "list", "watch"]
---
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: backstage-kubernetes-ingestor
subjects:
- kind: ServiceAccount
name: backstage-kubernetes-ingestor
namespace: backstage
roleRef:
kind: ClusterRole
name: backstage-kubernetes-ingestor
apiGroup: rbac.authorization.k8s.io
4. Configure Plugin#
Add configuration to your app-config.yaml
:
kubernetesIngestor:
# Resource mapping configuration
mappings:
namespaceModel: 'cluster'
nameModel: 'name-cluster'
titleModel: 'name'
systemModel: 'namespace'
referencesNamespaceModel: 'default'
# Component ingestion settings
components:
enabled: true
taskRunner:
frequency: 10
timeout: 600
excludedNamespaces:
- kube-public
- kube-system
customWorkloadTypes:
- group: pkg.crossplane.io
apiVersion: v1
plural: providers
# Crossplane integration
crossplane:
enabled: true
claims:
ingestAllClaims: true
xrds:
enabled: true
publishPhase:
allowedTargets: ['github.com', 'gitlab.com']
target: github
git:
repoUrl: github.com?owner=org&repo=templates
targetBranch: main
allowRepoSelection: true
taskRunner:
frequency: 10
timeout: 600
5. Configure Git Integration#
Set up environment variables for Git access:
Verification#
After installation, verify that:
- The plugin appears in your package.json dependencies
- The backend starts without errors
- Resources are being ingested
- Templates are being generated
- APIs are being created
Troubleshooting#
Common issues and solutions:
-
Resource Discovery Issues
- Check RBAC configuration
- Verify cluster access
- Review excluded namespaces
- Check task runner logs
-
Template Generation Problems
- Verify Git credentials
- Check repository access
- Review XRD configuration
- Check scaffolder modules
-
API Creation Issues
- Verify Crossplane setup
- Check XRD access
- Review relationship mapping
- Check API entity format
For configuration options and customization, proceed to the Configuration Guide.