--- updatedAt: 2026-08-21T16:12:58.000Z agentTools: projectIndex: https://docs.rackspace.com/llms.txt --- # Partially update a ModelClass # OpenAPI definition ```json { "openapi": "3.0.3", "info": { "title": "RackAI API", "description": "REST API for RackAI Custom Resources managed by the `rackai.rackspace.com` operator.\n\nMost requests are routed through the Kubernetes API server and authenticated\nwith a bearer token (service-account token or kubeconfig credential).\n\nOrganization management is the exception: tenants have no RBAC to edit the\n`Organization` custom resource directly, so those operations are served by the\norganizer service behind the Front Proxy and authenticated with an Auth0 OIDC\ntoken. See the **Organization** tag.\n\n**Base path:** `/apis/rackai.rackspace.com/v1alpha1`\n", "version": "v1alpha1", "contact": { "name": "Rackspace Spot Platform Engineering" } }, "servers": [ { "url": "https://{fqdn}/apis/rackai.rackspace.com/v1alpha1", "description": "API Server", "variables": { "fqdn": { "default": "localhost:6443", "description": "Fully-qualified domain name (and optional port) of the Front Proxy in front of the Kubernetes API server" } } } ], "security": [ { "BearerToken": [] } ], "tags": [ { "name": "ModelClass", "description": "ModelClass is a namespaced deployment template for an AI model.\nIt identifies the Model (via `spec.model`), the runtime (vllm/nim/...), and\nthe runtime-level resources, scaling, image, and arguments. Many\nModelDeployments may reference the same ModelClass; bootstrap may seed a\nset of ModelClass objects\ninto each namespace." } ], "paths": { "/namespaces/{namespace}/modelclasses/{name}": { "parameters": [ { "$ref": "#/components/parameters/namespace" }, { "$ref": "#/components/parameters/name" } ], "patch": { "tags": [ "ModelClass" ], "summary": "Partially update a ModelClass", "operationId": "patchNamespacedModelClass", "requestBody": { "required": true, "content": { "application/merge-patch+json": { "schema": { "$ref": "#/components/schemas/ModelClass" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ModelClass" } } } }, "400": { "$ref": "#/components/responses/BadRequest" }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "404": { "$ref": "#/components/responses/NotFound" }, "422": { "$ref": "#/components/responses/UnprocessableEntity" } } } } }, "components": { "securitySchemes": { "BearerToken": { "type": "http", "scheme": "bearer", "description": "Bearer token for the Kubernetes-extension API surface\n(`/apis/rackai.rackspace.com/v1alpha1/...`). Pass as\n`Authorization: Bearer `.\n\nNote: for paths reached through the Front Proxy, the credential\npresented is an Auth0-issued OIDC bearer that the proxy validates\nand forwards to the upstream apiserver (which validates the same\ntoken via OIDC). A Kubernetes service-account token or kubeconfig\ncredential is what's typically used when hitting the apiserver\ndirectly (e.g. from inside the cluster).\n" } }, "parameters": { "namespace": { "name": "namespace", "in": "path", "required": true, "description": "Kubernetes namespace of the resource.", "schema": { "type": "string" } }, "name": { "name": "name", "in": "path", "required": true, "description": "Name of the resource.", "schema": { "type": "string" } } }, "responses": { "BadRequest": { "description": "Bad Request — the request body or parameters are invalid." }, "Unauthorized": { "description": "Unauthorized — no or invalid bearer token provided." }, "Forbidden": { "description": "Forbidden — the authenticated principal lacks permission." }, "NotFound": { "description": "Not Found — the resource does not exist." }, "UnprocessableEntity": { "description": "Unprocessable Entity — the object failed schema validation." } }, "schemas": { "ModelClass": { "description": "ModelClass is a namespaced deployment template for an AI model.\nIt identifies the Model (via `spec.model`), the runtime (vllm/nim/...), and\nthe runtime-level resources, scaling, image, and arguments. Many\nModelDeployments may reference the same ModelClass; bootstrap may seed a\nset of ModelClass objects\ninto each namespace.", "properties": { "apiVersion": { "description": "APIVersion defines the versioned schema of this representation of an object.\nServers should convert recognized schemas to the latest internal value, and\nmay reject unrecognized values.\nMore info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#resources", "type": "string", "example": "rackai.rackspace.com/v1alpha1" }, "kind": { "description": "Kind is a string value representing the REST resource this object represents.\nServers may infer this from the endpoint the client submits requests to.\nCannot be updated.\nIn CamelCase.\nMore info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#types-kinds", "type": "string", "example": "ModelClass" }, "metadata": { "type": "object", "description": "metadata is a standard object metadata.\nMore info: https://git.k8s.io/community/contributors/devel/sig-architecture/api-conventions.md#metadata", "example": { "name": "qwen3-4b", "namespace": "org-idxxxxxxxxxx" } }, "spec": { "description": "Spec defines the desired state of ModelClass.", "properties": { "acceleratorClass": { "description": "AcceleratorClass references the AcceleratorClass that predictor pods\nfor deployments instantiating this class should land on. When set to\na real AcceleratorClass name, the controller stamps the referenced\nAcceleratorClass's nodeSelectorTerms into the predictor pod's\nrequired nodeAffinity.\n\nTwo reserved values disambiguate placement intent:\n - \"\" (unset) — default k8s scheduler; no nodeAffinity stamped, pod\n lands on any node that satisfies the resource request.\n - \"auto\" — reserved for the P4 rackai model-aware scheduler. The\n scheduler does not exist yet in Phase 1; the controller surfaces\n Available=False/AutoSchedulerPending on referencing\n ModelDeployments and FineTuningJobs until P4 ships.", "example": "h100-80gb", "type": "string" }, "args": { "description": "Args are the CLI arguments passed to the inference runtime.\nNames within this list must be unique. Deployment-level args may\noverride entries here by Name, or remove them via unset=true\n(merge semantics implemented by the controller in a later phase).\nThe unset field has no meaning here; use it only on ModelDeployment.Spec.Args.", "example": [ { "name": "max-model-len", "value": "32000" }, { "name": "enable-auto-tool-choice" } ], "items": { "description": "ArgEntry represents one CLI flag passed to the inference runtime.\nUsed by both ModelClass.Spec.Args (the template) and\nModelDeployment.Spec.Args (the deployment-level override).\n\nUniqueness of Name within a single args list is enforced at admission via\nthe +listType=map +listMapKey=name markers on the consuming field.\n\nMerge semantics (implemented by MergeArgs):\n - A ModelDeployment entry whose Name matches a ModelClass entry REPLACES\n the class entry in the merged result.\n - A ModelDeployment entry whose Name does not match any class entry is\n APPENDED.\n - A ModelDeployment entry with Unset=true and a matching class Name\n REMOVES the class entry from the merged result (the deployment entry\n itself does not appear in the merged output). When set without a\n matching class entry, Unset is a no-op.\n - Unset has no meaning on ModelClass.Spec.Args (the class is the\n baseline; there is nothing to unset).", "properties": { "name": { "description": "Name is the flag name without leading dashes\n(for example \"max-model-len\", \"enable-auto-tool-choice\",\n\"no-enable-auto-tool-choice\").", "minLength": 1, "type": "string" }, "unset": { "description": "Unset, when true on a ModelDeployment args entry whose Name matches a\nModelClass args entry, drops the class entry from the merged result.\nUse this to remove a class-level flag at deploy time without resorting\nto a runtime-specific negative flag (e.g., \"no-enable-lora\").\nNo-op when the Name does not match any class entry. Mutually exclusive\nwith Value. Has no meaning on ModelClass.Spec.Args.", "type": "boolean" }, "value": { "description": "Value is the flag's value. Omit for valueless / boolean flags\n(e.g. --enable-lora has Name=\"enable-lora\" and Value unset).\nMutually exclusive with Unset: an Unset=true entry must not carry a Value.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array", "x-kubernetes-list-map-keys": [ "name" ], "x-kubernetes-list-type": "map" }, "description": { "description": "Description is a human-readable description of this resource.", "example": "vLLM-optimized template for low-latency chat serving with tool use.", "maxLength": 1024, "type": "string" }, "displayName": { "description": "DisplayName is a short human-readable label for this resource. Distinct\nfrom metadata.name (which is the DNS-compatible identifier).", "example": "Qwen3 4B (vLLM)", "maxLength": 128, "type": "string" }, "env": { "description": "Env is the list of environment variables passed to the inference runtime\ncontainer. Names within this list must be unique. Deployment-level env\nentries may override entries here by Name, or remove them via unset=true\n(merge semantics implemented by MergeEnv).\nThe unset field has no meaning here; use it only on ModelDeployment.Spec.Env.\nReserved names (HF_TOKEN, NGC_API_KEY, HF_HOME, TRANSFORMER_CACHE,\nNVIDIA_VISIBLE_DEVICES) are rejected by the runtime adapter and surface\nas Available=False with Reason=ReservedEnvVar.", "example": [ { "name": "VLLM_LOGGING_LEVEL", "value": "DEBUG" }, { "name": "NCCL_DEBUG", "value": "INFO" } ], "items": { "description": "EnvVarEntry represents one environment variable for the inference runtime.\nUsed by both ModelClass.Spec.Env (the template) and ModelDeployment.Spec.Env\n(the deployment-level override). Mirrors the ArgEntry pattern — see\nargs.go for the same Name/Value/Unset merge semantics.\n\nMerge semantics (implemented by MergeEnv):\n - A ModelDeployment entry whose Name matches a ModelClass entry REPLACES\n the class entry in the merged result.\n - A ModelDeployment entry whose Name does not match any class entry is\n APPENDED.\n - A ModelDeployment entry with Unset=true and a matching class Name\n REMOVES the class entry. When set without a matching class entry,\n Unset is a no-op.\n - Unset has no meaning on ModelClass.Spec.Env.\n\nReserved names (HF_TOKEN, NGC_API_KEY, HF_HOME, TRANSFORMER_CACHE,\nNVIDIA_VISIBLE_DEVICES) are rejected at runtime adapter Build time so users\ncannot shadow operator-managed credential and runtime envs.", "properties": { "name": { "description": "Name is the environment variable name. POSIX C_IDENTIFIER.", "minLength": 1, "pattern": "^[A-Za-z_][A-Za-z0-9_]*$", "type": "string" }, "unset": { "description": "Unset, when true on a ModelDeployment env entry whose Name matches a\nModelClass env entry, drops the class entry from the merged result.\nNo-op when no class entry matches. Mutually exclusive with Value.\nHas no meaning on ModelClass.Spec.Env.", "type": "boolean" }, "value": { "description": "Value is the env var value. Empty string is a valid explicit value\n(the container sees NAME=\"\"). Mutually exclusive with Unset.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array", "x-kubernetes-list-map-keys": [ "name" ], "x-kubernetes-list-type": "map" }, "image": { "description": "Image specifies the container image for runtimes whose weights ship in\nthe image itself (e.g., NIM). Optional.", "example": "nvcr.io/nim/deepseek-ai/deepseek-r1:1.0.0", "type": "string" }, "model": { "description": "Model is the name of the Model this class deploys. Must be the\nmetadata.name of an existing Model in the same namespace.", "example": "llama3-8b-base", "minLength": 1, "type": "string" }, "modelFormat": { "description": "ModelFormat specifies the model format consumed by the inference runtime\n(e.g., \"tensorflow\", \"pytorch\", \"onnx\", \"vllmopenai\").", "example": "vllmopenai", "type": "string" }, "resources": { "description": "Resources defines compute resource requirements (template defaults).", "example": { "limits": { "cpu": "12", "memory": "16Gi", "nvidia.com/gpu": "1" }, "requests": { "cpu": "6", "memory": "8Gi", "nvidia.com/gpu": "1" } }, "properties": { "claims": { "description": "Claims lists the names of resources, defined in spec.resourceClaims,\nthat are used by this container.\n\nThis is an alpha field and requires enabling the\nDynamicResourceAllocation feature gate.\n\nThis field is immutable. It can only be set for containers.", "items": { "description": "ResourceClaim references one entry in PodSpec.ResourceClaims.", "properties": { "name": { "description": "Name must match the name of one entry in pod.spec.resourceClaims of\nthe Pod where this field is used. It makes that resource available\ninside a container.", "type": "string" }, "request": { "description": "Request is the name chosen for a request in the referenced claim.\nIf empty, everything from the claim is made available, otherwise\nonly the result of this request.", "type": "string" } }, "required": [ "name" ], "type": "object" }, "type": "array", "x-kubernetes-list-map-keys": [ "name" ], "x-kubernetes-list-type": "map" }, "limits": { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$", "x-kubernetes-int-or-string": true }, "description": "Limits describes the maximum amount of compute resources allowed.\nMore info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/", "type": "object" }, "requests": { "additionalProperties": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$", "x-kubernetes-int-or-string": true }, "description": "Requests describes the minimum amount of compute resources required.\nIf Requests is omitted for a container, it defaults to Limits if that is explicitly specified,\notherwise to an implementation-defined value. Requests cannot exceed Limits.\nMore info: https://kubernetes.io/docs/concepts/configuration/manage-resources-containers/", "type": "object" } }, "type": "object" }, "runtime": { "description": "Runtime specifies the inference runtime.", "enum": [ "vllm", "nim", "optimized-nim-vllm", "aim" ], "example": "vllm", "type": "string" }, "scaling": { "description": "Scaling defines autoscaling configuration (template defaults).", "example": { "maxReplicas": 1, "minReplicas": 1 }, "properties": { "autoscalingEnabled": { "description": "AutoscalingEnabled explicitly enables or disables metric-driven\nautoscaling for this layer. Tri-state with intentional semantics:\n nil — no opinion; inherit from the next layer. If both layers\n leave it nil after merge, autoscaling stays off — the\n controller stamps autoscalerClass=external on the\n predictor so KServe skips both the default HPA and any\n ScaledObject (treated identically to false).\n true — autoscaling is enabled. Requires a Metric to be configured\n at some layer; ConfigInvalid otherwise. Controller stamps\n autoscalerClass=keda and Predictor.AutoScaling.\n false — autoscaling is disabled. Merge forces Metric, Target,\n SteadyWindowSeconds and WakeHoldSeconds to nil so leftover\n fields on the same or other layer are soft-ignored (a\n single ScalingFieldsIgnored Warning event lists the\n dropped fields). The controller stamps\n autoscalerClass=external on the predictor — KServe skips\n both the default HPA and any ScaledObject — and the\n predictor sits pinned at MinReplicas. external is used\n rather than none because KServe v0.15.x's predictor\n reconciler does not honour none as a true\n skip-everything signal.\n\nNote: there is no implicit \"Metric set ⇒ enabled\" rule today. Setting\nonly Metric + Target without AutoscalingEnabled=true produces\nConditions[Autoscaling] = {False, Disabled, \"Autoscaling not enabled;\nset spec.scaling.autoscalingEnabled=true to opt in.\"}. See\ndocs/architecture/autoscaling.md for the stamping gate and the full\nmerge / validation behavior.\n\nUse case: a ModelClass sets metric+target as a template, a specific\nModelDeployment sets autoscalingEnabled=false to opt out without\nhaving to chase the class's metric+target through YAML.", "type": "boolean" }, "maxReplicas": { "description": "MaxReplicas is the maximum number of replicas. Must be >= 1.", "example": 1, "format": "int32", "minimum": 1, "type": "integer" }, "metric": { "description": "Metric is the scaling signal the autoscaler tracks. When unset, the\ndeployment runs at MinReplicas with no metric-driven scaling.\nRequires a runtime that supports metric-driven scaling; today vllm\nand optimized-nim-vllm support it, nim does not.", "enum": [ "WaitingRequests", "RunningRequests", "ActiveRequests", "VLLMKVCacheUtilization", "GPUMemoryUtilization", "WaitingAndRunningRequests" ], "example": "WaitingRequests", "type": "string" }, "minReplicas": { "description": "MinReplicas is the minimum number of replicas. Setting 0 enables\nscale-to-zero (first request after idle returns 503 + Retry-After).", "example": 1, "format": "int32", "minimum": 0, "type": "integer" }, "steadyWindowSeconds": { "description": "SteadyWindowSeconds is the lookback window used by the steady-state\nautoscaling trigger. The controller wraps each Metric's PromQL with\navg_over_time(...[s:30s]) so transient spikes\nand dips don't cause replica thrash. Default 60s when unset.\nMinimum 60s. Only applies when Metric is configured.\n\nNote: very long windows require correspondingly long Prometheus\nretention. The autoscaler will under-smooth silently if the\nrequested window exceeds available retention.", "example": 60, "format": "int32", "minimum": 60, "type": "integer" }, "target": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Target is the per-replica target value for the chosen Metric.\nRequired when Metric is set; rejected when Metric is unset.\nUnits depend on the Metric:\n - request-count metrics (WaitingRequests, RunningRequests,\n ActiveRequests): an integer count (e.g., \"5\").\n - utilization metrics (VLLMKVCacheUtilization, GPUMemoryUtilization):\n a fraction between 0 and 1 (e.g., \"0.8\").", "example": "5", "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$", "x-kubernetes-int-or-string": true }, "wakeHoldSeconds": { "description": "WakeHoldSeconds is the duration the wake-from-zero trigger stays\n\"active\" after the last 599 sentinel response. The controller wraps\nthe wake PromQL with max_over_time(...[s:30s]) so\na one-shot request keeps the predictor warm for this long before\nscale-to-zero is allowed again. Default 300s when unset. Minimum\n60s. Only applies when MinReplicas == 0 and Metric is configured.", "example": 300, "format": "int32", "minimum": 60, "type": "integer" } }, "type": "object" }, "sharedMemorySize": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "SharedMemorySize sets the size of the pod's /dev/shm tmpfs (an in-memory\nemptyDir). vLLM-backed runtimes use /dev/shm for KV-cache and\ninter-process communication; the container runtime default (64Mi) is too\nsmall for multi-GPU / long-context serving. When unset at both the class\nand deployment layers, the runtime adapter adds no /dev/shm volume and the\npod keeps the container runtime default. No implicit default is applied;\nset this explicitly (the bootstrap catalog sets it per entry).", "example": "8Gi", "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$", "x-kubernetes-int-or-string": true } }, "required": [ "model", "runtime" ], "type": "object" }, "status": { "description": "Status defines the observed state of ModelClass.", "properties": { "conditions": { "description": "Conditions represent the current state of the ModelClass resource.", "items": { "description": "Condition contains details for one aspect of the current state of this API Resource.", "properties": { "lastTransitionTime": { "description": "lastTransitionTime is the last time the condition transitioned from one status to another.\nThis should be when the underlying condition changed. If that is not known, then using the time when the API field changed is acceptable.", "format": "date-time", "type": "string" }, "message": { "description": "message is a human readable message indicating details about the transition.\nThis may be an empty string.", "maxLength": 32768, "type": "string" }, "observedGeneration": { "description": "observedGeneration represents the .metadata.generation that the condition was set based upon.\nFor instance, if .metadata.generation is currently 12, but the .status.conditions[x].observedGeneration is 9, the condition is out of date\nwith respect to the current state of the instance.", "format": "int64", "minimum": 0, "type": "integer" }, "reason": { "description": "reason contains a programmatic identifier indicating the reason for the condition's last transition.\nProducers of specific condition types may define expected values and meanings for this field,\nand whether the values are considered a guaranteed API.\nThe value should be a CamelCase string.\nThis field may not be empty.", "maxLength": 1024, "minLength": 1, "pattern": "^[A-Za-z]([A-Za-z0-9_,:]*[A-Za-z0-9_])?$", "type": "string" }, "status": { "description": "status of the condition, one of True, False, Unknown.", "enum": [ "True", "False", "Unknown" ], "type": "string" }, "type": { "description": "type of condition in CamelCase or in foo.example.com/CamelCase.", "maxLength": 316, "pattern": "^([a-z0-9]([-a-z0-9]*[a-z0-9])?(\\.[a-z0-9]([-a-z0-9]*[a-z0-9])?)*/)?(([A-Za-z0-9][-A-Za-z0-9_.]*)?[A-Za-z0-9])$", "type": "string" } }, "required": [ "lastTransitionTime", "message", "reason", "status", "type" ], "type": "object" }, "type": "array", "x-kubernetes-list-map-keys": [ "type" ], "x-kubernetes-list-type": "map" }, "observedGeneration": { "description": "ObservedGeneration is the .metadata.generation the controller has\nprocessed; lags spec.generation while a reconcile is in flight.", "format": "int64", "type": "integer" }, "ready": { "description": "Ready is true when the referenced Model exists and is itself Ready.\nDownstream ModelDeployments may wait on this signal before attempting\nto spin up an InferenceService.", "type": "boolean" } }, "type": "object", "readOnly": true } }, "required": [ "spec" ], "type": "object" } } } } ```