Un servidor de modelos al que solo su gateway puede llamar
Un servidor de modelos que se ejecuta en un clúster responde a quien alcance su dirección. En una red de pods sin ninguna política de red, que es el comportamiento predeterminado de Kubernetes, eso es cada carga de trabajo del clúster: el gateway colocado delante del modelo es la vía por la que se supone que llega el tráfico, no la única vía por la que puede llegar.
El Aggregate ya dice qué componentes llaman a cuáles: la conexión upstream del gateway nombra el servidor de modelos. core/caller-allowlist, que el operador vincula al servidor de modelos en la Release, convierte esa conexión declarada en la regla de la red del clúster. Este espacio de trabajo compila esta disposición a manifiestos de Kubernetes: un gateway NGINX en el namespace edge, un servidor de modelos Ollama en el namespace models, y la política de red que la vinculación escribe junto al servidor de modelos.
Este workspace no crea ninguna entidad de catálogo propia. Los tres archivos de entidad de aquí — un Aggregate, un Manifest y una Release — son todo lo que se escribe.
Quién escribe qué
| archivo | autor | qué dice aquí |
|---|---|---|
aggregate.yaml | el desarrollador | el gateway, el servidor de modelos y la conexión upstream del gateway hacia él |
release.yaml | el operador | los dos namespaces y, en la entrada del servidor de modelos, la vinculación allowlist con su infra |
manifest.yaml | el operador | qué Recipe realiza cada componente y la Feature en Kubernetes |
El Aggregate no lleva nada sobre la política de red. El desarrollador declara la conexión que hace el gateway; si el clúster rechaza cualquier otra es decisión del operador para este entorno, tomada en la Release bajo components.model.features. Cada entrada que acepta la Feature es infra, el pilar del operador. Lo que el desarrollador debe saber es la consecuencia: dondequiera que una Release vincule esta Feature a un componente, una llamada que el Aggregate no declara como arista uses hacia ese componente la rechaza el clúster, donde su plugin de red hace cumplir la política de red.
Lo que construye
| instancia | Component del catálogo | namespace | qué es aquí |
|---|---|---|---|
gateway | core/gateway/nginx | edge | el gateway al que llaman los clientes; reenvía al servidor de modelos |
model | core/ai-model/ollama | models | el servidor de modelos, que sirve llama3.1 |
Una arista uses: el socket upstream del gateway hacia el servidor de modelos. Una vinculación de Feature, en la Release: allowlist, core/caller-allowlist, en el servidor de modelos. La Release afirma que el clúster hace cumplir la política de red y nombra una fuente fuera del Aggregate, un agente de monitoreo.
Generar el ejemplo
Puedes compilar este ejemplo con los comandos de abajo, o hacer que tu asistente de IA lo compile por ti.
Escribe el ejemplo en una carpeta nueva con su nombre:
aggrega scaffold --example model-server-caller-allowlistDespués imprime los comandos que hay que ejecutar a continuación. El primero entra en la carpeta nueva:
cd model-server-caller-allowlistCompilación
aggrega build --release release.yaml --auto-pullUna release necesita un lockfile antes de compilarse, y los lockfiles se generan en lugar de distribuirse, así que un clon recién hecho no tiene ninguno. Resuelve uno primero, o deja que la compilación lo rellene:
aggrega pull --release release.yaml # resolve once, then build with no flagaggrega build --release release.yaml --auto-pull # or resolve during the buildEste espacio de trabajo resuelve las entidades de catálogo desde el registro predeterminado que nombra .aggrega-config.yaml; no se descarga nada de un repositorio de charts.
La compilación imprime, con <workspace> en lugar de la carpeta de este ejemplo:
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>/distLa advertencia trata de la política. El destino no coloca los manifiestos propios de una Feature en un namespace, así que la plantilla de la vinculación escribe en la política el namespace en el que se emite el StatefulSet del servidor de modelos — namespace: "models" más abajo.
Con un asistente de IA
Un asistente de IA configurado con las herramientas de Aggrega puede hacer lo mismo: pégale este prompt.
Usa solo las herramientas de Aggrega y no crees tú ninguna carpeta. Si la carpeta del espacio de trabajo aún no contiene una carpeta `model-server-caller-allowlist`, llama una vez a la herramienta `scaffold` con `example` establecido en `model-server-caller-allowlist` y sin `dir`: escribe el ejemplo en una nueva carpeta `model-server-caller-allowlist`. Después llama a la herramienta `build` con `workspace_root` establecido en `model-server-caller-allowlist`, `release` establecido en `release.yaml`, `auto_pull` establecido en true y `write` establecido en true. Dime qué archivos escribió la compilación; están en `model-server-caller-allowlist/dist/`.El árbol renderizado
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.yamlLa vinculación añade un archivo, la política. Cada uno de los demás archivos es, byte a byte, lo que la misma Release renderiza sin ella.
Qué puede llegar al servidor de modelos
dist/models/helm/model--allowlist--networkpolicy.yaml, desde su 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"La política está en models, el namespace en el que se emite el StatefulSet del servidor de modelos, selecciona los pods del servidor de modelos y admite conexiones hacia ellos desde tres fuentes, en el único puerto que declara el contenedor del servidor de modelos:
- Los pods propios del servidor de modelos, en
models, para que las réplicas de un mismo servidor puedan alcanzarse entre sí. - Los pods del gateway, en el namespace
edge. El selector de namespace y el selector de pods están en una misma entrada, así que un pod tiene que coincidir con ambos. Una carga de trabajo en otro namespace con las mismas etiquetas — el mismo Aggregate desplegado de nuevo en otro lugar, por ejemplo — no es el gateway y no se admite. - El agente de monitoreo que nombra la Release: los pods etiquetados
app.kubernetes.io/name: prometheusen el namespacemonitoring.
Los pods de cada componente se seleccionan con el selector que escribe su propio controlador — app: model para el StatefulSet del servidor de modelos, app: gateway para el Deployment del gateway — y cada namespace es aquel en el que se emite su carga de trabajo, ambos leídos de lo que emitieron los renderizados en lugar de repetidos a mano. Ninguno de los dos selectores lleva una versión, así que cuando se despliega una nueva compilación, los pods de la anterior siguen seleccionados y siguen admitidos hasta que se sustituyen.
Qué no puede llegar a él
- Cualquier otra carga de trabajo, en
models, enedgeo en cualquier otro namespace — incluido otro agente enmonitoring. - Un controlador de ingress, o cualquier cliente fuera del clúster. No se admite nada fuera del Aggregate a menos que la Release lo nombre, y esta Release solo nombra el agente de monitoreo. Los clientes llegan al servidor de modelos a través del gateway, que es la conexión que declara el Aggregate.
- Cualquier puerto distinto de 11434.
La política restringe quién puede conectarse, no lo que transporta una conexión: una solicitud que reenvía el gateway llega al modelo tal como el gateway la envió.
Lo que la compilación no puede saber
Si la regla se hace cumplir. Una política de red la hace cumplir el plugin de red del clúster, y solo donde ese plugin implementa la política de red; un clúster cuyo plugin no lo hace acepta la política y no hace cumplir nada. La compilación escribe la política y no puede ver el clúster, por eso la Release lleva control_plane_present: true en la vinculación: es la declaración del operador de que el clúster de destino la hace cumplir, y la compilación se detiene hasta que se hace.
Otras tres limitaciones vienen de cómo funciona la política de red y no de esta Feature:
- Las políticas se suman. Donde otra política del clúster selecciona los mismos pods, se admite una conexión que admita cualquiera de las dos.
- El gateway no queda restringido por esta vinculación. Esta protege el servidor de modelos; vincula también la Feature a la entrada del gateway en la Release para restringir quién llega al gateway, y nombra allí los clientes a los que sirve.
- El tráfico saliente no se toca. El servidor de modelos sigue llegando al registro del que descarga los pesos, y resuelve nombres como antes.
Qué detiene la compilación
Cada uno de estos casos es una frase que imprime la compilación, y que nombra qué cambiar:
-
El requisito previo no está afirmado. Quita
control_plane_present: truede la Release:[… 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 -
Un llamador cuya carga de trabajo no se emite en ningún namespace. Quita la anotación
aggrega.ai/namespacedel límiteedge, y el Deployment del gateway se emite sin ninguno:[… 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 -
La carga de trabajo del servidor de modelos emitida sin namespace, por la misma razón: una política selecciona pods solo en su propio namespace.
-
Una carga de trabajo de cualquiera de los dos que no escribe ningún selector de controlador y no lleva ninguna de las etiquetas de identidad que la compilación estampa en sus pods — un Job de un chart que se apoya en el selector que genera el clúster, por ejemplo. Seleccionarla por cada etiqueta que lleva dejaría de coincidir con sus pods la primera vez que cambiara una etiqueta de versión, así que la compilación se detiene en su lugar.
-
Un llamador, o el servidor de modelos, cuyo renderizado no emite ningún pod — uno realizado por un recurso personalizado cuyo controlador crea los pods más tarde, o al que se llega en una dirección fuera del clúster. Un componente así no se puede nombrar en una política, así que la compilación se detiene en lugar de escribir una política que lo rechazaría o no seleccionaría nada.
-
Una fuente en
admitted_sourcesque nombra tanto un rango de direcciones como pods, o ninguno de los dos.
Dónde el compilador no interpreta
El compilador canaliza a la política, como cadenas, los selectores, etiquetas y namespaces que informó cada renderizado. No contacta con el clúster, no sabe qué plugin de red se ejecuta allí y no sabe qué cargas de trabajo se ejecutan ya en un namespace. Cada detención anterior la declaran las propias entidades del catálogo, en la realización de la Feature, y ninguna de ellas se basa en conocimiento alguno del clúster.
Adaptarlo
- Admitir un controlador de ingress. Añade una entrada a
admitted_sourcescon su namespace y las etiquetas de sus pods — ambos en una misma entrada, para que solo se admitan esos pods en ese namespace. - Admitir un rango de direcciones. Añade una entrada con
cidr, como10.20.0.0/16. - Un segundo llamador. Añade una arista
usesdesde él hacia el servidor de modelos en el Aggregate y colócalo en un namespace que declare la Release; la siguiente compilación lo admite sin ningún cambio en la vinculación. - Compose. La Feature no está realizada allí: un stack de Compose pone cada servicio de un grupo en una sola red, y la configuración de un servicio no puede sacar a otro servicio de ella, así que una Release que enlaza esta Feature en Compose se detiene por falta de una realización.