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:
Copy
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):Copy
kubectl create namespace prefect
kubectl config set-context --current --namespace=prefect
Deploy the server
Show Deploy with default values
Show Deploy with default values
For a simple deployment using only the default values defined in the chart:
Copy
helm install prefect-server prefect/prefect-server --namespace prefect
Show Deploy with customized values to configure basic authentication
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):Copy
server:
basicAuth:
enabled: true
existingSecret: server-auth-secret
Create a secret for the API basic authentication username and password:
Copy
kubectl create secret generic server-auth-secret \
--namespace prefect --from-literal auth-string='admin:password123'
Install the server:
Copy
helm install prefect-server prefect/prefect-server \
--namespace prefect \
-f server-values.yaml
Copy
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:
Copy
kubectl --namespace prefect port-forward svc/prefect-server 4200:4200
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
Show Deploy with the minimum required values
Create a
worker-values.yaml file for the worker (see values.yaml template):Copy
worker:
apiConfig: selfHostedServer
config:
workPool: kube-test
selfHostedServerApiConfig:
apiUrl: http://prefect-server.prefect.svc.cluster.local:4200/api
Install the worker:
Copy
helm install prefect-worker prefect/prefect-worker \
--namespace prefect \
-f worker-values.yaml
Show Deploy with customized values to configure basic authentication
Show Deploy with customized values to configure basic authentication
Create a
worker-values.yaml file for the worker (see values.yaml template):Copy
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:
Copy
kubectl create secret generic worker-auth-secret \
--namespace prefect --from-literal auth-string='admin:password123'
Install the worker:
Copy
helm install prefect-worker prefect/prefect-worker \
--namespace prefect \
-f worker-values.yaml
Copy
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:Copy
helm uninstall prefect-worker
helm uninstall prefect-server
Troubleshooting
Show Container creation error
Show Container creation error
If you see this error:Run
Copy
Error from server (BadRequest): container "prefect-server" in pod "prefect-server-7c87b7f7cf-sgqj2" is waiting to start: CreateContainerConfigError
kubectl events and confirm that the authString is correct.Show Authentication error
Show Authentication error
If you see this error:Ensure
Copy
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.
basicAuth is configured in the worker-values.yaml file.Show Connection error
Show Connection error
If you see this error:Ensure the The URL format should look like the following:For additional troubleshooting and configuration, review the Prefect Worker Helm Chart.
Copy
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
PREFECT_API_URL environment variable is properly templated by running the following command:Copy
helm template prefect-worker prefect/prefect-worker -f worker-values.yaml
Copy
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.