Install & Compatibility
Where this runs
tested against v2.16.0 · pip install
no network on importno background threads
Install × environment matrix
Each cell = how many times install + import succeeded across repeated harness runs. Partial = flaky.
glibc = Debian/Ubuntu slim · musl = Alpine Linux
muslpy 3.10–3.910 runs
installs and imports cleanly · install 0.0s · import 0.000s · 93.7MB
glibcpy 3.10–3.910 runs
installs and imports cleanly · install 8.5s · import 0.000s · 95MB
96MB installed
● package 96MB
Code
Verified usage
Verified import paths — ran on the pinned version, not inferred.
Client
✓ from kfp import Client
✗ from kfp_kubernetes import common
This example demonstrates how to define a KFP pipeline and use `kfp_kubernetes.common` functions to add Kubernetes-specific configurations like a volume, node selector, and toleration to a component. This pipeline requires a KFP SDK v2 compatible environment for execution and an existing PVC named 'my-data-pvc' on the Kubernetes cluster.
import kfp
from kfp import dsl
from kfp_kubernetes import common
# Define a simple KFP component
@dsl.component
def hello_world_op(name: str) -> str:
import os
print(f"Hello, {name} from pod {os.environ.get('KUBERNETES_POD_NAME', 'unknown')}!")
return f"Hello, {name}!"
# Create a pipeline
@dsl.pipeline(name="kubernetes-config-pipeline")
def kubernetes_config_pipeline():
task = hello_world_op(name="World")
# Add a Kubernetes volume to the component's pod
# This assumes an existing PVC named 'my-data-pvc' on your cluster
common.add_volume_to_component(
task,
volume_name="my-data-volume",
mount_path="/mnt/data",
existing_pvc_name="my-data-pvc"
)
# Add a node selector to schedule the task on a specific node
common.add_node_selector_to_component(task, "kubernetes.io/hostname", "my-worker-node-label")
# Add a toleration to allow scheduling on tainted nodes
common.add_toleration_to_component(task, "key", "value", "Equal", "NoSchedule")
# Compile the pipeline (requires kfp to be installed)
if __name__ == "__main__":
try:
kfp.compiler.Compiler().compile(kubernetes_config_pipeline, "kubernetes_config_pipeline.yaml")
print("Pipeline compiled successfully to kubernetes_config_pipeline.yaml")
except Exception as e:
print(f"Error compiling pipeline: {e}")
Debug
Known issues
breakingThe KFP SDK v2 introduced significant API changes for configuring components, replacing direct manipulation of `ContainerOp` attributes (common in KFP v1) with utility functions or decorators.fixMigrate pipeline code to KFP SDK v2. Use functions from `kfp_kubernetes.common` (e.g., `add_volume_to_component`) or `kfp.kubernetes` module functions (if directly provided by the `kfp` package itself) on `dsl.Task` objects.
affects: KFP SDK v2.0.0 onwards
gotchaEnsuring strict version alignment between `kfp-kubernetes`, `kfp`, `kfp-server-api`, and `kfp-pipeline-spec` is critical. Mismatched versions can lead to runtime errors, unexpected behavior, or incorrect Kubernetes manifest generation.fixAlways install all KFP SDK related packages with the same exact version string, e.g., `pip install kfp==2.16.0 kfp-kubernetes==2.16.0 kfp-server-api==2.16.0 kfp-pipeline-spec==2.16.0`.
affects: All KFP SDK v2.x versions
gotchaStarting with KFP 2.15.0, the default object store deployment for new installations changed from MinIO to SeaweedFS. Existing installations or specific configurations might still use MinIO, but this change can affect how persistent volumes are expected to be managed.fixReview your Kubeflow cluster's object store configuration. Ensure your pipeline's volume configurations (e.g., via `add_volume_to_component`) are compatible with the deployed object store or explicitly configure your preferred storage solution.
affects: KFP SDK v2.15.0 and later
gotchaWhile `kfp-kubernetes` helps generate Kubernetes manifests for pipeline components, the final execution is dependent on the actual Kubernetes cluster configuration. Discrepancies (e.g., missing StorageClasses, incorrect node labels, RBAC permissions) can cause pipeline failures.fixValidate the generated Kubernetes YAML (e.g., `kubernetes_config_pipeline.yaml`) and ensure your cluster has the necessary resources, permissions (RBAC), node labels/taints, and storage classes to support the requested configurations.
affects: All versions
Upgrade
Version history
2.16.1latest on PyPI · released May 5, 2026
Audit
Dependencies
kfpoptionalMain KFP SDK, often used together for pipeline definition and compilation.
kfp-server-apioptionalKFP client API for interacting with the KFP backend.
kfp-pipeline-specoptionalProvides the pipeline definition specification.