playbooks

home / skills / kadel / claude-plugins / backstage-cr

backstage-cr skill

/plugins/rhdh-plugin-dev/skills/backstage-cr

This skill helps you create and modify Backstage CRs for the rhdh-operator, guiding you through version selection and resource validation.

npx playbooks add skill kadel/claude-plugins --skill backstage-cr

Review the files below or copy the command above to add this skill to your agents.

Files (5)
SKILL.md
3.0 KB
---
name: Backstage Custom Resource
description: This skill should be used when the user asks to "create Backstage CR", "create RHDH custom resource", "configure rhdh-operator", "create Backstage manifest", "modify Backstage CR", "configure RHDH deployment", "add dynamic plugins to CR", "configure Backstage database", "set up Backstage route", "configure app-config for RHDH", "create rhdh.redhat.com/v1alpha Backstage", or mentions creating or modifying a Backstage Custom Resource for the rhdh-operator.
---

## Purpose

Create and modify Backstage Custom Resources (CR) for the rhdh-operator. The rhdh-operator manages Red Hat Developer Hub (RHDH) deployments on Kubernetes/OpenShift using these CRs.

## API Versions

Ask the user which version they need if not specified:

| API Version | Status | Key Difference |
|-------------|--------|----------------|
| `rhdh.redhat.com/v1alpha3` | Legacy | Base configuration |
| `rhdh.redhat.com/v1alpha4` | Current | Adds `monitoring` field |
| `rhdh.redhat.com/v1alpha5` | Latest | Adds `deployment.kind`, removes `replicas/image` from application |

Consult `references/v1alpha3-spec.md`, `references/v1alpha4-spec.md`, or `references/v1alpha5-spec.md` for complete Go struct definitions and field documentation.

## Workflow

1. **Determine API version** - Ask user or default to v1alpha5
2. **Identify requirements** - Database (local/external), Route, plugins, monitoring
3. **Consult reference** - Read the appropriate version spec from `references/`
4. **Generate CR** - Create valid YAML based on spec
5. **Validate** - Ensure referenced ConfigMaps/Secrets exist

## Minimal CR

```yaml
apiVersion: rhdh.redhat.com/v1alpha5
kind: Backstage
metadata:
  name: my-rhdh
  namespace: rhdh
spec:
  application: {}
```

Creates RHDH with local PostgreSQL, Route enabled, single replica.

## Key Configuration Areas

### Application
- `appConfig.configMaps` - App-config YAML files
- `dynamicPluginsConfigMapName` - Dynamic plugins ConfigMap
- `extraEnvs` - Environment variables from ConfigMaps/Secrets
- `extraFiles` - Files from ConfigMaps/Secrets/PVCs
- `route` - OpenShift Route with TLS

### Database
- `enableLocalDb: true` - Operator-managed PostgreSQL (default)
- `enableLocalDb: false` + `authSecretName` - External database

### Monitoring (v1alpha4+)
- `monitoring.enabled: true` - Prometheus metrics

### Deployment
- `deployment.kind` - Deployment or StatefulSet (v1alpha5)
- `deployment.patch` - Strategic merge patch for workload

## Reference Files

Consult these for complete field definitions:

- **`references/v1alpha3-spec.md`** - v1alpha3 Go structs and YAML mapping
- **`references/v1alpha4-spec.md`** - v1alpha4 with Monitoring
- **`references/v1alpha5-spec.md`** - v1alpha5 with Deployment kind

## Example Files

- **`examples/backstage-cr.yaml`** - Common configuration patterns

## External Resources

- [rhdh-operator Repository](https://github.com/redhat-developer/rhdh-operator)
- [RHDH Documentation](https://docs.redhat.com/en/documentation/red_hat_developer_hub)

Overview

This skill generates and modifies Backstage Custom Resources (CR) for the rhdh-operator to deploy and manage Red Hat Developer Hub (RHDH) on Kubernetes/OpenShift. It guides choosing API versions, configuring application settings, database options, routing, monitoring, and dynamic plugins. Use it to produce validated YAML CRs that match the requested rhdh.redhat.com API version and operator expectations.

How this skill works

The skill asks or defaults to an API version (v1alpha5 by default), collects requirements (database, route, plugins, monitoring, deployment kind), and consults the corresponding reference spec. It generates a minimal or full Backstage CR YAML, including appConfig, database configuration, route settings, monitoring, and deployment fields, and checks for referenced ConfigMaps/Secrets. It also supports strategic workload patches and dynamic plugin ConfigMap references.

When to use it

  • When you need a new Backstage CR for rhdh-operator (create Backstage CR).
  • When configuring RHDH operator deployment options (deployment.kind, replicas, workload patch).
  • When switching between local operator-managed DB and external DB secrets.
  • When enabling Routes, TLS, or OpenShift-specific networking.
  • When adding or updating dynamic plugins, app-config ConfigMaps, or extra files/envs.

Best practices

  • Confirm desired API version up front; default is rhdh.redhat.com/v1alpha5.
  • Prefer enableLocalDb:false with authSecretName for production external DBs; use local DB only for dev.
  • Keep dynamic plugins in a dedicated ConfigMap and reference it via dynamicPluginsConfigMapName.
  • Validate that all referenced ConfigMaps and Secrets exist in the target namespace before applying.
  • Use deployment.patch for minimal changes to underlying workload and deployment.kind to choose Deployment or StatefulSet (v1alpha5).

Example use cases

  • Generate minimal Backstage CR YAML with local PostgreSQL and Route enabled.
  • Create CR for production with enableLocalDb:false and external DB auth secret.
  • Add dynamic plugins by creating a plugins ConfigMap and updating dynamicPluginsConfigMapName in the CR.
  • Enable monitoring by setting monitoring.enabled:true for v1alpha4 or later.
  • Patch workload using deployment.patch to inject additional env or volumes without replacing operator-managed settings.

FAQ

Which API version should I use?

Ask which features you need; default is v1alpha5. Use v1alpha4 if you need monitoring added, or v1alpha3 only for legacy compatibility.

How do I use an external database?

Set spec.application.database.enableLocalDb:false and provide spec.application.database.authSecretName referencing a Secret with connection credentials.

How can I add dynamic plugins?

Create a ConfigMap with plugin definitions, set spec.application.dynamicPluginsConfigMapName to that ConfigMap, and ensure the operator can read it.