> ## Documentation Index
> Fetch the complete documentation index at: https://zenml.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Kubernetes Orchestrator

> How to orchestrate pipelines with Kubernetes

The Kubernetes orchestrator is an [orchestrator](/component-gallery/orchestrators) flavor provided with the ZenML `kubernetes` integration that runs your pipelines on a [Kubernetes](https://kubernetes.io/) cluster.

This component is only meant to be used within the context of [remote ZenML deployment scenario](/getting-started/deploying-zenml). Usage with a local ZenML deployment may lead to unexpected behavior!

### When to use it

You should use the Kubernetes orchestrator if:

* you're looking lightweight way of running your pipelines on Kubernetes.

* you don't need a UI to list all your pipelines runs.

* you're not willing to maintain [Kubeflow Pipelines](/component-gallery/orchestrators/kubeflow) on your Kubernetes cluster.

* you're not interested in paying for managed solutions like [Vertex](/component-gallery/orchestrators/gcloud-vertexai).

### How to deploy it

The Kubernetes orchestrator requires a Kubernetes cluster in order to run. There are many ways to deploy a Kubernetes cluster using different cloud providers or on your custom infrastructure, and we can't possibly cover all of them, but you can check out our cloud guide

If the above Kubernetes cluster is deployed remotely on the cloud, then another pre-requisite to use this orchestrator would be to deploy and connect to a [remote ZenML server](/getting-started/deploying-zenml).

### How to use it

To use the Kubernetes orchestrator, we need:

* The ZenML `kubernetes` integration installed. If you haven't done so, run

```
zenml integration install kubernetes  
```

* [Docker](https://www.docker.com) installed and running.

* [kubectl](https://kubernetes.io/docs/tasks/tools/#kubectl) installed.

* A [remote artifact store](/component-gallery/artifact-stores) as part of your stack.

* A [remote container registry](/component-gallery/container-registries) as part of your stack.

* A Kubernetes cluster [deployed](/component-gallery/orchestrators/kubernetes#how-to-deploy-it) and the name of your Kubernetes context which points to this cluster. Run`kubectl config get-contexts` to see a list of available contexts.

We can then register the orchestrator and use it in our active stack:

```
zenml orchestrator register  \
    --flavor=kubernetes \
    --kubernetes_context=

# Register and activate a stack with the new orchestrator
zenml stack register  -o  ... --set
```

ZenML will build a Docker image called `<CONTAINER_REGISTRY_URI>/zenml:<PIPELINE_NAME>` which includes your code and use it to run your pipeline steps in Kubernetes. Check out [this page](/advanced-guide/pipelines/containerization) if you want to learn more about how ZenML builds these images and how you can customize them.

You can now run any ZenML pipeline using the Kubernetes orchestrator:

```
python file_that_runs_a_zenml_pipeline.py
```

#### Additional configuration

For additional configuration of the Kubernetes orchestrator, you can pass `KubernetesOrchestratorSettings` which allows you to configure (among others) the following attributes:

* `pod_settings`: Node selectors, affinity and tolerations to apply to the Kubernetes Pods running your pipline. These can be either specified using the Kubernetes model objects or as dictionaries.

```
from zenml.integrations.kubernetes.flavors.kubernetes_orchestrator_flavor import KubernetesOrchestratorSettings
from kubernetes.client.models import V1Toleration

kubernetes_settings = KubernetesOrchestratorSettings(
    pod_settings={
        "affinity": {
            "nodeAffinity": {
                "requiredDuringSchedulingIgnoredDuringExecution": {
                    "nodeSelectorTerms": [
                        {
                            "matchExpressions": [
                                {
                                    "key": "node.kubernetes.io/name",
                                    "operator": "In",
                                    "values": ["my_powerful_node_group"],
                                }
                            ]
                        }
                    ]
                }
            }
        },
        "tolerations": [
            V1Toleration(
                key="node.kubernetes.io/name",
                operator="Equal",
                value="",
                effect="NoSchedule"
            )
        ]
    }
)

@pipeline(
    settings={
        "orchestrator.kubernetes": kubernetes_settings
    }
)
  ...
```

Check out the [API docs](https://apidocs.zenml.io/latest/integration%5Fcode%5Fdocs/integrations-kubernetes/#zenml.integrations.kubernetes.flavors.kubernetes%5Forchestrator%5Fflavor.KubernetesOrchestratorSettings) for a full list of available attributes and [this docs page](/advanced-guide/pipelines/settings) for more information on how to specify settings.

A concrete example of using the Kubernetes orchestrator can be found [here](https://github.com/zenml-io/zenml/tree/main/examples/kubernetes%5Forchestration).

For more information and a full list of configurable attributes of the Kubernetes orchestrator, check out the [API Docs](https://apidocs.zenml.io/latest/integration%5Fcode%5Fdocs/integrations-kubernetes/#zenml.integrations.kubernetes.orchestrators.kubernetes%5Forchestrator.KubernetesOrchestrator).

#### Enabling CUDA for GPU-backed hardware

Note that if you wish to use this orchestrator to run steps on a GPU, you will need to follow [the instructions on this page](/advanced-guide/pipelines/gpu-hardware) to ensure that it works. It requires adding some extra settings customization and is essential to enable CUDA for the GPU to give its full acceleration.