【Backstage】Kubernetesへのデプロイガイド (PostgreSQL + MinIO構成)

こんにちは。
今回は、開発者ポータルとしてデファクトスタンダードになりつつあるOSS Backstageを、
Kubernetes (K8s) 環境に本番運用を見据えた構成でPostgreSQLや、TechDocs（ドキュメント管理）用の オブジェクトストレージ (MinIO) を組み合わせた構成の手順書が意外と少なかったので、備忘録として残しておきます。

今回の構成ゴール

• アプリ: Backstage (Backend)
• デプロイ先: Kubernetes クラスター
• DB: 既存の PostgreSQL (K8s内外問わずアクセス可能であること)
• Storage: 既存の MinIO (TechDocsのファイル保存先)
• デプロイツール: Helm Chart (公式)

SQLiteやローカルファイルシステムを使わず、ステートレスなコンテナとしてデプロイします。

---

1. Backstageアプリ側の準備

まずはローカルのBackstageプロジェクトで、PostgresとS3(MinIO)に対応するための準備をします。

1.1. アプリケーションの作成

まだ作成していない場合、以下のコマンドでプロジェクトを作成します。

npx @backstage/create-app@latest
cd my-backstage-app

1.2 pgクライアントの追加

デフォルトはSQLiteになっているため、PostgreSQLのドライバーを追加します。

# packages/backend ディレクトリで実行
cd packages/backend
yarn add pg

1.3 本番用設定ファイルの編集

app-config.production.yaml を作成（または編集）します。
ポイントは、機密情報を直接書かずに環境変数で受け取るようにすることと、MinIO特有の設定を入れることです。

app-config.production.yaml

app:
  # 本番環境のURL
  baseUrl: https://backstage.example.com

backend:
  baseUrl: https://backstage.example.com
  listen:
    port: 7007
  
  # PostgreSQL設定
  database:
    client: pg
    connection:
      host: ${POSTGRES_HOST}
      port: ${POSTGRES_PORT}
      user: ${POSTGRES_USER}
      password: ${POSTGRES_PASSWORD}
      # SSLが必要な場合は以下をコメントアウト解除
      # ssl: { rejectUnauthorized: false }

# TechDocs設定 (MinIO)
techdocs:
  builder: 'local' # ※本来はexternal推奨ですが、今回は簡易化のためlocal
  generator:
    runIn: 'local'
  publisher:
    type: 'awsS3'
    awsS3:
      bucketName: ${MINIO_BUCKET_NAME}
      endpoint: ${MINIO_ENDPOINT} # 例: http://minio.svc:9000
      s3ForcePathStyle: true # ★MinIOの場合はこれ必須！
      credentials:
        accessKeyId: ${MINIO_ACCESS_KEY}
        secretAccessKey: ${MINIO_SECRET_KEY}

Note: s3ForcePathStyle: true を忘れると、MinIOへの接続時にDNS解決エラー（バケット名がサブドメインとして解釈されるため）が発生します。

2. Dockerイメージのビルド

packages/backend にある Dockerfile を使ってイメージをビルドし、コンテナレジストリへPushします。

# packages/backend で実行。
yarn build:backend

# packages/backend で実行。
docker build ../.. -f ./Dockerfile --tag my-registry/backstage:latest

# Push
docker push my-registry/backstage:latest

Note: マルチプラットフォーム向けのビルド

docker buildx build \
  --platform linux/amd64,linux/arm64 \
  -t my-registry/backstage:latest \
  --no-cache \
  --push \
-f ./Dockerfile ../..

3. Kubernetesへのデプロイ (Helm)

公式のHelm Chartを使用します。これが一番管理しやすいです。

3.1 リポジトリの追加

helm repo add backstage https://backstage.github.io/charts
helm repo update

3.2 values.yaml の作成（重要）

values-custom.yaml という名前でファイルを作成し、以下の設定を記述します。
ここで 「Chart内蔵のPostgresを使わない設定」 と 「環境変数の注入」 を行います。

values-custom.yaml

# 自作したイメージを指定
image:
  repository: my-registry/backstage
  tag: latest
  pullPolicy: Always

# Chart内蔵のPostgreSQLを無効化 (外部DBを使うため)
postgresql:
  enabled: false

# DBやMinIOへの接続情報を環境変数として注入
# 値はK8sのSecretから読み込むのがセキュアです
extraEnv:
  - name: POSTGRES_HOST
    value: "postgres.database.svc.cluster.local" # 環境に合わせて変更
  - name: POSTGRES_PORT
    value: "5432"
  - name: POSTGRES_USER
    value: "backstage_user"
  - name: POSTGRES_PASSWORD
    valueFrom:
      secretKeyRef:
        name: backstage-secrets
        key: db-password
  - name: MINIO_ENDPOINT
    value: "http://minio.storage.svc.cluster.local:9000"
  - name: MINIO_BUCKET_NAME
    value: "techdocs"
  - name: MINIO_ACCESS_KEY
    valueFrom:
      secretKeyRef:
        name: backstage-secrets
        key: minio-access-key
  - name: MINIO_SECRET_KEY
    valueFrom:
      secretKeyRef:
        name: backstage-secrets
        key: minio-secret-key

# app-configの設定をHelm側から上書き/マージ
# ここに書いた内容はBackstage起動時にマージされます
appConfig:
  app:
    baseUrl: https://backstage.example.com
  backend:
    baseUrl: https://backstage.example.com
    database:
      client: pg
      connection:
        host: ${POSTGRES_HOST}
        port: ${POSTGRES_PORT}
        user: ${POSTGRES_USER}
        password: ${POSTGRES_PASSWORD}
  techdocs:
    publisher:
      type: 'awsS3'
      awsS3:
        bucketName: ${MINIO_BUCKET_NAME}
        endpoint: ${MINIO_ENDPOINT}
        s3ForcePathStyle: true
        credentials:
          accessKeyId: ${MINIO_ACCESS_KEY}
          secretAccessKey: ${MINIO_SECRET_KEY}

3.3 Secretの作成とデプロイ実行

パスワード類をSecretとして登録してから、Helm installを実行します。

# Namespace作成
kubectl create namespace backstage

# Secret作成
kubectl create secret generic backstage-secrets \
  --from-literal=db-password='YOUR_DB_PASSWORD' \
  --from-literal=minio-access-key='YOUR_MINIO_ACCESS' \
  --from-literal=minio-secret-key='YOUR_MINIO_SECRET' \
  -n backstage

# デプロイ
helm install backstage backstage/backstage \
  -f values-custom.yaml \
  -n backstage

4. 動作確認とトラブルシューティング

デプロイ後、Podが立ち上がらない場合の主なチェックポイントです。

1. DB接続エラー:

• kubectl logs -f deployment/backstage -n backstage でログを確認
• PostgreSQLのPod側で、Backstageからのアクセスが許可されているか（pg_hba.confなど）を確認してください

1. TechDocsが表示されない:

• MinIOのバケット（例: techdocs）は事前に作成してありますか？ Backstageは自動でバケットを作成しません
• s3ForcePathStyle: true が設定されているか再確認してください