콘텐츠로 이동
AggregaAggrega
언어 선택: 한국어
이 페이지는 기계 번역되었습니다. 영어 원문 읽기.

Workload

Workload 종류의 아키텍처상 역할, 즉 이 종류가 존재하는 이유, 다른 두 Recipe 입력 종류(sourced 및 artifacts)와 어떻게 조합되는지, 그리고 전체 스키마 표면은 ../../architecture/16-recipe-input-composition.md에서 다룹니다. 이 페이지는 Workload 작성 표면을 다룹니다. Recipe 작성자가 Workload 내용을 작성하는 방법, 컴파일러가 무엇을 언제 평가하는지, Workload 필드가 Component의 featuresSchema와 어떻게 상호 작용하는지, 그리고 Workload 내부의 템플릿이 어떤 기둥을 읽을 수 있는지 설명합니다.

작성 위치

Workload 콘텐츠는 Recipe 또는 FeatureRecipe 안에서 인라인으로 작성하거나 파일에서 가져옵니다(FeatureRecipe 참조). Recipe는 workload:를 최대 하나까지 선언하며, FeatureRecipe도 마찬가지로 자체 Workload를 최대 하나까지 선언합니다:

# Inline (block scalar)
spec:
workload: |
apiVersion: aggrega.ai/v1beta1
kind: Workload
# ...

또는

# File-loaded via $import: (path relative to the Recipe directory)
spec:
workload:
$import: ./workload/workload.yaml

두 형식 모두 파싱 후 동일한 Workload 객체를 생성하며, 어느 쪽을 선택할지는 작성 편의성의 문제입니다. 세 번째 형식은 여러 Recipes가 공유하는 Workload를 WorkloadLibrary 항목에서 그 bare-name 식별자로 가져옵니다: $import: <Library>#/workloads/<entry>. 통합된 파일 가져오기 어휘에 따라 $import:는 단일 소스만 받습니다. 보다 넓은 $ref: / $import: 구분은 ../vocabulary/cross-document-ref.md를 참조하십시오.

Workload YAML은 독립적인 카탈로그 엔터티로 작성되지 않습니다. catalog/workload/ 디렉터리는 없으며, Workload 문법은 Recipe 또는 FeatureRecipe가 사용하는 콘텐츠로만 존재합니다. 이 콘텐츠는 인라인으로, 그 옆의 파일에, 또는 WorkloadLibrary 항목에 작성됩니다. YAML 안의 apiVersion 및 kind 선언(apiVersion: aggrega.ai/v1beta1, kind: Workload)은 스키마 검증을 위해 포함된 콘텐츠를 식별할 뿐이며, Workload를 독립적으로 참조할 수 있게 만들지는 않습니다.

템플릿 평가

Workload 콘텐츠는 파싱 전에 전체 필러 컨텍스트를 대상으로 Go 템플릿 처리됩니다. Recipe 작성자가 다음과 같은 템플릿을 작성하면…

replicas: {{ optional .infra `replicas` 1 }}

…컴파일러는 렌더링의 Workload 하위 패스에서 해당 템플릿을 평가하고, .infra.replicas를 노드의 infra 페이로드에 대해 해석한 뒤, 결과 YAML을 Workload 문서로 파싱합니다. Recipe의 locals는 Workload가 평가되기 전에 해석되므로, Workload 템플릿은 이미 해석된 값을 .locals 아래에서 읽습니다.

Workload 템플릿 내부의 필러 접근:

  • .values — Aggregate에 선언된, 개발자가 작성한 인지 페이로드입니다.
  • .infra — Release에 선언된, Ops가 작성한 물리적 사이징입니다.
  • .parameters — 해석 시점에 이미 보간됩니다. Developer 또는 Ops가 작성 중에 .parameters.<name>을 참조한 곳이면 어디서나 .values / .infra를 통해 보입니다.
  • .locals — locals 프리앰블에서 해석되고 소스 해석 시점에 게시되는 Recipe 전용 상태입니다. 모든 Workload 템플릿 평가 위치에서 사용할 수 있습니다.
  • .context.instance_id — 노드의 평탄화된 인스턴스 ID입니다. 합성된 리소스의 이름을 아이덴티티에 따라 짓는 provider가 생성하는 리소스 이름의 접두사입니다.
  • .context.rendered_name — 합성된 리소스의 이름을 스스로 도출하는 provider가 부여하는 이름으로, helm의 release 이름 등이 있습니다. provider가 이름을 보고하는 경우에만 존재합니다. ../templates/rendered-resource-names.md를 참조하십시오.
  • .context.inject — 인터셉션 이후의 주입 파이프로, inject 매핑 중에 FeatureRecipe의 injectMapping에 의해 이미 재작성된 상태입니다.
  • .context.uses — 이 노드에서 나가는 보강된 토폴로지 엣지로, 각각 대상의 해석된 provides, labels, 연쇄 어노테이션을 담으며, .context.uses.<alias>.features.<slot> 아래에는 해당 연결이 담는 첨부 항목을 담습니다.
  • .features — 노드 자체의 첨부 항목으로, 각각 type, values, infra, 해석된 provides를 담습니다. Component가 featuresSchema에 선언한 슬롯의 이름을 가진 첨부 항목은 해당 슬롯을 채웁니다(아래 참조). 연결이 담는 첨부 항목은 여기에 포함되지 않습니다. 그것은 해당 연결 아래에서 읽히며, Workload는 연결의 이름을 지정하여 이를 전달합니다(연결이 담는 자격 증명 전달 참조).

전체 필러 접근 계약은 ../vocabulary/data-pillars.md를, 템플릿 평가 순서에서 Workload 평가가 위치하는 곳은 ../templates/expansion-matrix.md를 참조하십시오.

필드 의미 핵심

전체 Workload 스키마는 ../../architecture/16-recipe-input-composition.md의 “The Workload Kind” 항목에 있습니다. 아래의 작성 관례는 Recipe 작성자가 내리는 필드 수준의 결정을 다룹니다.

form

form은 워크로드의 추상적인 컨트롤러 형태, 즉 대상 플랫폼과 무관하게 워크로드가 갖는 런타임 수명 주기의 종류를 선언합니다. 단일 문자열로 stateless, stateful, daemon, scheduled, task, reference 중 하나이며, 생략하면 기본값은 stateless입니다:

  • stateless — 레플리카별 식별자가 없는, 서로 교체 가능하고 수평 확장되는 레플리카(일반적인 장기 실행 서비스).
  • stateful — 레플리카별로 안정적인 식별자와 레플리카별 스토리지를 갖는 레플리카. persistentTemplate 볼륨은 이 형태의 동반 요소입니다.
  • daemon — 대상이 되는 호스트마다 인스턴스 하나.
  • scheduled — 시간에 따라 트리거되는 반복 실행.
  • task — 완료될 때까지 한 번 실행.
  • reference — 자체 컨테이너가 없습니다. 컴포넌트는 외부 엔드포인트를 나타내며, 이는 endpoint(호스트 또는 URL로, 작성된 그대로 전달됨)와 선택 사항인 port로 지정됩니다. helm 프로바이더는 이를 ExternalName 타입의 Service로 내보내고, compose 프로바이더는 이에 대해 아무것도 내보내지 않습니다.

form 자체는 플랫폼 고유의 리소스 종류를 담지 않습니다. Workload를 합성하는 각 대상 provider가 form을 자체 고유 형태로 매핑합니다:

formKubernetes (helm)Compose
statelessDeploymentservice (영구 볼륨 없음)
statefulStatefulSetservice + 명명된 볼륨
daemonDaemonSet빌드를 중단함
scheduledCronJob빌드를 중단함
taskJob빌드를 중단함

terraform 및 cloudformation 프로바이더는 sourced Recipes와 artifacts만 있는 Recipes를 렌더링하며 Workload를 합성하지 않습니다. workload:를 선언하고 둘 중 하나에 바인딩된 Recipe는 해당 프로바이더가 지원하는 입력 종류를 명시하며 빌드를 중단시킵니다.

대상 provider에 어떤 form에 대한 깔끔한 매핑이 없으면, 의도를 잘못 표현하는 형태로 워크로드를 격하하는 대신 빌드가 명시적으로 중단됩니다. 대상 경계가 표현할 수 없는 form을 선택하는 것은 조용한 격하가 아니라 빌드 시점 오류입니다. compose provider는 daemon, scheduled, task에서 중단됩니다. helm provider는 scheduled에 대해 CronJob을 생성하며(아래 schedule 참조), 스케줄이 없거나 형식이 잘못된 경우에만 중단됩니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: stateful
containers:
db: { image: "postgres:16", ports: { db: 5432 } }
volumes:
data:
persistentTemplate:
size: "20Gi"
services:
headless:
type: Headless
ports:
db: 5432

schedule

schedule은 form: scheduled 워크로드의 cron 스케줄로, 반복 form에 반복 주기를 부여하는 동반 필드입니다. 하나의 표준 형식으로 된 단일 문자열입니다.

  • 분, 시, 일, 월, 요일로 구성된 표준 5필드 crontab 표현식(예: 매일 자정은 0 0 * * *, 15분마다는 */15 * * * *), 또는
  • 매크로 @hourly, @daily, @weekly, @monthly, @yearly 중 하나.

schedule은 form: scheduled일 때 필수이며 그때만 의미가 있습니다. 스케줄이 없는 form: scheduled 워크로드, 5필드 표현식도 인식된 매크로도 아닌 스케줄(초가 앞에 붙은 6필드 표현식, 인식되지 않는 @ 토큰, 허용되지 않는 문자가 있는 필드), 또는 다른 form에 설정된 schedule은 해결 방법을 알려 주는 빌드 시점 중단입니다. helm provider는 이 값을 생성된 CronJob의 spec.schedule에 그대로 전달합니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # daily at 02:00
containers:
report:
image: "reporter:1.0"
command: ["/report"]

suspend

