BackstageでIDPを構築する 1 — ソフトウェアカタログがすべて

+---------------------------------------------------------------+
|                Backstage (ポータルフレームワーク)                  |
|                                                               |
|  +----------------+  +----------------+  +-----------------+  |
|  |   Software     |  |   Scaffolder   |  |    TechDocs     |  |
|  |   Catalog      |  | (ゴールデンパス)  |  |  (docs-as-code) |  |
|  |  (本記事の主題)   |  |    [第2回]      |  |     [第3回]     |  |
|  +-------+--------+  +-------+--------+  +--------+--------+  |
|          |                   |                    |           |
|  +-------v-------------------v--------------------v--------+  |
|  |        プラグインエコシステム (K8s, ArgoCD, ...)             |  |
|  +----------------------------------------------------------+  |
+---------------------------------------------------------------+

                      +------------------+
                      |     Domain       |   例: payments-domain
                      |  (ビジネス領域)    |
                      +--------^---------+
                               | partOf
                      +--------+---------+
                      |     System       |   例: payment-system
                      +--------^---------+
                               | partOf
          +--------------------+--------------------+
          |                    |                    |
  +-------+--------+   +------+---------+   +------+--------+
  |   Component    |   |   Component    |   |   Component   |
  |  payment-api   |   | payment-worker |   |  payment-web  |
  +---+-------+----+   +-------+--------+   +---------------+
      |       |                |
      |       | providesApi    | consumesApi
      |       v                v
      |    +--+----------------+--+
      |    |         API          |   例: payment-v1 (OpenAPI)
      |    +----------------------+
      | dependsOn
      v
  +---+------------+        +-----------------+
  |   Resource     |        |     Group       |
  |  payment-db    |        | team-payments   |
  +----------------+        +--------^--------+
                                     | ownedBy (すべてのエンティティから)

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: payment-api
  title: Payment API Server
  description: 決済承認/キャンセルを処理する中核バックエンドサービス
  annotations:
    github.com/project-slug: acme-corp/payment-api
    backstage.io/techdocs-ref: dir:.
    backstage.io/kubernetes-id: payment-api
    pagerduty.com/integration-key: PD-INTEGRATION-KEY
    sonarqube.org/project-key: acme_payment-api
  tags:
    - java
    - spring-boot
    - payments
  links:
    - url: https://grafana.acme.io/d/payment-api
      title: Grafana Dashboard
      icon: dashboard
spec:
  type: service
  lifecycle: production
  owner: group:default/team-payments
  system: payment-system
  providesApis:
    - payment-v1
  dependsOn:
    - resource:payment-db
    - resource:payment-events-topic

apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: payment-v1
  title: Payment API v1
  description: 決済承認、キャンセル、照会のREST API
spec:
  type: openapi
  lifecycle: production
  owner: group:default/team-payments
  system: payment-system
  definition:
    $text: ./openapi/payment-v1.yaml

apiVersion: backstage.io/v1alpha1
kind: Resource
metadata:
  name: payment-db
  description: 決済元帳PostgreSQL (AWS RDS)
  annotations:
    amazonaws.com/arn: arn:aws:rds:ap-northeast-2:111122223333:db:payment-db
spec:
  type: database
  owner: group:default/team-payments
  system: payment-system
---
apiVersion: backstage.io/v1alpha1
kind: System
metadata:
  name: payment-system
  description: 決済承認から精算までを担当するシステム
spec:
  owner: group:default/team-payments
  domain: commerce
---
apiVersion: backstage.io/v1alpha1
kind: Domain
metadata:
  name: commerce
  description: コマースビジネスドメイン
spec:
  owner: group:default/commerce-tribe

  GitHub Org          LDAP/AD           静的locations
      |                  |                    |
      v                  v                    v
+-----+------------------+--------------------+-----+
|            Entity Providers (注入レイヤ)            |
+--------------------------+-------------------------+
                           v
+--------------------------+-------------------------+
| 処理ループ: 検証 -> 変換 -> リレーション生成 -> 保存      |
| (Processorが各段階で介入)                            |
+--------------------------+-------------------------+
                           v
                 +---------+---------+
                 |  PostgreSQL (DB)  |
                 +---------+---------+
                           v
                 +---------+---------+
                 |  Catalog REST API |
                 +-------------------+

