Repository: PrefectHQ/prefect
Pull request: feat: Add Prefect Server and Worker Helm Tutorial
Adds a tutorial for installing Prefect Server and a Worker with Helm
Closes https://github.com/PrefectHQ/prefect/issues/17360
Relates to https://linear.app/prefect/issue/PLA-1087/[quickstart-guide]-how-to-deploy-a-worker-server-with-helm
### Checklist


- [x] This pull request references any related issue by including "closes `<link to issue>`"
- [ ] If this pull request adds new functionality, it includes unit tests that cover the changes
- [ ] If this pull request removes docs files, it includes redirect settings in `mint.json`.
- [ ] If this pull request adds functions or classes, it includes helpful docstrings.


Problem statement:
PrefectServer + PrefectWorker QuickStart Guide
### Describe the current behavior

Currently only prefect-helm contains instructions / README and is not directly referenced, or can be hard to find for a new user.

### Describe the proposed behavior

Add a quickstart tutorial for platform engineers to quickly stand-up a Prefect Server (OSS) and Prefect Worker to integrate with.

### Example Use

A new platform engineer user persona wants to quickly spin-up Prefect OSS and a worker for testing or POC.

### Additional context

_No response_

Hints from issue discussion:

Commit message: Update server-and-worker.mdx

Patch to review:
diff --git a/docs/mint.json b/docs/mint.json
index 69433b9d826a..30a1acbdd012 100644
--- a/docs/mint.json
+++ b/docs/mint.json
@@ -80,7 +80,8 @@
             "v3/tutorials/platform",
             "v3/tutorials/debug",
             "v3/tutorials/alerts",
-            "v3/tutorials/modal"
+            "v3/tutorials/modal",
+            "v3/tutorials/server-and-worker"
           ]
         }
       ],