suspend는 form: scheduled 워크로드의 반복 일정을 보류합니다. 불리언이며 기본값은 false입니다. suspend: true이면 예약된 리소스는 여전히 schedule을 그대로 둔 채 렌더링되지만, 재개될 때까지 그 일정에 따라 시작되는 실행은 없으며, 리소스에서 수동으로 실행을 시작하는 것은 여전히 가능합니다. 이는 누군가 요청할 때만 실행되어야 하는 작업을 위한 형태입니다.

helm 프로바이더는 이 필드를 CronJob의 spec.suspend: true로 내보냅니다. Kubernetes에서는 kubectl create job <name> --from=cronjob/<cronjob>으로 보류된 CronJob에서 실행을 시작할 수 있고, spec.suspend가 다시 false가 되면 일정이 재개됩니다. suspend: false는 suspend를 생략한 것과 똑같이 렌더링되므로, 이 필드는 설정되기 전까지 출력을 바꾸지 않습니다. compose 프로바이더에는 예약 실행 형태가 없어, 보류 여부와 관계없이 모든 form: scheduled 워크로드에서 빌드를 중단합니다.

다른 form에 suspend: true를 지정하면 수정 방법을 명시하며 빌드 시점에 중단됩니다. 다른 form에는 보류할 일정이 없기 때문입니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: scheduled
schedule: "0 2 * * *" # documents when it would run; nothing starts it while suspended
suspend: true
containers:
report:
image: "reporter:1.0"
command: ["/report"]

replicas

워크로드의 레플리카 수를 나타내는 단일 정수입니다. 생략하면 기본값은 1입니다. Ops가 선언한 크기 설정으로 레플리카를 제어하려면 템플릿 표현식을 사용합니다.

replicas: {{ optional .infra `replicas` 1 }}

containers와 initContainers 비교

containers는 컨테이너 이름을 키로 하는 순서 있는 맵입니다. 컨테이너 0(첫 번째 맵 키)은 Kubernetes 출력의 pod spec 순서와 기본 컨테이너 의미에 영향을 줍니다. initContainers는 init 컨테이너 항목의 순서 있는 목록이며, 각 항목은 name, image, 그리고 메인 컨테이너와 동일한 변수/시크릿/볼륨 마운트 작성 형태를 가집니다.

initContainers 항목에서 name은 선택 사항입니다. 이를 생략한 항목의 이름은 init-<index>가 되며, index는 0부터 센 목록 내 항목의 위치입니다. 이름은 렌더링된 출력과 해당 컨테이너를 가리키는 진단에서 컨테이너를 식별하므로, 참조할 가치가 있는 항목에는 명시적으로 이름을 붙이는 것이 좋습니다.

작성 순서 보존은 Workload 모델의 핵심적인 계약입니다. 컴파일러는 모든 빌드에서 containers, volumes, services, 컨테이너 ports, 컨테이너 variables, 컨테이너 attachments를 각각 Recipe 작성자가 선언한 순서대로 생성합니다. Recipe 작성자는 이 순서 있는 형태에 의존할 수 있습니다. 실행 시점에 일어나는 일이 순서에 따라 달라지는 경우(사이드카 시작, 환경 변수의 $(VAR) 연쇄, 앞서 선언된 볼륨을 참조하는 volumeMounts), 각 컬렉션 내에서는 작성 순서가 곧 런타임 순서입니다. 컨테이너의 환경은 이 중 두 가지를 결합하며, 두 컬렉션에 걸쳐 합성하는 provider는 attachment 읽기 항목(as: env로 전달되는 attachments)을 먼저, 일반 variables를 그 뒤에 쓰고 각 종류는 작성 순서를 따릅니다. 따라서 Kubernetes 대상에서 변수는 해당 컨테이너의 모든 attachment 읽기 변수와 자신보다 앞에 선언된 모든 변수를 $(NAME)으로 참조할 수 있습니다(helm provider의 환경 순서 참조). 하나의 이름을 variables 항목과 as: env로 전달되는 attachments 항목 양쪽에 지정한 컨테이너는 빌드를 중단시킵니다. 이 순서만으로 프로세스가 두 값 중 어느 것을 보게 될지가 결정되기 때문입니다(A container gives one environment variable two values (컨테이너가 하나의 환경 변수에 두 값을 지정함) 참조).

컨테이너 필드 작성은 다음 관례를 따릅니다.

  • **image**는 일반적으로 .values.image(Developer가 선택한 이미지)를 참조하는 템플릿 표현식이며, 환경별 레지스트리 접두사를 위해 선택적으로 .infra.* 재정의를 사용합니다.
  • **variables**는 환경 변수를 위한 단순한 문자열 → 문자열 맵입니다. 이 맵은 Go 템플릿 표현식을 통해 서로 다른 두 데이터 소스를 섞습니다. developer pillar 리터럴(템플릿 표현식이 .values / .infra / .locals를 읽는 항목 — Component의 pillar에서 비롯된 페이로드)과 cross-component 파이프 데이터(템플릿 표현식이 .context.inject.env.<KEY>를 읽는 항목 — 다른 component의 provides:에서 비롯되어 토폴로지 파이프를 통해 전달된 페이로드)입니다. 두 소스는 같은 variables 맵으로 흘러 들어가며, 작성자는 값이 component 로컬인지 다른 component에서 파생된 것인지에 따라 항목마다 하나를 선택합니다. 일반적인 패턴: LOG_LEVEL: "{{ .values.log_level }}"은 developer pillar(component 로컬)이고, DB_HOST: "{{ .context.inject.env.DB_HOST }}"는 cross-component 파이프입니다(값은 대상 component의 provides.host에서 비롯되어 호출자의 uses[].inject.env.DB_HOST 선언을 통해 전달됨). 두 형태 모두 렌더링된 Deployment의 단일 Kubernetes env: 목록으로 컴파일되며, 이중 소스 의미는 작성 시점에만 존재합니다.
  • **attachments**는 Component의 featuresSchema에 선언된 슬롯을 참조하거나, 연결의 이름을 지정하여 그 연결의 소켓이 선언한 슬롯을 참조합니다(아래 통합 섹션 참조).
  • **ports**는 이름 있는 포트 맵(web: 8080, admin: 9901)입니다. 포트 이름은 컨테이너 범위의 포트 이름과 일치하며 services.<service>.ports.<portname>으로 참조됩니다. 대상의 기본값이 아닌 전송 방식을 사용하는 포트는 대신 확장 형태로 작성합니다. 아래 포트 전송 프로토콜을 참조하십시오.
  • **volumeMounts**는 Workload의 volumes: 섹션에 선언된 볼륨을 이름으로 참조합니다.
  • **resources**는 컨테이너의 requests와 limits, 즉 cpu와 memory 수량 및 선택적으로 GPU와 기타 장치를 위한 확장 리소스 키를 선언합니다(아래 GPU 및 장치 워크로드 참조).
  • **health**는 의도 형태(http: /path, tcp: <port>, exec: [cmd, ...])를 사용합니다. 아래 상태 프로브 섹션을 참조하십시오.

volumes

각 볼륨은 정확히 하나의 유형을 가집니다: ephemeral, configmap, secret, persistent, persistentTemplate 중 하나입니다. 하나의 볼륨 선언 안에서 이 유형들은 상호 배타적이며, 각 유형은 고유한 필수 필드를 가집니다:

volumes:
app-config:
configmap:
source: "{{ .locals.app_cm }}"
data:
persistent:
size: "10Gi"
class: "gp3"
cache:
ephemeral:
sizeLimit: "1Gi"

persistentTemplate는 StatefulSet 형태의 변환에서 레플리카별 PVC를 생성합니다. compose 변환에서는 공유되는 단일 명명 볼륨으로 축소되며, 빌드와 함께 경고가 보고됩니다. 생성된 파일 자체에는 이 축소에 대한 표시가 없으며, 경고가 없을 때와 바이트 단위로 동일합니다.

Provider별 변환. 각 provider는 다섯 가지 볼륨 변형을 자신의 네이티브 형태로 변환합니다:

변형Helm / helm-chart (K8s)Compose손실 사항
ephemeralemptyDir: { sizeLimit }마운트 경로를 지정하는 서비스 수준 tmpfs: 항목(메모리 내)Compose tmpfs는 RAM 기반이고, helm의 emptyDir은 기본적으로 노드의 디스크 기반입니다. 즉 기반 저장 매체의 의미가 다릅니다. sizeLimit은 compose 출력의 어느 부분에도 반영되지 않으며, 생성되는 항목은 마운트 경로뿐입니다. 작성된 sizeLimit은 이를 지정하는 unsupported-field 경고를 발생시키며, 이 경고는 생성된 파일에 기록되지 않고 빌드와 함께 보고됩니다.
configmapConfigMap 볼륨 참조(Recipe의 artifacts: 또는 Feature가 생성한 ConfigMap 리소스를 사용)configmap을 지정하고 볼륨 마운트 경로에 마운트되는 서비스 수준 configs: 참조. 대응하는 최상위 configs: 항목은 Recipe의 artifacts:에서 옵니다두 대상 모두 configmap을 이름으로 참조하며 어느 쪽도 그 내용을 읽지 않으므로 작성 형태는 대칭적입니다. compose가 잃는 것은 K8s ConfigMap의 롤아웃 시 갱신 의미입니다. compose config는 빌드가 생성한 내용으로 고정됩니다. 어떤 최상위 항목으로도 해석되지 않는 참조는 실행 시점에 끊어질 마운트를 생성하는 대신 빌드를 중단합니다.
secretSecret 볼륨 참조(자격 증명 attachment가 지정하는 Secret을 사용. 해당 FeatureRecipe가 생성한 것이거나 이미 존재하는 것)env 형태의 secret에는 env_file:, 경로 형태의 secret에는 바인드 마운트된 secret 파일Compose에는 일급 Kubernetes Secret 의미가 없습니다. 경로 형태의 secret은 의도적으로 configmap 변형의 configs: 경로를 따르지 않습니다. 인라인 config 항목은 secret의 값을 생성되는 compose 파일에 평문으로 기록하게 되며, 컴파일러는 secret을 평문으로 해석하지 않습니다. 바인드 소스는 운영자가 compose 호스트에서 접근 가능하게 만드는 경로이며, vault-fetch CRD 수명 주기 밖에 있습니다.
persistentPVC 리소스 + volume.persistentVolumeClaim명명 볼륨Compose 명명 볼륨은 평면적인 호스트 측 추상화입니다. helm의 PVC는 compose가 무시하는 스토리지 클래스, 액세스 모드, 용량 선언을 지원합니다.
persistentTemplateStatefulSet.volumeClaimTemplates(레플리카별 PVC, form: stateful의 동반 요소)명명 볼륨(축소됨 — 레플리카 간 공유되는 단일 볼륨, 경고 보고)Compose는 레플리카별 템플릿을 표현할 수 없습니다. persistentTemplate가 compose로 변환되면 단일 명명 볼륨이 생성되고, 낮아진 충실도는 생성된 파일에 기록되지 않고 빌드와 함께 경고로 보고됩니다. 레플리카별 볼륨 격리에 의존하는 Workloads는 compose 전용 경계를 대상으로 해서는 안 됩니다.

