[dennis-upbound]

Description of your changes

Fixes #462.

A ModelDeployment could only run an engine that listens on port 8000 and answers GET /health. The engine's default http port, its readiness probe, and the InferencePool's targetPorts were all fixed at 8000, the probe always asked /health, and the XRD rejected a readinessProbe on the engine container. An engine like the one in the issue, on 8080 with readiness at /v1/models, never went Ready.

This adds serving.port, the port every serving pod receives requests on, and lets the engine container set its own readinessProbe. Both mirror what's already there: ports and readinessProbe already exist on member containers for sidecars. The engine's probe uses the same corev1-shaped field, and a probe set there replaces the default whole. Before, the engine had to be on 8000 and answer /health. After:

serving:
  port: 8080
engines:
- name: main
  members:
  - role: Standalone
    template:
      spec:
        containers:
        - name: engine
          image: registry.example.com/my-engine:1.0
          readinessProbe:
            httpGet:
              path: /v1/models
              port: http

The port is on serving rather than on the engine because a replica's serving pods share one InferencePool, and its targetPorts applies to every pod. With PrefillDecode, the prefill engine and the decode sidecar both serve on it. The XRD port rules that hardcoded 8000 now compare against serving.port, so they move from each member up to the spec, where serving is visible. A rejection now points at the spec rather than at the member. The engine's http port defaults to the serving port, so the collector's scrape (by port name) and the default probe follow it. Neither ModelEndpoint URLs nor the gateway include the engine port, so neither changes.

serving.port has no schema default, so a deployment that doesn't set it stores and propagates exactly what it did before, and its replicas compose the same resources. New XRD validation rejects a probe path that doesn't start with / and a probe port outside 1 to 65535. These apply to sidecar probes too.

Decisions:

• Modelplane doesn't probe a Worker, so a probe set on a Worker's engine passes through as written, the same as its ports. A Worker doesn't serve requests, and Modelplane doesn't give it an http port. The XRD rejects a Worker probe that refers to a port its engine container doesn't declare, because the worker pod would never go Ready.
• The port rules read the port as self.?serving.?port.orValue(8000). CRD validation rules accept CEL optional types from Kubernetes 1.29: k8s.io/apiserver adds cel.OptionalTypes() to the base environment at version 1.28, and new rules compile against the previous minor version. The install guide requires a Kubernetes release that the project still supports, and the oldest of those is newer than 1.29.
• serving.port needs nothing else. mode defaults to Unified before validation, so serving: {port: 8080} is enough.
• The e2e mock engine runs on 8080 with serving.port set. Its probe asks /v1/models, and it no longer answers /health. It's the only end-to-end coverage of a port other than 8000, and the run fails if the engine's probe or the pool's port isn't applied. The unit tests and the live regression scenario cover the default port and probe.

Alternatives I considered:

• Deriving the pool's port from the engine's http port when no sidecar declares 8000, with no new field. That breaks with PrefillDecode, where the decode pod's front port is the sidecar's, and it infers intent from which ports happen to be declared.
• port and health (a path) on the engine. That covers fewer probes than a readinessProbe, and it would duplicate the ports and readinessProbe fields containers already have.

The second limit in the issue is out of scope: the endpoint picker rejects request paths it has no parser for, so a non-chat engine now goes Ready but still isn't reachable through the gateway. A follow-up issue will track it.

I haven't run e2e on this branch. I checked the CEL rules against a kube-apiserver 1.34 (envtest) with kubectl apply --dry-run=server, using valid and invalid ModelDeployments and ModelReplicas and every ModelDeployment under docs/manifests and e2e/manifests.

I have:

• Read and followed Modelplane's contribution process.
• Run nix flake check (or ./nix.sh flake check) and made sure it passes.
• Added or updated tests covering any composition function changes.
• Signed off every commit with git commit -s.

🤖 Generated with Claude Code

[github-actions]

Docs preview: https://modelplane-docs-pr-573.vercel.app (ready once the site's Content workflow finishes)