Definiciones y versiones compatibles

Documentos > Definiciones y versiones compatibles

Estructura de metadatos y versiones compatibles

El Catálogo de software utiliza esquemas de definición para almacenar y mostrar metadatos relevantes sobre tus servicios. Los esquemas tienen reglas de validación integradas para garantizar que sólo se aceptan valores válidos. Puedes ver las advertencias en la pestaña Definición, en el panel lateral del Catálogo de software, para cualquier servicio seleccionado.

Opción de previsualización de la versión más reciente del Catálogo de software.

Request Access

Versiones compatibles

Datadog admite cuatro versiones del esquema de definición:

v3.0: Versión más reciente con modelo de datos ampliado, compatibilidad con múltiples propietarios, declaración manual de dependencias y funciones mejoradas para infraestructuras complejas.
v2.2: Admite anotaciones de usuario para metadatos personalizados y asociaciones de pipeline de CI para vincular servicios con sus procesos de compilación.
v2.1: Admite agrupaciones de servicio para mejorar la organización e introduce campos adicionales para descripciones más completas de servicio.
v2: Versión compatible más antigua, que proporciona campos esenciales para la documentación y los metadatos básicos de servicio.

Cada versión se basa en la anterior, añadiendo nuevas funciones y manteniendo la compatibilidad con versiones anteriores. Elige la versión que mejor se adapte a tus necesidades y a la complejidad de infraestructura.

Comparación de versiones

Cada versión admite las siguientes funciones:

Función	v3.0	v2.2	v2.1	v2.0
Metadatos básicos
Agrupaciones de servicio
Anotaciones del usuario
Asociaciones de CI Pipeline
Modelo de datos ampliado
Multipropiedad
Declaración manual de dependencia

Para obtener información detallada sobre cada versión, incluidos esquemas completos y archivos YAML de ejemplo, consulta las páginas de cada versión en Versiones compatibles.

Añadir metadatos al Catálogo de software

Añadir metadatos desde la interfaz de usuario de Datadog

En la página del Catálogo de software, haz clic en Setup & Config (Configurar).
Haz clic en Create New Entry (Crear nueva entrada).
Especifica el servicio al que deseas añadir metadatos.
Introduce los detalles de los enlaces Equipo, De guardia, Contactos, Documentación, Repositorio de código y Otros.
Cambia a YAML o JSON para ver el código generado y el comando cURL.
Si dispones del permiso de escritura del Catálogo de software, puedes enviar los metadatos haciendo clic en Save Entry (Guardar entrada) o ejecutando el comando cURL proporcionado.

Añadir metadatos con automatización

Almacenar y editar definiciones en GitHub

Configurar la integración GitHub para enlazar directamente desde dónde ves la definición del servicio en el Catálogo de software hasta donde se almacena y se puede editar en GitHub. Datadog analiza los archivos service.datadog.yaml y entity.datadog.yaml en cada repositorio con permisos de lectura.

Para instalar la integración GitHub:

Navega hasta el cuadro de la integración.
Haz clic en Link GitHub Account (Cuenta de enlace de GitHub) en la pestaña Repo Configuration (Configuración del repositorio).

Cuando la integración GitHub está configurado para tus definiciones, aparece un botón Edit in GitHub (Editar en GitHb) en la pestaña Definition (Definición) y te enlaza con GitHub para confirmar los cambios.

Un botón Editar en GitHub aparece en la pestaña Definición de un servicio en el Catálogo de software

Una vez actualizados los archivos YAML de tus repositorios, los cambios se propagan al Catálogo de software. Puedes registrar varios servicios en un archivo YAML creando varios documentos YAML. Separa cada documento con tres guiones (---).

Para evitar sobrescrituras accidentales, crea y modifica tus archivos de definición con la integración GitHub o con los endpoints de la API de definición. Actualizar el mismo servicio utilizando tanto GitHub como la API puede dar lugar a eliminaciones involuntarias.

Automatizar las actualizaciones de definiciones con Terraform

El Catálogo de software proporciona una definición como recurso Terraform. La creación y la gestión de servicios en el Catálogo de software a través de pipelines automatizados requieren Datadog Provider v3.16.0 o posterior.

Proveedor de metadatos de código abierto

Como alternativa a la integración GitHub y Terraform, puedes utilizar una solución GitHub Action de código abierto llamada proveedor de metadatos del Catálogo de software de Datadog.

Añadir metadatos a endpoints

Puedes añadir metadatos a las API a través de la interfaz de usuario o la API de Datadog, o utilizar pipelines automatizados a través de la integración GitHub o Terraform.

Combina el esquema de metadatos v3.0 con definiciones OpenAPI configurando kind: api y especificando el campo owner:

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

Crear extensiones personalizadas

La disponibilidad de las extensiones personalizadas es limitada.

El campo extensions es compatible con todas las versiones, incluida la v2.0. Puedes incorporar este campo personalizado en el proceso de despliegue para estandarizar y codificar las prácticas recomendadas.

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"

Complementos de IDE

Datadog proporciona un Esquema JSON para las definiciones, de modo que cuando se edita una definición en un IDE compatible, se proporcionan funciones como autocompletar y validación.