컨트롤러 형태는 볼륨이 아니라 워크로드의 form으로 선택됩니다. StatefulSet은 form: stateful일 때 생성되며, persistentTemplate 볼륨은 그 form의 동반 요소입니다. 즉 StatefulSet이 제공하는 레플리카별 식별성을 이미 가진 워크로드에 레플리카별 스토리지를 선언합니다. 다른 form(또는 기본값 stateless)에 persistentTemplate 볼륨을 선언하면 해결 방법 declare form: stateful을 알려 주는 빌드 시점 오류가 됩니다. 반대는 허용됩니다. form: stateful 워크로드가 persistentTemplate 볼륨을 선언할 필요는 없습니다. StatefulSet 의미를 원하는 작성자는 form: stateful을 직접 설정합니다.

helm provider에서 form: stateful 워크로드에는 헤드리스 거버닝 Service가 필요합니다. 같은 Workload 안에 type: Headless인 service를 정확히 하나 선언하십시오. provider는 StatefulSet의 serviceName을 그 헤드리스 Service에 연결합니다(이 Service가 StatefulSet에 필요한 안정적인 파드별 네트워크 식별성을 제공합니다). 헤드리스 service가 선언되지 않으면 StatefulSet이 지정할 거버닝 Service가 없으므로 빌드가 중단되고, 둘 이상 선언되어 거버닝 Service가 모호해져도 빌드가 중단됩니다. StatefulSet 워크로드는 하나의 헤드리스 거버닝 service 외에 추가적인 비헤드리스 service(예: 클라이언트 접근용 ClusterIP service)를 선언할 수 있습니다.

리소스 수량

다음 Workload 값은 수량, 즉 Kubernetes가 리소스에 사용하는 표기법으로 작성된 양입니다: 컨테이너(또는 init 컨테이너)의 cpu, memory 및 모든 확장 리소스 키에 대한 resources.requests와 resources.limits 값, 그리고 볼륨의 ephemeral.sizeLimit, persistent.size, persistentTemplate.size입니다. Workload 스키마는 각각을 문자열로 정의하며 형식을 제한하지 않습니다. 대상에 대해 Workload를 합성하는 provider가 생성하는 모든 수량을 검사하며, Recipe의 템플릿이 평가한 결과의 Workload를 검사하므로 infra, Release 파라미터 또는 다른 템플릿 입력을 통해 들어온 값은 렌더링된 문자열로 판단됩니다.

수량은 앞뒤에 아무것도 없이 다음으로 구성됩니다:

  • 선택적 부호 + 또는 -;
  • 숫자가 하나 이상 있는 수 — 2, 0.5, .5 또는 1.;
  • 최대 하나의 지수 — e 또는 E, 선택적 부호, 그다음 숫자(1e3 또는 5E-2처럼) — 또는 단위 접미사: 10진 접미사 n, u, m, k, M, G, T, P 또는 E(10⁻⁹부터 10¹⁸까지 1000 단위), 또는 2진 접미사 Ki, Mi, Gi, Ti, Pi 또는 Ei(1024부터 1024⁶까지).

500m, 0.5, 2, 128Mi, 1.5Gi, 1e3, 5n, 4u는 수량이고, lots, 1.5 cores, 1 gigabyte, 10 GB, 1e1.5는 수량이 아닙니다. 지수는 정수입니다. 수 뒤의 단독 E는 10¹⁸을 나타내는 10진 접미사이며(12E), 뒤에 숫자가 오면 지수를 시작합니다(1E3).

이는 Kubernetes 자체 수량 파서가 허용하는 형식이며, 의도적인 차이가 하나 있습니다. 수 부분에 숫자가 없는 문자열 — m, Ki, +, ., e5 — 은 거부되며, Kubernetes는 이를 0으로 읽습니다. 이런 문자열은 템플릿이 보간하는 값이 비어 있을 때 정확히 남기는 결과입니다. cpu가 비어 있으면 "{{ .infra.cpu }}m"는 m으로 렌더링됩니다. 이를 거부하면 빈 입력이 아무도 보고하지 않는 크기 0의 요청이 되는 대신, 필드를 지정하는 중단으로 바뀝니다.

각 대상이 수량을 처리하는 방식:

  • helm은 각 수량을 위의 형식에 대해 검사한 후 모든 수량을 그대로 생성합니다. 형식에서 벗어난 값은 노드, Workload 내 필드의 경로 — containers.main.resources.requests.cpu, initContainers[0].resources.limits.memory, volumes.data.persistent.size — 그리고 값을 지정하는 오류와 함께 빌드를 중단합니다. Helm Provider → Workload(합성) 모드를 참조하십시오.
  • compose는 파싱된 값에서 cpu와 memory를 자체 단위로 변환합니다. cpus는 10진 코어 수(500m → 0.5)가 되고 memory는 정확한 바이트 수(1.5Gi → 1610612736)가 됩니다. 수량이 아닌 값은 빌드를 중단하며, compose가 정확히 표현할 수 없는 수량 — 음수, 정수 바이트가 아닌 메모리 양(1500m), 코어의 소수점 아홉 자리보다 세밀한 cpu 양 — 도 빌드를 중단하고, 오류는 둘 중 어느 경우인지 알려 줍니다. nvidia.com/gpu 개수도 같은 방식으로 읽혀 장치 수가 되므로, 정수 개의 장치가 아닌 값도 중단됩니다. compose는 다른 확장 리소스나 볼륨 크기를 생성하지 않으므로 이를 검사하지 않습니다. 다른 확장 리소스 키와 ephemeral.sizeLimit은 경고와 함께 제외되며, persistent 크기는 출력에 아무 영향을 주지 않습니다. Compose Provider → 컨테이너 리소스를 참조하십시오.

이 검사는 형식만 판단합니다. 클러스터가 그 양을 스케줄링할 수 있는지, 그 양이 장치에 적합한지는 검사 범위 밖입니다.

services

서비스 노출의 순서 있는 맵입니다. 각 서비스는 포트가 도달하는 범위를 나타내는 유형(ClusterIP, Headless, NodePort, LoadBalancer, Loopback)과 이름 있는 포트 맵을 선언합니다. 포트 이름은 Workload의 다른 곳에서 선언된 컨테이너 포트 이름과 일치해야 합니다:

services:
http:
type: ClusterIP
ports:
web: 8080 # must exist in containers.<name>.ports

하나의 Workload에 여러 서비스를 두는 것은 내부 트래픽과 외부 트래픽을 따로 노출할 때 흔히 쓰입니다(클러스터 내부 소비자를 위한 내부 ClusterIP, 외부 트래픽을 위한 LoadBalancer, Prometheus 스크래핑을 위한 ClusterIP).

서비스 포트의 도달 범위. type이 이를 나타내며, 각 대상은 이를 자체 방식으로 렌더링합니다:

type도달 범위helmcompose
ClusterIP대상 자체 네트워크상의 워크로드 피어유형이 ClusterIP인 Service아무것도 게시하지 않으며, 피어는 compose 네트워크에서 포트에 도달합니다
Headless위와 같되 클러스터 주소 없음clusterIP: None이 지정된 유형 ClusterIP의 Service아무것도 게시하지 않음
NodePort대상 자체 네트워크 너머유형이 NodePort인 Service각 포트를 모든 호스트 인터페이스에 <service port>:<container port> 형태로 게시
LoadBalancer대상 자체 네트워크 너머유형이 LoadBalancer인 ServiceNodePort와 동일
Loopback호스트 자체의 루프백 주소만서비스를 명시하며 빌드를 중단합니다각 포트를 IPv4 루프백 주소에 127.0.0.1:<service port>:<container port> 형태로 게시

서비스 포트의 번호와 그것이 지정하는 컨테이너 포트는 Kubernetes Service의 port와 targetPort처럼 서로 다른 두 숫자입니다. helm은 항목의 번호를 Service의 port로 쓰고 컨테이너 포트를 이름으로 대상 지정하며, compose는 항목의 번호를 호스트에 게시하여 컨테이너 포트의 번호로 연결합니다. 두 숫자가 같으면 compose는 양쪽에 그 숫자를 씁니다.

Loopback은 같은 머신의 무언가(호스트에서 실행되는 브라우저나 에이전트)가 도달하고, 그 밖의 어떤 것도 도달해서는 안 되는 포트를 위한 것입니다. compose에서는 IPv4 루프백 주소에만 바인딩됩니다. IPv6 루프백 주소 ::1은 바인딩되지 않으므로, ::1로 해석될 수 있는 이름 대신 127.0.0.1로 포트에 접근하십시오. 선언된 전송 프로토콜은 다른 게시 포트와 마찬가지로 항목에 표기됩니다(예: 127.0.0.1:5514:5514/udp).

두 항목이 같은 포트를 지정하면 더 넓은 도달 범위가 우선합니다. NodePort 또는 LoadBalancer 항목이 게시하는 포트는 Loopback 항목이 함께 지정하더라도, 둘 중 어느 것이 먼저 선언되었는지와 관계없이 모든 인터페이스에 게시됩니다.

