Overview

To add entity definitions to Software Catalog, you can:

• manually create definitions through the Datadog UI.
• manage definitions in code and automate import through GitHub, Terraform, or the Datadog API.

Through the Datadog UI

Software Catalog provides a guided workflow for creating entity definitions. After you select an entity type from the Kind dropdown (Service, API, System, and others), the form presents metadata fields and options specific to that type. For example, selecting API surfaces fields for uploading an OpenAPI or gRPC specification, while selecting Service surfaces fields for defining the service type and lifecycle.

To create an entity definition:

1. Navigate to the Software Catalog Setup & Config page.

2. Click Create a New Entry.

3. Select the entity type from the Kind dropdown.

4. Fill in the metadata fields, such as ownership and reference links.

5. (Optional) Switch to YAML or JSON to see the generated code and cURL command. In the code editors, Datadog automatically flags invalid data.

6. Submit the metadata by clicking Save Entry or by running the provided cURL command.

   Note: You must have Software Catalog Write permission to save the entry.

Through automation

To automate import through GitHub, Terraform, the Datadog Software Metadata Provider, or the Datadog Service Definition API:

Create the entity definition

1. Create service.datadog.yaml or entity.datadog.yaml to define your entity (Datadog accepts both file names).

2. Name your entity in the dd-service (schema version v2.2 or prior) or name (schema version v3.0+) field.

   For example:

   service.datadog.yaml

   Copy

       schema-version: v2.2
       dd-service: my-unmonitored-cron-job
       team: e-commerce
       lifecycle: production
       application: shopping-app
       description: important cron job for shopist backend
       tier: "2"
       type: web
       contacts:
       - type: slack
       contact: https://datadogincidents.slack.com/archives/XXXXX
       links:
       - name: Common Operations
       type: runbook
       url: https://datadoghq.atlassian.net/wiki/
       - name: Disabling Deployments
       type: runbook
       url: https://datadoghq.atlassian.net/wiki/
       tags: []
       integrations:
       pagerduty:
       service-url: https://datadog.pagerduty.com/service-directory/XXXXXXX
       External Resources (Optional)
      

3. (Optional) Register multiple services in one YAML file by separating each definition with three dashes (---).

Import the definition

Import the definition in one of the following ways:

1. Terraform: Create and import the definition as a Terraform resource.

   Note: Creating and managing services in the Software Catalog through automated pipelines requires Datadog Provider v3.16.0 or later.

2. Datadog APIs: Import your definition using the Service Definition API (for schema v2.x) or the Software Catalog API (for schema v3+), which are both open-sourced GitHub Action solutions.

3. GitHub: Configure the Datadog GitHub integration to manage and import your definitions.

GitHub integration

Configure the GitHub integration to directly link from where you view the service’s definition in the Software Catalog to where it’s stored and editable in GitHub. Datadog scans for the service.datadog.yaml and entity.datadog.yaml files throughout 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 Software 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.

Integration validation

To validate your service definitions ingested by Datadog’s GitHub integration, you can view events when services are updated or when there is an error. To view validation errors in Event Management, filter by source:software_catalog and status:error. Adjust the timeframe as needed.

Further reading

Additional helpful documentation, links, and articles:

Create and manage service definitions with TerraformEXTERNAL SITE Learn about the GitHub IntegrationDOCUMENTATION Learn about the Service Definition APIAPI Learn about the Software Catalog APIAPI