# app-config.yaml
catalog:
  providers:
    github:
      acmeProvider:
        organization: 'acme-corp'
        catalogPath: '/catalog-info.yaml'
        filters:
          branch: 'main'
          repository: '.*'        # 正規表現で対象リポジトリをフィルタ
          topic:
            include: ['backstage-managed']
        schedule:
          frequency: { minutes: 30 }
          timeout: { minutes: 3 }

// packages/backend/src/index.ts
backend.add(import('@backstage/plugin-catalog-backend-module-github/alpha'));

catalog:
  providers:
    githubOrg:
      - id: acme-github-org
        githubUrl: https://github.com
        orgs: ['acme-corp']
        schedule:
          frequency: { hours: 1 }
          timeout: { minutes: 15 }

apiVersion: backstage.io/v1alpha1
kind: Group
metadata:
  name: team-payments
  description: 決済プラットフォームチーム
spec:
  type: team
  profile:
    displayName: Payments Team
    email: team-payments@acme.io
  parent: commerce-tribe
  children: []
---
apiVersion: backstage.io/v1alpha1
kind: User
metadata:
  name: youngju.kim
spec:
  profile:
    displayName: Youngju Kim
    email: youngju.kim@acme.io
  memberOf:
    - team-payments

# .github/workflows/catalog-lint.yaml
name: catalog-lint
on:
  pull_request:
    paths:
      - 'catalog-info.yaml'
jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - name: Validate catalog entity
        run: npx @roadiehq/backstage-entity-validator validate catalog-info.yaml

// 組織ポリシー検証プロセッサの骨格
import { CatalogProcessor } from '@backstage/plugin-catalog-node';
import { Entity } from '@backstage/catalog-model';

export class RequiredAnnotationsProcessor implements CatalogProcessor {
  getProcessorName(): string {
    return 'RequiredAnnotationsProcessor';
  }

  async validateEntityKind(entity: Entity): Promise<boolean> {
    if (entity.kind === 'Component' && entity.spec?.lifecycle === 'production') {
      const annotations = entity.metadata.annotations ?? {};
      if (!annotations['pagerduty.com/integration-key']) {
        throw new Error(
          `production component ${entity.metadata.name} requires pagerduty annotation`,
        );
      }
    }
    return false; // 他のプロセッサが処理を継続できるように
  }
}

# app-config.production.yaml
app:
  baseUrl: https://backstage.acme.io

backend:
  baseUrl: https://backstage.acme.io
  listen:
    port: 7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      ssl:
        rejectUnauthorized: true
  cache:
    store: memory

integrations:
  github:
    - host: github.com
      apps:
        - $include: github-app-credentials.yaml

catalog:
  rules:
    - allow: [Component, API, Resource, System, Domain, Group, User, Location]

apiVersion: apps/v1
kind: Deployment
metadata:
  name: backstage
  namespace: backstage
spec:
  replicas: 2
  selector:
    matchLabels:
      app: backstage
  template:
    metadata:
      labels:
        app: backstage
    spec:
      containers:
        - name: backstage
          image: ghcr.io/acme-corp/backstage:1.0.3
          ports:
            - containerPort: 7007
          envFrom:
            - secretRef:
                name: backstage-secrets
          readinessProbe:
            httpGet:
              path: /healthcheck
              port: 7007
          resources:
            requests:
              cpu: 500m
              memory: 1Gi
            limits:
              memory: 2Gi
---
apiVersion: v1
kind: Service
metadata:
  name: backstage
  namespace: backstage
spec:
  selector:
    app: backstage
  ports:
    - port: 80
      targetPort: 7007

auth:
  environment: production
  providers:
    github:
      production:
        clientId: ${AUTH_GITHUB_CLIENT_ID}
        clientSecret: ${AUTH_GITHUB_CLIENT_SECRET}
        signIn:
          resolvers:
            - resolver: usernameMatchingUserEntityName

auth:
  environment: production
  providers:
    oidc:
      production:
        metadataUrl: https://keycloak.acme.io/realms/acme/.well-known/openid-configuration
        clientId: ${AUTH_OIDC_CLIENT_ID}
        clientSecret: ${AUTH_OIDC_CLIENT_SECRET}
        prompt: auto
        signIn:
          resolvers:
            - resolver: emailMatchingUserEntityProfileEmail

backend.add(import('@backstage/plugin-auth-backend'));
backend.add(import('@backstage/plugin-auth-backend-module-github-provider'));
// または OIDC モジュール
backend.add(import('@backstage/plugin-auth-backend-module-oidc-provider'));