helm에서 Loopback 항목은 실제와 다른 무언가로 렌더링되는 대신 빌드를 중단시킵니다. Kubernetes Service에는 호스트의 루프백 주소에 바인딩하는 유형이 없습니다. NodePort Service가 어떤 노드 주소에서 수신하는지는 개별 Service가 아니라 클러스터 전체의 설정입니다. 따라서 ClusterIP Service는 항목이 요구하는 도달 범위를 잃게 되고, NodePort Service는 클러스터가 허용하는 모든 노드 주소에 포트를 게시하게 됩니다. 중단 시 노드와 서비스가 명시됩니다. A service type the helm provider cannot render (helm provider가 렌더링할 수 없는 서비스 유형)를 참조하십시오.

합성 이름 관례. helm provider가 Workload의 서비스를 합성할 때, 각 Service의 metadata.name은 워크로드 자체 컨트롤러가 가지는 이름과 서비스의 작성 키로부터 결정적으로 도출됩니다. 컴포넌트의 Workload에서 그 이름은 노드의 release 이름입니다: <release name>-<service-key>. release 이름은 Kubernetes 이름이 허용하는 문자 집합으로 작성된 component의 식별자로, 차트가 렌더링에 사용하는 것과 같은 이름이며 Recipe의 템플릿에서 {{ .context.rendered_name }}로 읽을 수 있습니다. 따라서 식별자에 밑줄과 대문자가 없는 경우에는 instance_id와 같습니다. 노드 api-server에서 services.http를 선언한 Workload는 api-server-http라는 Service를 생성하고, 같은 Workload가 노드 billing에서는 billing-http를, 노드 my_api에서는 my-zuapi-http를 생성합니다. 출력 파일 이름도 같은 관례를 따릅니다: <release name>-<service-key>-service.yaml. 이러한 Service의 주소를 게시하는 Recipe는 이를 {{ .context.rendered_name }}로 구성하며, 결코 {{ .context.instance_id }}로 구성하지 않습니다. 두 값이 다른 경우 후자는 어떤 Service도 가리키지 않기 때문입니다. ../templates/rendered-resource-names.md를 참조하십시오.

Feature 첨부의 FeatureRecipe가 합성하는 Workload는 release 이름이 아니라 첨부 자체의 합성된 식별자를 따라 이름이 지어집니다. 이는 그 리소스가 aggrega.ai/component-id 레이블에 가지는 값으로, 호스트 컴포넌트와 features: 아래에 작성된 키로 구성되며 앞에 cfr--가 붙습니다. 거기서 도출된 release 이름은 호스트의 이름이 되어, 첨부의 리소스를 호스트 자체 리소스의 이름으로 짓게 됩니다. 따라서 노드 front-door의 첨부 stats에 대해, Workload가 services.scrape를 선언하는 FeatureRecipe는 Deployment cfr--front-door--stats와 Service cfr--front-door--stats-scrape를 생성합니다. 이 첫 번째 세그먼트는 결코 instance_id와 같지 않으며, FeatureRecipe의 템플릿 컨텍스트에 이를 담는 키는 없습니다. 첨부의 템플릿에서 {{ .context.rendered_name }}와 {{ .context.instance_id }}는 모두 호스트(front-door)를 가리키고, {{ .attachment_name }}는 키 자체(stats)입니다. 따라서 {{ .context.rendered_name }}-scrape는 호스트가 scrape Service를 선언한 경우 호스트 자체의 그 Service를 가리키며, 결코 첨부의 Service를 가리키지 않습니다. ../templates/rendered-resource-names.md를 참조하십시오. 출력 파일은 첨부가 내보내는 모든 파일이 가지는 접두사(호스트의 이름과 첨부의 이름, 각각 뒤에 --가 붙음) 뒤에 위치하므로, 그 Service는 front-door--stats--cfr--front-door--stats-scrape-service.yaml에 기록됩니다.

이 관례에는 두 가지 실질적인 결과가 있습니다. 첫째, 노드 간 충돌은 구조상 불가능합니다. 이름 접두사가 경계 내 모든 노드에 걸쳐 서비스를 구별하기 때문입니다. 서로 다른 두 식별자는 항상 서로 다른 두 release 이름이 되고, 첨부의 식별자는 호스트와 키를 모두 담으며, 어떤 컴포넌트 이름도 cfr--로 시작할 수 없습니다(그렇게 시작하는 이름이 있으면 빌드가 중단됩니다. Component identity cannot be stamped on what it emits (Component 식별자를 그것이 내보내는 것에 찍을 수 없음) 참조). 따라서 각각 services.http를 선언하는 두 Workload는 이름이 겹치지 않는 별개의 K8s Service 리소스를 생성합니다. 유일하게 남는 예외는 대상에 비해 너무 긴 첨부 식별자입니다. 이는 전체의 다이제스트를 중심으로 단축되며, 단축된 두 식별자는 원칙적으로 일치할 수 있습니다. 렌더링된 출력에 붙는 출처 레이블을 참조하십시오. 둘째, Workload는 하나의 서비스 키를 두 번 선언할 수 없습니다. 키를 두 번 지정한 services: 맵은 Workload의 YAML을 파싱할 때 거부되며, 빌드는 해당 키와 그 줄을 명시하며 중단됩니다.

남아 있는 충돌 위험은 K8s 이름 길이 경계에 있습니다. Kubernetes Service 이름은 최대 63자이며, 합성된 <release name>-<service-key> 형태는 두 부분이 모두 길면 이 한도를 넘을 수 있습니다. Aggrega 컴파일러는 이 한도를 강제하지 않습니다. 빌드는 Service를 내보내고, Kubernetes가 적용 시점에 이를 거부합니다. 깊게 중첩된 인스턴스 ID(예: data-layer.regional.eu-west.primary)에 긴 서비스 키를 함께 쓰는 경우 합친 길이를 63자 미만으로 유지해야 합니다. 첨부의 Workload도 마찬가지입니다. 대상에 비해 너무 긴 합성 식별자는 단축되지만 그 뒤에 덧붙는 서비스 키는 단축되지 않으므로, 긴 키를 가진 첨부 Service는 여전히 63자를 넘을 수 있고 빌드는 중단되지 않습니다.

Provider별 참고 사항(compose). compose provider는 IR uses 엣지로부터 depends_on을 자동으로 도출합니다. 이 항목들은 조건 없이 출력됩니다. 대상이 healthcheck를 선언했는지와 관계없이 service_started 의미를 가지므로, 의존성이 모두 uses 엣지에서 오는 서비스는 짧은 형식의 목록(depends_on: [<target>])을 출력합니다. 엣지에서 도출된 항목을 대상의 상태에 따라 조건화하는 기능은 구현되어 있지 않습니다. 긴 형식은 항목이 실제로 조건을 가질 때 출력되며, init 컨테이너에 대한 대기가 이렇게 표현됩니다. providers/compose.md를 참조하십시오.

포트 전송 프로토콜

컨테이너 포트는 동등한 두 가지 형식 중 하나로 작성합니다. 숫자만 쓰는 것이 짧은 형식이며 전송 프로토콜을 선언하지 않으므로, 대상이 자체 기본값을 적용합니다. 기본값이 있는 모든 대상에서 기본값은 TCP입니다.

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080

확장 형식은 번호와 전송 프로토콜을 함께 담으며, 포트가 그 기본값 이외의 것을 전달할 때 필요한 형식입니다.

containers:
main:
image: "{{ .values.image }}"
ports:
web: 8080 # short form — no transport declared
dns:
port: 53
protocol: UDP # TCP | UDP | SCTP
sigtran:
port: 2905
protocol: SCTP

하나의 ports 맵 안에서 두 형식을 자유롭게 섞어 쓸 수 있으며, 선언할 전송 프로토콜이 없는 포트는 짧은 형식으로 둡니다.

전송 프로토콜은 컨테이너 포트에서 한 번만 선언합니다. services.<service>.ports 항목은 컨테이너 포트를 지정하고 그 포트의 전송 프로토콜을 함께 가져가므로, 서비스 노출이 컨테이너가 연 포트와 어긋날 수 없습니다. 서비스 포트에는 protocol 키가 없으며, 이를 작성하면 거부됩니다.

이 필드가 존재하는 이유. 배포 대상은 지정되지 않은 전송 프로토콜을 스트리밍 방식으로 취급합니다. 데이터그램 포트가 필요한 컴포넌트(실시간 미디어, 전화, 이름 확인, 사설 네트워킹, 게임 서버)는 그렇지 않으면 번호만 선언할 수 있고, 그러면 모든 검사를 통과한 채 스택이 배포되지만 어떤 클라이언트도 연결되지 않습니다. 트래픽은 데이터그램인데 열린 포트는 그렇지 않기 때문입니다. 전송 프로토콜을 선언하면 이를 표현할 수 있습니다.

컴파일러는 값을 해석하지 않습니다. 포트의 이름에서 전송 프로토콜을 읽어 내지 않으며, 선언된 전송 프로토콜을 포트 뒤의 프로세스가 실제로 사용하는 것과 대조하지도 않습니다. 이 값은 사용자가 선언하고 대상의 엔진이 출력하는 데이터입니다. protocol 키가 없는 dns라는 이름의 포트는 TCP 포트이고, protocol: UDP를 선언한 web이라는 이름의 포트는 UDP 포트입니다.

대상별 동작.

대상전송 프로토콜이 선언되지 않은 포트선언된 전송 프로토콜
helmcontainerPort와 Service 포트에 protocol 키가 없음컨테이너 포트와 이를 지정하는 모든 Service 포트에 protocol:로 그대로 출력됨
compose<host>:<container>로 변경 없이 게시됨<host>:<container>/tcp 또는 /udp로 게시됨. SCTP는 compose 표기가 없으므로 다른 전송 프로토콜을 전달하게 될 포트를 게시하는 대신 빌드를 중단함

어떤 서비스도 게시하지 않는 컨테이너 포트는 compose 파일의 어느 부분에도 나타나지 않습니다. 이는 컨테이너 포트에 대한 compose의 기본 동작입니다. 따라서 그런 포트에 선언된 전송 프로토콜은 표기될 곳이 없으며 빌드를 중단하지 않습니다.

헬스 프로브 — 의도 형태

