--- updatedAt: 2026-08-21T16:12:58.000Z agentTools: projectIndex: https://docs.rackspace.com/llms.txt --- # Replace a Model Replaces the full Model object. The following spec fields are **immutable** after creation and must match the existing values: `spec.source.type`, `spec.source.uri`. # 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": "Model", "description": "Model represents a stored or remotely-sourced AI model artifact within a namespace.\nIt carries descriptive metadata about the model (family, type, precision,\nquantization, parameter count, etc.) and acts as the central identity that\nModelClass, LoRAAdapter, and FineTuningJob reference.\n\nrackai.rackspace.com/uri-hash label with the following rules:\n - Controller service account (e.g. rackai-controller-manager) MAY add,\n update, or remove the label. The controller stamps it when cache=true is\n first reconciled and removes it during the cache=true→false cleanup path.\n - All other principals (end-users, CI, kubectl) MUST NOT modify or delete\n the label once it has been stamped. Reject the request with a clear\n message explaining that the label is managed by the controller.\n\nA webhook is necessary here because CEL transition rules apply to ALL\nmutations regardless of who makes them, so CEL cannot distinguish the\ncontroller from a user and would block legitimate controller cleanup." } ], "paths": { "/namespaces/{namespace}/models/{name}": { "parameters": [ { "$ref": "#/components/parameters/namespace" }, { "$ref": "#/components/parameters/name" } ], "put": { "tags": [ "Model" ], "summary": "Replace a Model", "description": "Replaces the full Model object. The following spec fields are\n**immutable** after creation and must match the existing values:\n`spec.source.type`, `spec.source.uri`.\n", "operationId": "replaceNamespacedModel", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "responses": { "200": { "description": "OK", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Model" } } } }, "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": { "Model": { "description": "Model represents a stored or remotely-sourced AI model artifact within a namespace.\nIt carries descriptive metadata about the model (family, type, precision,\nquantization, parameter count, etc.) and acts as the central identity that\nModelClass, LoRAAdapter, and FineTuningJob reference.\n\nrackai.rackspace.com/uri-hash label with the following rules:\n - Controller service account (e.g. rackai-controller-manager) MAY add,\n update, or remove the label. The controller stamps it when cache=true is\n first reconciled and removes it during the cache=true→false cleanup path.\n - All other principals (end-users, CI, kubectl) MUST NOT modify or delete\n the label once it has been stamped. Reject the request with a clear\n message explaining that the label is managed by the controller.\n\nA webhook is necessary here because CEL transition rules apply to ALL\nmutations regardless of who makes them, so CEL cannot distinguish the\ncontroller from a user and would block legitimate controller cleanup.", "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": "Model" }, "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": "llama3-8b-base", "namespace": "org-idxxxxxxxxxx" } }, "spec": { "description": "Spec defines the desired state of Model.", "properties": { "authors": { "description": "Authors is the list of individuals or organizations that created the model.", "items": { "type": "string" }, "type": "array" }, "description": { "description": "Description is a human-readable description of this resource.", "example": "LLaMA 3.1 8B Instruct, original FP16 weights from Meta.", "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": "LLaMA 3.1 8B Instruct", "maxLength": 128, "type": "string" }, "integrity": { "description": "Integrity contains user-provided MD5 hashes for file integrity verification.", "properties": { "md5": { "additionalProperties": { "type": "string" }, "description": "MD5 contains the expected hex-encoded MD5 hashes of files to be verified.\nKeys MUST be the full storage path as it appears in SeaweedFS, e.g.\n\"/models///\". Basenames or relative paths are not\naccepted — the controller looks each key up verbatim in the observed\nstorage layout. The controller sets Ready=false with reason\nIntegrityCheckFailed on any mismatch.", "type": "object" } }, "type": "object", "x-kubernetes-validations": [ { "message": "Spec.Integrity.MD5 keys must be absolute storage paths starting with '/'", "rule": "!has(self.md5) || self.md5.all(k, k.startsWith('/'))" } ] }, "languages": { "description": "Languages is the list of ISO 639-1 language codes the model supports.", "items": { "type": "string" }, "type": "array" }, "modelFamily": { "description": "ModelFamily is the architectural family the model belongs to\n(e.g., \"LLaMA\", \"Mistral\", \"Qwen\").", "example": "LLaMA", "type": "string" }, "parameterCount": { "description": "ParameterCount is the approximate size of the model expressed as a human-readable string\n(e.g., \"7B\", \"13B\", \"70B\", \"405B\").", "example": "7B", "type": "string" }, "precision": { "description": "Precision is the floating-point format of the stored model weights\n(e.g., \"FP32\", \"FP16\", \"BF16\", \"FP8\", \"FP4\", \"INT8\", \"INT4\", or any\nother vendor-specific format).", "example": "FP16", "type": "string" }, "quantization": { "description": "Quantization is the post-training quantization scheme applied to the\nmodel weights (e.g., \"none\", \"INT8\", \"INT4\", \"NF4\", \"GPTQ\", \"AWQ\",\n\"EXL2\", \"HQQ\", \"Bitsandbytes\", or any other vendor-specific scheme).", "example": "none", "type": "string" }, "source": { "description": "Source describes where the model's weights come from.", "properties": { "cache": { "description": "Cache controls whether the platform pre-fetches URI-sourced weights into\ncluster storage and shares them (via per-namespace PV/PVC) across\ndeployments. When false (the default), each deployment downloads the\nweights to its pod at startup. Ignored when Type=Upload (uploaded bytes\nare inherently stored).", "type": "boolean" }, "modelPullCredential": { "description": "ModelPullCredential is the name of a RegistryCredential (Type=modelPull)\nin the same namespace used to authenticate when fetching weights from\nURI. Consulted by the cache-fetcher when cache=true, and injected into\nthe runtime container when cache=false. Required for private URIs;\nleave unset for public sources. Ignored when Type=Upload.", "example": "hf-modelpull-token", "type": "string" }, "type": { "description": "Type is \"Upload\" (user-supplied bytes) or \"URI\" (platform-fetched).\nImmutable after creation.", "enum": [ "Upload", "URI" ], "type": "string" }, "uri": { "description": "URI is the remote source. Required when Type=URI; must be empty when Type=Upload.\nImmutable after creation.", "example": "hf://qwen/qwen3-4b", "type": "string" } }, "required": [ "type" ], "type": "object", "x-kubernetes-validations": [ { "message": "source.type is immutable", "rule": "self.type == oldSelf.type" }, { "message": "source.uri is immutable", "rule": "has(self.uri) == has(oldSelf.uri) && (!has(self.uri) || self.uri == oldSelf.uri)" } ] }, "tasks": { "description": "Tasks is the list of ML tasks the model is suited for\n(e.g., \"text-generation\", \"summarization\", \"question-answering\").", "items": { "type": "string" }, "type": "array" } }, "required": [ "source" ], "type": "object" }, "status": { "description": "Status defines the observed state of Model.", "properties": { "conditions": { "description": "Conditions represent the current state of the Model 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" }, "files": { "description": "Files is the list of files discovered under the storage path.", "items": { "description": "ModelFileInfo describes a single file observed in storage.", "properties": { "path": { "description": "Path is the full path of the file within the storage backend.", "type": "string" }, "size": { "description": "Size is the file size in bytes.", "format": "int64", "type": "integer" } }, "required": [ "path", "size" ], "type": "object" }, "type": "array" }, "integrity": { "description": "Integrity holds MD5 hashes observed from the storage backend, keyed by file path.", "properties": { "md5": { "additionalProperties": { "type": "string" }, "description": "MD5 contains MD5 hashes of the model files as observed from the storage backend.", "type": "object" } }, "type": "object" }, "observedGeneration": { "description": "ObservedGeneration is the most recent generation observed by the controller.", "format": "int64", "type": "integer" }, "phase": { "description": "Phase is a high-level summary of the Model lifecycle state.", "enum": [ "Pending", "Processing", "Ready", "Failed" ], "type": "string" }, "pvName": { "description": "PVName is the name of the PersistentVolume provisioned for this Model.", "type": "string" }, "pvcName": { "description": "PVCName is the name of the PersistentVolumeClaim provisioned for this Model.", "type": "string" }, "ready": { "description": "Ready indicates whether the Model artifacts are present, accessible,\nand passing integrity checks (if configured).", "type": "boolean" }, "size": { "anyOf": [ { "type": "integer" }, { "type": "string" } ], "description": "Size is the total on-disk size of all files under the storage path.", "pattern": "^(\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))(([KMGTPE]i)|[numkMGTPE]|([eE](\\+|-)?(([0-9]+(\\.[0-9]*)?)|(\\.[0-9]+))))?$", "x-kubernetes-int-or-string": true } }, "type": "object", "readOnly": true } }, "required": [ "spec" ], "type": "object" } } } } ```