커스텀 엔터티 YAML 구성 설명¶

이 문서는 사용자가 수동으로 커스텀 엔터티를 생성할 때 YAML을 어떻게 작성해야 하는지 설명합니다.

이는 특정 엔터티 유형의 고정 템플릿이 아니라 범용 작성 규칙입니다. 문서 내 Host 예시는 단지 '필드를 어떻게 작성해야 하는지' 이해를 돕기 위한 것이며, 모든 엔터티가 Host 관련 필드를 반드시 포함해야 한다는 의미는 아닙니다.

구성 원칙¶

수동으로 엔터티 YAML을 작성할 때는 아래와 같은 순서로 구성하는 것을 권장합니다.

1. attributes를 엔터티 속성의 주체로 사용
2. 먼저 공통 거버넌스 필드를 작성하고, 그다음에 엔터티 전용 필드를 보충
3. name은 안정적인 식별자를 사용하고, 자주 변경되는 표시 이름을 직접 사용하지 않음
4. owner는 기본적으로 책임 팀을 입력하고, 개인 연락처는 contact에 넣어 하나의 필드에 팀과 개인이라는 두 가지 의미를 동시에 부여하지 않음
5. component_of와 depends_on은 entity_type:entity_name 형식으로 다른 엔터티를 참조

최소 사용 가능 예시¶

가장 기본적인 엔터티 정보만 먼저 등록하려면 최소한 다음 내용을 작성하세요.

attributes:
  name: payment-worker-01
  display_name: 결제 워커 노드 01
  project: payment
  owner: sre-platform

전체 예시¶

다음은 전체 예시입니다. Host를 예로 들어 공통 필드와 엔터티 전용 필드를 어떻게 조합할 수 있는지 보여줍니다.

attributes:
  name: prod-host-01
  host: prod-host-01
  project: payment
  display_name: 호스트 01
  description: 결제 핵심 서비스의 프로덕션 환경 호스트로, 정산 및 대사 작업을 처리합니다.

  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: 온콜 메일
      value: sre@example.com
    - type: slack
      name: 알림 채널
      value: https://company.slack.com/archives/C12345678
    - type: phone
      name: 온콜 전화
      value: 123456789

  link:
    - type: view
      name: 호스트 모니터링 대시보드
      dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
    - type: doc
      name: 장애 처리 핸드북
      provider: wiki
      link: https://wiki.example.com/host-runbook
    - type: repo
      name: 레포지토리
      provider: github
      link: https://github.com/example/payment-host

필드 구분¶

YAML의 필드는 두 가지로 나눌 수 있습니다.

1. 공통 필드¶

이러한 필드는 거버넌스, 검색, 소속, 협업에 사용되며, 대부분의 엔터티 유형에서 지원하는 것이 좋습니다.

2. 엔터티 전용 필드¶

이러한 필드는 구체적인 엔터티 유형에 따라 결정되며, 엔터티마다 다릅니다.

예를 들어 Host는 다음과 같은 필드를 가질 수 있습니다.

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

다른 커스텀 엔터티도 자체 전용 필드를 정의할 수 있습니다. 예:

• system_type
• business_owner
• tier
• app_id
• language

YAML을 작성할 때 모든 엔터티의 필드를 다 넣을 필요는 없으며, 다음만 작성하면 됩니다.

• 공통 필드 중 거버넌스와 표시에 필요한 부분
• 현재 엔터티 유형에서 실제로 사용하는 전용 필드

공통 필드 설명¶

name¶

name은 엔터티의 안정적인 식별자이며, 다음 원칙을 만족하는 것이 좋습니다.

• 한글, 공백, 자주 변경되는 이름은 사용하지 않는 것이 좋습니다.
• 표시 이름을 name에 직접 사용하지 마십시오.
• 엔터티가 다른 객체에 의해 참조된 후에는 자주 변경하지 않는 것이 좋습니다.

권장 작성법:

name: payment-worker-01

display_name¶

display_name은 사용자에게 표시되는 이름으로, 더 자연스럽고 읽기 쉬운 이름을 사용합니다.

display_name: 결제 워커 노드 01

description¶

한두 문장으로 엔터티의 역할, 용도, 컨텍스트를 설명합니다.

description: 결제 대사 작업을 처리하는 프로덕션 노드

project¶

엔터티를 프로젝트, 비즈니스 도메인, 제품 라인 등으로 분류하는 데 사용합니다.

project: payment

env¶

엔터티가 속한 환경을 식별합니다. 팀 내에서 동일한 용어를 사용하고, prod와 production 같은 동의어가 동시에 나타나지 않도록 하는 것이 좋습니다.

env: prod

owner¶

owner는 기본적으로 책임 팀을 입력하는 것이 좋습니다. 예:

owner: sre-platform

owner를 '팀'과 '개인 담당자'로 동시에 사용하지 않는 것이 좋습니다. 권장 규칙은 다음과 같습니다.

• owner에는 팀을 입력
• 개인 연락처는 contact에 입력

component_of¶

'현재 엔터티가 누구에 속하는지'를 나타내며, 주로 소속 관계를 설명하는 데 사용합니다.

통일된 작성법:

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

약속된 형식:

entity_type:entity_name

예:

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

depends_on¶

'현재 엔터티가 누구에게 의존하는지'를 나타내며, 주로 호출, 의존 관계, 리소스 사용 관계를 설명하는 데 사용합니다.

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

직접 의존 관계만 작성하고, 전체 의존 체인을 모두 펼치지 않는 것이 좋습니다.

custom_tags¶

분류 정보를 보충하는 데 사용합니다. 단순 태그와 네임스페이스가 있는 태그를 모두 지원합니다.

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

권장 사항:

• 태그는 짧고 안정적이어야 합니다.
• 같은 의미는 한 가지 작성법만 유지하는 것이 좋습니다.
• 팀에 이미 태그 규칙이 있다면 기존 명명을 우선 재사용하세요.

contact¶

contact는 객체 배열로, 각 항목은 하나의 연락처입니다.

예시:

contact:
  - type: email
    name: 온콜 메일
    value: sre@example.com
  - type: phone
    name: 온콜 전화
    value: 13800000000
  - type: slack
    name: 알림 채널
    value: https://company.slack.com/archives/C12345678

link¶

link는 엔터티와 관련된 링크 정보(대시보드, 문서, 레포지토리 등)를 연결하는 데 사용합니다.

일반적인 작성법:

link:
  - type: view
    name: 호스트 모니터링 대시보드
    dashboardUUID: dsbd_a7b598b675e76125614712354feb826e1d
  - type: doc
    name: 장애 처리 핸드북
    provider: wiki
    link: https://wiki.example.com/host-runbook
  - type: repo
    name: 레포지토리
    provider: github
    link: https://github.com/example/payment-host

일반적인 하위 필드 의미:

엔터티 전용 필드 추가 방법¶

특정 엔터티를 생성할 때 공통 필드 외에 해당 엔터티의 속성을 추가할 수 있습니다.

예를 들어 Host를 생성할 때:

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

예를 들어 사용자 정의 비즈니스 시스템을 생성할 때:

attributes:
  name: payment-platform
  display_name: 결제 플랫폼
  system_type: business
  tier: core
  owner: payment-tech

필드가 '엔터티 전용 필드'인지 판단하는 기준:

• 주로 거버넌스, 소속, 검색, 연락에 사용된다면 일반적으로 공통 필드
• 특정 엔터티 유형에만 비즈니스적 의미가 있다면 일반적으로 엔터티 전용 필드

자주 발생하는 오류¶

1. owner에 개인 이름을 입력한 경우¶

owner는 책임 팀을 정의합니다. 개인 연락처는 contact에 넣는 것이 더 안정적입니다.

2. 표시 이름을 name으로 사용한 경우¶

display_name은 유연하게 변경할 수 있지만, name은 최대한 안정적이어야 합니다. 그렇지 않으면 참조 관계와 검색에 영향을 줄 수 있습니다.

3. 여러 연락처를 하나의 value에 넣은 경우¶

연락처는 하나씩 분리해서 작성하는 것이 표시, 알림, 후속 처리에 유리합니다.

4. 모든 필드를 템플릿에서 그대로 복사한 경우¶

이 문서의 목적은 '필드를 어떻게 구성하는지'를 이해시키는 것이지, 예시의 모든 필드를 그대로 사용하라는 것이 아닙니다. 실제로 작성할 때는 현재 엔터티에 실제로 필요한 필드만 유지하면 됩니다.