Kubernetes Quickstart

Prerequisites

A Kubernetes cluster currently set as the current context in kubectl
kubectl and helm installed

Quickstart

Generate encryption keys

There are 4 encryption secrets required for Hatchet to run which can be generated via the following bash script (requires docker and openssl):

#!/bin/bash
 
# Define an alias for generating random strings. This needs to be a function in a script.
randstring() {
    openssl rand -base64 69 | tr -d "\n=+/" | cut -c1-$1
}
 
# Create keys directory
mkdir -p ./keys
 
# Function to clean up the keys directory
cleanup() {
    rm -rf ./keys
}
 
# Register the cleanup function to be called on the EXIT signal
trap cleanup EXIT
 
# Check if Docker is installed
if ! command -v docker &> /dev/null
then
    echo "Docker could not be found. Please install Docker."
    exit 1
fi
 
# Generate keysets using Docker
docker run --user $(id -u):$(id -g) -v $(pwd)/keys:/hatchet/keys ghcr.io/hatchet-dev/hatchet/hatchet-admin:latest /hatchet/hatchet-admin keyset create-local-keys --key-dir /hatchet/keys
 
# Read keysets from files
SERVER_ENCRYPTION_MASTER_KEYSET=$(<./keys/master.key)
SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET=$(<./keys/private_ec256.key)
SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET=$(<./keys/public_ec256.key)
 
# Generate the random strings for SERVER_AUTH_COOKIE_SECRETS
SERVER_AUTH_COOKIE_SECRET1=$(randstring 16)
SERVER_AUTH_COOKIE_SECRET2=$(randstring 16)
 
# Create the YAML file
cat > hatchet-values.yaml <<EOF
api:
  enabled: true
  env:
    SERVER_AUTH_COOKIE_SECRETS: "$SERVER_AUTH_COOKIE_SECRET1 $SERVER_AUTH_COOKIE_SECRET2"
    SERVER_ENCRYPTION_MASTER_KEYSET: "$SERVER_ENCRYPTION_MASTER_KEYSET"
    SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET: "$SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET"
    SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET: "$SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET"
 
engine:
  enabled: true
  env:
    SERVER_AUTH_COOKIE_SECRETS: "$SERVER_AUTH_COOKIE_SECRET1 $SERVER_AUTH_COOKIE_SECRET2"
    SERVER_ENCRYPTION_MASTER_KEYSET: "$SERVER_ENCRYPTION_MASTER_KEYSET"
    SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET: "$SERVER_ENCRYPTION_JWT_PRIVATE_KEYSET"
    SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET: "$SERVER_ENCRYPTION_JWT_PUBLIC_KEYSET"
EOF

Run this script to generate the encryption keys and the hatchet-values.yaml file:

bash generate-keys.sh

⚠️

Warning: do not commit these keys to your Git repository, use api.envFrom or engine.envFrom to pull in values from a secret.

Deploy Hatchet

To deploy hatchet-stack, run the following commands:

helm repo add hatchet https://hatchet-dev.github.io/hatchet-charts
helm install hatchet-stack hatchet/hatchet-stack --values hatchet-values.yaml --set api.replicaCount=0 --set engine.replicaCount=0
helm upgrade hatchet-stack hatchet/hatchet-stack --values hatchet-values.yaml --set caddy.enabled=true

This default installation will run the Hatchet server as an internal service in the cluster and spins up a reverse proxy via Caddy to get local access. To view the Hatchet server, run the following command:

export NAMESPACE=default # TODO: replace with your namespace
export POD_NAME=$(kubectl get pods --namespace $NAMESPACE -l "app=caddy" -o jsonpath="{.items[0].metadata.name}")
export CONTAINER_PORT=$(kubectl get pod --namespace $NAMESPACE $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
kubectl --namespace $NAMESPACE port-forward $POD_NAME 8080:$CONTAINER_PORT

And then navigate to http://localhost:8080 to see the Hatchet frontend running.

Set up your Hatchet account

You can create a new user account by clicking the Register button on the Hatchet login screen, and then creating a new account and tenant.

Next, navigate to your settings tab in the Hatchet dashboard. You should see a section called "API Keys". Click "Create API Key", input a name for the key and copy the key. Then copy the following environment variables into a .env file where you'd like to run your worker:

HATCHET_CLIENT_TOKEN="<token>"
HATCHET_CLIENT_TLS_STRATEGY=none

You will need this in the following example.

Port forward to the Hatchet engine

export NAMESPACE=default # TODO: replace with your namespace
export POD_NAME=$(kubectl get pods --namespace $NAMESPACE -l "app.kubernetes.io/name=hatchet-engine,app.kubernetes.io/instance=hatchet" -o jsonpath="{.items[0].metadata.name}")
export CONTAINER_PORT=$(kubectl get pod --namespace $NAMESPACE $POD_NAME -o jsonpath="{.spec.containers[0].ports[0].containerPort}")
kubectl --namespace $NAMESPACE port-forward $POD_NAME 7070:$CONTAINER_PORT

This will spin up the Hatchet engine service on localhost:7070 which you can then connect to from the examples.

Run your first worker

Make sure you have the following dependencies installed:

pip install python-dotenv
pip install hatchet-sdk

We are using python-dotenv (opens in a new tab) to load the environment variables from a .env file. This isn't required, and you can use your own method to load environment variables.

Create a worker.py file with the following contents:

worker.py

from hatchet_sdk import Hatchet
from dotenv import load_dotenv
 
load_dotenv()
 
hatchet = Hatchet(debug=True)
 
@hatchet.workflow(name="first-python-workflow",on_events=["user:create"])
class MyWorkflow:
    @hatchet.step()
    def step1(self, context):
        return {
            "result": "success"
        }
 
worker = hatchet.worker('first-worker')
worker.register_workflow(MyWorkflow())
 
worker.start()

Open a new terminal and start the worker with:

python3 worker.py

Run your first workflow

The worker is now running and listening for steps to execute. You should see your first worker registered in the Workers tab of the Hatchet dashboard:

Quickstart 1

You can now trigger your first workflow by navigating to the Workflows tab, selecting your workflow, and clicking the top right "Trigger workflow" button:

Quickstart 2

That's it! You've successfully deployed Hatchet and run your first workflow.

Docker Compose Installing with Glasskube