diff --git a/docs/v3/tutorials/server-and-worker.mdx b/docs/v3/tutorials/server-and-worker.mdx
new file mode 100644
index 000000000000..7345ec836a27
--- /dev/null
+++ b/docs/v3/tutorials/server-and-worker.mdx
@@ -0,0 +1,189 @@
+---
+title: Deploy a Prefect Server and Worker with Helm
+description: Deploy a Prefect OSS Server and Worker with Helm.
+---
+
+In this tutorial, you'll learn how to deploy an [OSS Server](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-server) and [Worker](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker) with Helm.
+
+## Prerequisites
+
+- A Kubernetes cluster
+- Helm CLI installed
+
+## Getting Started
+
+### Before You Begin
+
+<Note>
+**Disclaimers:**
+- Configuring ingress / publicly exposing Prefect from the cluster is business dependent and not covered in this tutorial.
+- For details on Ingress configuration, consult the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/).
+</Note>
+
+### Set Up Your Environment
+
+Create a new namespace to work from (all commands in this quick-start will use this namespace):
+   ```bash
+   kubectl create namespace prefect-server
+   kubectl config set-context --current --namespace=prefect-server
+   ```
+
+## Deploy Prefect Server with Helm
+
+1. Add the Prefect Helm repository:
+   ```bash
+   helm repo add prefect https://prefecthq.github.io/prefect-helm
+   ```
+
+2. For a basic deployment with default values, using the latest Prefect version and no auth:
+   ```bash
+   helm install prefect-server prefect/prefect-server
+   ```
+
+3. For a customized deployment, create a values.yaml file for Prefect Server (see [values.yaml template](https://github.com/PrefectHQ/prefect-helm/blob/main/charts/prefect-server/values.yaml)).
+
+4. Create a secret for the API basic auth:
+   ```bash
+   kubectl create secret generic server-auth-secret --from-literal auth-string='admin:password123'
+   ```
+
+5. Example `server-values.yaml` file for this tutorial:
+   ```yaml
+   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
+   ```
+
+6. Install Prefect Server with custom values:
+   ```bash
+   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-server
+   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!
+   ```
+
+7. Access the Prefect UI:
+   ```bash
+   kubectl --namespace prefect-server port-forward svc/prefect-server 4200:4200
+   ```
+
+8. Navigate to `localhost:4200` and login with `admin:password123`.
+
+## Deploy a Prefect Worker
+
+To connect a worker to your Prefect server in the same cluster:
+
+1. Create a secret for the API basic auth:
+   ```bash
+   kubectl create secret generic worker-auth-secret --from-literal auth-string='admin:password123'
+   ```
+
+2. Create a `worker-values.yaml` file for this tutorial:
+   ```yaml
+   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
+   ```
+
+3. Install the Prefect Worker:
+   ```bash
+   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-server
+   STATUS: deployed
+   REVISION: 1
+   TEST SUITE: None
+   NOTES:
+   ```
+
+## Cleanup
+
+To uninstall Prefect Server and Worker:
+
+```bash
+helm uninstall prefect-worker
+helm uninstall prefect-server
+```
+
+## Troubleshooting
+
+<Expandable title="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
+```
+
+Check events with `kubectl events`. Confirm that the authString is correct.
+</Expandable>
+
+<Expandable title="Authentication error">
+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.
+</Expandable>
+
+<Expandable title="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 is properly templated.
+
+This can be confirmed via:
+```bash
+helm template prefect-worker prefect/prefect-worker -f worker-values.yaml
+```
+
+If you are following this quick-start and the worker is in the same cluster and namespace, the format should be:
+```
+http://prefect-server.prefect-server.svc.cluster.local:4200/api
+```
+
+For additional troubleshooting and configuration, review the [Prefect Helm Worker Chart](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker).
+</Expandable>


Code review comments:
diff_hunk: @@ -0,0 +1,189 @@
+---
+title: Deploy a Prefect Server and Worker with Helm
+description: Deploy a Prefect OSS Server and Worker with Helm.
+---
+
+In this tutorial, you'll learn how to deploy an [OSS Server](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-server) and [Worker](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker) with Helm.
+
+## Prerequisites
+
+- A Kubernetes cluster
+- Helm CLI installed
+
+## Getting Started
+
+### Before You Begin
+
+<Note>
+**Disclaimers:**
+- Configuring ingress / publicly exposing Prefect from the cluster is business dependent and not covered in this tutorial.
+- For details on Ingress configuration, consult the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/).
+</Note>
+
+### Set Up Your Environment
+
+Create a new namespace to work from (all commands in this quick-start will use this namespace):
+   ```bash
+   kubectl create namespace prefect-server
+   kubectl config set-context --current --namespace=prefect-server
path: docs/v3/tutorials/server-and-worker.mdx
text: @user1:
```suggestion
   kubectl create namespace prefect
   kubectl config set-context --current --namespace=prefect
```

diff_hunk: @@ -0,0 +1,189 @@
+---
+title: Deploy a Prefect Server and Worker with Helm
+description: Deploy a Prefect OSS Server and Worker with Helm.
+---
+
+In this tutorial, you'll learn how to deploy an [OSS Server](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-server) and [Worker](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker) with Helm.
+
+## Prerequisites
+
+- A Kubernetes cluster
+- Helm CLI installed
+
+## Getting Started
+
+### Before You Begin
+
+<Note>
+**Disclaimers:**
+- Configuring ingress / publicly exposing Prefect from the cluster is business dependent and not covered in this tutorial.
+- For details on Ingress configuration, consult the [Kubernetes documentation](https://kubernetes.io/docs/concepts/services-networking/ingress/).
+</Note>
+
+### Set Up Your Environment
+
+Create a new namespace to work from (all commands in this quick-start will use this namespace):
+   ```bash
+   kubectl create namespace prefect-server
+   kubectl config set-context --current --namespace=prefect-server
+   ```
+
+## Deploy Prefect Server with Helm
+
+1. Add the Prefect Helm repository:
+   ```bash
+   helm repo add prefect https://prefecthq.github.io/prefect-helm
+   ```
+
+2. For a basic deployment with default values, using the latest Prefect version and no auth:
path: docs/v3/tutorials/server-and-worker.mdx
text: @user1:
I would recommend splitting this up into 2 additional sub-headings (maybe ones that we can toggle open/closed). 
1. Basic (no config) install
2. Customized install with basic auth enabled
3. Nothing today -- could add to this in the future for other things like exposing an ingress, etc etc

@author:
Sounds good, I can do that