Implementation:Kubeflow Kubeflow Model Registry API

Knowledge Sources	Kubeflow Model Registry README
Domains	MLOps, Model Management, REST API
Last Updated	2026-02-13 00:00 GMT

Overview

Concrete tool for registering, versioning, and managing trained model artifacts provided by the Kubeflow Model Registry component.

Description

The Kubeflow Model Registry provides both a REST API and a Python SDK (model-registry package) for cataloging trained models. The registry stores three primary entities: RegisteredModel (the logical model identity), ModelVersion (a specific version with artifacts and metadata), and ModelArtifact (the physical artifact location and format). The Python SDK exposes these through the ModelRegistryClient class, which provides methods such as register_model(), get_registered_model(), get_model_version(), and list_model_versions().

The registry integrates with KServe through labels on InferenceService resources that reference the registered model and version, enabling automated deployment of registered models. It also integrates with Kubeflow Pipelines for automated registration as a pipeline step. Model versions carry a lifecycle state (LIVE or ARCHIVED) that supports governed promotion workflows.

External Reference

Usage

Use the Model Registry API when:

Trained model artifacts must be cataloged with versioning, metadata, and lineage information.
A governed workflow is needed to promote models through lifecycle states before deployment.
KServe InferenceService deployments must reference models from the registry.
Automated pipeline steps need to register models programmatically after training and evaluation.
Teams need to compare and query model versions by metrics and metadata.

Code Reference

Source Location

Repository: kubeflow/model-registry
File: clients/python/src/model_registry/ (Python SDK source)

Signature

from model_registry import ModelRegistryClient

client = ModelRegistryClient(
    server_address="http://model-registry-service.kubeflow.svc.cluster.local",
    port=8080,
    author="user@example.com",
)

registered_model = client.register_model(
    name="my-model",
    uri="s3://models/my-model/v1/model.pt",
    version="v1",
    description="Initial trained model",
    model_format_name="pytorch",
    model_format_version="2.0",
    storage_key="s3-credentials",
    metadata={
        "accuracy": 0.94,
        "dataset": "training-set-v3",
        "pipeline_run_id": "run-abc123",
    },
)

Import

# Install the Model Registry Python SDK
pip install model-registry

# Deploy Model Registry on the cluster
kubectl apply -k "github.com/kubeflow/model-registry/manifests/kustomize/overlays/db"

I/O Contract

Inputs

Name	Type	Required	Description
name	string	Yes	Logical name of the registered model (e.g., "fraud-detector")
uri	string	Yes	Storage URI pointing to the model artifacts
version	string	Yes	Version identifier for this model version
description	string	No	Human-readable description of this model version
model_format_name	string	No	Model format (e.g., pytorch, tensorflow, onnx, sklearn)
model_format_version	string	No	Version of the model format
storage_key	string	No	Reference to storage credentials for accessing the model URI
metadata	dict	No	Key-value metadata including metrics, hyperparameters, and lineage info

Outputs

Name	Type	Description
RegisteredModel	RegisteredModel object	The top-level model identity in the registry
ModelVersion	ModelVersion object	Versioned record with URI, state, and metadata
ModelVersion.state	enum (LIVE, ARCHIVED)	Lifecycle state governing deployment eligibility
Model URI	string	Canonical URI for the model artifacts, usable by serving infrastructure

Usage Examples

Basic Usage

from model_registry import ModelRegistryClient

# Initialize the client
client = ModelRegistryClient(
    server_address="http://model-registry-service.kubeflow.svc.cluster.local",
    port=8080,
    author="ml-engineer@example.com",
)

# Register a new model version
rm = client.register_model(
    name="fraud-detector",
    uri="s3://ml-models/fraud-detector/v2/model.onnx",
    version="v2",
    description="Retrained with Q4 2025 data, improved precision",
    model_format_name="onnx",
    model_format_version="1.14",
    metadata={
        "accuracy": 0.967,
        "precision": 0.943,
        "recall": 0.951,
        "f1_score": 0.947,
        "training_pipeline_run": "run-xyz789",
        "dataset_version": "fraud-data-q4-2025",
    },
)

# Retrieve model version details
model_version = client.get_model_version(
    name="fraud-detector",
    version="v2",
)

# List all versions for a registered model
versions = client.list_model_versions(name="fraud-detector")
for v in versions:
    print(f"Version: {v.version}, State: {v.state}, URI: {v.uri}")

Pipeline Integration

from kfp import dsl
from model_registry import ModelRegistryClient

@dsl.component(
    base_image="python:3.11",
    packages_to_install=["model-registry"],
)
def register_model_step(
    model_uri: str,
    model_name: str,
    version: str,
    accuracy: float,
):
    client = ModelRegistryClient(
        server_address="http://model-registry-service.kubeflow.svc.cluster.local",
        port=8080,
        author="pipeline-automation",
    )
    client.register_model(
        name=model_name,
        uri=model_uri,
        version=version,
        model_format_name="pytorch",
        metadata={"accuracy": accuracy},
    )

Related Pages

Implements Principle

Principle:Kubeflow_Kubeflow_Register_Model

Requires Environment

Environment:Kubeflow_Kubeflow_Python_KFP_SDK_Environment

Page Connections

Double-click a node to navigate. Hold to expand connections.

Principle

Implementation

Heuristic

Environment