---
title: Create Entities
description: Datadog, the leading service for cloud-scale monitoring.
breadcrumbs: >-
  Docs > Internal Developer Portal > Software Catalog > Set Up Software Catalog
  > Create Entities
---

# Create Entities

{% callout %}
# Important note for users on the following Datadog sites: app.ddog-gov.com

{% alert level="danger" %}
This product is not supported for your selected [Datadog site](https://docs.datadoghq.com/getting_started/site). ().
{% /alert %}

{% /callout %}

## Overview{% #overview %}

To add [entity definitions](https://docs.datadoghq.com/internal_developer_portal/software_catalog/entity_model) 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{% #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](https://app.datadoghq.com/software/settings/get-started) page.

1. Click **Create a New Entry**.

1. Select the entity type from the **Kind** dropdown.

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

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

   {% image
      source="https://datadog-docs.imgix.net/images/tracing/software_catalog/software_catalog_definition_editor.cea0f246a56eb7f7384f9b6224d5ca1e.png?auto=format"
      alt="Service metadata editor showing sample service definition." /%}

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

**Note**: You must have [Software Catalog Write permission](https://docs.datadoghq.com/internal_developer_portal/software_catalog/set_up#role-based-access-and-permissions) to save the entry.

## Through automation{% #through-automation %}

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

### Create the entity definition{% #create-the-entity-definition %}

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

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

For example:

In the `service.datadog.yaml` file:

   ```yaml
       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)
      
```

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

### Import the definition{% #import-the-definition %}

Import the definition in one of the following ways:

1. **Terraform**: Create and import the definition as a [Terraform resource](https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/service_definition_yaml).

**Note**: Creating and managing services in the Software Catalog through automated pipelines requires [Datadog Provider](https://registry.terraform.io/providers/DataDog/datadog/latest) v3.16.0 or later.

1. **Datadog APIs**: Import your definition using the [Service Definition API](https://docs.datadoghq.com/api/latest/service-definition/) (for schema v2.x) or the [Software Catalog API](https://docs.datadoghq.com/api/latest/software-catalog/) (for schema v3+), which are both open-sourced GitHub Action solutions.

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

#### GitHub integration{% #github-integration %}

Configure the [GitHub integration](https://docs.datadoghq.com/integrations/github/) 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](https://app.datadoghq.com/integrations/github).
1. 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.

{% image
   source="https://datadog-docs.imgix.net/images/tracing/software_catalog/svc_cat_contextual_link.fd29df874b31d977410b93e79d950493.png?auto=format"
   alt="An Edit in GitHub button appears in the Definition tab of a service in the Software Catalog" /%}

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](https://docs.datadoghq.com/api/latest/software-catalog/#create-or-update-entities). Updating the same service using both the GitHub and the API may result in unintended overwriting.

##### Integration validation{% #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](https://app.datadoghq.com/event/explorer), filter by `source:software_catalog` and `status:error`. Adjust the timeframe as needed.

{% image
   source="https://datadog-docs.imgix.net/images/tracing/software_catalog/github_error_event.e0f5570d0c7a4dc85f3d39a8b9c2b56b.png?auto=format"
   alt="Github event showing error message from service definition." /%}

## Further reading{% #further-reading %}

- [Create and manage service definitions with Terraform](https://registry.terraform.io/providers/DataDog/datadog/latest/docs/resources/service_definition_yaml)
- [Learn about the GitHub Integration](https://docs.datadoghq.com/integrations/github)
- [Learn about the Service Definition API](https://docs.datadoghq.com/api/latest/service-definition/)
- [Learn about the Software Catalog API](https://docs.datadoghq.com/api/latest/software-catalog/)