각 컨테이너는 자신의 health: 키(containers.<name>.health) 아래에 추상적인 의도 형태로 프로브를 선언하며, Workload에는 최상위 health가 없습니다. 각 provider는 합성 시점에 이 의도를 자신의 네이티브 프로브 형태로 변환합니다.

health:
ready:
http: /healthz # intent: HTTP GET probe
timeoutSeconds: 5
live:
tcp: 8080 # intent: TCP socket check
timeoutSeconds: 5
startup:
exec: ["check-ready.sh"] # intent: command exec
timeoutSeconds: 30
periodSeconds: 10

세 가지 의도 형태(http:, tcp:, exec:)는 하나의 프로브 선언 안에서 상호 배타적입니다. 명시적인 포트가 없는 http:의 포트 결정은 컨테이너가 containers.<name>.ports 아래에 선언한 포트 이름 중 알파벳 순으로 첫 번째인 것을 사용합니다. 두 대상 모두에 같은 규칙이 적용되므로, 어느 대상이 렌더링하든 프로브는 같은 포트를 읽습니다. 이름이 있는 포트를 선언하지 않은 컨테이너는 HTTP 프로브를 가질 수 없습니다. 이 경우 문제가 된 프로브를 명시하는 변환 오류와 함께 빌드가 중단됩니다.

provider별 변환. 각 provider는 합성 시점에 추상 프로브 의도를 자신의 네이티브 형태로 변환합니다.

의도Helm (K8s)Compose손실 사항
http: /pathhttpGet.path: /path, httpGet.port: <alphabetically-first port name>CMD-SHELL "curl -f http://localhost:<port>/path"Compose에는 네이티브 HTTP 프로브 형태가 없습니다. CMD-SHELL 래퍼는 컨테이너 이미지에 curl이 있어야 동작합니다.
tcp: <port>tcpSocket.port: <port>CMD-SHELL "nc -z localhost <port>"Compose에는 네이티브 TCP 프로브 형태가 없습니다. CMD-SHELL 래퍼는 컨테이너 이미지에 nc가 있어야 동작합니다.
exec: [cmd, ...]exec.command: [cmd, ...]CMD [cmd, ...]일대일 매핑입니다. 두 provider 모두 명령 목록을 그대로 전달합니다.

Compose의 CMD-SHELL 래퍼는 셸에서 평가 가능한 조건식으로 HTTP 및 TCP 프로브를 근사합니다. compose에 없는 것은 네이티브 프로브 형태이지 타이밍 필드가 아닙니다. 작성된 periodSeconds, timeoutSeconds, failureThreshold, initialDelaySeconds는 healthcheck에 각각 interval, timeout, retries, start_period로 옮겨집니다. 필드별 매핑은 providers/compose.md의 “Probes”에 있습니다. 네이티브 exec: 형태는 래퍼가 전혀 필요 없으며 두 대상 모두에서 일대일로 변환됩니다.

래핑된 프로브는 조용히 변환됩니다. 출력된 docker-compose.yaml에는 이를 표시하는 내용이 없으며, 래핑을 보고하는 진단도 없습니다. 이 경로에서 빌드가 실제로 보고하는 것은 출력에 전혀 도달하지 않는 프로브 슬롯입니다. compose 서비스는 healthcheck를 하나만 가지므로, Workload가 ready:, live:, startup: 중 둘 이상을 선언하면 우선순위가 가장 높은 슬롯만 변환되고(live, ready, startup 순), unsupported-field 경고가 변환된 슬롯과 버려진 슬롯을 알려 줍니다.

Provider별 참고 사항(compose). compose를 대상으로 하는 Workload에 health: 블록을 작성해도 depends_on 순서가 health에 따라 제어되지 않습니다. uses: 엣지에서 파생된 compose provider의 depends_on 항목은 대상 Workload가 health probe를 선언하는지와 관계없이 항상 service_started 의미 체계를 사용합니다. 이러한 항목을 대상의 health에 따라 제어하는 기능은 구현되어 있지 않습니다. 그러한 조건을 담을 긴 형식 자체는 init 컨테이너 대기를 위해 출력되므로, 빠져 있는 것은 이를 표현할 형식이 아니라 엣지를 health에 따라 제어하도록 선택하는 기능입니다. 전체 추론 규칙은 providers/compose.md를 참조하십시오.

K8s 형태의 패스스루 필드 — scheduling, serviceAccount, podSecurityContext

Workload 스키마는 세 가지 선택적 최상위 필드를 허용합니다. 이 필드들은 주로 Aggrega의 구조적 형태를 유지하면서 Kubernetes 네이티브 기본 요소를 helm provider로 전달하기 위해 존재합니다. compose provider는 Compose에 대응 개념이 있는 부분을 변환하고, 나머지는 경고를 출력하며 무시합니다. Aggrega는 바깥 형태를 검증하지만 안쪽 내용은 검사하지 않습니다(아래의 검증 범위 참조). K8s 네이티브 안쪽 값은 helm으로 렌더링된 pod spec에 그대로 전달됩니다.

scheduling

scheduling은 네 가지 K8s 네이티브 스케줄링 기본 요소인 nodeSelector, affinity, tolerations, topologySpreadConstraints를 목적별로 키가 지정된 하나의 블록으로 묶습니다. 각 하위 필드는 대응하는 Kubernetes pod-spec 필드와 정확히 같은 형태입니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
scheduling:
nodeSelector:
disktype: ssd
region: us-east-1
tolerations:
- key: dedicated
operator: Equal
value: gpu-workloads
effect: NoSchedule
affinity:
podAntiAffinity:
preferredDuringSchedulingIgnoredDuringExecution:
- weight: 100
podAffinityTerm:
labelSelector:
matchLabels: { app: "{{ .context.instance_id }}" }
topologyKey: kubernetes.io/hostname
topologySpreadConstraints:
- maxSkew: 1
topologyKey: topology.kubernetes.io/zone
whenUnsatisfiable: ScheduleAnyway
containers:
app: { image: "..." }

Provider 변환. helm 프로바이더는 각 하위 필드를 렌더링된 pod spec에 그대로 전달합니다. compose 프로바이더는 네 가지 중 어느 것도 변환하지 않습니다. scheduling 블록 전체를 생략하고, 이를 명시하는 경고를 출력합니다.

serviceAccount

serviceAccount는 워크로드가 실행될 ServiceAccount의 이름을 담는 일반 문자열입니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
serviceAccount: "{{ .context.rendered_name }}-runner"
containers:
app: { image: "..." }

이 이름은 helm provider가 워크로드 자체 리소스의 이름에 사용하는 릴리스 이름인 {{ .context.rendered_name }}으로 만들어지므로, 컴포넌트의 이름이 무엇이든 클러스터가 허용하는 이름이 됩니다. 이 필드는 기존 ServiceAccount를 참조할 뿐 새로 생성하지 않습니다. 함께 필요한 RBAC 리소스(ServiceAccount 객체 자체와 Role / RoleBinding / ClusterRole / ClusterRoleBinding)는 다음 두 경로 중 하나로 제공해야 합니다.

  • Recipe artifacts: — RBAC가 이 Recipe에 고유한 경우(Recipe가 특정 작업을 위해 특정 Role이 필요하다는 것을 아는 경우).
  • 리소스 생성을 사용하는 Features — RBAC가 여러 영역에 걸치는 경우(특정 레이블을 가진 모든 컴포넌트에 IAM에 바인딩된 ServiceAccount를 연결하는 Workload-Identity FeatureRecipe).

지정한 ServiceAccount가 존재하도록 준비하지 않고 serviceAccount:를 설정하면 빌드 시점 오류가 아니라 적용 시점에 K8s 런타임 오류가 발생합니다. 워크로드 스키마 검증은 ServiceAccount의 존재 여부를 교차 확인하지 않습니다(AOT 순수성 불변 조건에 따라 컴파일 시점에는 클러스터 상태에 접근할 수 없습니다).

compose provider는 경고와 함께 serviceAccount:를 무시합니다. Compose에는 이에 해당하는 ID 바인딩 개념이 없습니다.

podSecurityContext

podSecurityContext는 pod 내 모든 컨테이너에 적용되는 pod 수준 보안 기본 요소(UID, GID, fsGroup, supplementalGroups)를 담습니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
podSecurityContext:
runAsUser: 1000
runAsGroup: 3000
fsGroup: 2000
supplementalGroups: [4000, 5000]
containers:
app: { image: "..." }

필드 의미. 네 필드는 모두 정수입니다(문자열이 아닌 숫자 UID/GID). runAsUser와 runAsGroup은 컨테이너 프로세스의 유효 UID/GID를 설정하고, fsGroup은 pod에 마운트된 볼륨의 그룹 소유권을 설정하며, supplementalGroups는 각 컨테이너의 프로세스 그룹에 추가 GID를 더합니다.

Provider 변환. helm 프로바이더는 이 블록을 렌더링된 pod spec에 그대로 전달합니다. compose 프로바이더에는 fsGroup이나 supplementalGroups에 해당하는 기능이 없어 각각을 경고와 함께 생략합니다. runAsUser/runAsGroup은 Workload가 생성하는 모든 서비스(사이드카와 init 컨테이너 포함)에서 Compose의 user: 1000:3000 형태로 변환되며, 옆에 runAsUser가 없는 runAsGroup은 경고와 함께 생략됩니다. 각 컨테이너와 init 컨테이너도 자체 securityContext를 가집니다. 즉 runAsUser, runAsGroup, runAsNonRoot, readOnlyRootFilesystem, allowPrivilegeEscalation, 그리고 capabilities.add / capabilities.drop입니다. helm 프로바이더는 이를 컨테이너에 내보냅니다. compose 프로바이더는 readOnlyRootFilesystem을 read_only로, capabilities.add / capabilities.drop을 cap_add / cap_drop으로, runAsUser / runAsGroup을 컨테이너 자체의 user로 내보내며, 이것이 pod의 값을 대신합니다. runAsNonRoot, allowPrivilegeEscalation, 그리고 runAsUser 없이 작성된 runAsGroup은 각각 경고와 함께 생략하며, 컨테이너 자체의 runAsUser 때문에 pod의 runAsGroup이 빠지는 경우에도 경고합니다. 필드별 매핑은 providers/compose.md에 있습니다.

