README.md.gotmpl

{{ template "chart.header" . }}

## Overview

[Workers](https://docs.prefect.io/latest/concepts/work-pools/#worker-overview) are lightweight polling services that retrieve scheduled runs from a work pool and execute them.

Workers each have a type corresponding to the execution environment to which they will submit flow runs. Workers are only able to join work pools that match their type. As a result, when deployments are assigned to a work pool, you know in which execution environment scheduled flow runs for that deployment will run.

## Installing the Chart

### Prerequisites

1. Add the Prefect Helm repository to your Helm client:

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

2. Create a new namespace in your Kubernetes cluster to deploy the Prefect worker in:

    ```bash
    kubectl create namespace prefect
    ```

### Configuring a Worker for Prefect Cloud

1. Create a Kubernetes secret for a Prefect Cloud API key

    First create a file named `api-key.yaml` with the following contents:

    ```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: prefect-api-key
      namespace: prefect
    type: Opaque
    data:
      key:  <base64-encoded-api-key>
    ```

    Replace `<base64-encoded-api-key>` with your Prefect Cloud API key encoded in base64. The helm chart looks for a secret of this name and schema, this can be overridden in the `values.yaml`.

    You can use the following command to generate the base64-encoded value:

    ```bash
    echo -n "your-prefect-cloud-api-key" | base64
    ```

    Then apply the `api-key.yaml` file to create the Kubernetes secret:

    ```bash
    kubectl apply -f api-key.yaml
    ```

    Alternatively, you can create the Kubernetes secret via the cli with the following command. In this case, Kubernetes will take care of base64 encoding the value on your behalf:

    ```bash
    kubectl create secret generic prefect-api-key --from-literal=key=pnu_xxxx
    ```

2. Configure the Prefect worker values

    Create a `values.yaml` file to customize the Prefect worker configuration. Add the following contents to the file:

    ```yaml
    worker:
      cloudApiConfig:
        accountId: <target account ID>
        workspaceId: <target workspace ID>
      config:
        workPool: <target work pool name>
    ```

    These settings will ensure that the worker connects to the proper account, workspace, and work pool.
    View your Account ID and Workspace ID in your browser URL when logged into Prefect Cloud. For example: `https://app.prefect.cloud/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here`

### Configuring a Worker for Self Hosted Cloud (not to be confused with [Prefect Server](https://github.com/PrefectHQ/prefect-helm/tree/main/charts/prefect-worker#configuring-a-worker-for-prefect-server))

1. Create a Kubernetes secret for a Prefect Self Hosted Cloud API key

    First create a file named `api-key.yaml` with the following contents:

    ```yaml
    apiVersion: v1
    kind: Secret
    metadata:
      name: prefect-api-key
      namespace: prefect
    type: Opaque
    data:
      key:  <base64-encoded-api-key>
    ```

    Replace `<base64-encoded-api-key>` with your Prefect Self Hosted Cloud API key encoded in base64. The helm chart looks for a secret of this name and schema, this can be overridden in the `values.yaml`.

    You can use the following command to generate the base64-encoded value:

    ```bash
    echo -n "your-prefect-self-hosted-cloud-api-key" | base64
    ```

    Then apply the `api-key.yaml` file to create the Kubernetes secret:

    ```bash
    kubectl apply -f api-key.yaml
    ```

    Alternatively, you can create the Kubernetes secret via the cli with the following command. In this case, Kubernetes will take care of base64 encoding the value on your behalf:

    ```bash
    kubectl create secret generic prefect-api-key --from-literal=key=pnu_xxxx
    ```

2. Configure the Prefect worker values

    Create a `values.yaml` file to customize the Prefect worker configuration. Add the following contents to the file:

    ```yaml
    worker:
      apiConfig: selfHosted
      config:
        workPool: <target work pool name>
      selfHostedCloudApiConfig:
        # If the prefect server is located external to this cluster, set a fully qualified domain name as the apiUrl
        # If the prefect server pod is deployed to this cluster, use the cluster DNS endpoint: http://<prefect-server-service-name>.<namespace>.svc.cluster.local:<prefect-server-port>/api
        apiUrl: "https://<DNS of Self Hosted Cloud API>"
        accountId: <target account ID>
        workspaceId: <target workspace ID>
        uiUrl: "https://<DNS of Self Hosted Cloud UI>"
    ```

    These settings will ensure that the worker connects to the proper account, workspace, and work pool.
    View your Account ID and Workspace ID in your browser URL when logged into Prefect Cloud. For example: `https://self-hosted-prefect.company/account/abc-my-account-id-is-here/workspaces/123-my-workspace-id-is-here`

### Configuring a Worker for Prefect Server

1. Configure the Prefect worker values

    Create a `values.yaml` file to customize the Prefect worker configuration. Add the following contents to the file:

    ```yaml
    worker:
      apiConfig: server
      config:
        workPool: <target work pool name>
      serverApiConfig:
        apiUrl: <dns or ip address of the prefect-server pod here>
    ```

    These settings will ensure the worker connects with the local deployment of Prefect Server.
    If the Prefect Server pod is deployed in the same cluster, you can use the local Kubernetes DNS address to connect to it: `prefect-server.<namespace>.svc.cluster.local`

### Installing & Verifying Deployment of the Prefect Worker

1. Install the Prefect worker using Helm

    ```bash
    helm install prefect-worker prefect/prefect-worker --namespace=prefect -f values.yaml
    ```

2. Verify the deployment

    Check the status of your Prefect worker deployment:

    ```bash
    kubectl get pods -n prefect

    NAME                              READY   STATUS    RESTARTS       AGE
    prefect-worker-658f89bc49-jglvt   1/1     Running   0              25m
    ```

    You should see the Prefect worker pod running

## FAQ

### Deploying multiple workers to a single namespace

If you want to run more than one worker in a single Kubernetes namespace, you will need to specify the `fullnameOveride` parameter at install time of one of the workers.

```yaml
fullnameOverride: prefect-worker-2
```

If you want the workers to share a service account, add the following to your `values.yaml`:

```yaml
fullnameOverride: prefect-worker-2
serviceAccount:
  create: false
  name: "prefect-worker"
```

### Configuring a Base Job Template on the Worker

If you want to define the [base job template](https://docs.prefect.io/concepts/work-pools/#base-job-template) of the worker and pass it as a value in this chart, you will need to do the following. **Note** if the `workPool` already exists, the base job template passed **will** be ignored.

1. Define the base job template in a local file. To get a formatted template, run the following command & store locally in `base-job-template.json`

```bash
# you may need to install `prefect-kubernetes` first
pip install prefect-kubernetes

prefect work-pool get-default-base-job-template --type kubernetes > base-job-template.json
```

2. Modify the base job template as needed

3. Install the chart as you usually would, making sure to use the `--set-file` command to pass in the `base-job-template.json` file as a paramater:

```bash
helm install prefect-worker prefect/prefect-worker -f values.yaml --set-file worker.config.baseJobTemplate=base-job-template.json
```

{{ template "chart.maintainersSection" . }}

{{ template "chart.requirementsSection" . }}

{{ template "chart.valuesSection" . }}

{{ template "helm-docs.versionFooter" . }}