Deploy a Prefect Server and Worker with Helm

In this tutorial, you’ll learn how to deploy an OSS Server and Worker with Helm.

Prerequisites

A Kubernetes cluster
Install the Helm CLI

Get started

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.

Set up your environment

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 Prefect Server with Helm

Add the Prefect Helm repository:

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

For a customized deployment, create a values.yaml file for Prefect Server (see values.yaml template).

Create a secret for the API basic auth:

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

Example server-values.yaml file for this tutorial:

server:
  basicAuth:
    enabled: true
    # Must pre-exist if existingSecret is used; use authString otherwise
    existingSecret: "server-auth-secret"  
  autoscaling:
    enabled: true
  livenessProbe:
    enabled: true
  readinessProbe:
    enabled: true

Install Prefect Server:

helm install prefect-server prefect/prefect-server -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-server port-forward svc/prefect-server 4200:4200

Visit http://localhost:4200 to use Prefect!

Access the Prefect UI:

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

Open localhost:4200 in your browser and sign in with admin:password123.

Deploy a Prefect Worker

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

Create a worker-values.yaml file for this tutorial:

worker:
  apiConfig: selfHostedServer
  config:
    workPool: kube-test
  selfHostedServerApiConfig:
    # SERVICE.NAMESPACE if in same cluster, or FQDN if external
    apiUrl: http://prefect-server.prefect-server.svc.cluster.local:4200/api

Install the Prefect Worker:

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

Create a secret for the API basic auth:

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

Create a worker-values.yaml file for this tutorial:

worker:
  apiConfig: selfHostedServer
  config:
    workPool: kube-test
  selfHostedServerApiConfig:
    # SERVICE.NAMESPACE if in same cluster, or FQDN if external
    apiUrl: http://prefect-server.prefect-server.svc.cluster.local:4200/api
  basicAuth:
    enabled: true
    existingSecret: worker-auth-secret

Install the Prefect Worker:

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

Expected output:

Release "prefect-worker" has been upgraded. 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 Prefect Server and Worker:

helm uninstall prefect-worker
helm uninstall prefect-server

Troubleshooting

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.

If you see this error:

prefect.exceptions.PrefectHTTPStatusError: Client error '401 Unauthorized' for url 'http://prefect-server.prefect-server.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.

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-server.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 Helm Worker Chart.

Get started

Tutorials

Develop

Deploy

Automate

Operate

Migrate

Deploy a Prefect Server and Worker with Helm

Prerequisites

Get started

Set up your environment

Deploy Prefect Server with Helm

Deploy a Prefect Worker

Cleanup

Troubleshooting

Get started

Tutorials

Develop

Deploy

Automate

Operate

Migrate

​Prerequisites

​Get started

​Set up your environment

​Deploy Prefect Server with Helm

​Deploy a Prefect Worker

​Cleanup

​Troubleshooting

Prerequisites

Get started

Set up your environment

Deploy Prefect Server with Helm

Deploy a Prefect Worker

Cleanup

Troubleshooting