DevOps 内部開発者プラットフォーム プレイブック 2026

# Backstage CLIで新規プロジェクトを作成
npx @backstage/create-app@latest --skip-install

# 生成されるディレクトリ構造
my-backstage/
├── app-config.yaml           # コア設定ファイル
├── app-config.production.yaml
├── packages/
│   ├── app/                  # フロントエンド（React）
│   └── backend/              # バックエンド（Node.js）
├── plugins/                  # カスタムプラグイン
├── catalog-info.yaml         # このプロジェクト自体のカタログ登録
└── package.json

# 依存関係のインストールと実行
cd my-backstage
yarn install
yarn dev
# http://localhost:3000 でアクセス

# app-config.yaml
app:
  title: 'MyOrg Developer Platform'
  baseUrl: http://localhost:3000

organization:
  name: 'MyOrg'

backend:
  baseUrl: http://localhost:7007
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}

# GitHub統合（サービスカタログ自動探索）
integrations:
  github:
    - host: github.com
      token: ${GITHUB_TOKEN}

# ソフトウェアカタログ設定
catalog:
  import:
    entityFilename: catalog-info.yaml
  rules:
    - allow: [Component, System, API, Resource, Location, Group, User]
  locations:
    # 組織のすべてのリポジトリからcatalog-info.yamlを自動探索
    - type: github-discovery
      target: https://github.com/my-org/*/blob/main/catalog-info.yaml
    # 手動登録
    - type: file
      target: ./catalog-entities/all-systems.yaml

# 認証（GitHub OAuth）
auth:
  environment: development
  providers:
    github:
      development:
        clientId: ${GITHUB_OAUTH_CLIENT_ID}
        clientSecret: ${GITHUB_OAUTH_CLIENT_SECRET}

# catalog-info.yaml
apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: order-service
  description: '注文処理マイクロサービス'
  annotations:
    github.com/project-slug: my-org/order-service
    backstage.io/techdocs-ref: dir:.
    datadoghq.com/dashboard-url: https://app.datadoghq.com/dashboard/abc-123
    pagerduty.com/service-id: PXXXXXX
    argocd/app-name: order-service-prod
  tags:
    - java
    - spring-boot
    - tier-1
  links:
    - url: https://order.internal.example.com
      title: 本番URL
    - url: https://grafana.internal.example.com/d/order-service
      title: Grafanaダッシュボード
spec:
  type: service
  lifecycle: production
  owner: team-commerce
  system: commerce-platform
  dependsOn:
    - component:payment-service
    - resource:orders-database
  providesApis:
    - order-api
  consumesApis:
    - payment-api
    - inventory-api
---
apiVersion: backstage.io/v1alpha1
kind: API
metadata:
  name: order-api
  description: '注文REST API'
spec:
  type: openapi
  lifecycle: production
  owner: team-commerce
  definition:
    $text: ./docs/openapi.yaml

# templates/spring-boot-service/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: spring-boot-service
  title: 'Spring Boot マイクロサービス'
  description: 'CI/CD、モニタリング、カタログが自動設定されたSpring Bootサービスを作成します'
  tags:
    - java
    - spring-boot
    - recommended
