catalog-info.yaml

About

Teaches AI agents how to write and configure catalog-info.yaml — the single source of truth for how the builder deploys your service. Covers all framework types (nextjs, express, hono, fastify, static, worker), their default build/start commands, annotation reference, spec fields for routes, databases, dependencies, and deploy-gated tests (0.5.0+).

Skill Content

This is the raw markdown that gets installed as a Claude Code rule.

# catalog-info.yaml Conventions

## What this skill covers
How to write and configure catalog-info.yaml — the single source of truth for how the builder deploys your service.

## Minimal Example

```yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: my-svc
  description: My API service
  annotations:
    insureco.io/framework: express
spec:
  type: service
  lifecycle: production
  owner: my-org
```

## Framework Types and Defaults

| Framework | Build Command | Start Command | Port | Health Endpoint |
|-----------|--------------|---------------|------|-----------------|
| `nextjs` | `npm run build` | `npm start` | 3000 | `/api/health` |
| `express` | `npm run build` | `node dist/index.js` | 3000 | `/health` |
| `hono` | `npm run build` | `node dist/index.js` | 3000 | `/health` |
| `fastify` | `npm run build` | `node dist/index.js` | 3000 | `/health` |
| `static` | (none) | nginx | 80 | `/health` |
| `worker` | `npm run build` | `node dist/worker.js` | 3000 | (none) |

## All Annotations

```yaml
metadata:
  annotations:
    insureco.io/framework: express       # REQUIRED: nextjs, express, hono, fastify, static, worker
    insureco.io/node-version: "20"       # Node.js version (default: 20)
    insureco.io/build-command: "npm run build"  # Override build command
    insureco.io/start-command: "npm start"      # Override start command
    insureco.io/output-dir: "dist"              # Build output directory
    insureco.io/port: "3000"                    # Container port
    insureco.io/health-endpoint: "/health"      # Health check path
    insureco.io/env-vars: "VAR1,VAR2"          # Build-time env vars to inject
    insureco.io/pod-tier: "nano"               # Pod size: nano, small, medium, large, xlarge
```

## Spec Fields

```yaml
spec:
  type: service
  lifecycle: production
  owner: my-org                    # Organization name (from your JWT)

  # API routes (registered in Koko gateway)
  routes:
    - path: /api/users
      methods: [GET, POST]
      auth: required

  # Databases (auto-provisioned)
  databases:
    - type: mongodb                # Creates MONGODB_URI env var
    - type: redis                  # Creates REDIS_URL env var
    - type: neo4j                  # Creates NEO4J_URI env var

  # Internal dependencies (auto-resolved to K8s DNS URLs)
  internalDependencies:
    - service: iec-wallet
      port: 3000                   # Creates IEC_WALLET_URL env var
    - service: koko
      port: 3000                   # Creates KOKO_URL env var

  # Deploy-gated tests (catalog version 0.5.0+)
  tests:
    smoke:
      - path: /health
        expect: 200
      - path: /api/ping
        expect: 200
```

## Deploy-Gated Tests (catalog version 0.5.0+)

Requires annotation: `insureco.io/catalog-version: "0.5.0"`

Tests run automatically after Helm deploy via iec-test. Failure blocks build completion but does NOT roll back the deployment.

### Smoke Tests

HTTP GET probes with expected status codes and exponential backoff retries:

```yaml
spec:
  tests:
    smoke:
      - path: /health        # Required: endpoint path
        expect: 200           # Required: expected HTTP status code
```

### Environment Behavior

| Environment | Suites Run |
|-------------|-----------|
| sandbox/uat | smoke + e2e |
| prod | smoke only |

## Key Rules
- `metadata.name` becomes your hostname — a service named `my-svc` deploys to `my-svc.tawa.insureco.io`
- `spec.owner` is set automatically when you scaffold with `tawa sample`
- Only `mongodb`, `redis`, and `neo4j` database types are supported
- The framework annotation determines Dockerfile generation, build commands, and health checks
- Pod tier defaults to `nano` if not specified
- You do NOT need a Dockerfile — the builder generates one based on your framework

## Common Mistakes
- Using `type: postgres` or `type: mysql` — only mongodb, redis, neo4j are supported
- Forgetting the framework annotation — build will fail
- Setting port to a string without quotes in YAML — use `"3000"` not `3000`
- Putting routes under metadata instead of spec

Install

Copy the skill content and save it to:

~/.claude/rules/catalog-info.md

Details

Format

Rule

Category

configure

Version

1.1.0

Tokens

~1,500

Updated

2026-02-24