Backstageの拡張: カスタムアノテーションの定義と予約語の衝突防止戦略

6月 29, 2026

—

こんにちは！本日は、Backstageの柔軟性を最大限に高めるアノテーション(Annotations)、特にその管理に不可欠なネームスペーシング(Namespacing)のルールについて深く掘り下げていきます。🚀

Backstageを運用していると、基本機能以外に組織独自の特別なデータを追加したい場面が多くあります。その際に使用するのがアノテーションです。しかし、安易な名前を使用するとシステム内部で衝突が発生する可能性があります。本日は、「絶対に使用してはならない予約済みのプレフィックス」と、正しいネームスペーシング戦略を完璧に解説します！💡

🏗️ Backstageアノテーションとは？

Backstageのcatalog-info.yamlファイルにおいて、metadata.annotationsセクションはエンティティに関する非構造化メタデータを保存する場所です。

プラグインはこれらのアノテーションを読み取り、特定の機能を有効にしたり、データを取得したりします。例えば、「このコンポーネントのGitHubリポジトリはどこか？」や「このサービスのArgoCDアプリケーション名は何であるか？」といった情報を含みます。🏷️

🚫 核心質問: コアコンポーネントのために予約されているプレフィックスは？

結論から申し上げますと、Backstageのコア機能と公式プラグインのために予約されているプレフィックスは、まさにbackstage.io/です。

なぜこのプレフィックスを避けるべきなのでしょうか？

システム衝突の防止: Backstageエンジンが内部的に使用するロジックと、皆さんのカスタム設定が衝突するのを防ぐためです。
将来の互換性: 現在は使用されていなくても、将来のBackstageアップデートでbackstage.io/new-featureという公式アノテーションが追加される可能性があります。その際に皆さんが同じ名前を使用していると、システムが混乱する可能性があります。絡まった糸を解くのは本当に大変です！🧶

🌟 正しいネームスペーシング戦略 (カスタムアノテーション)

組織内でカスタムアノテーションを定義する際には、以下のルールを推奨します。

1. 組織独自のプレフィックスを使用する 🏢

最も良い方法は、会社のドメインをプレフィックスとして使用することです。

悪い例: my-custom-plugin: value (ネームスペースなし)
良い例: acme.com/project-id: “PRJ-123”

2. サブドメインを活用する 📂

特定のチームや特定のツール向けであれば、さらに細分化してください。

engineering.acme.com/cost-center: “DEPT-404”
security.acme.com/scan-id: “SCAN-99”

🛠️ 実践例: catalog-info.yamlの構成

実際にどのように適用されるか、コードで確認してみましょう。

YAML

apiVersion: backstage.io/v1alpha1
kind: Component
metadata:
  name: billing-service
  annotations:
    # ✅ 公式/コアアノテーション (backstage.ioプレフィックスを使用)
    backstage.io/managed-by-location: url:https://github.com/...
    backstage.io/techdocs-ref: dir:.

    # ✅ 外部公式プラグインアノテーション (各サービスドメインを使用)
    github.com/project-slug: backstage/backstage
    argocd.io/app-name: billing-app

    # ✅ 私たちの組織独自のカスタムアノテーション (私たちのドメインを使用)
    company.com/team-slack-channel: "#team-billing"
    company.com/on-call-rotation: "https://pagerduty.com/..."
spec:
  type: service
  owner: billing-team
  lifecycle: production

上記の例のように、backstage.io/はシステムが管理する領域に譲り、私たち自身の領域を構築することが保守性の鍵となります。🛠️

🧐 よくある質問 (FAQ)

Q: プレフィックスなしでアノテーションを使用するとどうなりますか？

A: 当面は動作するかもしれませんが、規模が大きくなるにつれて、どのプラグインがどの値を使用しているかを追跡するのが難しくなります。後で同じ名前の別のデータが入力されると、上書きエラーが発生する可能性があります。😱

Q: backstage.io/以外に注意すべきプレフィックスはありますか？

A: 広く使われているオープンソースプラグインのプレフィックス（例: github.com/, jenkins.io/, sentry.io/）も、そのツールを使用していなくても避けるのが慣例です。

🏁 結論: クリーンなネームスペーシングが健全なカタログを構築します！

Backstageのソフトウェアカタログは、組織のすべての遺産を収める宝物庫のようなものです。backstage.io/という聖域を尊重しつつ、私たち独自の体系的なネームスペースを構築すれば、数千のサービスを管理する場合でも混乱のない完璧なプラットフォームを運用できるでしょう。🚀