Metadata structure and supported versions

Service Catalog uses definition schemas to store and display relevant metadata about your services. The schemas have built-in validation rules to ensure that only valid values are accepted. You can view warnings in the Definition tab on the Service Catalog side panel for any selected services.

Supported versions

Datadog supports four versions of the definition schema:

• v3.0 (in Preview): Latest version with expanded data model, multi-ownership support, manual dependency declaration, and enhanced features for complex infrastructure.
• v2.2: Supports user annotations for custom metadata and CI pipeline associations to link services with their build processes.
• v2.1: Supports service groupings for improved organization and introduces additional fields for more comprehensive service descriptions.
• v2: Earliest supported version, providing essential fields for basic service metadata and documentation.

Each version builds upon the previous one, adding new functionality while maintaining backwards compatibility. Choose the version that best suits your needs and infrastructure complexity.

Version comparison

The following features are supported in each version:

For detailed information about each version, including full schemas and example YAML files, see the individual version pages in Supported versions.

Add metadata to Service Catalog

Add metadata from the Datadog UI

1. On the Service Catalog page, click Setup & Config.
2. Click Create New Entry.
3. Specify the service you are adding metadata to.
4. Enter details for Team, On-call, Contacts, Documentation, Code repo, and Other links.
5. Switch to YAML or JSON to see the generated code and cURL command.
6. If you have the Service Catalog Write permission, you can submit the metadata by clicking Save Entry or by running the provided cURL command.

Add metadata with automation

Store and edit definitions in GitHub

Configure the GitHub integration to directly link from where you view the service’s definition in the Service Catalog to where it’s stored and editable in GitHub. Datadog scans for the service.datadog.yaml file at the root of each repository with read permissions.

To install the GitHub integration:

1. Navigate to the integration tile.
2. Click Link GitHub Account in the Repo Configuration tab.

When the GitHub integration is set up for your definitions, an Edit in GitHub button appears in the service’s Definition tab and links you to GitHub to commit changes.

After you update the YAML files for your repositories, your changes propagate to the Service Catalog. You can register multiple services in one YAML file by creating multiple YAML documents. Separate each document with three dashes (---).

To prevent accidental overwriting, create and modify your definition files with either the GitHub integration or the Definition API endpoints. Updating the same service using both the GitHub and the API may result in unintended overwriting.

Automate definition updates with Terraform

The Service Catalog provides a definition as a Terraform resource. Creating and managing services in the Service Catalog through automated pipelines requires Datadog Provider v3.16.0 or later.

Open-source metadata provider

As an alternative to the GitHub integration and Terraform, you can use an open-sourced GitHub Action solution named Datadog Service Catalog Metadata Provider.

Build custom extensions

The extensions field is supported in all versions including v2.0. You can incorporate this custom field into deployment processes to standardize and codify best practices.

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"

IDE Plugins

Datadog provides a JSON Schema for definitions so that when you are editing a definition in a supporting IDE, features such as autocomplete and validation are provided.

The JSON schema for Datadog definitions is registered with the open source Schema Store.

Further reading

Documentation, liens et articles supplémentaires utiles:

Create and manage definitions with TerraformEXTERNAL SITE Learn about the Definition APIAPI Learn about the GitHub IntegrationDOCUMENTATION Import Backstage YAML files into DatadogBLOG