GPU 및 장치 워크로드

GPU나 그 밖의 벤더 제공 장치 같은 특수 하드웨어가 필요한 워크로드는 서로 독립적인 두 가지 관심사를 표현합니다. 하나는 장치를 지원하는 노드가 노출하는 파드 수준 런타임(runtimeClassName)이고, 다른 하나는 워크로드가 요청하는 컨테이너별 장치 수량(컨테이너의 resources 아래 확장 리소스 키)입니다. 일반적인 GPU 워크로드는 둘을 함께 선언하지만, 각각은 독립적이며 어느 한쪽만 나타날 수도 있습니다.

두 필드는 모두 컴퓨팅, 즉 장치 위에서 실행되는 파드와 컨테이너를 기술하므로 컨테이너를 실행하는 워크로드에 속합니다. 외부 엔드포인트만 가지고 자체 컨테이너를 선언하지 않는 워크로드에는 이를 붙일 파드나 컨테이너가 없습니다. 이러한 엔드포인트 전용 워크로드에 runtimeClassName을 설정하면 runtimeClassName과 이를 선언한 Workload의 Recipe를 명시하며 빌드가 중단되고, 컨테이너가 없으므로 장치 리소스 요청을 둘 곳도 없습니다.

runtimeClassName

runtimeClassName은 파드가 실행될 RuntimeClass, 즉 장치를 지원하는 노드가 노출하는 컨테이너 런타임(예: nvidia라는 이름의 GPU 런타임)을 지정하는 단일 문자열입니다. 이는 파드 수준 선택자로, 워크로드의 모든 컨테이너에 적용됩니다. 컴파일러는 이 이름을 결정적 포인터로서 그대로 전달하고, 클러스터는 스케줄 시점에 이를 관리자가 구성한 RuntimeClass로 해석합니다. Aggrega는 일치하는 RuntimeClass가 존재하는지 확인하지 않습니다. 컴파일 시점에 클러스터 상태에 접근할 수 없기 때문입니다. 따라서 구성된 RuntimeClass가 없는 이름은 빌드 시점 오류가 아니라 적용 시점의 스케줄링 오류로 드러납니다.

확장 리소스 키

컨테이너의 resources.requests와 resources.limits에는 일반적인 cpu 및 memory 수량과 함께 확장 리소스 키가 들어갑니다. 확장 리소스 키는 nvidia.com/gpu나 amd.com/gpu처럼 완전한 <domain>/<name> 형식의 이름을 키로 하는, 벤더 또는 도메인 범위의 장치 수량입니다. 도메인 부분에는 점이 하나 이상 있으며, 이 점이 확장 키(nvidia.com/gpu)를 접두사 없는 cpu 및 memory 수량과 구별합니다. 각 값은 컴파일러가 그대로 전달하는 문자열 수량("1", "2")이며, helm 프로바이더는 이를 출력하기 전에 형식을 검사합니다(리소스 수량 참고). 클러스터의 장치 플러그인은 스케줄 시점에 장치를 해석하고 할당합니다.

실전 예제 — GPU 추론 워크로드

apiVersion: aggrega.ai/v1beta1
kind: Workload
runtimeClassName: nvidia
containers:
inference:
image: "{{ .values.image }}"
resources:
requests:
cpu: "2"
memory: "8Gi"
nvidia.com/gpu: "1"
limits:
nvidia.com/gpu: "1"

이 워크로드는 파드에 nvidia 런타임을 선택하고 inference 컨테이너에 GPU 하나를 요청합니다. GPU 수량은 requests와 limits 양쪽에 나타납니다. 장치는 초과 할당할 수 없으므로 요청과 제한을 같은 값으로 설정합니다.

프로바이더 변환. 이들은 Kubernetes 고유 개념입니다. helm 프로바이더는 렌더링된 파드 스펙에 runtimeClassName을 출력하고, 각 확장 리소스 키를 컨테이너의 resources.requests / resources.limits 아래에 그대로 출력하므로, 이들은 Kubernetes 출력을 통해 클러스터에 도달합니다. compose 프로바이더는 nvidia.com/gpu 개수만큼의 NVIDIA GPU를 컨테이너의 서비스에 예약합니다(Compose Provider → 컨테이너 리소스 참고). 단일 호스트에는 런타임 클래스 개념이 없고 다른 확장 리소스 키에 대응하는 것도 없으므로, runtimeClassName이나 다른 키를 선언한 워크로드는 compose 대상에서 해당 항목 없이 렌더링됩니다.

노드의 네트워크에서 실행하기

기본적으로 워크로드는 자체 네트워크 네임스페이스에서 실행됩니다. 컨테이너는 자신의 인터페이스만 보며, 트래픽은 대상의 주소 변환을 거쳐 컨테이너에 도달합니다. hostNetwork: true는 다른 방식을 요청합니다. 워크로드는 노드 자체의 네트워크 네임스페이스에서 실행되므로 노드의 인터페이스를 보며, 컨테이너가 여는 포트는 중간 변환 없이 노드 자체의 주소에서 접근할 수 있습니다.

이는 특정 부류의 소프트웨어 전체에 필요한 방식입니다. 실시간 미디어, 전화, 가상 사설망 및 이와 유사한 트래픽은 페이로드 안에 상대방의 주소를 담으므로, 전송 중에 재작성된 주소는 상대방이 도달할 수 없는 곳을 가리킨 채 도착합니다. 노드의 주소에서 실행하면 두 주소가 일관되게 유지됩니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
hostNetwork: true
containers:
media:
image: "{{ .values.image }}"
ports:
rtp:
port: 7881
protocol: UDP

선언하는 것과 선언하지 않는 것

hostNetwork는 네트워크 네임스페이스를 선택하며, 그것이 전부입니다.

  • 포트를 선언하지 않습니다. 워크로드가 여는 포트는 이 필드가 없을 때와 똑같이 여전히 containers.<name>.ports 아래에 선언하며, 의미도 그대로입니다. hostNetwork를 선언해도 포트가 추가되지 않으며, 포트를 선언할 필요가 없어지지도 않습니다.
  • 포트의 개수를 선언하지 않습니다. 연속된 많은 포트가 필요한 애플리케이션(예: 머신의 프로세서 수에 맞춰 범위를 정하는 미디어 서버)은 시작 시 읽는 다른 모든 설정과 마찬가지로, 운영자가 제공하는 값을 바탕으로 자체 구성 본문에서 그 범위를 구성합니다. 이는 워크로드 설정이 아니라 애플리케이션 설정이며, 워크로드 계약에 둘 항목이 아닙니다.
  • 아무것도 추론하지 않습니다. 컴파일러는 이 값에서 의미를 읽지 않으며 다른 어떤 것에서도 이 값을 도출하지 않습니다. 포트 이름, 컴포넌트의 유형이나 레이블, 선언된 포트 수에서도 도출하지 않습니다. 워크로드는 그렇게 명시할 때, 그리고 그때에만 노드의 네트워크에서 실행됩니다.

hostNetwork는 컴퓨팅을 기술하므로 컨테이너를 실행하는 워크로드에 속합니다. 외부 엔드포인트만 가진 워크로드는 컨테이너를 선언하지 않으므로 선택할 네트워크 네임스페이스가 없습니다. 엔드포인트 전용 워크로드에 hostNetwork를 선언하면 hostNetwork와 이를 선언한 Workload의 Recipe를 명시하며 빌드가 중단됩니다.

Provider 변환

helm 프로바이더는 렌더링된 파드 스펙에 hostNetwork: true를 출력하며, 이는 Kubernetes가 같은 선택을 표현하는 방식입니다. 이 선언은 파드 스펙에만 반영되고 그 밖의 어디에도 영향을 주지 않습니다. 출력되는 Service는 이 선언의 유무와 관계없이 동일합니다.

compose 프로바이더는 워크로드 자체 서비스에 network_mode: host를 출력합니다. compose가 네트워크를 모델링하는 방식에서 한 가지 결과가 따릅니다. 이 모드의 서비스는 경계 네트워크에 연결되지 않는데, compose는 네트워크에 연결하는 것과 호스트의 네임스페이스를 채택하는 것을 함께 할 수 있는 것이 아니라 양자택일로 취급하기 때문입니다. 따라서 피어는 서비스 이름 대신 호스트 자체의 주소로 이 서비스에 접근하며(이는 어느 대상에서든 호스트 네트워킹이 뜻하는 바입니다), 경계의 다른 모든 서비스는 영향을 받지 않습니다.

이 대상에서 두 가지 형태가 이와 함께 구성됩니다. 사이드카 컨테이너는 아무것도 선언하지 않고도 메인 서비스를 따라 호스트의 네트워크로 갑니다. 메인 서비스를 지정하여 그 네임스페이스를 사용하기 때문입니다. init 컨테이너는 그렇지 않습니다. init 컨테이너는 메인 서비스가 기다리는 서비스가 되므로, 그 대기를 순환으로 만들 네임스페이스를 채택하는 대신 자체적으로 경계 네트워크에 참여합니다. 따라서 hostNetwork와 initContainers를 모두 선언한 워크로드는 자체 서비스를 노드의 네트워크에서 실행하고 init 서비스는 경계 네트워크에 남깁니다. 이는 파드 형태가 제공하는 단일 공유 네임스페이스보다 좁은 배치이며, compose 프로바이더는 이를 실행 시점에 발견되도록 두지 않고 unsupported-field 경고로 명시합니다.

hostNetwork를 선언하지 않은 워크로드는 출력에 해당 키를 갖지 않습니다. 키는 false로 출력되는 것이 아니라 아예 없습니다.

Component의 featuresSchema와의 attachment 통합

Workload의 containers.<name>.attachments 블록은 Component의 featuresSchema에 선언된 자격 증명 슬롯을 참조하며, 연결을 지정하는 항목의 경우 그 연결의 소켓이 선언하는 슬롯을 참조합니다(연결이 전달하는 자격 증명 제공 참조). 새 슬롯을 선언하지는 않습니다. featuresSchema 작성 방법은 ../entities/component.md를 참조하십시오. from은 슬롯을 지정하며, 생성되는 Secret의 이름이 아닙니다.

