How to self-host the Prefect Server with Helm

You can use Helm to manage a self-hosted Prefect server and a worker.

Prerequisites

A Kubernetes cluster
Install the Helm CLI

Deploy a server with Helm

Configuring ingress or publicly exposing Prefect from the cluster is business dependent and not covered in this tutorial. For details on Ingress configuration, consult the Kubernetes documentation.

Add the Prefect Helm repository:

helm repo add prefect https://prefecthq.github.io/prefect-helm helm repo update

Create a namespace

Create a new namespace for this tutorial (all commands will use this namespace):

kubectl create namespace prefect kubectl config set-context --current --namespace=prefect 

Deploy the server

Show Deploy with default values

For a simple deployment using only the default values defined in the chart:

helm install prefect-server prefect/prefect-server --namespace prefect

Show Deploy with customized values to configure basic authentication

For a customized deployment, first create a server-values.yaml file for the server (see values.yaml template):

server:  basicAuth:  enabled: true  existingSecret: server-auth-secret

Create a secret for the API basic authentication username and password:

kubectl create secret generic server-auth-secret \  --namespace prefect --from-literal auth-string='admin:password123' 

Install the server:

helm install prefect-server prefect/prefect-server \  --namespace prefect \  -f server-values.yaml 

Expected output:

NAME: prefect-server LAST DEPLOYED: Tue Mar 4 09:08:07 2025 NAMESPACE: prefect STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: Run the following command to port-forward the UI to your localhost: $ kubectl --namespace prefect port-forward svc/prefect-server 4200:4200  Visit http://localhost:4200 to use Prefect! 

Access the Prefect UI:

kubectl --namespace prefect port-forward svc/prefect-server 4200:4200

Open localhost:4200 in your browser. If using basic authentication, sign in with admin:password123.

Deploy a worker with Helm

To connect a worker to your self-hosted Prefect server in the same cluster:

Show Deploy with the minimum required values

Create a worker-values.yaml file for the worker (see values.yaml template):

worker:  apiConfig: selfHostedServer  config:  workPool: kube-test  selfHostedServerApiConfig:  apiUrl: http://prefect-server.prefect.svc.cluster.local:4200/api 

Install the worker:

helm install prefect-worker prefect/prefect-worker \  --namespace prefect \  -f worker-values.yaml 

Show Deploy with customized values to configure basic authentication

Create a worker-values.yaml file for the worker (see values.yaml template):

worker:  apiConfig: selfHostedServer  config:  workPool: kube-test  selfHostedServerApiConfig:  apiUrl: http://prefect-server.prefect.svc.cluster.local:4200/api  basicAuth:  enabled: true  existingSecret: worker-auth-secret 

Create a secret for the API basic authentication username and password:

kubectl create secret generic worker-auth-secret \  --namespace prefect --from-literal auth-string='admin:password123' 

Install the worker:

helm install prefect-worker prefect/prefect-worker \  --namespace prefect \  -f worker-values.yaml 

Expected output:

Release "prefect-worker" has been installed. Happy Helming! NAME: prefect-worker LAST DEPLOYED: Tue Mar 4 11:26:21 2025 NAMESPACE: prefect STATUS: deployed REVISION: 1 TEST SUITE: None NOTES: 

Cleanup

To uninstall the self-hosted Prefect server and Prefect worker:

helm uninstall prefect-worker helm uninstall prefect-server

Troubleshooting

Show Container creation error

If you see this error:

Error from server (BadRequest): container "prefect-server" in pod "prefect-server-7c87b7f7cf-sgqj2" is waiting to start: CreateContainerConfigError 

Run kubectl events and confirm that the authString is correct.

Show Authentication error

If you see this error:

prefect.exceptions.PrefectHTTPStatusError: Client error '401 Unauthorized' for url 'http://prefect-server.prefect.svc.cluster.local:4200/api/work_pools/kube-test' Response: {'exception_message': 'Unauthorized'} For more information check: https://developer.mozilla.org/en-US/docs/Web/HTTP/Status/401 An exception occurred. 

Ensure basicAuth is configured in the worker-values.yaml file.

Show Connection error

If you see this error:

File "/usr/local/lib/python3.11/site-packages/httpcore/_backends/anyio.py", line 113, in connect_tcp  with map_exceptions(exc_map): File "/usr/local/lib/python3.11/contextlib.py", line 158, in __exit__  self.gen.throw(typ, value, traceback) File "/usr/local/lib/python3.11/site-packages/httpcore/_exceptions.py", line 14, in map_exceptions  raise to_exc(exc) from exc httpcore.ConnectError: [Errno -2] Name or service not known 

Ensure the PREFECT_API_URL environment variable is properly templated by running the following command:

helm template prefect-worker prefect/prefect-worker -f worker-values.yaml

The URL format should look like the following:

http://prefect-server.prefect.svc.cluster.local:4200/api

If the worker is not in the same cluster and namespace, the precise format will vary.

For additional troubleshooting and configuration, review the Prefect Worker Helm Chart.

Workflows

Automations

Workflow Infrastructure

Platform

Extensibility

How to self-host the Prefect Server with Helm

Prerequisites

Deploy a server with Helm

Add the Prefect Helm repository:

Create a namespace

Deploy the server

Create a secret for the API basic authentication username and password:

Install the server:

Access the Prefect UI:

Deploy a worker with Helm

Install the worker:

Create a secret for the API basic authentication username and password:

Install the worker:

Cleanup

Troubleshooting

Workflows

Automations

Workflow Infrastructure

Platform

Extensibility

​Prerequisites

​Deploy a server with Helm

​Add the Prefect Helm repository:

​Create a namespace

​Deploy the server

​Create a secret for the API basic authentication username and password:

​Install the server:

​Access the Prefect UI:

​Deploy a worker with Helm

​Install the worker:

​Create a secret for the API basic authentication username and password:

​Install the worker:

​Cleanup

​Troubleshooting

Prerequisites

Deploy a server with Helm

Add the Prefect Helm repository:

Create a namespace

Deploy the server

Create a secret for the API basic authentication username and password:

Install the server:

Access the Prefect UI:

Deploy a worker with Helm

Install the worker:

Create a secret for the API basic authentication username and password:

Install the worker:

Cleanup

Troubleshooting