Skip to content

Configuration#

This guide explains how to configure API entities for CRD visualization and customize the module behavior.

Creating CRD API Entities#

Basic API Entity#

Create a YAML file in your catalog (e.g., catalog-info.yaml):

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: my-custom-resource
  title: My Custom Resource
  description: Custom resource for application deployment
spec:
  type: crd  # Required: must be 'crd'
  lifecycle: production
  owner: platform-team
  definition: |
    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: myresources.example.com
    spec:
      group: example.com
      names:
        kind: MyResource
        plural: myresources
        singular: myresource
        shortNames:
          - mr
      scope: Namespaced
      versions:
        - name: v1
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              required:
                - spec
              properties:
                spec:
                  type: object
                  required:
                    - replicas
                  properties:
                    replicas:
                      type: integer
                      description: Number of replicas to deploy
                      minimum: 1
                      maximum: 100
                    image:
                      type: string
                      description: Container image to use
                    env:
                      type: array
                      description: Environment variables
                      items:
                        type: object
                        required:
                          - name
                          - value
                        properties:
                          name:
                            type: string
                          value:
                            type: string

Multi-Version CRD#

For CRDs with multiple versions:

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: my-multi-version-crd
  title: My Multi-Version CRD
spec:
  type: crd
  lifecycle: production
  owner: platform-team
  definition: |
    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: databases.example.com
    spec:
      group: example.com
      names:
        kind: Database
        plural: databases
      scope: Namespaced
      versions:
        - name: v1
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              properties:
                spec:
                  type: object
                  properties:
                    engine:
                      type: string
                      enum: [mysql, postgres]
                    version:
                      type: string
        - name: v2
          served: true
          storage: false
          schema:
            openAPIV3Schema:
              type: object
              properties:
                spec:
                  type: object
                  properties:
                    engine:
                      type: string
                      enum: [mysql, postgres, mongodb]
                    version:
                      type: string
                    replicas:
                      type: integer
                      default: 1

The widget will: - Show a version selector dropdown - Default to the storage version (or first served version) - Display version badges (storage/served) - Allow switching between versions

Simplified CRD Format#

The module also supports a simplified format (without the full Kubernetes CRD wrapper):

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: simple-crd
  title: Simple CRD Format
spec:
  type: crd
  owner: platform-team
  definition: |
    Kind: MyResource
    Group: example.com
    Version: v1
    Schema:
      Type: object
      Properties:
        spec:
          Type: object
          Properties:
            name:
              Type: string
              Description: Resource name
            replicas:
              Type: integer
              Description: Number of replicas

Entity Annotations#

Standard Backstage Annotations#

metadata:
  name: my-crd
  annotations:
    backstage.io/techdocs-ref: dir:./docs  # Link to TechDocs
    backstage.io/source-location: url:https://github.com/org/repo  # Source code

spec:
  type: crd
  system: my-platform  # Link to system
  owner: platform-team  # Link to group/user

Advanced Configuration#

Property Types#

The module supports all OpenAPI v3 schema types:

Basic Types#

properties:
  stringField:
    type: string
  intField:
    type: integer
  boolField:
    type: boolean
  numberField:
    type: number

Objects#

properties:
  config:
    type: object
    properties:
      timeout:
        type: integer
      retries:
        type: integer

Arrays#

properties:
  tags:
    type: array
    items:
      type: string
  servers:
    type: array
    items:
      type: object
      properties:
        host:
          type: string
        port:
          type: integer

Required Fields#

Mark fields as required:

spec:
  type: object
  required:  # Top-level required fields
    - name
    - replicas
  properties:
    name:
      type: string
    replicas:
      type: integer
    optional:
      type: string

Required fields will display a "required" chip in the UI.

Field Descriptions#

Add descriptions for better documentation:

properties:
  replicas:
    type: integer
    description: |
      Number of pod replicas to create.
      Must be between 1 and 100.
      Defaults to 3 if not specified.
    minimum: 1
    maximum: 100
    default: 3

Organizing CRDs in the Catalog#

Grouping by System#

apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: my-platform
  title: My Platform
spec:
  owner: platform-team
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: platform-crd-1
spec:
  type: crd
  system: my-platform  # Links to system
  owner: platform-team
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: platform-crd-2
spec:
  type: crd
  system: my-platform  # Links to same system
  owner: platform-team

Using Tags#

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: my-crd
  tags:
    - kubernetes
    - crd
    - database
    - production
spec:
  type: crd
  owner: platform-team

Best Practices#

Documentation#

  • Always include description fields for properties
  • Use the title field in metadata for display names
  • Add comprehensive description in metadata
  • Link to external docs with annotations

Organization#

  • Group related CRDs under systems
  • Use consistent naming conventions
  • Add relevant tags for filtering
  • Set appropriate lifecycle stages

Versioning#

  • Always mark one version as storage
  • Include migration guides in descriptions
  • Document breaking changes between versions
  • Use semantic versioning (v1, v2, etc.)

Schema Design#

  • Mark required fields explicitly
  • Provide default values where applicable
  • Use enums for fixed value sets
  • Add validation rules (min, max, pattern)

Required status, default values and enum allowed values are all surfaced in the rendered schema, so the guidance above directly improves the generated documentation.

Example: Complete CRD Entity#

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: application-deployment-crd
  title: Application Deployment CRD
  description: |
    Custom resource for managing application deployments across clusters.
    Supports multi-region deployments, blue-green strategies, and automatic scaling.
  tags:
    - kubernetes
    - crd
    - deployment
    - platform
  annotations:
    backstage.io/techdocs-ref: dir:./docs
    backstage.io/source-location: url:https://github.com/org/platform-crds
spec:
  type: crd
  lifecycle: production
  owner: platform-team
  system: application-platform
  definition: |
    apiVersion: apiextensions.k8s.io/v1
    kind: CustomResourceDefinition
    metadata:
      name: applicationdeployments.platform.example.com
    spec:
      group: platform.example.com
      names:
        kind: ApplicationDeployment
        plural: applicationdeployments
        shortNames:
          - appd
      scope: Namespaced
      versions:
        - name: v1
          served: true
          storage: true
          schema:
            openAPIV3Schema:
              type: object
              required:
                - spec
              properties:
                spec:
                  type: object
                  required:
                    - image
                    - replicas
                  properties:
                    image:
                      type: string
                      description: Container image to deploy
                    replicas:
                      type: integer
                      description: Number of replicas
                      minimum: 1
                      maximum: 100
                      default: 3
                    regions:
                      type: array
                      description: Target deployment regions
                      items:
                        type: string
                        enum: [us-east-1, us-west-2, eu-west-1]
                    strategy:
                      type: object
                      description: Deployment strategy configuration
                      properties:
                        type:
                          type: string
                          enum: [rolling, bluegreen, canary]
                          default: rolling
                        canaryPercent:
                          type: integer
                          minimum: 0
                          maximum: 100

Next Steps#