자신의 게이트웨이만 호출할 수 있는 모델 서버
클러스터에서 실행되는 모델 서버는 자신의 주소에 도달하는 누구에게나 응답합니다. Kubernetes의 기본값인, 네트워크 정책이 없는 파드 네트워크에서는 클러스터의 모든 워크로드가 그 대상입니다. 모델 앞에 배치된 게이트웨이는 트래픽이 도착하도록 의도된 경로일 뿐, 트래픽이 도착할 수 있는 유일한 경로는 아닙니다.
Aggregate는 이미 어떤 컴포넌트가 어떤 컴포넌트를 호출하는지 기술합니다. 게이트웨이의
upstream 연결이 모델 서버를 지정합니다. 운영자가 Release에서 모델 서버에 연결하는
core/caller-allowlist는 선언된 그 연결을 클러스터 네트워크의 규칙으로 바꿉니다. 이
워크스페이스는 이 구성을 Kubernetes 매니페스트로 컴파일합니다. 네임스페이스 edge의 NGINX 게이트웨이,
네임스페이스 models의 Ollama 모델 서버, 그리고 이 연결이 모델 서버 옆에 작성하는
네트워크 정책입니다.
이 워크스페이스는 자체 카탈로그 엔티티를 작성하지 않습니다. 여기 있는 세 개의 엔티티 파일, 즉 Aggregate, Manifest, Release가 누구든 작성하는 내용의 전부입니다.
누가 무엇을 작성하는가
| 파일 | 작성자 | 여기서 기술하는 내용 |
|---|---|---|
aggregate.yaml | 개발자 | 게이트웨이, 모델 서버, 그리고 게이트웨이에서 모델 서버로 가는 upstream 연결 |
release.yaml | 운영자 | 두 네임스페이스, 그리고 모델 서버 항목에 붙는 allowlist 연결과 그 infra |
manifest.yaml | 운영자 | Kubernetes에서 각 컴포넌트와 Feature를 구현하는 Recipe |
Aggregate에는 네트워크 정책에 관한 내용이 전혀 없습니다. 개발자는 게이트웨이가 맺는
연결을 선언합니다. 클러스터가 그 밖의 모든 연결을 거부할지는 이 환경에 대한 운영자의
결정이며, Release의 components.model.features 아래에서 정합니다. 이 Feature가 받는
모든 입력은 운영자의 축인 infra입니다. 개발자가 알아야 할 것은 그 결과입니다. Release가
이 Feature를 어떤 컴포넌트에 연결하든, Aggregate가 그 컴포넌트로 향하는 uses 엣지로
선언하지 않은 호출은 클러스터의 네트워크 플러그인이 네트워크 정책을 시행하는 곳에서
클러스터가 거부합니다.
구성되는 내용
| 인스턴스 | 카탈로그 Component | 네임스페이스 | 여기서의 역할 |
|---|---|---|---|
gateway | core/gateway/nginx | edge | 클라이언트가 호출하는 게이트웨이로, 모델 서버로 요청을 전달합니다 |
model | core/ai-model/ollama | models | llama3.1을 서빙하는 모델 서버 |
uses 엣지는 하나로, 게이트웨이의 upstream 소켓에서 모델 서버로 향합니다. Feature 연결도 하나로, Release에서 모델 서버에 allowlist, core/caller-allowlist를 연결합니다. Release는 클러스터가 네트워크 정책을 적용한다는 점을 확인하고, Aggregate 외부의 소스 하나인 모니터링 에이전트를 지정합니다.
예제 생성하기
아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.
예제 이름을 딴 새 폴더에 예제를 씁니다:
aggrega scaffold --example model-server-caller-allowlist그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:
cd model-server-caller-allowlist빌드
aggrega build --release release.yaml --auto-pullrelease는 빌드하기 전에 lockfile이 필요하며, lockfile은 배포되지 않고 생성되므로 새로 clone한 저장소에는 lockfile이 없습니다. 먼저 lockfile을 해석하여 생성하거나, 빌드가 채우도록 합니다:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the build이 워크스페이스는 .aggrega-config.yaml이 지정하는 기본 레지스트리에서 카탈로그 엔터티를 해석하며, chart 저장소에서 가져오는 것은 없습니다.
빌드는 다음을 출력하며, <workspace>는 이 예제의 폴더를 나타냅니다.
warning: node "model" (provider "helm"): target "helm" does not support annotation aggrega.ai/namespace on artifacts-only input and ignored it[… omitted: the resolution's summary and a total build time, which differ per run]Build completed: 6 files written to <workspace>/dist이 경고는 정책에 관한 것입니다. 대상은 Feature 자체의 manifest를 namespace에
배치하지 않으므로, attachment의 템플릿이 모델 서버의 StatefulSet이 출력되는 namespace를
정책에 기록합니다. 아래의 namespace: "models"가 그것입니다.
AI 어시스턴트 사용
Aggrega 도구로 설정한 AI 어시스턴트도 같은 작업을 할 수 있습니다. 다음 프롬프트를 붙여 넣으십시오.
Aggrega 도구만 사용하고 폴더를 직접 만들지 마십시오. 작업 공간 폴더에 아직 `model-server-caller-allowlist` 폴더가 없으면 `example`에 `model-server-caller-allowlist` 값을 지정하고 `dir` 없이 `scaffold` 도구를 한 번 호출하십시오. 그러면 예제가 새 `model-server-caller-allowlist` 폴더에 작성됩니다. 그런 다음 `workspace_root` 값은 `model-server-caller-allowlist`, `release` 값은 `release.yaml`, `auto_pull` 값은 true, `write` 값은 true로 설정하여 `build` 도구를 호출하십시오. 빌드가 작성한 파일을 알려 주십시오. 파일은 `model-server-caller-allowlist/dist/` 아래에 있습니다.렌더링된 트리
dist/├── edge/helm/│ ├── gateway-default-service.yaml│ └── gateway-deployment.yaml└── models/helm/ ├── model--allowlist--networkpolicy.yaml ├── model-default-service.yaml ├── model-headless-service.yaml └── model-statefulset.yamlattachment는 파일 하나, 즉 policy를 추가합니다. 그 밖의 모든 파일은 attachment 없이 같은 Release가 렌더링하는 것과 바이트 단위로 동일합니다.
모델 서버에 접근할 수 있는 것
dist/models/helm/model--allowlist--networkpolicy.yaml의 spec 이후 부분:
spec: podSelector: matchLabels: "app": "model" policyTypes: - Ingress ingress: - from: - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "models" podSelector: matchLabels: "app": "model" - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "edge" podSelector: matchLabels: "app": "gateway" - namespaceSelector: matchLabels: "kubernetes.io/metadata.name": "monitoring" podSelector: matchLabels: "app.kubernetes.io/name": "prometheus" ports: - port: 11434 protocol: "TCP"이 정책은 모델 서버의 StatefulSet이 출력되는 네임스페이스인 models에 위치하며,
모델 서버의 파드를 선택하고, 모델 서버의 컨테이너가 선언하는 단 하나의 포트에서
세 가지 출처로부터의 연결을 허용합니다.
models에 있는 모델 서버 자신의 파드. 따라서 한 서버의 레플리카끼리 서로 접근할 수 있습니다.- 네임스페이스
edge에 있는 게이트웨이의 파드. 네임스페이스 셀렉터와 파드 셀렉터가 하나의 항목에 있으므로 파드는 두 셀렉터를 모두 만족해야 합니다. 같은 레이블을 가진 다른 네임스페이스의 워크로드는, 예컨대 같은 Aggregate가 다른 곳에 다시 릴리스된 경우라도, 게이트웨이가 아니므로 허용되지 않습니다. - Release가 지정하는 모니터링 에이전트: 네임스페이스
monitoring에서app.kubernetes.io/name: prometheus레이블이 붙은 파드입니다.
각 컴포넌트의 파드는 해당 컨트롤러가 직접 작성하는 셀렉터로 선택됩니다.
모델 서버의 StatefulSet은 app: model, 게이트웨이의 Deployment는 app: gateway입니다.
또한 각 네임스페이스는 해당 워크로드가 출력되는 네임스페이스이며, 둘 다 수작업으로
다시 적는 것이 아니라 렌더링이 출력한 결과에서 읽어 옵니다.
어느 셀렉터에도 버전이 포함되지 않으므로, 새 빌드가 롤아웃될 때 이전 빌드의 파드는
교체될 때까지 계속 선택되고 허용됩니다.
모델 서버에 도달할 수 없는 것
- 다른 모든 워크로드:
models,edge또는 다른 어떤 네임스페이스에 있든 마찬가지이며,monitoring에 있는 다른 에이전트도 포함됩니다. - 인그레스 컨트롤러 또는 클러스터 외부의 모든 클라이언트. Release가 지정하지 않는 한 Aggregate 외부의 어떤 것도 허용되지 않으며, 이 Release는 모니터링 에이전트만 지정합니다. 클라이언트는 게이트웨이를 통해 모델 서버에 도달하며, 이것이 Aggregate가 선언하는 연결입니다.
- 11434 이외의 모든 포트.
이 정책은 누가 연결할 수 있는지를 제한할 뿐, 연결이 무엇을 전달하는지는 제한하지 않습니다. 게이트웨이가 전달하는 요청은 게이트웨이가 보낸 그대로 모델에 도달합니다.
빌드가 알 수 없는 것
규칙이 실제로 적용되는지 여부. 네트워크 정책은 클러스터의 네트워크 플러그인이 적용하며, 그 플러그인이 네트워크 정책을 구현하는 경우에만 적용됩니다. 플러그인이 이를 구현하지 않는 클러스터는 정책을 받아들이지만 아무것도 적용하지 않습니다. 빌드는 정책을 작성할 뿐 클러스터를 볼 수 없으며, 이 때문에 Release는 연결 항목에 control_plane_present: true를 지정합니다. 이는 대상 클러스터가 정책을 적용한다는 운영자의 선언이며, 이 선언이 있을 때까지 빌드는 중단됩니다.
다음 세 가지 제한은 이 Feature가 아니라 네트워크 정책의 동작 방식에서 비롯됩니다.
- 정책은 합산됩니다. 클러스터의 다른 정책이 같은 파드를 선택하는 경우, 둘 중 어느 하나라도 허용하는 연결은 허용됩니다.
- 게이트웨이는 이 연결로 제한되지 않습니다. 이 연결은 모델 서버를 보호합니다. 게이트웨이에 접근할 수 있는 대상을 제한하려면 Release의 게이트웨이 항목에도 Feature를 연결하고, 그곳에 게이트웨이가 서비스하는 클라이언트를 지정합니다.
- 아웃바운드 트래픽은 영향을 받지 않습니다. 모델 서버는 여전히 가중치를 가져오는 레지스트리에 접근할 수 있으며, 이전과 같이 이름을 확인합니다.
빌드를 중단시키는 것
다음 각 경우에 빌드는 무엇을 바꿔야 하는지 알려 주는 문장을 출력합니다.
-
전제 조건이 확인되지 않은 경우. Release에서
control_plane_present: true를 제거하면 다음과 같습니다.[… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the template position and the assertion's own source]error calling fail: assertion failed: core/caller-allowlist attachment "allowlist" on "model" writes a network policy, which restricts connections only where the cluster's network plugin enforces network policy; once the target cluster's plugin does, affirm it by setting infra.control_plane_present to true on this attachment in the Release -
워크로드가 어떤 네임스페이스에도 출력되지 않는 호출자.
edge경계에서aggrega.ai/namespace어노테이션을 제거하면 게이트웨이의 Deployment가 네임스페이스 없이 출력됩니다.[… omitted: what resolving the lockfile prints, the same halt among it, and the halt's heading, the artifact being rendered, the template position and the template's own source]error calling fail: core/caller-allowlist attachment "allowlist" on "model": "gateway" connects to "model" through its "upstream" socket, but the Deployment "gateway" it renders is emitted into no namespace, so the policy cannot name where its pods run; set aggrega.ai/namespace on the boundary holding "gateway", or on its own entry, in the Release, or have the manifest that carries it write one -
모델 서버의 워크로드가 어떤 네임스페이스에도 출력되지 않는 경우도 같은 이유로 중단됩니다. 정책은 자신의 네임스페이스에 있는 파드만 선택하기 때문입니다.
-
둘 중 어느 쪽이든 컨트롤러 셀렉터를 작성하지 않고, 빌드가 파드에 부여하는 식별 레이블도 전혀 갖지 않는 워크로드 — 예를 들어 클러스터가 생성하는 셀렉터에 의존하는 차트의 Job입니다. 이런 워크로드를 그것이 가진 모든 레이블로 선택하면 버전 레이블이 처음 바뀌는 순간 파드와 일치하지 않게 되므로, 빌드는 대신 중단됩니다.
-
렌더링 결과로 파드가 출력되지 않는 호출자 또는 모델 서버 — 컨트롤러가 나중에 파드를 생성하는 커스텀 리소스로 구현되거나, 클러스터 외부의 주소로 접근되는 경우입니다. 이런 구성 요소는 정책에서 지정할 수 없으므로, 빌드는 그것을 거부하거나 아무것도 선택하지 않는 정책을 작성하는 대신 중단됩니다.
-
admitted_sources의 소스가 주소 범위와 파드를 모두 지정하거나, 둘 다 지정하지 않는 경우.
컴파일러가 해석하지 않는 부분
컴파일러는 각 렌더가 보고한 셀렉터, 레이블, 네임스페이스를 문자열로 정책에 전달합니다. 컴파일러는 클러스터에 접속하지 않으며, 그곳에서 어떤 네트워크 플러그인이 실행되는지도, 네임스페이스에서 이미 어떤 워크로드가 실행 중인지도 알지 못합니다. 위의 각 중단은 카탈로그 자체의 엔티티가 Feature의 구현에서 선언한 것이며, 그중 어느 것도 클러스터에 대한 지식에 의존하지 않습니다.
응용하기
- ingress 컨트롤러 허용하기.
admitted_sources에 해당 컨트롤러의 네임스페이스와 파드 레이블을 담은 항목을 추가합니다. 두 가지를 하나의 항목에 함께 넣으므로 그 네임스페이스에 있는 해당 파드만 허용됩니다. - 주소 범위 허용하기.
10.20.0.0/16과 같은cidr를 담은 항목을 추가합니다. - 두 번째 호출자. Aggregate에 해당 호출자에서 모델 서버로 향하는
uses간선을 추가하고, Release가 선언하는 네임스페이스에 배치합니다. 다음 빌드는 연결 설정을 변경하지 않고도 이 호출자를 허용합니다. - Compose. 이 Feature는 Compose에서 실현되지 않습니다. Compose 스택은 그룹의 모든 서비스를 하나의 네트워크에 두며, 한 서비스의 구성으로 다른 서비스를 그 네트워크에서 떼어 낼 수 없으므로, Compose에서 이 Feature를 바인딩하는 Release는 실현이 없어 중단됩니다.