定義およびサポートされるバージョン

メタデータ構造およびサポートされるバージョン

Software Catalog は、サービスに関する関連メタデータを保存・表示するために定義スキーマを使用します。これらのスキーマには、有効な値のみが受け入れられるように検証ルールが組み込まれています。選択したサービスの Software Catalog サイドパネルの Definition タブで、警告を確認できます。

Opt in to the Preview for the latest version of Software Catalog.

Request Access

サポートされるバージョン

Datadog は以下の 4 つの定義スキーマバージョンをサポートしています。

v3.0: 拡張されたデータモデル、マルチオーナーシップのサポート、依存関係の手動宣言、複雑なインフラ向けに強化された機能を備えた最新バージョン
v2.2: カスタムメタデータ用のユーザー注釈、およびサービスをビルドプロセスと関連付ける CI パイプラインサポートを提供
v2.1: サービスのグルーピングをサポートし、より包括的なサービス記述のための追加フィールドを導入
v2: 基本的なサービスメタデータとドキュメンテーション用の必要最低限のフィールドを提供する、最も初期のサポートバージョン

各バージョンは前のバージョンを拡張し、新機能を追加しながら後方互換性を維持しています。自分のニーズやインフラの複雑さに応じて、最適なバージョンを選択してください。

バージョン比較

以下は各バージョンでサポートされる機能一覧です。

機能	v3.0	v2.2	v2.1	v2.0
基本的なメタデータ
サービスグルーピング
ユーザー注釈
CI パイプライン関連付け
拡張データモデル
マルチオーナーシップ
手動での依存関係宣言

各バージョンごとの完全なスキーマや YAML ファイルの例など、詳細な情報についてはサポートされるバージョンの各バージョンページを参照してください。

Software Catalog にメタデータを追加する

Datadog UI からメタデータを追加する

Software Catalog ページで Setup & Config をクリックします。
Create New Entry をクリックします。
メタデータを追加するサービスを指定します。
Team、On-call、Contacts、Documentation、Code repo、Other links の詳細を入力します。
YAML または JSON に切り替えて、生成されたコードと cURL コマンドを確認します。
Software Catalog Write 権限がある場合、Save Entry をクリックするか、提供されている cURL コマンドを実行してメタデータを送信できます。

自動化によるメタデータ追加

GitHub に定義を保存・編集

GitHub integration を構成すると、Software Catalog 上で表示しているサービス定義から、保存・編集されている GitHub リポジトリへ直接リンクできます。Datadog は読み取り権限のある各リポジトリ内の service.datadog.yaml と entity.datadog.yaml をスキャンします。

GitHub インテグレーションをインストールするには

インテグレーションタイルに移動します。
Repo Configuration タブで Link GitHub Account をクリックします。

GitHub インテグレーションが定義に適用されると、サービスの Definition タブに Edit in GitHub ボタンが表示され、クリックすると GitHub 上で変更をコミットする画面へ移動します。

Software Catalog 内のサービスの Definition タブに表示される Edit in GitHub ボタン

リポジトリの YAML ファイルを更新すると、変更が Software Catalog に反映されます。1 つの YAML ファイルで複数のサービスを登録する場合は、複数の YAML ドキュメントを作成し、--- で区切ってください。

誤った上書きを防ぐため、定義ファイルを作成・変更する際は GitHub インテグレーションまたは Definition API エンドポイントのいずれか片方を使用してください。GitHub と API の両方で同一サービスを更新すると、意図しない上書きが発生する可能性があります。

Terraform による定義更新の自動化

Software Catalog の定義は Terraform resource として提供されます。自動化パイプライン経由で Software Catalog 上のサービスを作成・管理するには、Datadog Provider v3.16.0 以降が必要です。

オープンソースのメタデータプロバイダー

GitHub インテグレーションや Terraform の代替手段として、Datadog Software Catalog Metadata Provider というオープンソースの GitHub アクションを利用できます。

エンドポイントにメタデータを追加する

Datadog の UI または API から API にメタデータを追加できます。あるいは、GitHub インテグレーションや Terraform を用いた自動化パイプラインでも追加できます。

kind: api を設定し、owner フィールドを指定すると、メタデータスキーマ v3.0 を OpenAPI 定義と組み合わせられます。

apiVersion: v3
kind: api
metadata:
  name: API Name
  description: API Description 
  displayName: API Name
  owner: dd-team
spec:
  type: openapi
  interface:
    definition:
      info:
        title: API Name
      openapi: 3.0.2
      paths:
        /api/v2/customers/{id}:
          get:
            summary: get customer information
            operationId: getCustomerInfo
            tags:
              - public
              - important
            parameters:
              - in: path
                name: id
            responses:
              '200':
                description: Successful operation
                content:
                  application/vnd.api+json:
                    schema:
                      type: object
                      properties:
                        data:
                          type: array
                          description: Contains customer information
              '400':
                description: Invalid arguments
              '401':
                description: Unauthorized operation
              '500':
                description: Internal server error

カスタム拡張機能を構築する

カスタム拡張機能は Limited Availability です。

extensions フィールドは v2.0 を含むすべてのバージョンでサポートされています。このカスタムフィールドを導入プロセスに組み込み、ベストプラクティスを標準化・コード化することが可能です。

service.datadog.yaml

schema-version: v2.2
dd-service: web-store
team: shopist
...
extensions:
  shopist.com/release-scheduler:
    release-manager:
      slack: "release-train-shopist"
      schedule: "* * * * *"
      env:
        - name: "staging"
          ci_pipeline: "//domains/examples/apps/hello-joe/config/k8s:release-staging"
          branch: "hello-joe/staging"
          schedule: "* * * * 1"