Deploy: Cloud / VM (Helm)¶

Deploy KubeIntellect to any Kubernetes cluster — AKS, EKS, GKE, or Kind on a VM.

Requirements: kubectl pointing at your cluster, helm, Docker (to build the image).

Option A — Azure VM (Kind on VM)¶

Run a Kind cluster on a Linux VM and expose it via nginx + TLS.

1. Clone the repo¶

git clone https://github.com/mskazemi/kubeintellect
cd kubeintellect

2. Create the Kind cluster¶

make kind-cluster-create-vm    # auto-installs kind/kubectl/helm; creates single-node cluster

3. Configure¶

cp deploy/helm/kubeintellect/values-production.yaml.example \
   deploy/helm/kubeintellect/values-production.yaml

Edit values-production.yaml:

ingress:
  hosts:
    - api.your-domain.com      # internet access — your public domain
    - api.kubeintellect.local  # local VM access (add to /etc/hosts on clients)

config:
  llmProvider: azure          # or: openai
  prometheusUrl: ""           # add after monitoring install
  lokiUrl: ""

Dual hostname setup

The VM nginx reverse proxy passes the original Host header through to the Kind cluster, so both hostnames route to the same pod. Add api.kubeintellect.local to /etc/hosts on any machine that needs local access without going through DNS.

cp .env.example .env

Edit .env:

LLM_PROVIDER=azure
AZURE_OPENAI_API_KEY=...
AZURE_OPENAI_ENDPOINT=https://your-resource.openai.azure.com/
POSTGRES_PASSWORD=changeme
KUBEINTELLECT_ADMIN_KEYS=ki-admin-<run: openssl rand -hex 10>

4. Build and deploy¶

make kind-build-kubeintellect    # build Docker image + load into Kind
make vm-deploy-kubeintellect     # helm install KubeIntellect

5. Install monitoring (optional)¶

make monitoring-install    # Prometheus + Grafana + Loki → monitoring namespace
make langfuse-install      # Langfuse LLM tracing → monitoring namespace

Then update values-production.yaml:

config:
  prometheusUrl: http://kube-prometheus-stack-prometheus.monitoring.svc.cluster.local:9090
  lokiUrl: http://loki.monitoring.svc.cluster.local:3100

Redeploy: make vm-deploy-kubeintellect

6. Set up TLS¶

bash scripts/vm/setup-nginx.sh    # configure nginx reverse proxy
bash scripts/vm/setup-tls.sh      # get Let's Encrypt cert

7. Verify¶

curl https://api.your-domain.com/healthz           # → {"status":"ok"}  (internet)
curl http://api.kubeintellect.local/healthz         # → {"status":"ok"}  (local, if /etc/hosts set)

Option B — AKS / EKS / GKE¶

1. Clone the repo¶

git clone https://github.com/mskazemi/kubeintellect
cd kubeintellect

2. Configure¶

cp deploy/helm/kubeintellect/values-cloud.yaml.example \
   deploy/helm/kubeintellect/values-cloud.yaml

Edit values-cloud.yaml:

ingress:
  hosts:
    - api.your-domain.com    # ← your public domain
  className: nginx          # or: alb (EKS), gce (GKE)

config:
  llmProvider: azure        # or: openai
  prometheusUrl: https://prometheus.company.com
  lokiUrl: https://loki.company.com

postgres:
  external:
    url: postgresql://user:pass@host:5432/dbname    # use managed DB in production

cp .env.example .env
# Edit .env: API keys, POSTGRES_PASSWORD, KUBEINTELLECT_ADMIN_KEYS

3. Deploy¶

make aks-deploy-kubeintellect    # helm upgrade --install

4. Verify¶

curl https://api.your-domain.com/healthz    # → {"status":"ok"}

Automated deploys (GitHub Actions)¶

Push to main → image is built and pushed to GHCR automatically.

Manual deploy button in GitHub Actions (workflow_dispatch) triggers SSH deploy to VM.

Required secrets in GitHub repo settings: - VM_HOST — VM IP or hostname - VM_USER — SSH user - VM_SSH_KEY — private key for SSH access

See .github/workflows/deploy.yml.

Upgrade¶

make kind-build-kubeintellect    # rebuild image (if building locally on VM)
make vm-deploy-kubeintellect     # helm upgrade --install (idempotent)

Or push to main and click Deploy in GitHub Actions.

Connect¶

pipx install kube-q
KUBE_Q_API_KEY=<your-admin-key> kq --url https://api.your-domain.com