파이프라인 단계를 사용해야 하는 경우
FeatureRecipe는 Feature가 기여하는 출력을 구성하는 두 가지 방법을 제공합니다. 자체 문서를 생성하는 템플릿 FeatureRecipe와, 렌더링된 출력에 대해 Wasm 플러그인을 실행하는 파이프라인 단계(pipeline:)입니다. 두 방법은 서로 다른 문제를 해결합니다. 이 페이지는 선택 가이드입니다. 파이프라인 단계는 정확히 두 가지 조건에서만 사용하고, 그 밖의 모든 경우에는 템플릿 FeatureRecipe를 사용합니다.
두 가지 도구
템플릿 FeatureRecipe는 지역적이며 생성적입니다. Go 템플릿을 통해 자체 값으로부터 자체 문서를 생성합니다. 사이드카의 ConfigMap, 정책 CRD, 오토스케일러 객체 등이 그 예입니다. 출력하는 모든 것은 Feature의 values:와 infra:, 그리고 템플릿에 전달되는 렌더 컨텍스트의 함수입니다. 다른 엔터티의 출력에 손대지 않으며, 자체 문서를 추가할 뿐입니다. 생성해야 하는 것을 Feature가 이미 알고 있는 정보로 작성할 수 있다면, 템플릿 FeatureRecipe가 올바르고 더 간단한 도구입니다. 플러그인도 파이프라인도 필요 없습니다.
파이프라인 단계는 전역적이며 변환적입니다. 렌더링 이후, 빌드가 이미 출력한 실제 문서 집합에 대해 실행됩니다. 호스트는 키가 지정된 문서 집합 전체를 단계에 전달합니다. 단계는 실제 내용을 읽고, 대상 문서를 선택한 뒤, 그 구조에 대한 정밀한 RFC 6902 패치를 반환하거나 부수 효과로 새 문서를 출력합니다. 단계는 Feature가 선언한 것뿐 아니라 실제로 렌더링된 것을 기준으로 판단합니다. 이러한 접근 범위가 단계가 존재하는 이유의 전부이며, 동시에 단계를 신중하게 사용해야 하는 이유이기도 합니다.
파이프라인 단계를 사용하는 두 가지 조건
다음 중 하나에 해당할 때만 파이프라인 단계를 사용합니다. 둘 다 해당하지 않으면 대신 템플릿 FeatureRecipe로 문서를 생성합니다.
-
호스트 범위 패치 — 이미 렌더링된 다른 엔터티의 구조에 손대야 하는 경우. 대표적인 예는 사용하는 컴포넌트의 워크로드, 즉 Feature 자신이 작성하지 않은 문서에 환경 변수, 볼륨 마운트 또는 사이드카 컨테이너를 주입하는 것입니다. 템플릿 FeatureRecipe는 이를 할 수 없습니다. 자체 문서를 생성할 뿐, 다른 이의 문서를 편집하지 않기 때문입니다. 파이프라인 단계는 렌더링된 집합에서 동작하며 호스트 컴포넌트의 문서를 키로 지정할 수 있으므로 이를 할 수 있습니다.
-
내용 의존적 출력 또는 패치 — 출력이 렌더링된 집합에 무엇이 들어 있는지에 따라 달라지는 경우. 출력하는 리소스나 적용하는 패치가 빌드가 생성한 내용의 함수일 때, 즉 Deployment가 선언한 실제 포트, 매니페스트에 최종적으로 포함된 컨테이너 이름, 차트가 확장된 결과 리소스 등에 따라 달라질 때는 렌더링된 내용을 확보해야 결정할 수 있습니다. 템플릿 FeatureRecipe는 Feature 자체 값으로 렌더링하며 완성된 집합을 보지 못하므로 내용 의존적 선택을 할 수 없습니다. 파이프라인 단계는 먼저 내용을 읽은 뒤 동작합니다.
두 조건은 같은 형태를 공유합니다. 렌더링 이후에만 존재하는 정보, 즉 다른 엔터티의 구조나 출력된 내용 자체가 필요하다는 점입니다. 지역적 생성에는 그러한 정보가 필요 없으므로, 지역적 생성에는 파이프라인 단계가 필요 없습니다.
단계는 변환하고, 정책은 검증합니다
파이프라인 단계는 변환기로, 렌더링된 집합을 변경합니다. 결과가 허용 가능한지 확인하는 곳이 아닙니다. 빌드를 검증하려면, 즉 패치된 워크로드에 사이드카가 있는지, 평문 시크릿이 출력에 포함되지 않았는지, 필수 레이블이 있는지 확인하려면 렌더 단계 정책을 연결합니다. 이는 render-verdict 역할의 거버넌스 플러그인으로, 렌더링 이후 출력된 아티팩트에 대해 실행되어 판정을 반환합니다. halt 판정은 빌드를 중단하고, warn 또는 info 판정은 차단하지 않고 권고만 합니다.
두 가지를 분리해 두십시오. 파이프라인 단계에 검증 로직을 구현하지 말고, 출력을 변경하기 위해 정책을 사용하지 마십시오. 판정 역할에 연결된 거버넌스 플러그인은 판정을 반환할 뿐 패치하지 않으며, 호스트는 판정 역할의 출력을 결정으로만 읽습니다. 단계는 출력을 구성하고, render-verdict 정책은 출력을 판정합니다. 거버넌스 소켓 페이지에서 네 가지 거버넌스 역할과 판정 심각도를 모두 다룹니다.
단계의 조합
파이프라인 단계는 타입이 지정된 입력 및 출력 계약을 선언할 수 있으므로, with: 입력과 반환된 출력은 자유 형식 데이터가 아니라 검증된 형태가 됩니다. 단계는 이름이 지정된 outputs도 반환하며, 같은 파이프라인에서 나중에 선언된 단계는 자신의 with: 템플릿에서 앞선 단계의 출력을 .steps.<id>.outputs.<key>로 읽습니다. 이를 통해 두 부분으로 이루어진 패턴을 결합 없이 조합할 수 있습니다. Fetcher 단계는 자격 증명 리소스를 출력하고 결과 Secret의 이름을 출력으로 게시합니다. Injector 단계는 그 이름을 읽어 사용하는 워크로드가 이를 마운트하도록 패치합니다. 각 단계는 하나의 관심사만 담당하며, 파이프라인은 선언된 순서대로 출력을 전달합니다.
상호 참조
entities/featurerecipe.md—pipeline:을 포함한 FeatureRecipe 작성 인터페이스.plugins/plugin-contract.md— 파이프라인 단계의 전송 형태: 키가 지정된 문서 집합 입력, RFC 6902 패치, 부수 효과, 진단, 단계 출력.plugins/policy-socket.md— 빌드 출력을 검증하는 렌더 단계 판정 역할을 포함한 거버넌스 소켓.templates/template-context-contract.md— 이후 단계가 읽는.steps.<id>.outputs필드.examples/04-secrets.md— Fetcher + Injector 파이프라인 형태.