{"id":6036,"library":"prefect-kubernetes","title":"Prefect Kubernetes Integration","description":"Prefect-kubernetes provides integrations for running Prefect flows on Kubernetes. It enables Prefect 2.x deployments to provision Kubernetes Jobs for flow runs using `KubernetesDeployment` and manage them with `KubernetesWorker`. The current version is 0.7.7, and it follows the Prefect core library's release cadence, with integrations typically updated alongside major Prefect releases.","status":"active","version":"0.7.7","language":"en","source_language":"en","source_url":"https://github.com/PrefectHQ/prefect/tree/main/src/integrations/prefect-kubernetes","tags":["prefect","kubernetes","orchestration","workflow","worker","deployment"],"install":[{"cmd":"pip install prefect-kubernetes","lang":"bash","label":"Install prefect-kubernetes"}],"dependencies":[{"reason":"Core Prefect library, required for defining flows and interacting with the API.","package":"prefect","optional":false},{"reason":"Kubernetes Python client library, required for interacting with the Kubernetes API.","package":"kubernetes","optional":false}],"imports":[{"note":"KubernetesDeployment is part of the prefect-kubernetes integration package, not the core prefect library.","wrong":"from prefect.deployments import KubernetesDeployment","symbol":"KubernetesDeployment","correct":"from prefect_kubernetes.deployments import KubernetesDeployment"},{"note":"The worker class is located in the `workers` submodule as of recent versions.","wrong":"from prefect_kubernetes.kubernetes_worker import KubernetesWorker","symbol":"KubernetesWorker","correct":"from prefect_kubernetes.workers import KubernetesWorker"}],"quickstart":{"code":"import os\nfrom prefect import flow\nfrom prefect_kubernetes.deployments import KubernetesDeployment\n\n# 1. Define a simple Prefect Flow\n@flow(log_prints=True)\ndef hello_kubernetes_flow(name: str = \"world\"):\n    import platform\n    print(f\"Hello, {name} from Kubernetes! Running on {platform.node()}\")\n\n# 2. Create a Kubernetes Deployment definition\n# This deployment will tell Prefect how to run `hello_kubernetes_flow` on Kubernetes.\n# It requires a work pool named \"kubernetes-work-pool\" to exist in your Prefect server.\n# Create it with: `prefect work-pool create kubernetes-work-pool --type kubernetes`\n\n# IMPORTANT: The 'image' specified here must contain your flow code and Prefect installed.\n# For a real scenario, you would build a custom Docker image for your flow.\n# Example custom image setup:\n#   Dockerfile:\n#     FROM prefecthq/prefect:2-python3.10\n#     COPY quickstart_kubernetes.py /app/quickstart_kubernetes.py\n#     WORKDIR /app\n#   Build & Push:\n#     docker build -t your-registry/your-flow-image:latest .\n#     docker push your-registry/your-flow-image:latest\n# Then use `your-registry/your-flow-image:latest` below.\n\ntry:\n    deployment = KubernetesDeployment(\n        name=\"hello-kubernetes-flow-deployment\",\n        description=\"Runs a simple 'Hello, Kubernetes!' flow on Kubernetes.\",\n        flow_name=hello_kubernetes_flow.name,\n        work_pool_name=\"kubernetes-work-pool\", # This work pool MUST exist in your Prefect server\n        image=\"prefecthq/prefect:2-python3.10\", # Base Prefect image; replace for custom flows\n        entrypoint=\"quickstart_kubernetes.py:hello_kubernetes_flow\", # Assumes this code is saved as quickstart_kubernetes.py\n        # You can also pass job_variables or infra_overrides for custom Kubernetes Job spec\n        # job_variables={\"MY_ENV_VAR\": \"my_value\"},\n        # infra_overrides={\n        #     \"job_template\": {\n        #         \"spec\": {\"template\": {\"spec\": {\"nodeSelector\": {\"kubernetes.io/hostname\": \"your-node\"}}}}\n        #     }\n        # }\n    )\n    deployment_id = deployment.apply()\n    print(f\"Deployment '{deployment.name}' created/updated with ID: {deployment_id}\")\n\nexcept Exception as e:\n    print(f\"Failed to create Kubernetes Deployment: {e}\")\n    print(\"Ensure PREFECT_API_URL is set and Prefect server is running.\")\n\n# To start the Kubernetes Worker that will pick up runs for this deployment:\n# prefect worker start --pool kubernetes-work-pool\n","lang":"python","description":"This quickstart demonstrates how to define a Prefect flow and then create a `KubernetesDeployment` object to run it on a Kubernetes cluster. To make this runnable:\n1. Ensure a Prefect server (e.g., `prefect server start`) and a Kubernetes cluster are running.\n2. Configure your `kubectl` context to point to your cluster.\n3. Set your `PREFECT_API_URL` environment variable to point to your Prefect server.\n4. Create a Kubernetes work pool: `prefect work-pool create kubernetes-work-pool --type kubernetes`.\n5. Save the provided Python code as `quickstart_kubernetes.py` and run it: `python quickstart_kubernetes.py`. This will register the deployment with your Prefect server.\n6. Start a Kubernetes worker: `prefect worker start --pool kubernetes-work-pool`.\n7. Create a flow run from the Prefect UI or CLI: `prefect deployment run 'hello-kubernetes-flow-deployment'`."},"warnings":[{"fix":"Rewrite deployment definitions using `KubernetesDeployment` and manage execution with `KubernetesWorker`. Refer to the Prefect 2.x migration guide for detailed steps.","message":"Prefect 1.x `KubernetesAgent` and `KubernetesRunner` are deprecated and replaced by Prefect 2.x `KubernetesWorker` and `KubernetesDeployment`. Migrating from Prefect 1.x to 2.x requires a complete rewrite of your deployment definitions and infrastructure setup for Kubernetes.","severity":"breaking","affected_versions":"Prefect < 2.0 to Prefect >= 2.0"},{"fix":"Familiarize yourself with Prefect 2.x concepts: Work Pools define the environment, Workers execute runs based on Work Pool definitions, and Deployments define *what* to run. The `KubernetesWorker` acts as an orchestrator, submitting K8s Jobs.","message":"Understanding the interaction between Prefect 2.x Workers, Work Pools, and Kubernetes Jobs is crucial. A `KubernetesWorker` polls a `KubernetesWorkPool` for flow runs, and for each run, it dynamically creates a Kubernetes Job. This is different from Prefect 1.x 'Agents' which directly ran flow code.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Ensure the environment where `KubernetesWorker` runs (or the local machine if deploying externally) has appropriate Kubernetes client configuration and permissions. For in-cluster workers, verify the service account has `create`, `get`, `list`, `watch`, `delete` permissions for `jobs` and `pods`.","message":"Correct Kubernetes authentication and configuration (e.g., `kubeconfig` context or in-cluster service account permissions) are essential. Misconfiguration often leads to `prefect-kubernetes` failing to create or monitor Kubernetes Jobs.","severity":"gotcha","affected_versions":">=0.1.0"},{"fix":"Always build a custom Docker image that includes your flow script and its `requirements.txt`. Push this image to a registry accessible by your Kubernetes cluster. If the registry is private, configure `imagePullSecrets` in your Kubernetes deployment or worker configuration.","message":"The Docker image specified in a `KubernetesDeployment` must contain your flow's code and all its Python dependencies. If the image is private, Kubernetes also needs image pull secrets configured.","severity":"gotcha","affected_versions":">=0.1.0"}],"env_vars":null,"last_verified":"2026-04-14T00:00:00.000Z","next_check":"2026-07-13T00:00:00.000Z"}