# ModelRoute

Source: /reference/modelroutes/

A ModelRoute is one ModelService's routing on one InferenceGateway: the AIGatewayRoute matching the service's model name, plus, per endpoint, the Backend, credential and policy the gateway needs to reach it. The ModelService composes one per gateway that serves it, pinned to that gateway, and this renders onto the gateway's cluster.
It is machine-generated. `kubectl get modelroutes -l modelplane.ai/service=<name>` is the per-gateway view of where a service is served and whether each gateway is carrying it.

Apply instances as `apiVersion: modelplane.ai/v1alpha1`, `kind: ModelRoute`.

## Definition

The CompositeResourceDefinition this reference is generated from, with the complete OpenAPI schema, validation rules, and defaults:

```yaml
apiVersion: apiextensions.crossplane.io/v2
kind: CompositeResourceDefinition
metadata:
  name: modelroutes.modelplane.ai
spec:
  group: modelplane.ai
  names:
    categories: [crossplane, modelplane]
    kind: ModelRoute
    plural: modelroutes
    shortNames: [mrt]
  scope: Namespaced
  versions:
  - name: v1alpha1
    served: true
    referenceable: true
    additionalPrinterColumns:
    - name: GATEWAY
      type: string
      jsonPath: .spec.gatewayName
    - name: ADDRESS
      type: string
      jsonPath: .status.address
    schema:
      openAPIV3Schema:
        description: >-
          A ModelRoute is one ModelService's routing on one InferenceGateway: the
          AIGatewayRoute matching the service's model name, plus, per endpoint,
          the Backend, credential and policy the gateway needs to reach it. The
          ModelService composes one per gateway that serves it, pinned to that
          gateway, and this renders onto the gateway's cluster.

          It is machine-generated. `kubectl get modelroutes -l
          modelplane.ai/service=<name>` is the per-gateway view of where a service
          is served and whether each gateway is carrying it.
        type: object
        required: [spec]
        properties:
          spec:
            type: object
            # A ModelRoute is machine-generated by the ModelService compose
            # function. The API server still serves and accepts it, so requiring
            # these lets the consuming function trust the resolved shape rather
            # than re-checking it.
            required: [gatewayName, serviceName, endpoints]
            properties:
              gatewayName:
                type: string
                minLength: 1
                maxLength: 253
                description: >-
                  Name of the InferenceGateway this route is pinned to. The
                  function resolves the gateway's cluster, its ProviderConfig and
                  its address from here, and renders onto that cluster.
              serviceName:
                type: string
                minLength: 1
                maxLength: 253
                description: >-
                  Name of the ModelService this route belongs to. With the
                  ModelRoute's own namespace it derives the composed object names
                  and the model name a caller passes (<namespace>/<service>), so
                  the service and its routes agree on both.
              endpoints:
                type: array
                description: >-
                  A priority order over ModelEndpoints, each entry selecting a
                  set of them by label. A verbatim copy of the ModelService's
                  spec.endpoints.
                minItems: 1
                maxItems: 32
                items:
                  type: object
                  required: [selector]
                  properties:
                    priority:
                      type: integer
                      description: >-
                        Lower is preferred. Entries at the same priority share
                        traffic by weight; a higher number is only tried when
                        nothing below it has a healthy endpoint.
                      minimum: 0
                      maximum: 63
                      default: 0
                    weight:
                      type: integer
                      description: >-
                        Share of traffic for this entry relative to the other
                        entries at the same priority, spread as evenly as
                        possible across the endpoints it matches.
                      minimum: 1
                      maximum: 1000000
                      default: 1
                    selector:
                      type: object
                      description: >-
                        Selects ModelEndpoints in this route's namespace.
                      required: [matchLabels]
                      properties:
                        matchLabels:
                          type: object
                          additionalProperties:
                            type: string
                            maxLength: 63
                          minProperties: 1
                          maxProperties: 16
          status:
            type: object
            properties:
              model:
                type: string
                description: >-
                  The name a caller passes as the request's model,
                  <namespace>/<service>.
              address:
                type: string
                description: External address of the gateway this route is on.
              hostname:
                type: string
                description: The name that gateway answers on, if it has one.
              endpoints:
                type: object
                description: >-
                  Observed endpoint counts for this route, across all priorities.
                properties:
                  total:
                    type: integer
                  ready:
                    type: integer
              conditions:
                type: array
                items:
                  type: object
```