Self-built Entity YAML Configuration Guide¶

This document explains how to write YAML when manually creating self-built entities.

This is not a fixed template for a specific entity type, but a general specification for filling out fields. The Host snippet in this document is just an example to help understand "how fields should be written" and does not mean all entities must contain Host-related fields.

Configuration Principles¶

When manually writing entity YAML, it is recommended to organize it according to the following approach:

1. Use attributes as the main body for entity attributes.
2. Fill in general governance fields first, then supplement with entity-specific fields.
3. Use a stable identifier for name, do not directly use a display name that changes frequently.
4. Fill in the responsible team for owner by default; place individual contacts in contact to avoid a single field carrying both team and individual semantics.
5. Use the entity_type:entity_name format uniformly for component_of and depends_on to reference other entities.

Minimum Viable Example¶

If you only want to record the most basic entity information first, it is recommended to fill in at least the following content:

attributes:
  name: payment-worker-01
  display_name: Payment Worker Node 01
  project: payment
  owner: sre-platform

Complete Example¶

Below is a complete example. It uses Host as an example to show how general fields and entity-specific fields can be combined:

attributes:
  name: prod-host-01
  host: prod-host-01
  project: payment
  display_name: Host 01
  description: Production host for the core payment service, handling settlement and reconciliation tasks.

  host_ip: 10.20.30.40
  os: linux
  lifecycle: active
  env: prod

  cloud_provider: aliyun
  instance_id: i-bp1example
  region: cn-hangzhou
  zone: cn-hangzhou-h

  owner: sre-platform

  component_of:
    - system:payment-cluster
    - system:payment-platform
  depends_on:
    - service:config-center
    - database:mysql-payment-prod

  custom_tags:
    - category:settlement
    - critical

  contact:
    - type: email
      name: On-call Email
      value: sre@example.com
    - type: slack
      name: Alert Channel
      value: https://company.slack.com/archives/C12345678
    - type: phone
      name: On-call Phone
      value: 123456789

  link:
    - type: view
      name: Host Monitoring Dashboard
      dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
    - type: doc
      name: Troubleshooting Manual
      provider: wiki
      link: https://wiki.example.com/host-runbook
    - type: repo
      name: Repository
      provider: github
      link: https://github.com/example/payment-host

How to Categorize Fields¶

Fields in the YAML can be divided into two categories for understanding:

1. General Fields¶

These fields are used for governance, retrieval, ownership, and collaboration. Most entity types are recommended to support them.

2. Entity-Specific Fields¶

These fields are determined by the specific entity type and will differ between entities.

For example, Host might have:

• host
• host_ip
• os
• cloud_provider
• instance_id
• region
• zone
• lifecycle

Other self-built entities can also define their own specific fields, for example:

• system_type
• business_owner
• tier
• app_id
• language

When writing YAML, you do not need to include all fields for all entities, only fill in:

• The parts of the general fields you need for governance and display.
• The entity-specific fields that are actually useful for the current entity type.

General Field Descriptions¶

name¶

name is the stable identifier for the entity. It is recommended to follow these principles:

• Try not to use Chinese characters, spaces, or names that are prone to change.
• Do not use the display name directly as the name.
• Once an entity is referenced by other objects, try not to change it frequently.

Recommended writing:

name: payment-worker-01

display_name¶

display_name is the name displayed to users, which can be more natural and readable.

display_name: Payment Worker Node 01

description¶

Use one or two sentences to describe the entity's responsibilities, purpose, or context.

description: Production node handling payment reconciliation tasks.

project¶

Used to categorize the entity under a project, business domain, or product line.

project: payment

env¶

Used to identify the environment where the entity resides. It is recommended to unify terminology within the team to avoid synonymous values like prod and production appearing simultaneously.

env: prod

owner¶

owner is recommended to be filled with the responsible team by default, for example:

owner: sre-platform

It is not recommended to use owner for both "team" and "individual responsible person". The recommended convention is:

• Fill the team in owner.
• Place individual contacts in contact.

component_of¶

Indicates "who the current entity belongs to", often used to describe ownership relationships.

Uniform writing:

component_of:
  - system:payment-platform
  - cluster:payment-cluster

The agreed format is:

entity_type:entity_name

For example:

• system:payment-platform
• service:order-service
• database:mysql-payment-prod

depends_on¶

Indicates "who the current entity depends on", often used to describe invocation, dependency, or resource usage relationships.

depends_on:
  - service:config-center
  - database:mysql-payment-prod

It is recommended to only fill in direct dependencies, and not to expand the entire dependency chain.

custom_tags¶

Used to supplement classification information. Supports simple tags and namespaced tags.

custom_tags:
  - critical
  - category:settlement
  - team:sre

Recommendations:

• Keep tags short and stable.
• Try to keep only one way of writing for the same meaning.
• If the team already has a tagging specification, prioritize reusing existing naming.

contact¶

contact is an array of objects, each item being a piece of contact information:

Example:

contact:
  - type: email
    name: On-call Email
    value: sre@example.com
  - type: phone
    name: On-call Phone
    value: 13800000000
  - type: slack
    name: Alert Channel
    value: https://company.slack.com/archives/C12345678

link¶

link is used to attach information about links related to the entity, such as dashboards, documentation, and repositories.

Common writing is as follows:

link:
  - type: view
    name: Host Monitoring Dashboard
    dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
  - type: doc
    name: Troubleshooting Manual
    provider: wiki
    link: https://wiki.example.com/host-runbook
  - type: repo
    name: Repository
    provider: github
    link: https://github.com/example/payment-host

Common field meanings:

How to Supplement Entity-Specific Fields¶

When you are creating a specific type of entity, you can supplement its own attributes beyond the general fields.

For example, when creating a Host:

attributes:
  name: prod-host-01
  host: prod-host-01
  host_ip: 10.20.30.40
  os: linux
  cloud_provider: aliyun

For example, when creating a custom business system:

attributes:
  name: payment-platform
  display_name: Payment Platform
  system_type: business
  tier: core
  owner: payment-tech

To determine if a field is an "entity-specific field", you can use this criterion:

• If it is mainly used for governance, ownership, retrieval, or contact, it usually belongs to general fields.
• If it only has business meaning for a specific type of entity, it usually belongs to entity-specific fields.

Common Mistakes¶

1. Filling owner with an individual's name¶

owner defines the responsible team. Individual contact information is more stable when placed in contact.

2. Using the display name as the name¶

display_name can change flexibly, but name should be as stable as possible, otherwise it can easily affect reference relationships and retrieval.

3. Stuffing multiple contact methods into a single value¶

It is recommended to write contact information item by item, which facilitates display, notification, and subsequent processing.

4. Copying all fields from the template¶

The goal of this document is to help you understand "how to organize fields", not to require you to copy all fields from the example. When actually filling it out, only keep the fields that the current entity truly needs.