Local Kubernetes (Minikube) Guide

This doc covers how to start Minikube locally and expose services running in the cluster via Ingress.

Prereqs

• kubectl
• minikube
• A container runtime: Docker or Podman

Optional: - helm (if you use Helm charts)

Build and deploy md-server

Enable the Minikube registry addon:

bash minikube addons enable registry

If you are using the registry over plain HTTP (no TLS), trust it in your local container runtime:

Docker (Linux):

bash sudo mkdir -p /etc/docker cat <<'EOF' | sudo tee /etc/docker/daemon.json { "insecure-registries": ["registry.cydu.net"] } EOF sudo systemctl restart docker

Podman:

bash sudo mkdir -p /etc/containers cat <<'EOF' | sudo tee /etc/containers/registries.conf.d/cydu.conf [[registry]] location = "registry.cydu.net" insecure = true EOF

Build the Docker image locally, push it to the Minikube registry, and deploy to the cydu namespace. The Makefile uses docker for build/push.

bash make ingress make secret make build make deploy

You can override defaults:

bash make build IMAGE=registry.cydu.net/cydu/md-server:latest MINIKUBE_PROFILE=minikube make deploy NAMESPACE=cydu

make secret reads FIREWORKS_API_KEY and OPENAI_API_KEY (optional) from .env.

Start Minikube

bash minikube start

If you need a specific runtime:

bash minikube start --driver=docker

Confirm cluster access:

bash kubectl get nodes kubectl config current-context

Add a new deployment/service and Cloudflare proxy

1) Add a new manifest in k8s/ (Deployment + Service). 2) Apply it:

bash kubectl apply -f k8s/<your-service>.yaml

3) Add a new host rule to the existing Ingress in k8s/nuc-ingress.yaml (do not create a separate Ingress), then apply it:

bash kubectl apply -f k8s/nuc-ingress.yaml

Example rule to add under spec.rules:

yaml - host: <new-host> http: paths: - path: / pathType: Prefix backend: service: name: <service-name> port: number: 80

4) Update the local Cloudflare Tunnel config to point the hostname at your local Ingress entrypoint:

• Edit /etc/cloudflared/config.yml
• Add an ingress rule with the new hostname and service target

Example:

yaml ingress: - hostname: demo.cydu.net service: http://<minikube-ip> - service: http_status:404

5) Validate and restart the tunnel:

bash sudo cloudflared tunnel validate --config /etc/cloudflared/config.yml sudo systemctl restart cloudflared

Expose a local service via Ingress

We use an Ingress to route a host name to the service.

1) Get the Minikube IP:

bash minikube ip

2) Ensure the Ingress is created for your host and points to the service:

bash kubectl -n cydu get ingress kubectl -n cydu describe ingress nuc-ingress

3) Build the URL using the host configured in the Ingress and the Minikube IP (via /etc/hosts or DNS):

bash http://demo.cydu.net

Useful cleanup

Remove everything in the namespace:

bash kubectl delete namespace local-testing

Stop or delete the Minikube cluster:

bash minikube stop minikube delete