You can add metadata to existing Service Catalog entries through the Datadog UI, API, or use automated pipelines through the GitHub integration or Terraform.
Metadata structure and supported versions
Service Catalog uses service 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 and you can view warnings in the Definition tab on the side panel for any selected services.
There are three supported versions of the schema:
V2 is the earliest version, and contains some experimental features, such as dd-team, which are removed from v2.1.
V2.1 supports additional UI elements such as service groupings and fields like application, tier, and lifecycle. Application, along with Teams, can be used as grouping variables in Service Catalog. Lifecycle helps you differentiate between production, experimental, or deprecated services to indicate development stages and apply different reliability and availability requirements. Tier indicates the criticality of services, to prioritize during incident triage. For example, tier 1 typically represents the most critical services whose failure would result in severe customer impact, whereas tier 4 services typically have no impacts on actual customer experience.
V2.2 supports user annotation and overwriting auto-detected service type and languages using the fields type and languages. It also adds support for associating CI pipelines with a service using the field ci-pipeline-fingerprints. This version also includes less restrictive validation logic for contact.type and link.type, so users should expect fewer warnings while submitting YAML.
For more information about the latest updates, see the schemas on GitHub.
Service Definition Schema (v2.2)
The Service Definition Schema is a structure that contains basic information about a service. See the full schema on GitHub.
If your service is listed in Service Catalog and already has metadata associated with it, the original source is listed in the Metadata Source column on the Ownership view. Return to that source to make any updates you need to make.
If the service has not been assigned any service definition metadata, or if the service isn’t listed in the Service Catalog yet, you can add it:
On the Service Catalog page, click Setup & Config. The Manage Entries tabs shows you how many services are without metadata.
Click Create New Entry.
Specify which service you are adding metadata to. This can be the name of a service already listed in the Service Catalog that doesn’t have service definition metadata defined for it yet, or it can be the name of a service not sending any data.
Enter details for Team, On-call, Contacts, Documentation, Code repo, and Other links.
Switch to the Code view to see the JSON and cURL generated for the metadata you’ve entered. You can copy this code as a jumping off point for programmatically providing service definitions by API, Terraform, or GitHub, without having to learn the schema for service definitions.
If you have the Service Catalog Write permission, you can submit the metadata by clicking Save Entry, or by running the cURL command provided on the Code view.
Automation options for adding metadata
Store and edit service 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.
To install the GitHub integration, navigate to the integration tile and click Link GitHub Account in the Repo Configuration tab.
Service definition YAML files
Datadog scans for the service.datadog.yaml file at the root of each repository with read permissions. You can register multiple services in one YAML file by creating multiple YAML documents. Separate each document with three dashes (---).
Modify service definition
When the GitHub integration is set up for your service 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.
To prevent accidental overwriting, create and modify your service definition files with either the GitHub integration or the Service Definition API endpoints. Updating the same service using both the GitHub and the API may result in unintended overwriting.
Automate service definition updates with Terraform
The Service Catalog provides a service definition as a Terraform resource. Creating and managing services in the Service Catalog through automated pipelines requires Datadog Provider v3.16.0 or later.
This GitHub Action allows you to register your services with the Service Catalog using a GitHub Action, with full control over when this information is sent to Datadog, and implement other compliance checks unique to your organization.
Further reading
Additional helpful documentation, links, and articles: