복합 모듈과 하위 모듈 재정의

복합 모듈(Composite module)은 이미 게시된 모듈들을 하위 모듈로 조합합니다. 공통 구성을 작은 단위로 관리하면서 상위 구성에서 필요한 변수와 설정을 연결할 수 있습니다.

두 모듈 조합하기

다음은 가상의 제품들이 존재하고 해당 버전 구성을 지원한다고 가정한 예시입니다.

첫 번째 모듈은 example-module-1.yml에 정의합니다.

name: example-module-1
displayName: Example Module 1
entities:
  - type: helmChart
    helmChart:
      productId: com.example:backend-service
      k8sNamespace: app-namespace
      configOverrides: |
        "2.0.0":
          overrides: {}

두 번째 모듈은 example-module-2.yml에 정의합니다.

name: example-module-2
displayName: Example Module 2
entities:
  - type: helmChart
    helmChart:
      productId: com.example:monitoring-service
      k8sNamespace: app-namespace
      configOverrides: |
        "2.0.0":
          overrides: {}

각각 0.1.0, 0.2.0으로 게시되어 있다면 상위 모듈에 정확한 버전을 지정합니다.

name: example-composite-module
displayName: Example Composite Module
submodules:
  - name: example-module-1
    version: 0.1.0
  - name: example-module-2
    version: 0.2.0

상위 모듈에는 두 하위 모듈의 배포 개체가 포함됩니다.

하위 모듈 필드

필드	필수 여부	의미
`name`	필수	이미 Apollo에 있는 모듈 이름. 없으면 생성 오류
`version`	필수	사용할 정확한 버전
`key`	조건부	같은 모듈을 여러 번 포함할 때 구별하는 고유 문자열
`variableOverrides`	선택	하위 모듈 변수의 값 또는 상위 변수 연결
`entityOverrides`	선택	하위 모듈의 배포 개체 구성과 비밀정보 요구 사항 재정의

상위 모듈의 한 버전에서 하위 모듈 버전은 고정됩니다. 하위 버전을 바꾸려면 상위 모듈도 새 버전으로 게시해야 합니다.

같은 모듈을 여러 번 포함

같은 모듈을 서로 다른 구성이나 네임스페이스에 사용하려면 각 항목에 고유한 key를 지정합니다. 키는 문자열이며 두 하위 모듈 항목을 구분합니다.

실제 배포 개체의 이름도 환경 안에서 고유해야 합니다. 다음 예시는 하위 모듈이 k8sNamespace와 instanceName 변수를 제공하고, instanceName을 개체의 entityName에 사용하는 경우입니다.

name: repeated-backend-module
submodules:
  - name: backend-module
    version: 0.1.0
    key: test-backend
    variableOverrides:
      k8sNamespace: test-namespace
      instanceName: backend-test
  - name: backend-module
    version: 0.1.0
    key: production-backend
    variableOverrides:
      k8sNamespace: prod-namespace
      instanceName: backend-production

key는 하위 모듈의 구분값이고 entityName은 배포 개체의 식별 이름이므로 같은 필드로 취급하지 않습니다.

변수 재정의

variableOverrides는 다음 두 방식을 지원합니다.

미리 아는 값을 고정하여 설치자가 입력할 항목을 줄입니다.
여러 하위 모듈의 변수를 상위 모듈 변수 하나에 연결합니다.

직접 참조하는 하위 모듈의 변수만 재정의할 수 있습니다. 그 하위 모듈의 하위 모듈에 있는 변수에 직접 접근하는 방식은 아닙니다.

재정의하지 않은 변수는 설치 시 구성 대상으로 남습니다. 해당 정의에 기본값이 있으면 이를 사용할 수 있으며, 필요한 값에 기본값도 없으면 설치자가 제공해야 합니다.

고정값 지정

하위 모듈에 다음과 같이 네임스페이스 변수가 있다고 가정합니다.

name: namespace-module
variables:
  k8sNamespace:
    type: string
    string:
      defaultValue: app-namespace
      description: 설치할 네임스페이스
entities:
  - type: helmChart
    helmChart:
      productId: com.example:backend-service
      k8sNamespace: "{{ moduleVariable.k8sNamespace }}"
      configOverrides: |
        "2.0.0":
          overrides: {}

상위 모듈이 값을 고정하면 이 네임스페이스를 설치 때 다시 입력하지 않아도 됩니다.

name: fixed-namespace-module
submodules:
  - name: namespace-module
    version: 0.1.0
    variableOverrides:
      k8sNamespace: application-namespace

상위 변수에 연결

아래 예시는 두 하위 모듈이 k8sNamespace 문자열 변수와 resourceProfile options 변수를 제공한다고 가정합니다. 두 모듈 모두 resourceProfile에서 small, medium, large를 선택할 수 있습니다.

name: shared-configuration-module
variables:
  k8sNamespace:
    type: string
    string:
      defaultValue: application-namespace
      description: 공통 설치 네임스페이스
  parentResourceProfile:
    type: options
    options:
      values: [small, medium]
      defaultValue: small
      description: 하위 모듈의 공통 배포 규모
submodules:
  - name: backend-module
    version: 0.1.0
    variableOverrides:
      k8sNamespace: "{{ moduleVariable.k8sNamespace }}"
      resourceProfile: "{{ moduleVariable.parentResourceProfile }}"
  - name: frontend-module
    version: 0.1.0
    variableOverrides:
      k8sNamespace: "{{ moduleVariable.k8sNamespace }}"
      resourceProfile: "{{ moduleVariable.parentResourceProfile }}"

같은 값을 여러 하위 모듈에 따로 입력하지 않고 상위 변수로 함께 지정할 수 있습니다.

프리셋의 제한

stringPreset 변수 자체는 재정의할 수 없습니다.
options는 고정된 선택값이나 상위 모듈의 다른 options 변수로 재정의할 수 있습니다.
상위 options 변수를 연결할 때 상위의 선택지 집합은 하위 선택지 집합의 부분집합이어야 합니다.
options 변수에 일반 string 변수를 연결하는 방식은 사용할 수 없습니다.

상위 모듈의 선택지인 small과 medium은 하위 모듈의 선택지인 small, medium, large에 모두 포함되므로 허용됩니다.

문자열과 변수 참조 조합

문자열 변수 재정의에서는 고정 문자열과 여러 상위 변수 참조를 섞을 수도 있습니다. 아래는 상위 모듈에 tenantName과 domain이 정의되어 있고, 하위 모듈에 frontendUrl이 있는 경우입니다.

variableOverrides:
  frontendUrl: "https://{{ moduleVariable.tenantName }}.{{ moduleVariable.domain }}.com"

배포 개체 재정의

entityOverrides로 하위 모듈의 개체에 새 구성값을 추가하거나 기존 값을 덮어쓰고, 비밀정보 요구 사항을 조정할 수 있습니다. 직접 하위 모듈에 선언된 개체뿐 아니라 그 아래 구성에 포함된 개체도 대상으로 삼을 수 있습니다.

다만 적용 대상 모듈에 restrictions.submoduleUsage.allowEntityOverrides: false가 있으면 개체 재정의는 거절됩니다. 변수 재정의는 계속 허용됩니다.

필드	의미
`type`	대상 개체와 같은 종류. 필수
`productId`	대상 제품 ID. 필수
`entityName`	같은 제품의 개체가 여러 개일 때 대상 구분
`override`	적용할 재정의 블록. 필수
`override.configOverrides`	병합할 버전별 구성의 YAML 문자열
`override.secretRequirements`	병합하거나 대체할 비밀정보 요구 사항

가상의 상위 모듈에서 대상 개체의 구성과 비밀정보 요구 사항을 바꾸는 예시는 다음과 같습니다.

name: control-plane-composite
submodules:
  - name: control-plane-base
    version: 0.1.0
    entityOverrides:
      - type: helmChart
        helmChart:
          productId: com.example:control-plane
          override:
            configOverrides: |
              "2.0.0":
                overrides:
                  num-threads: 100
            secretRequirements:
              service-secret:
                type: multikey
                multikey:
                  description: 서비스 간 통신용 키
                  keys: [replacement-api-key]

구성 병합의 우선순위

하위 모듈의 구성과 상위 entityOverrides의 구성이 같은 키를 정의하면 상위 값이 우선합니다. 상위가 지정하지 않은 기존 키는 유지되고 새로운 키는 추가됩니다.

기존 개체의 구성은 다음과 같습니다.

configOverrides: |
  "2.0.0":
    overrides:
      num-threads: 50
      thread-pool-size: 10

상위 모듈은 다음 구성을 덧붙입니다.

entityOverrides:
  - type: helmChart
    helmChart:
      productId: com.example:control-plane
      override:
        configOverrides: |
          "2.0.0":
            overrides:
              num-threads: 100
              storage-size: 10Gi

결과는 다음과 같습니다.

키	결과
`num-threads`	상위 값 `100`으로 대체
`thread-pool-size`	기존 값 `10` 유지
`storage-size`	`10Gi` 추가

이 값들은 버전 블록의 overrides 안에 놓는 제품 구성 키입니다. 버전 블록의 다른 메타데이터와 같은 수준으로 잘못 배치하지 않습니다.

비밀정보 요구 사항 병합

같은 비밀정보 이름의 요구 정의를 재정의하면 새 정의가 우선합니다. 이름이 다른 항목은 추가되며, 같은 이름의 키 목록은 자동으로 합쳐지지 않습니다.

다음은 가상의 기존 요구 사항입니다.

secretRequirements:
  service-secret:
    type: multikey
    multikey:
      description: 서비스 간 통신용 키
      keys: [api-key]

상위 모듈에서 다음과 같이 재정의합니다.

entityOverrides:
  - type: helmChart
    helmChart:
      productId: com.example:control-plane
      override:
        secretRequirements:
          service-secret:
            type: multikey
            multikey:
              description: 서비스 간 통신용 키
              keys: [replacement-api-key]
          another-secret:
            type: multikey
            multikey:
              description: 별도 연동 키
              keys: [another-key]

결과에서 service-secret의 요구 키는 replacement-api-key로 바뀌고 another-secret이 추가됩니다. 기존 api-key 요건은 제외됩니다.

이는 비밀정보의 요구 사항을 정의하는 것이며 실제 비밀값을 모듈 YAML에 적는 방식이 아닙니다. 필요한 값은 설치 시 비밀정보 설정에서 충족합니다.

개체 재정의 안의 변수

entityOverrides 안에서도 모듈 변수를 사용할 수 있습니다. 아래는 상위 모듈에 양의 정수 문자열(예: 100)을 받는 numThreads가 정의된 경우입니다. 내포된 YAML에서는 변수 치환 뒤 숫자로 해석되도록 값을 넣습니다.

entityOverrides:
  - type: helmChart
    helmChart:
      productId: com.example:control-plane
      override:
        configOverrides: |
          "2.0.0":
            overrides:
              num-threads: {{ moduleVariable.numThreads }}

모듈을 게시하고 설치하기 전에 적용할 변수 값, 최종 구성과 비밀정보 요구 사항을 확인합니다. Git에서 관리한다면 잠금 파일로 중첩을 펼친 결과를 검토할 수 있습니다.

Keyboard shortcuts

팔란티어 플랫폼 한국어 해설