spec:
  owner: team-platform
  type: service
  parameters:
    - title: サービス情報
      required:
        - serviceName
        - ownerTeam
        - tier
      properties:
        serviceName:
          title: サービス名
          type: string
          pattern: '^[a-z][a-z0-9-]*$'
          description: '小文字、数字、ハイフンのみ許可'
        ownerTeam:
          title: オーナーチーム
          type: string
          ui:field: OwnerPicker
          ui:options:
            catalogFilter:
              kind: Group
        tier:
          title: サービスティア
          type: string
          enum: ['tier-1', 'tier-2', 'tier-3']
          enumNames: ['Tier 1 (99.99% SLO)', 'Tier 2 (99.9% SLO)', 'Tier 3 (99% SLO)']
        javaVersion:
          title: Javaバージョン
          type: string
          default: '21'
          enum: ['17', '21']

    - title: インフラ設定
      properties:
        database:
          title: データベース
          type: string
          default: 'postgresql'
          enum: ['postgresql', 'mysql', 'none']
        messageQueue:
          title: メッセージキュー
          type: string
          default: 'none'
          enum: ['kafka', 'rabbitmq', 'none']
        replicaCount:
          title: デフォルトレプリカ数
          type: integer
          default: 3
          minimum: 1
          maximum: 20

  steps:
    # 1. テンプレートからリポジトリを生成
    - id: fetch-template
      name: テンプレートコード生成
      action: fetch:template
      input:
        url: ./skeleton
        values:
          serviceName: ${{ parameters.serviceName }}
          ownerTeam: ${{ parameters.ownerTeam }}
          tier: ${{ parameters.tier }}
          javaVersion: ${{ parameters.javaVersion }}
          database: ${{ parameters.database }}
          replicaCount: ${{ parameters.replicaCount }}

    # 2. GitHubリポジトリを作成
    - id: publish
      name: GitHubリポジトリ作成
      action: publish:github
      input:
        allowedHosts: ['github.com']
        repoUrl: github.com?owner=my-org&repo=${{ parameters.serviceName }}
        defaultBranch: main
        repoVisibility: internal
        protectDefaultBranch: true
        requireCodeOwnerReviews: true

    # 3. ArgoCDアプリケーションを登録
    - id: register-argocd
      name: ArgoCDアプリケーション登録
      action: argocd:create-resources
      input:
        appName: ${{ parameters.serviceName }}-prod
        argoInstance: main
        namespace: ${{ parameters.serviceName }}
        repoUrl: https://github.com/my-org/${{ parameters.serviceName }}
        path: k8s/overlays/production

    # 4. Backstageカタログに登録
    - id: register-catalog
      name: カタログ登録
      action: catalog:register
      input:
        repoContentsUrl: ${{ steps['publish'].output.repoContentsUrl }}
        catalogInfoPath: /catalog-info.yaml

  output:
    links:
      - title: リポジトリ
        url: ${{ steps['publish'].output.remoteUrl }}
      - title: カタログ
        icon: catalog
        entityRef: ${{ steps['register-catalog'].output.entityRef }}

# mkdocs.yml（各サービスリポジトリのルート）
site_name: order-service
nav:
  - Home: index.md
  - Architecture: architecture.md
  - API Reference: api.md
  - Runbook: runbook.md
  - ADR:
      - adr/001-database-choice.md
      - adr/002-event-schema.md

plugins:
  - techdocs-core

<!-- docs/runbook.md -->

# Order Service 運用ランブック

## 障害対応

### 注文処理遅延（P95 > 500ms）

1. Grafanaダッシュボードを確認：[リンク]
2. DBコネクションプールの状態を確認：
   ```bash
   kubectl exec -it deploy/order-service -- curl localhost:8080/actuator/metrics/hikaricp.connections.active
   ```

## Play 7：セルフサービスインフラプロビジョニング

開発者がBackstage UIからデータベース、メッセージキュー、キャッシュなどを直接プロビジョニングできるようにする。実際のインフラ作成はTerraform + GitOpsで処理する。

