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

자신의 게이트웨이만 호출할 수 있는 모델 서버

클러스터에서 실행되는 모델 서버는 자신의 주소에 도달하는 누구에게나 응답합니다. 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네임스페이스여기서의 역할
gatewaycore/gateway/nginxedge클라이언트가 호출하는 게이트웨이로, 모델 서버로 요청을 전달합니다
modelcore/ai-model/ollamamodelsllama3.1을 서빙하는 모델 서버

uses 엣지는 하나로, 게이트웨이의 upstream 소켓에서 모델 서버로 향합니다. Feature 연결도 하나로, Release에서 모델 서버에 allowlist, core/caller-allowlist를 연결합니다. Release는 클러스터가 네트워크 정책을 적용한다는 점을 확인하고, Aggregate 외부의 소스 하나인 모니터링 에이전트를 지정합니다.

예제 생성하기

아래 명령으로 이 예제를 빌드하거나, AI 어시스턴트에게 대신 빌드하게 할 수 있습니다.

예제 이름을 딴 새 폴더에 예제를 씁니다:

Terminal window
aggrega scaffold --example model-server-caller-allowlist

그런 다음 이어서 실행할 명령을 출력합니다. 첫 번째 명령은 새 폴더로 이동합니다:

Terminal window
cd model-server-caller-allowlist

빌드

Terminal window
aggrega build --release release.yaml --auto-pull

release는 빌드하기 전에 lockfile이 필요하며, lockfile은 배포되지 않고 생성되므로 새로 clone한 저장소에는 lockfile이 없습니다. 먼저 lockfile을 해석하여 생성하거나, 빌드가 채우도록 합니다:

Terminal window
aggrega pull --release release.yaml # resolve once, then build with no flag
aggrega 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.yaml

attachment는 파일 하나, 즉 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는 실현이 없어 중단됩니다.