セルフホストノード YAML 設定説明¶

本稿では、ユーザーが手動でセルフホストノードを作成する際に、YAML をどのように記述すべきかを説明します。

これは特定のエンティティタイプの固定テンプレートではなく、共通の記述ルールです。文中の Host 部分はあくまで例であり、「フィールドの記述方法」を理解するためのもので、すべてのエンティティが Host 関連フィールドを含む必要があることを示すものではありません。

設定の原則¶

手動でエンティティ YAML を作成する際は、以下のように構成することを推奨します。

1. attributes をエンティティ属性の主体として使用する
2. 最初に共通管理フィールドを記入し、その後にエンティティ固有フィールドを補足する
3. name には安定した識別子を使用し、頻繁に変更される表示名を直接使用しない
4. owner にはデフォルトで責任チームを記入する。個人の連絡先は contact に配置し、1 つのフィールドにチームと個人の両方の意味を持たせないようにする
5. component_of と depends_on は、統一して entity_type:entity_name の形式で他のエンティティを参照する

最小限の実装例¶

まず最も基本的なエンティティ情報を 1 件だけ登録したい場合は、最低限以下の内容を記入することを推奨します。

attributes:
  name: payment-worker-01
  display_name: 決済ワーカーノード 01
  project: payment
  owner: sre-platform

完全な例¶

以下は完全な例です。Host を例として、共通フィールドとエンティティ固有フィールドをどのように組み合わせるかを示します。

attributes:
  name: prod-host-01
  host: prod-host-01
  project: payment
  display_name: ホスト 01
  description: 決済中核サービスの本番環境ホスト。決済と照合タスクを実行します。

  host_ip: 10.20.30.40
  os: linux
  lifecycle: active
  env: prod

  cloud_provider: aliyun
  instance_id: i-bp1example
  region: cn-hangzhou
  zone: cn-hangzhou-h

  owner: sre-platform

  component_of:
    - system:payment-cluster
    - system:payment-platform
  depends_on:
    - service:config-center
    - database:mysql-payment-prod

  custom_tags:
    - category:settlement
    - critical

  contact:
    - type: email
      name: オンコールメール
      value: sre@example.com
    - type: slack
      name: アラートチャンネル
      value: https://company.slack.com/archives/C12345678
    - type: phone
      name: オンコール電話
      value: 123456789

  link:
    - type: view
      name: ホスト監視ダッシュボード
      dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
    - type: doc
      name: 障害対応マニュアル
      provider: wiki
      link: https://wiki.example.com/host-runbook
    - type: repo
      name: リポジトリ
      provider: github
      link: https://github.com/example/payment-host

フィールドの分類¶

YAML のフィールドは、次の 2 つに分類して理解できます。

1. 共通フィールド¶

これらのフィールドは、管理、検索、帰属、コラボレーションに使用され、ほとんどのエンティティタイプでサポートが推奨されます。

2. エンティティ固有フィールド¶

これらのフィールドは、特定のエンティティタイプによって決定され、エンティティごとに異なります。

例えば、Host には以下のようなフィールドが含まれる可能性があります。

• host
• host_ip
• os
• cloud_provider
• instance_id
• region
• zone
• lifecycle

その他のセルフホストノードでも、独自の固有フィールドを定義できます。例：

• system_type
• business_owner
• tier
• app_id
• language

YAML を作成する際は、すべてのエンティティのフィールドを記述する必要はなく、以下のみを記入すれば十分です。

• 共通フィールドのうち、管理および表示が必要な部分
• 現在のエンティティタイプで実際に使用する固有フィールド

共通フィールドの説明¶

name¶

name はエンティティの安定した識別子です。以下の原則を満たすことを推奨します。

• 日本語、スペース、および頻繁に変更される名前はできるだけ使用しない
• 表示名をそのまま name として使用しない
• エンティティが他のオブジェクトから参照されている場合、頻繁に変更しない

推奨される記述：

name: payment-worker-01

display_name¶

display_name はユーザーに表示される名前であり、より自然で読みやすいものにします。

display_name: 決済ワーカーノード 01

description¶

1 ～ 2 文で、エンティティの役割、用途、またはコンテキストを説明します。

