From f5c07173f48c7a316863152835a69dbc626e94b0 Mon Sep 17 00:00:00 2001 From: David Wetmore <167476544+dwetmore@users.noreply.github.com> Date: Tue, 10 Feb 2026 17:12:22 -0500 Subject: [PATCH] docs: rewrite README for GitOps deployment overview --- README.md | 149 ++++++++++++++++++++++++++++++++++++++++++++++-------- 1 file changed, 129 insertions(+), 20 deletions(-) diff --git a/README.md b/README.md index 5a2fc29..807d9d5 100644 --- a/README.md +++ b/README.md @@ -1,31 +1,140 @@ -# Chatbot GitOps +# Chatbot GitOps: OpenWebUI + Ollama on MicroK8s + +This repository defines a GitOps deployment for a chatbot stack on Kubernetes using Argo CD and Kustomize. It exists to provide a clean, reproducible way to run OpenWebUI + Ollama (plus the chatbot API) on a local MicroK8s-style environment. + +## What you get + +- GitOps-friendly Kubernetes manifests that Argo CD can continuously reconcile from Git. +- A `base/` layer for the chatbot API plus shared namespace/config resources. +- A `overlays/dev-ollama/` environment overlay that adds Ollama and OpenWebUI. +- Ingress-based access for both chatbot and OpenWebUI using nip.io hostnames in the dev overlay. +- Local-dev-friendly defaults (single-replica services, PVC-backed model/UI data, straightforward `make` commands). ## Architecture -This repo uses Kustomize to manage Kubernetes manifests. +Flow: + +1. User calls OpenWebUI ingress. +2. OpenWebUI calls Ollama service (`http://ollama:11434`). +3. Chatbot API (separate service/ingress) also calls Ollama via in-cluster DNS. +4. Argo CD watches this repo and applies desired state into the cluster. + +Core components: + +- `chatbot` Deployment + Service + Ingress +- `ollama` Deployment + Service + PVC +- `openwebui` Deployment + Service + Ingress + PVC +- `chatbot-config` ConfigMap for model provider and endpoint settings + +Namespace: + +- Workloads are deployed to `chatbot`. + +## Repo layout + +- `base/`: reusable core resources (`Namespace`, `ConfigMap`, chatbot `Deployment`, `Service`, `Ingress`). +- `overlays/dev-ollama/`: environment-specific resources for Ollama/OpenWebUI and ingress host patching for dev. + +## Deploy (GitOps) + +Create an Argo CD `Application` that points to this repo and overlay: + +- **Repo URL**: your fork/remote for this repository +- **Path**: `overlays/dev-ollama` +- **Destination namespace**: `chatbot` +- **Target revision**: `main` (or your branch) + +Example `Application` manifest: + +```yaml +apiVersion: argoproj.io/v1alpha1 +kind: Application +metadata: + name: chatbot-gitops + namespace: argocd +spec: + project: default + source: + repoURL: https://github.com/dwetmore/chatbot-gitops.git + targetRevision: main + path: overlays/dev-ollama + destination: + server: https://kubernetes.default.svc + namespace: chatbot + syncPolicy: + automated: + prune: true + selfHeal: true +``` + +Apply it: + +```bash +kubectl apply -f application.yaml +``` + +Sync: + +```bash +argocd app sync chatbot-gitops +``` + +## Validate + +```bash +kubectl get pods -n chatbot +kubectl get svc -n chatbot +kubectl get ingress -n chatbot +kubectl describe ingress chatbot -n chatbot +kubectl describe ingress openwebui -n chatbot +``` + +## Operations + +Logs: + +```bash +kubectl logs deploy/openwebui -n chatbot --tail=100 -f +kubectl logs deploy/ollama -n chatbot --tail=100 -f +``` + +Rollout restart: + +```bash +kubectl rollout restart deploy/openwebui -n chatbot +kubectl rollout restart deploy/ollama -n chatbot +kubectl rollout restart deploy/chatbot -n chatbot +``` + +Update flow: + +1. Commit and push manifest changes to Git. +2. Argo CD detects drift and syncs automatically (or sync manually). +3. Validate pods/services/ingress after reconciliation. + +## Troubleshooting + +- **OpenWebUI loads, but no models respond** + Check Ollama pod health and logs: `kubectl get pods -n chatbot` and `kubectl logs deploy/ollama -n chatbot`. -- `base/` defines the core chatbot deployment, service, ingress, and ConfigMap. -- `overlays/dev-ollama/` adds Ollama and OpenWebUI resources for a dev setup. +- **OpenWebUI cannot reach Ollama** + Confirm service DNS/port from deployment env (`OLLAMA_BASE_URL=http://ollama:11434`) and verify `kubectl get svc ollama -n chatbot`. -The chatbot container is configured via `base/configmap.yaml`. It sets `LLM_PROVIDER=ollama` and -points `OLLAMA_BASE_URL` at the in-cluster Ollama service (`http://ollama.chatbot.svc.cluster.local:11434`). -This lets the chatbot API call Ollama directly over the cluster network. +- **Chatbot cannot reach Ollama** + Verify `chatbot-config` has `OLLAMA_BASE_URL=http://ollama.chatbot.svc.cluster.local:11434` and restart chatbot deployment. -OpenWebUI is deployed in the dev overlay. Its deployment sets `OLLAMA_BASE_URL=http://ollama:11434`, -so OpenWebUI talks to the Ollama service through the Kubernetes DNS name and port exposed by -`overlays/dev-ollama/ollama.yaml`. +- **Ingress hostname does not resolve** + Ensure the nip.io host IP in ingress manifests matches your ingress controller IP, then re-apply/sync. -## Ingress URLs +- **Argo CD shows OutOfSync after edits** + Confirm changes were pushed to the same branch used by `targetRevision`, then trigger a manual sync. -- Chatbot ingress (base): `chat.example.invalid` (placeholder). -- Dev overlay nip.io hosts: - - Chatbot: `chat.172.17.93.185.nip.io` (from `overlays/dev-ollama/patch-ingress-host.yaml`). - - OpenWebUI: `webui.172.17.93.185.nip.io` (from `overlays/dev-ollama/openwebui-ing.yaml`). +## Roadmap -Update the nip.io IP if your ingress controller IP changes. +- [ ] Add CI to run `kustomize build overlays/dev-ollama` on every PR. +- [ ] Review and tighten CPU/memory resource limits across workloads. +- [ ] Add security hardening notes (image pinning, network policies, secrets strategy). -## Useful commands +## Related repos -- `make render` to print the dev overlay manifests. -- `make validate` to ensure `kustomize build overlays/dev-ollama` succeeds. -- `make show-urls` to print the expected nip.io hostnames. +- Application/source repository details (for example, `chatbot`, `notes-app`) are not linked in this repo yet.