Version: 2.0 Last Updated: 2025-11-10 Status: Production Ready Audience: Developers, Platform Engineers
Deploy the complete Kagenti AI Agent Platform on your local machine in 15 minutes.
- Overview
- Prerequisites
- Installation
- Verification
- Accessing Services
- Troubleshooting
- Next Steps
- References
Purpose: Get a fully functional Kagenti platform running locally for development and testing.
What You Get:
- ✅ Kubernetes cluster (Kind)
- ✅ GitOps with ArgoCD
- ✅ Service mesh (Istio)
- ✅ Distributed tracing (Tempo + Phoenix)
- ✅ SSO authentication (Keycloak)
- ✅ Observability (Grafana + Prometheus + Kiali)
- ✅ CI/CD (Tekton)
- ✅ Kagenti UI and sample agents
Time Required: 15-20 minutes
Source: Based on Kind Quick Start
| Tool | Minimum Version | Check Command | Install |
|---|---|---|---|
| Docker | 20.10+ | docker --version |
Install Docker |
| kubectl | 1.28+ | kubectl version --client |
Install kubectl |
| kind | 0.20+ | kind --version |
Install Kind |
| helm | 3.12+ | helm version |
Install Helm |
| argocd CLI | 2.8+ | argocd version --client |
Install ArgoCD CLI |
- CPU: 4 cores minimum (8 cores recommended)
- RAM: 8 GB minimum (16 GB recommended)
- Disk: 20 GB free space
- OS: macOS, Linux, or Windows with WSL2
Source: Kind System Requirements
# Check all tools installed
docker --version && kubectl version --client && kind --version && helm version && argocd version --client
# Check Docker running
docker ps
# Expected: Docker daemon is running# Clone repository
git clone https://github.com/Ladas/kagenti-demo-deployment.git
cd kagenti-demo-deployment
# Run deployment script
./scripts/deploy/deploy-kind.sh
# Expected output:
# ✅ Kind cluster created: kind-kagenti-demo
# ✅ ArgoCD installed
# ✅ All applications synced
# ✅ Platform deployed successfullyWhat This Does:
- Creates Kind cluster with ingress support
- Installs ArgoCD
- Deploys all platform components via GitOps
- Configures networking and certificates
Source: scripts/deploy/deploy-kind.sh
Duration: 10-15 minutes (depending on internet speed)
# Monitor deployment
watch kubectl get pods -A
# Wait until all pods are Running or Completed
# Ctrl+C to exit watch
# Quick health check
kubectl get pods -A | grep -vE "Running|Completed"
# Expected: No output (all pods healthy)Source: Kubernetes Pod Lifecycle
# Check ArgoCD applications
kubectl get applications -n argocd
# Expected: All applications show "Healthy" and "Synced"
# Check critical services
kubectl get pods -n argocd,keycloak,observability,kagenti-system,istio-system
# Expected: All pods Running (1/1)| Component | Namespace | Command | Expected |
|---|---|---|---|
| ArgoCD | argocd | kubectl get pods -n argocd |
7/7 Running |
| Keycloak | keycloak | kubectl get pods -n keycloak |
2/2 Running |
| Istio | istio-system | kubectl get pods -n istio-system |
1/1 Running |
| Grafana | observability | kubectl get pods -n observability |
1/1 Running |
| Tempo | observability | kubectl get pods -n observability -l app=tempo |
1/1 Running |
| Phoenix | observability | kubectl get pods -n observability -l app=phoenix |
1/1 Running |
| Kagenti UI | kagenti-system | kubectl get pods -n kagenti-system -l app=kagenti-ui |
1/1 Running |
Source: Kubernetes Get Pods
kubectl port-forward svc/argocd-server -n argocd 8080:443
# Access: https://localhost:8080
# Username: admin
# Password: (get with command below)
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -dSource: ArgoCD Getting Started
kubectl port-forward svc/grafana -n observability 3000:80
# Access: http://localhost:3000
# Username: admin
# Password: adminSource: Grafana Configuration
kubectl port-forward svc/keycloak -n keycloak 8082:8080
# Access: http://localhost:8082
# Username: admin
# Password: adminSource: Keycloak Server Installation
kubectl port-forward svc/phoenix -n observability 6006:6006
# Access: http://localhost:6006Source: Phoenix Documentation
kubectl port-forward svc/kiali -n kiali-system 20001:20001
# Access: http://localhost:20001Source: Kiali Quick Start
Symptoms: Pods stuck in Pending, CrashLoopBackOff, or ImagePullBackOff
Diagnosis:
# Check pod status
kubectl get pods -A | grep -vE "Running|Completed"
# Describe problem pod
kubectl describe pod <pod-name> -n <namespace>
# Check logs
kubectl logs <pod-name> -n <namespace>Common Causes:
- Insufficient resources (increase Docker resources)
- Image pull failures (check Docker Hub rate limits)
- Configuration errors (check ArgoCD app status)
Source: Kubernetes Troubleshooting
Symptoms: error: unable to forward port because pod is not running
Solution:
# Verify pod is running
kubectl get pods -n <namespace>
# Restart port-forward
pkill -f "port-forward"
kubectl port-forward svc/<service> -n <namespace> <local-port>:<remote-port>Symptoms: Applications stuck in "OutOfSync" or "Progressing"
Solution:
# Check application status
argocd app list
# Sync manually
argocd app sync <app-name>
# Force refresh
argocd app sync <app-name> --forceSource: ArgoCD Troubleshooting
-
Explore Observability:
- View Distributed Tracing Guide
- Check Grafana dashboards
- Explore Phoenix LLM traces
-
Configure Authentication:
- Read Keycloak SSO Guide
- Create users in Keycloak
- Configure OAuth2 for services
-
Deploy Agents:
- Review Agents Guide (coming soon)
- Create custom AI agents
- Test agent interactions
-
Review Planning Docs:
-
Harden Security:
- Rotate default passwords
- Enable mTLS STRICT mode
- Configure network policies
- Set up secrets management
-
Plan Migration:
- Review OpenShift Migration Guide (coming soon)
- Understand OLM vs Kubernetes
- Kind: kind.sigs.k8s.io
- Kubernetes: kubernetes.io/docs
- ArgoCD: argo-cd.readthedocs.io
- Istio: istio.io/docs
- Main README: ../README.md
- Distributed Tracing: ../04-observability/distributed-tracing.md
- Keycloak SSO: ../03-authentication/keycloak.md
- GitHub: Ladas/kagenti-demo-deployment
- Issues: Report Issues
Last Updated: 2025-11-10 Document Version: 2.0 Maintained By: Platform Engineering Team License: Apache 2.0