description: 決済照合タスクを実行する本番ノード

project¶

エンティティをプロジェクト、ビジネスドメイン、またはプロダクトラインに分類するために使用します。

project: payment

env¶

エンティティが存在する環境を識別するために使用します。チーム内で統一された用語を使用し、prod と production のような同義語が混在しないようにすることを推奨します。

env: prod

owner¶

owner には、デフォルトで責任チームを記入することを推奨します。例：

owner: sre-platform

owner を「チーム」と「個人責任者」の両方の意味で使用することは推奨しません。推奨されるルールは以下の通りです。

• owner にはチームを記入する
• 個人の連絡先は contact に配置する

component_of¶

「現在のエンティティが何に属するか」を示し、帰属関係の記述によく使用されます。

統一された記述方法：

component_of:
  - system:payment-platform
  - cluster:payment-cluster

フォーマットは次のように統一します。

entity_type:entity_name

例：

• system:payment-platform
• service:order-service
• database:mysql-payment-prod

depends_on¶

「現在のエンティティが何に依存するか」を示し、呼び出し、依存、またはリソース使用関係の記述によく使用されます。

depends_on:
  - service:config-center
  - database:mysql-payment-prod

直接の依存関係のみを記入し、依存チェーン全体を展開することは推奨しません。

custom_tags¶

分類情報を補足するために使用します。シンプルなタグと、名前空間を持つタグの両方をサポートします。

custom_tags:
  - critical
  - category:settlement
  - team:sre

推奨事項：

• タグは短く、安定したものにする
• 同じ意味のタグは、1 つの記述方法に統一する
• チームですでにタグのルールがある場合は、既存の命名を優先して再利用する

contact¶

contact はオブジェクトの配列で、各項目が 1 つの連絡先です。

例：

contact:
  - type: email
    name: オンコールメール
    value: sre@example.com
  - type: phone
    name: オンコール電話
    value: 13800000000
  - type: slack
    name: アラートチャンネル
    value: https://company.slack.com/archives/C12345678

link¶

link は、エンティティに関連するリンク情報（ダッシュボード、ドキュメント、リポジトリなど）を添付するために使用します。

一般的な記述方法は以下の通りです。

link:
  - type: view
    name: ホスト監視ダッシュボード
    dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
  - type: doc
    name: 障害対応マニュアル
    provider: wiki
    link: https://wiki.example.com/host-runbook
  - type: repo
    name: リポジトリ
    provider: github
    link: https://github.com/example/payment-host

一般的なフィールドの意味：

エンティティ固有フィールドの追加方法¶

特定のエンティティを作成する際に、共通フィールドに加えて、そのエンティティ独自の属性を追加できます。

例：Host を作成する場合

attributes:
  name: prod-host-01
  host: prod-host-01
  host_ip: 10.20.30.40
  os: linux
  cloud_provider: aliyun

例：カスタムビジネスシステムを作成する場合

attributes:
  name: payment-platform
  display_name: 決済プラットフォーム
  system_type: business
  tier: core
  owner: payment-tech

あるフィールドが「エンティティ固有フィールド」であるかどうかを判断する基準は以下の通りです。

• 主に管理、帰属、検索、連絡に使用される場合は、通常は共通フィールド
• 特定のエンティティタイプにのみビジネス上の意味がある場合は、通常はエンティティ固有フィールド

よくある誤り¶

1. owner に個人名を記入する¶

owner は責任チームを定義するものです。個人の連絡先は contact に記載する方が安定しています。

2. 表示名を name として使用する¶

display_name は柔軟に変更できますが、name はできるだけ安定させる必要があります。そうしないと、参照関係や検索に影響を与える可能性があります。

3. 複数の連絡先を 1 つの value に詰め込む¶

連絡先は、表示、通知、および後続の処理のために、1 つずつ分けて記述することを推奨します。

4. すべてのフィールドをテンプレートからそのままコピーする¶

このドキュメントの目的は、「フィールドの構成方法」を理解していただくことであり、例のフィールドをすべてそのままコピーすることを求めるものではありません。実際に記入する際は、現在のエンティティに本当に必要なフィールドのみを保持してください。