containers.<name>.attachments 항목은 Secret 리소스에 대한 참조, 즉 Kubernetes secretKeyRef(as: env의 경우) 또는 Secret 기반 볼륨(as: file의 경우)으로 렌더링되며, 둘 다 Secret을 이름으로 가리킵니다. 합성기는 그 이름과 데이터 키를 슬롯이 노출하는 provides에서 결정합니다. 항목의 렌더링된 secretKeyRef.name은 슬롯의 .features.<slot>.provides.name이고 데이터 키는 .features.<slot>.provides.key입니다. Recipe 작성자는 from: <slot>과 as: env만 작성하며, 합성기는 결정된 provides를 읽을 뿐 이름을 다시 도출하지 않습니다. 이는 소스 Recipe가 existingSecret에 사용하는 것과 같은 .features.<slot>.provides.<key> 읽기입니다. 하나의 자격 증명 슬롯이 소스 Recipe 소비자와 합성된 Workload 소비자 모두에 동일하게 공급됩니다(소스/workload 대칭).

이 통합에는 네 가지 검증 규칙이 적용됩니다.

  • 모든 attachments.<KEY>.from 값은 Component의 featuresSchema에, 또는 연결을 지정하는 항목의 경우 그 연결의 소켓에 선언된 슬롯 이름과 일치해야 합니다. 알 수 없는 슬롯 이름은 로드 시점 오류입니다.
  • as: 전달 방식(env 또는 file)은 Component가 선언한 슬롯의 inject: 허용 목록에 있어야 합니다. featuresSchema 항목이 inject: [env]를 지정한 슬롯에 대해 as: file을 선언하는 Workload는 로드 시점 오류입니다.
  • Component의 featuresSchema에서 inject: [](블랙박스 전달)로 표시된 슬롯은 Workload attachments: 블록에 전혀 나타날 수 없습니다. 이러한 슬롯은 Workload 노출이 아니라 Recipe의 내부 배선(예: Helm 차트의 existingSecret 파라미터)으로 전달됩니다.
  • 참조되는 슬롯은 참조 가능해야 합니다. 즉, 그 채움이 Secret 리소스(실현 과정에서 생성되는 것이든 이미 존재하는 것이든)에 대한 provides 위치 지정자(name, key)를 게시해야 합니다. inject로 전달되는 자격 증명(inject 파이프에 값을 쓰고 위치 지정자를 게시하지 않는 자격 증명)으로 채워진 슬롯은 가리킬 대상이 없으므로, Workload attachments: 항목에서 이를 참조하면 로드 시점 오류입니다. inject로 전달되는 자격 증명은 attachments: 항목이 아니라 슬롯의 inject 파이프(.context.inject.env.<KEY>를 읽는 variables 항목)를 통해 컨테이너에 도달합니다.

Provider 참고. Helm은 위에서 설명한 secretKeyRef/Secret 볼륨 참조를 렌더링합니다. compose provider에는 Secret에서 환경 변수를 가져오는 네이티브 기본 요소가 없으므로, compose 대상 Workload의 as: env attachment 항목은 빈 값의 환경 항목과 해당 항목을 지정하는 경고로 렌더링됩니다(compose provider 페이지 참조). 이때에도 참조 가능성 규칙(기능에 구애받지 않는)은 그대로 적용됩니다.

예:

# In the Component catalog entity
spec:
featuresSchema:
db_password:
required: true
inject: [env, file] # transparent: Workload may dictate delivery
root_password:
required: true
inject: [] # blackbox: Recipe handles internally
# In the Recipe's Workload
workload: |
containers:
main:
attachments:
DB_PASSWORD: # OK — db_password slot allows env inject
from: db_password
as: env
# ROOT_PASSWORD: ... # rejected at load time: blackbox slot

연결이 전달하는 자격 증명 제공

Component의 소켓은 usesSchema.<socket>.featuresSchema에서 그 소켓을 통해 배선된 각 연결이 채우는 슬롯을 선언할 수 있습니다. 따라서 여러 대상에 도달하는 component는 모든 대상에 하나가 아니라 연결마다 하나의 자격 증명을 가집니다. 이러한 attachment는 component 자체의 .features에 속하지 않고 그 연결 아래인 .context.uses.<alias>.features.<slot>에 위치합니다. Workload 항목은 슬롯 옆에 연결을 지정하여 이를 전달합니다.

  • 컨테이너의 attachments 항목에서는 from: <slot> 옆에 connection: <alias>를 지정합니다.
  • 컨테이너의 envFrom 항목에서는 secret: <slot> 옆에 connection: <alias>를 지정합니다. connection은 secret 옆에서만 허용됩니다.

두 형식 모두 모든 컨테이너와 모든 init 컨테이너에서 허용됩니다. <alias>는 Aggregate 또는 Release에서 component의 uses 블록에 연결이 작성된 이름, 즉 Recipe가 .context.uses 아래에서 그 연결을 읽을 때 쓰는 키이며, <slot>은 그 연결이 배선된 소켓이 선언하는 슬롯입니다.

위의 어떤 규칙이 Workload를 읽기 전에, 연결을 지정하는 각 항목은 그 연결이 해당 슬롯에 전달하는 attachment가 component에서 갖는 이름, 즉 별칭, 점, 슬롯(gpt.credential)으로 다시 작성됩니다. 이후 모든 규칙은 Component 자체의 슬롯을 지정하는 항목에서와 똑같이 다시 작성된 항목에 실행됩니다. 소켓 슬롯의 inject: 허용 목록이 as:를 제어하고, inject: []를 선언한 소켓 슬롯은 참조할 수 없으며, 그 슬롯을 채우는 attachment는 참조 가능해야 하고, provider는 그 attachment의 결정된 provides에서 Secret의 이름과 데이터 키를 결정합니다. 따라서 각 연결의 항목은 그 연결 자체의 자격 증명을 참조합니다. sensitive: true를 선언한 소켓 슬롯은 Component 슬롯의 선언과 똑같이 항목에 반영됩니다. provider가 받는 것은 다시 작성된 항목이며, connection 키는 provider에 전달되지 않습니다.

다음 세 가지 항목은 거부되며, 각 거부는 항목이 지정한 것을 명시합니다.

  • component가 사용하지 않는 연결을 지정하는 항목: 거부 메시지는 그 연결, 슬롯, 그리고 component가 사용하는 연결들을 명시합니다.
  • 연결의 소켓이 선언하지 않는 슬롯을 지정하는 항목: 거부 메시지는 그 슬롯, 연결, 소켓, 그리고 소켓이 선언하는 슬롯들을 명시합니다.
  • 조합된 이름(from: gpt.credential)을 직접 작성하는 항목. 연결의 슬롯은 연결을 지정하는 방식으로 지정하므로, 조합된 이름은 결코 그 슬롯에 도달하는 두 번째 방법이 아닙니다.

해당 슬롯에 attachment를 전달하지 않는 연결은 항목에 참조할 대상을 남기지 않으므로 참조 가능성 규칙이 이를 거부합니다. FeatureRecipe가 렌더링하는 Workload는 그것이 구현하는 Feature가 선언하는 슬롯으로 제한되며, 이 슬롯은 호스트 component의 어떤 연결에도 도달하지 않습니다. 따라서 그곳에서 연결을 지정하는 항목은 component가 사용하지 않는 연결을 지정한 것으로 거부됩니다.

예:

# In the Component catalog entity
spec:
usesSchema:
models:
featuresSchema:
credential:
sensitive: true
inject: [env]
# In the Recipe's Workload — the component draws connections `gpt` and `nim`
# through the `models` socket, each carrying its own `credential`
workload: |
containers:
main:
attachments:
MODEL_KEY_GPT:
from: credential
connection: gpt
as: env
MODEL_KEY_NIM:
from: credential
connection: nim
as: env

helm에서 MODEL_KEY_GPT는 gpt 연결의 자격 증명이 게시한 Secret을 지정하는 secretKeyRef로 렌더링되고, MODEL_KEY_NIM은 nim 연결의 자격 증명이 게시한 Secret을 지정하는 것으로 렌더링됩니다. compose에서는 연결을 지정하는 as: env 항목이 빈 값으로 생성되며, Component 자체의 슬롯을 지정하는 항목과 동일한 부분 지원 안내가 함께 표시됩니다.

검증 범위

모든 Workload는 렌더링이 실행되기 전에 Recipe 로드 시점에 검증됩니다. 검증은 두 단계로 이루어집니다.

  • 스키마 검증. Workload 값은 내장된 aggrega.ai/v1beta1 Workload 스키마와 통합(unify)됩니다. 오류에는 필드 경로와 위반된 제약 조건이 포함됩니다(예: .containers.main.health.ready: multiple oneOf branches matched (branches [0, 1] of 3): expected exactly one). 스키마 검증은 스키마에 선언된 모든 타입, enum, 범위, 분리(disjunction)를 강제합니다. 여기에는 닫힌 집합인 컨트롤러 form(stateless, stateful, daemon, scheduled, task, reference 중 하나), 닫힌 집합인 서비스 type(ClusterIP, Headless, NodePort, LoadBalancer, Loopback 중 하나), 정수 포트 범위(1..65535), 프로브 형태 분리(http, tcp, exec 중 정확히 하나), 볼륨 변형 분리(ephemeral, configmap, secret, persistent, persistentTemplate 중 정확히 하나)가 포함됩니다.
  • 교차 참조 검증. Workload의 attachment 참조는 Component의 featuresSchema에 대해 — 그리고 connection을 지정하는 항목의 경우 해당 connection의 socket이 선언하는 슬롯에 대해 — 검사되고(슬롯 소속 여부, as: 전달 허용 목록, 블랙박스 제외), 참조된 각 슬롯의 확정된 provides에 대해서도 검사됩니다(참조 가능성 — fill이 name/key를 게시해야 함). 이는 스키마만으로는 수행할 수 없는 엔터티 간 검사입니다.