```yaml
# templates/provision-postgresql/template.yaml
apiVersion: scaffolder.backstage.io/v1beta3
kind: Template
metadata:
  name: provision-postgresql
  title: 'PostgreSQLデータベースプロビジョニング'
  description: 'RDS PostgreSQLインスタンスをセルフサービスで作成します'
spec:
  owner: team-platform
  type: resource
  parameters:
    - title: データベース設定
      required:
        - dbName
        - environment
        - instanceClass
      properties:
        dbName:
          title: DB名
          type: string
          pattern: '^[a-z][a-z0-9_]*$'
        environment:
          title: 環境
          type: string
          enum: ['dev', 'staging', 'production']
        instanceClass:
          title: インスタンスサイズ
          type: string
          default: 'db.r7g.large'
          enum:
            - 'db.t4g.medium'
            - 'db.r7g.large'
            - 'db.r7g.xlarge'
            - 'db.r7g.2xlarge'
          enumNames:
            - 'Small (2 vCPU, 4GB) - dev/staging'
            - 'Medium (2 vCPU, 16GB) - production'
            - 'Large (4 vCPU, 32GB) - production'
            - 'XLarge (8 vCPU, 64GB) - high traffic'
        storageGb:
          title: ストレージ（GB）
          type: integer
          default: 100
          minimum: 20
          maximum: 16000
        multiAz:
          title: Multi-AZデプロイメント
          type: boolean
          default: false

  steps:
    - id: create-terraform-pr
      name: Terraform PR作成
      action: publish:github:pull-request
      input:
        repoUrl: github.com?owner=my-org&repo=infrastructure
        branchName: provision-db-${{ parameters.dbName }}
        title: 'DBプロビジョニング: ${{ parameters.dbName }} (${{ parameters.environment }})'
        description: |
          自動生成されたDBプロビジョニングリクエストです。

          - DB名: ${{ parameters.dbName }}
          - 環境: ${{ parameters.environment }}
          - インスタンス: ${{ parameters.instanceClass }}
          - ストレージ: ${{ parameters.storageGb }}GB
          - Multi-AZ: ${{ parameters.multiAz }}
        targetPath: terraform/rds/${{ parameters.environment }}/${{ parameters.dbName }}
        sourcePath: ./terraform-template

# platform_metrics.py - プラットフォームKPIダッシュボードデータ収集
import requests
from datetime import datetime, timedelta

class PlatformMetrics:
    def __init__(self, github_token: str, backstage_url: str):
        self.github = github_token
        self.backstage = backstage_url

    def service_creation_lead_time(self) -> dict:
        """新規サービス作成所要時間（目標：30分以内）"""
        # Backstage scaffolderログから抽出
        response = requests.get(
            f"{self.backstage}/api/scaffolder/v2/tasks",
            params={"createdAfter": (datetime.now() - timedelta(days=90)).isoformat()}
        )
        tasks = response.json()["items"]

        lead_times = []
        for task in tasks:
            if task["status"] == "completed":
                start = datetime.fromisoformat(task["createdAt"])
                end = datetime.fromisoformat(task["completedAt"])
                lead_times.append((end - start).total_seconds() / 60)

        return {
            "median_minutes": sorted(lead_times)[len(lead_times) // 2],
            "p95_minutes": sorted(lead_times)[int(len(lead_times) * 0.95)],
            "total_services_created": len(lead_times),
        }

    def golden_path_adoption_rate(self) -> dict:
        """ゴールデンパス採用率（目標：80%以上）"""
        # GitHub APIからreusable workflowの使用状況を照会
        repos = requests.get(
            "https://api.github.com/orgs/my-org/repos",
            headers={"Authorization": f"token {self.github}"},
            params={"per_page": 100, "type": "internal"}
        ).json()

        using_golden_path = 0
        total_active = 0

        for repo in repos:
            if repo["archived"]:
                continue
            total_active += 1
            # CIワークフローでゴールデンパスの参照を確認
            workflows = requests.get(
                f"https://api.github.com/repos/my-org/{repo['name']}/actions/workflows",
                headers={"Authorization": f"token {self.github}"}
            ).json()

            for wf in workflows.get("workflows", []):
                if "golden" in wf.get("path", "").lower():
                    using_golden_path += 1
                    break

        return {
            "adoption_rate": using_golden_path / max(total_active, 1),
            "using_golden_path": using_golden_path,
            "total_active_repos": total_active,
        }

    def developer_nps(self) -> dict:
        """開発者満足度NPS（目標：30以上）"""
        # 四半期サーベイ結果（Google Forms / Typeformなど）
        # API連携するか、手動入力
        return {
            "nps_score": 42,
            "promoters_pct": 55,
            "detractors_pct": 13,
            "response_rate": 0.72,
            "top_complaints": [
                "ビルド時間が遅い",
                "ログ検索UIが不便",
                "権限申請の自動化が不十分",
            ]
        }

WARN: Entity refresh for component:order-service took 45s (threshold: 10s)

# 解決策：スキャン範囲の制限 + キャッシュ設定
catalog:
  providers:
    github:
      myOrg:
        organization: 'my-org'
        catalogPath: '/catalog-info.yaml'
        filters:
          repository: '^(?!archived-).*$' # archived-プレフィックスのリポジトリを除外
          topic:
            include: ['backstage-enabled'] # トピックベースのフィルタリング
        schedule:
          frequency: { minutes: 30 } # 30分間隔（デフォルトは5分）
          timeout: { minutes: 5 }

Error: Resource not accessible by integration
HttpError: 403 - Resource not accessible by integration

# GitHub App権限の確認
# Settings > Developer settings > GitHub Apps > [アプリ名] > Permissions
# 必要な権限：
# - Repository: Administration (Read & Write)
# - Repository: Contents (Read & Write)
# - Organization: Members (Read)

# またはPersonal Access Token（PAT）使用時に必要なscope：
# repo, workflow, admin:org

mkdocs build failed: No module named 'techdocs_core'

# 解決策：TechDocsビルド環境にプラグインをインストール
pip install mkdocs-techdocs-core

# Dockerビルドを使用する場合
docker run --rm -v $(pwd):/content \
  spotify/techdocs:latest \
  build --site-dir /content/site

# app-config.yamlでビルド方式を設定
techdocs:
  builder: 'external'          # CIでビルド
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: 'my-org-techdocs'
      region: 'ap-northeast-2'