두 단계 모두 CATALOG_ERROR 접두사가 붙은 동일한 형태의 메시지를 생성하며, 실패하면 렌더링 출력이 생성되기 전에 빌드가 중단됩니다. Recipe 작성자는 실패한 정확한 필드와 이를 거부한 제약 조건을 짚어 주는 피드백을 받습니다.

K8s 형태의 패스스루 필드(scheduling.affinity, scheduling.tolerations, scheduling.topologySpreadConstraints, ConfigMap 및 Secret 볼륨 내부의 items 목록, lifecycle httpGet 훅)는 구조적으로만 검증됩니다. Aggrega의 스키마는 이 필드의 존재와 외부 형태를 제약하지만, K8s API가 정의하는 이 값들의 내부 형태는 provider의 책임입니다(helm provider는 이를 K8s pod spec에 그대로 전달하고, compose provider는 상황에 따라 거부하거나 축소 적용합니다). 형태가 잘못된 affinity 값을 사용하는 Workload는 Aggrega 검증을 통과하고, 대신 provider 합성 중에 오류가 드러납니다.

리소스 수량도 마찬가지로 스키마에서는 문자열이므로, 어느 단계도 그 형식을 검사하지 않습니다. 합성하는 provider가 평가된 Workload에서 이를 검사하며, 수량 형식에 맞지 않는 값이 있으면 중단합니다. 리소스 수량을 참조하십시오.

보조 리소스는 Workload 외부에 둡니다

Workload는 워크로드의 형태만 기술합니다. 즉 컨테이너, 볼륨, 서비스, 레플리카, 스케줄링, 보안 컨텍스트, 서비스 계정입니다. additionalResources 필드는 없으며, ConfigMap / Secret / CRD를 인라인으로 선언할 수도 없습니다.

Recipe 작성자는 Workload 외부의 두 가지 경로를 통해 보조 리소스를 내보냅니다.

  • Recipe 수준의 artifacts: — 해당 Recipe에 고유한 리소스에 사용합니다(Recipe의 Workload가 참조하는 특정 ConfigMap, Recipe에 필요한 일회성 CRD 등록 등). 이 필드는 이름이 붙은 항목의 맵이며, 각 항목은 인라인으로 작성하거나 항목별 $import:로 불러옵니다. 세 가지 작성 방식은 ../../architecture/16-recipe-input-composition.md의 Artifacts Mechanism 절을 참조하십시오.
  • Resource Generation을 사용하는 Features — Release 셀렉터로 부착되는 횡단 관심사에 사용합니다(메트릭을 노출하는 모든 컴포넌트에 부착되는 ServiceMonitor Feature, 모든 프로덕션 워크로드에 부착되는 NetworkPolicy Feature 등). FeatureRecipe 작성 방법은 ../entities/featurerecipe.md를 참조하십시오.

Workload는 워크로드의 형태에만 집중하며, 횡단 관심사 및 Recipe 고유의 보조 매니페스트는 각각 별도의 작성 위치를 가집니다.

일반적인 Workload 패턴

Workload 스키마는 폭이 넓어서 단일 컨테이너 HTTP 서버, 다중 컨테이너 사이드카 패턴, init 컨테이너 체인, 배치 작업, 영구 볼륨을 사용하는 상태 저장 서비스를 모두 다룹니다. 그중 세 가지 패턴은 자주 반복되므로 Recipe마다 상용구를 처음부터 작성하는 것은 낭비입니다. 아래 블록은 Recipe 작성자가 특정 컴포넌트에 맞게 조정할 수 있는 복사·붙여넣기용 템플릿입니다.

여러 Recipes가 공유하는 패턴은 WorkloadLibrary 항목으로 한 번 게시하고 $import: <Library>#/workloads/<entry>로 가져올 수 있습니다. 여기의 템플릿은 상황에 맞게 고쳐 쓰거나 그런 방식으로 게시할 수 있는 출발점입니다.

패턴 1 — 메트릭을 노출하는 서버

한 포트에서 애플리케이션 트래픽을 처리하고 별도의 포트에서 Prometheus가 수집하는 메트릭을 노출하는 일반적인 웹 애플리케이션입니다. Workload에 애플리케이션용과 메트릭용 두 개의 서비스를 두면 서비스 메시 정책과 로드 밸런서 구성을 깔끔하게 분리할 수 있습니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
app:
image: "{{ .values.image }}"
ports:
web: {{ optional .values `port` 8080 }}
metrics: {{ optional .values `metrics_port` 9090 }}
variables:
LOG_LEVEL: "{{ optional .values `log_level` "info" }}"
health:
ready:
http: /healthz
timeoutSeconds: 5
live:
http: /healthz
timeoutSeconds: 5
services:
http:
type: ClusterIP
ports:
web: {{ optional .values `port` 8080 }}
metrics:
type: ClusterIP
ports:
metrics: {{ optional .values `metrics_port` 9090 }}

메트릭 서비스에는 일반적으로 Release 표면에서 Feature 연결을 통해 Prometheus 탐지용 어노테이션이 붙습니다(예: feature.aggrega.ai/prometheus-scrape: "true"). Workload 자체에는 프로바이더별 수집 어노테이션이 들어가지 않습니다.

패턴 2 — 배치 작업

트래픽을 무기한 처리하는 대신 완료될 때까지 실행되는 워크로드입니다. 이 패턴은 form: task를 설정하고 services:를 완전히 생략하며(배치 작업은 포트를 노출하지 않습니다), 대상 프로바이더의 작업 형태에 의존합니다(helm 프로바이더에서는 Kubernetes Job이며, compose 프로바이더에는 작업 형태가 없어 form: task에서 빌드를 중단합니다). Job 파드는 Always 기본값을 사용할 수 없으므로, helm 프로바이더는 Job에 유효한 파드 restartPolicy(컨테이너가 OnFailure를 선언하지 않는 한 Never)를 고정합니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
form: task
containers:
worker:
image: "{{ .values.image }}"
command: ["{{ .values.entrypoint }}"]
args:
- "--config"
- "/etc/config/job.yaml"
variables:
JOB_ID: "{{ .context.instance_id }}-{{ .metadata.release_name }}"
volumeMounts:
- name: config
path: /etc/config
volumes:
config:
configmap:
source: "{{ .context.instance_id }}-config"

config 볼륨은 Recipe가 artifacts:를 통해 Workload와 함께 생성할 것으로 예상되는 ConfigMap을 참조합니다(위의 “Workload 외부에 두는 보조 리소스” 참조). Workload 자체는 사용하는 쪽만 선언합니다. compose처럼 워크로드 이름을 식별자에 따라 짓는 프로바이더에서는 식별자가 그 이름을 정합니다. 워크로드의 리소스 이름을 릴리스 이름에 따라 짓는 helm에서는 여기와 아티팩트 모두에서 ConfigMap 이름을 {{ .context.rendered_name }}로부터 만들어, 컴포넌트 이름이 무엇이든 클러스터가 받아들이는 이름이 되도록 합니다.

패턴 3 — 사이드카 쌍

메인 컨테이너가 애플리케이션 로직을 처리하고 사이드카가 횡단 관심사(TLS 종료, 로그 전송, 서비스 메시 프록시, AI 가드레일)를 처리하는 두 컨테이너 파드입니다. containers:의 작성 순서는 중요한 의미를 가집니다. helm 프로바이더는 선언된 순서대로 컨테이너를 생성하며, 첫 번째 키(여기서는 main)가 kubectl logs 및 유사한 도구의 기본 컨테이너 대상이 됩니다.

apiVersion: aggrega.ai/v1beta1
kind: Workload
replicas: {{ optional .infra `replicas` 2 }}
containers:
main:
image: "{{ .values.app_image }}"
ports:
app: {{ optional .values `app_port` 8080 }}
variables:
UPSTREAM_URL: "http://localhost:{{ optional .values `app_port` 8080 }}"
sidecar:
image: "{{ .values.sidecar_image }}"
ports:
proxy: {{ optional .values `proxy_port` 9000 }}
variables:
PROXY_TARGET: "http://localhost:{{ optional .values `app_port` 8080 }}"
services:
external:
type: ClusterIP
ports:
proxy: {{ optional .values `proxy_port` 9000 }}

Service는 메인 컨테이너가 아닌 사이드카의 포트를 노출하여, 외부 트래픽을 사이드카를 거쳐 localhost를 통해 메인 컨테이너로 라우팅합니다. 두 컨테이너는 파드의 네트워크 네임스페이스를 공유하므로 localhost:<port>로 상대 컨테이너에 직접 접근할 수 있습니다. 자격 증명 주입이 필요한 사이드카(대표적인 AI 가드레일 패턴)의 경우, 자격 증명은 일반적으로 메인 컨테이너가 아닌 사이드카의 attachments: 블록에 두어 자격 증명의 범위를 사이드카의 프로세스 경계로 한정합니다.

패턴 선택

세 패턴은 각기 다른 배포 형태의 관심사에 대응합니다.

  • 메트릭을 노출하는 서버 — 클러스터가 계속 실행 상태로 유지하는 장기 실행 서비스. 트래픽 분리를 위한 여러 Service 노출.
  • 배치 작업 — 한정된 실행. Service 노출 없음. 입력은 Recipe가 생성한 ConfigMap이나 외부 상태에 의존.
  • 사이드카 쌍 — 네트워크 네임스페이스를 공유하는 다중 컨테이너 파드. 사이드카의 Service가 횡단 관심사를 노출.

네 번째 패턴인 영구 볼륨을 사용하는 상태 저장 서버는 form: stateful을 설정하고 volumes.<name>.persistentTemplate으로 레플리카별 스토리지를 선언합니다. helm 프로바이더는 stateful 형태에 대해 StatefulSet을 생성합니다(providers/helm.md 참조). 이 패턴은 형태상 “메트릭을 노출하는 서버”와 같으며, form: stateful, 추가 persistentTemplate 볼륨, 그리고 StatefulSet을 관리할 정확히 하나의 type: Headless 서비스가 더해집니다(이 서비스가 없으면 빌드가 중단됩니다). 이 패턴이 필요한 작성자는 세 가지 선언을 모두 넣어 패턴 1을 조정합니다.

상호 참조