diff --git a/.dockerignore b/.dockerignore new file mode 100644 index 0000000..05fe846 --- /dev/null +++ b/.dockerignore @@ -0,0 +1,68 @@ +# Python +__pycache__/ +*.py[cod] +*$py.class +*.so +.Python +*.egg-info/ +.installed.cfg +*.egg + +# Virtual environments +venv/ +.venv/ +env/ +ENV/ +env.bak/ +venv.bak/ + +# IDE +.vscode/ +.idea/ +*.swp +*.swo +*~ + +# Testing +.pytest_cache/ +.coverage +.hypothesis/ +htmlcov/ +.tox/ +.nox/ + +# Environment files +.env +.envrc +.env.* + +# Git +.git/ +.gitignore +.gitattributes + +# Documentation +*.md +README.md +LICENSE +docs/ + +# CI/CD +.github/ + +# Development files +test_*.py +*_test.py +tests/ + +# OS +.DS_Store +Thumbs.db + +# Logs +*.log + +# Temporary files +tmp/ +temp/ +*.tmp diff --git a/.github/workflows/build.yaml b/.github/workflows/build.yaml new file mode 100644 index 0000000..9317082 --- /dev/null +++ b/.github/workflows/build.yaml @@ -0,0 +1,100 @@ +name: Build and Package Agent Bot Service + +on: + push: + branches: + - 'main' + - 'devOps' + - 'dev' + pull_request: + branches: + - 'main' + - 'devOps' + - 'dev' + +# Permissions needed to push Docker images to your org's GitHub packages +permissions: + contents: read + packages: write + +jobs: + # JOB 1: Test the Python application + build-test: + name: Install Dependencies and Test + runs-on: ubuntu-latest + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + - name: Set up Python 3.11 + uses: actions/setup-python@v5 + with: + python-version: '3.11' + cache: 'pip' + + - name: Cache pip packages + uses: actions/cache@v4 + with: + path: ~/.cache/pip + key: ${{ runner.os }}-pip-${{ hashFiles('**/requirements.txt') }} + restore-keys: | + ${{ runner.os }}-pip- + + - name: Install dependencies + run: | + python -m pip install --upgrade pip + pip install -r requirements.txt + + - name: Lint with flake8 (optional) + run: | + pip install flake8 + # Stop the build if there are Python syntax errors or undefined names + flake8 . --count --select=E9,F63,F7,F82 --show-source --statistics + # Exit-zero treats all errors as warnings + flake8 . --count --exit-zero --max-complexity=10 --max-line-length=127 --statistics + continue-on-error: true + + - name: Test import of main module + run: | + python -c "import main; print('Main module loaded successfully')" + + # JOB 2: Build and push Docker image + build-and-push-docker: + name: Build & Push Docker Image + # This job only runs on pushes to 'main', 'devOps', or 'dev', not on PRs + if: github.ref == 'refs/heads/main' || github.ref == 'refs/heads/devOps' || github.ref == 'refs/heads/dev' + runs-on: ubuntu-latest + # This job runs *after* the build-test job succeeds + needs: build-test + + steps: + - name: Checkout code + uses: actions/checkout@v4 + + # This action generates smart tags for your Docker image + - name: Docker meta + id: meta + uses: docker/metadata-action@v5 + with: + images: ghcr.io/${{ github.repository }} # e.g., ghcr.io/TechTorque-2025/Agent_Bot + tags: | + type=sha,prefix= + type=raw,value=latest,enable={{is_default_branch}} + + # Logs you into the GitHub Container Registry (GHCR) + - name: Log in to GHCR + uses: docker/login-action@v3 + with: + registry: ghcr.io + username: ${{ github.actor }} + password: ${{ secrets.GITHUB_TOKEN }} # This token is auto-generated + + # Builds the Docker image and pushes it to GHCR + - name: Build and push Docker image + uses: docker/build-push-action@v5 + with: + context: . # Dockerfile is in the root of this repo + push: true + tags: ${{ steps.meta.outputs.tags }} + labels: ${{ steps.meta.outputs.labels }} diff --git a/.github/workflows/deploy.yaml b/.github/workflows/deploy.yaml new file mode 100644 index 0000000..4023ce3 --- /dev/null +++ b/.github/workflows/deploy.yaml @@ -0,0 +1,69 @@ +name: Deploy Agent Bot Service to Kubernetes + +on: + workflow_run: + # This MUST match the 'name:' of your build.yaml file + workflows: ["Build and Package Agent Bot Service"] + types: + - completed + branches: + - 'main' + - 'devOps' + +jobs: + deploy: + name: Deploy Agent Bot Service to Kubernetes + # We only deploy if the build job was successful + if: ${{ github.event.workflow_run.conclusion == 'success' }} + runs-on: ubuntu-latest + + steps: + # We only need the SHA of the new image + - name: Get Commit SHA + id: get_sha + run: | + echo "sha=$(echo ${{ github.event.workflow_run.head_sha }} | cut -c1-7)" >> $GITHUB_OUTPUT + + # 1. Checkout your 'k8s-config' repository + - name: Checkout K8s Config Repo + uses: actions/checkout@v4 + with: + # This points to your k8s config repo + repository: 'TechTorque-2025/k8s-config' + # This uses the org-level secret you created + token: ${{ secrets.REPO_ACCESS_TOKEN }} + # We'll put the code in a directory named 'config-repo' + path: 'config-repo' + # Explicitly checkout the 'main' branch + ref: 'main' + + - name: Install kubectl + uses: azure/setup-kubectl@v3 + + - name: Install yq + run: | + sudo wget https://github.com/mikefarah/yq/releases/latest/download/yq_linux_amd64 -O /usr/bin/yq + sudo chmod +x /usr/bin/yq + + - name: Set Kubernetes context + uses: azure/k8s-set-context@v4 + with: + kubeconfig: ${{ secrets.KUBE_CONFIG_DATA }} # This uses your Org-level secret + + # 2. Update the image tag for the agent-bot service + - name: Update image tag in YAML + run: | + yq -i '(select(.kind == "Deployment") | .spec.template.spec.containers[0].image) = "ghcr.io/techtorque-2025/agent_bot:${{ steps.get_sha.outputs.sha }}"' config-repo/k8s/services/agent-bot-deployment.yaml + + # Display file contents before apply for debugging + - name: Display file contents before apply + run: | + echo "--- Displaying k8s/services/agent-bot-deployment.yaml ---" + cat config-repo/k8s/services/agent-bot-deployment.yaml + echo "------------------------------------------------------" + + # 3. Deploy the updated file + - name: Deploy to Kubernetes + run: | + kubectl apply -f config-repo/k8s/services/agent-bot-deployment.yaml + kubectl rollout status deployment/agent-bot-deployment diff --git a/CICD_K8S_DEPLOYMENT.md b/CICD_K8S_DEPLOYMENT.md new file mode 100644 index 0000000..32c59aa --- /dev/null +++ b/CICD_K8S_DEPLOYMENT.md @@ -0,0 +1,288 @@ +# Agent Bot - CI/CD and Kubernetes Deployment Guide + +## Overview + +This document describes the CI/CD pipeline and Kubernetes deployment configuration for the Agent_Bot service, which is the AI-powered chatbot and RAG service for the TechTorque platform. + +## Architecture + +**Service Type**: Python FastAPI microservice +**Port**: 8091 +**Dependencies**: +- Google Gemini API (for AI responses) +- Pinecone (for vector storage/RAG) +- Internal microservices (via API Gateway) + +## CI/CD Pipeline + +### GitHub Actions Workflows + +The Agent_Bot uses two GitHub Actions workflows following the same pattern as other TechTorque microservices: + +#### 1. Build Workflow (`.github/workflows/build.yaml`) + +**Triggers:** +- Push to `main`, `devOps`, or `dev` branches +- Pull requests to these branches + +**Jobs:** + +1. **build-test** + - Sets up Python 3.11 + - Installs dependencies from `requirements.txt` + - Runs linting with flake8 (optional) + - Tests module imports + - Caches pip packages for faster builds + +2. **build-and-push-docker** + - Only runs on pushes (not PRs) + - Builds Docker image from Dockerfile + - Tags image with commit SHA and `latest` + - Pushes to GitHub Container Registry (GHCR) + - Image name: `ghcr.io/techtorque-2025/agent_bot:latest` + +#### 2. Deploy Workflow (`.github/workflows/deploy.yaml`) + +**Triggers:** +- Runs after successful completion of Build workflow +- Only for `main` and `devOps` branches + +**Jobs:** + +1. **deploy** + - Checks out k8s-config repository + - Updates image tag in `agent-bot-deployment.yaml` + - Applies configuration to Kubernetes cluster + - Monitors rollout status + +### Docker Configuration + +**Dockerfile highlights:** +- Base image: `python:3.11-slim` +- Installs system dependencies (gcc, g++) +- Uses multi-stage caching for faster builds +- Exposes port 8091 +- Includes health check on `/health` endpoint +- Runs with `uvicorn` ASGI server + +## Kubernetes Configuration + +### Location +All K8s configurations are in the `k8s-config` repository: +- ConfigMap: `k8s/configmaps/agent-bot-configmap.yaml` +- Secrets: `k8s/secrets/agent-bot-secrets.template.yaml` +- Deployment: `k8s/services/agent-bot-deployment.yaml` + +### ConfigMap (`agent-bot-config`) + +Contains non-sensitive configuration: +- Service URLs (API Gateway endpoints) +- Gemini model settings +- Pinecone configuration (non-sensitive) +- RAG parameters (chunk size, overlap, context length) + +### Secrets (`agent-bot-secrets`) + +Contains sensitive API keys: +- `GOOGLE_API_KEY`: Google Gemini API key +- `PINECONE_API_KEY`: Pinecone vector database API key + +**Creating the secret:** +```bash +# Method 1: Using the automated script +cd k8s-config +./create-all-secrets.sh + +# Method 2: Manual creation +kubectl create secret generic agent-bot-secrets \ + --from-literal=GOOGLE_API_KEY='your-gemini-api-key' \ + --from-literal=PINECONE_API_KEY='your-pinecone-api-key' \ + --namespace=default +``` + +### Deployment Configuration + +**Replica count**: 2 (for high availability) + +**Resource limits:** +- Memory: 512Mi (request) / 1Gi (limit) +- CPU: 250m (request) / 500m (limit) + +**Health checks:** +- Liveness probe: `/health` endpoint (30s initial delay) +- Readiness probe: `/health` endpoint (15s initial delay) + +**Service:** +- Type: ClusterIP (internal only) +- Internal port: 80 +- Target port: 8091 + +### API Gateway Integration + +The Agent_Bot service is accessible through the API Gateway at: +``` +http://api-gateway/api/v1/ai/chat +``` + +The API Gateway should be configured to route `/api/v1/ai/*` requests to `http://agent-bot-service:80`. + +## Deployment Process + +### Prerequisites + +1. **GitHub Secrets** (Organization level): + - `REPO_ACCESS_TOKEN`: Personal access token with repo access + - `KUBE_CONFIG_DATA`: Base64-encoded kubeconfig for K3s cluster + +2. **Kubernetes Cluster** (K3s): + - Running and accessible + - kubectl configured + +3. **API Keys**: + - Google Gemini API key + - Pinecone API key and index created + +### Initial Setup + +1. **Create Kubernetes secrets:** + ```bash + cd k8s-config + ./create-all-secrets.sh + # Enter API keys when prompted for agent-bot + ``` + +2. **Apply ConfigMap:** + ```bash + kubectl apply -f k8s/configmaps/agent-bot-configmap.yaml + ``` + +3. **Deploy the service:** + ```bash + kubectl apply -f k8s/services/agent-bot-deployment.yaml + ``` + +### Automated Deployment + +Once the initial setup is complete, deployments happen automatically: + +1. Developer pushes code to `main` or `devOps` branch +2. Build workflow runs: + - Tests the application + - Builds Docker image + - Pushes to GHCR +3. Deploy workflow runs: + - Updates K8s manifest with new image tag + - Applies to cluster + - Waits for rollout completion + +## Verification + +### Check Deployment Status +```bash +kubectl get deployments agent-bot-deployment +kubectl get pods -l app=agent-bot-service +kubectl get service agent-bot-service +``` + +### Check Logs +```bash +# Get pod name +kubectl get pods -l app=agent-bot-service + +# View logs +kubectl logs + +# Follow logs +kubectl logs -f +``` + +### Test the Service +```bash +# From within the cluster +kubectl run -it --rm debug --image=curlimages/curl --restart=Never -- \ + curl http://agent-bot-service/health + +# Through API Gateway +curl http:///api/v1/ai/chat \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -d '{"message": "Hello", "session_id": "test"}' +``` + +## Troubleshooting + +### Common Issues + +1. **Image pull errors:** + - Ensure GITHUB_TOKEN has correct permissions + - Check image name matches: `ghcr.io/techtorque-2025/agent_bot:latest` + +2. **Secret not found:** + - Run `kubectl get secret agent-bot-secrets` + - Recreate using `create-all-secrets.sh` + +3. **Service not responding:** + - Check logs: `kubectl logs ` + - Verify API keys are correct in secrets + - Ensure Pinecone index exists + +4. **Health check failures:** + - Check if port 8091 is accessible + - Verify dependencies are installed correctly + - Check application logs for startup errors + +### Rollback + +To rollback to a previous version: +```bash +# View rollout history +kubectl rollout history deployment/agent-bot-deployment + +# Rollback to previous version +kubectl rollout undo deployment/agent-bot-deployment + +# Rollback to specific revision +kubectl rollout undo deployment/agent-bot-deployment --to-revision= +``` + +## Monitoring + +### Key Metrics to Monitor +- Pod restart count +- Memory/CPU usage +- Response time for `/health` endpoint +- Error rates in application logs +- API rate limits (Gemini, Pinecone) + +### Scaling + +To scale the deployment: +```bash +# Manual scaling +kubectl scale deployment agent-bot-deployment --replicas=3 + +# Or edit the deployment file and apply +``` + +## Security Considerations + +1. **API Keys**: Never commit real API keys to version control +2. **Secrets**: Use Kubernetes secrets, not environment variables in deployments +3. **Network**: Service is ClusterIP only, not exposed externally +4. **RBAC**: Ensure proper service account permissions + +## Differences from Java Microservices + +Unlike the Java Spring Boot services, Agent_Bot: +- Uses Python 3.11 instead of Java 17 +- No Maven build process +- Uses `uvicorn` instead of Spring Boot embedded Tomcat +- Different dependency management (pip vs Maven) +- Smaller base image but includes ML libraries +- Different health check patterns + +## Related Documentation + +- [Agent Bot README](../../Agent_Bot/README.md) +- [Authentication Service CI/CD](../../Authentication/.github/workflows/) +- [K8s Ingress Configuration](./k8s/config/INGRESS_NOTES.md) diff --git a/COMPLETE_INTEGRATION_GUIDE.md b/COMPLETE_INTEGRATION_GUIDE.md new file mode 100644 index 0000000..9846763 --- /dev/null +++ b/COMPLETE_INTEGRATION_GUIDE.md @@ -0,0 +1,575 @@ +# Agent Bot - Complete Integration Guide + +## ๐ŸŽฏ Overview + +This document provides a complete guide for integrating the Agent_Bot service into the TechTorque microservices ecosystem with full CI/CD and Kubernetes deployment. + +## โœ… What Has Been Created + +### 1. Agent_Bot Repository +``` +Agent_Bot/ +โ”œโ”€โ”€ .github/workflows/ +โ”‚ โ”œโ”€โ”€ build.yaml โœ… NEW - Build & push Docker image +โ”‚ โ””โ”€โ”€ deploy.yaml โœ… NEW - Deploy to Kubernetes +โ”œโ”€โ”€ .dockerignore โœ… NEW - Optimize Docker builds +โ”œโ”€โ”€ Dockerfile โœ… NEW - Python FastAPI container +โ”œโ”€โ”€ requirements.txt โœ… UPDATED - Clean dependencies +โ”œโ”€โ”€ IMPLEMENTATION_SUMMARY.md โœ… NEW - This implementation +โ”œโ”€โ”€ CICD_K8S_DEPLOYMENT.md โœ… NEW - Detailed guide +โ””โ”€โ”€ QUICK_REFERENCE.md โœ… NEW - Quick commands +``` + +### 2. k8s-config Repository +``` +k8s-config/ +โ”œโ”€โ”€ k8s/ +โ”‚ โ”œโ”€โ”€ configmaps/ +โ”‚ โ”‚ โ””โ”€โ”€ agent-bot-configmap.yaml โœ… NEW +โ”‚ โ”œโ”€โ”€ secrets/ +โ”‚ โ”‚ โ””โ”€โ”€ agent-bot-secrets.template.yaml โœ… NEW +โ”‚ โ””โ”€โ”€ services/ +โ”‚ โ”œโ”€โ”€ agent-bot-deployment.yaml โœ… NEW +โ”‚ โ””โ”€โ”€ gateway-deployment.yaml โœ… UPDATED - Added Agent Bot URL +โ””โ”€โ”€ create-all-secrets.sh โœ… UPDATED - Added Agent Bot secrets +``` + +### 3. API Gateway +``` +API_Gateway/ +โ””โ”€โ”€ config.yaml โœ… UPDATED - Configured AI service routing +``` + +## ๐Ÿ”ง Configuration Changes Summary + +### API Gateway Updates + +**config.yaml** - Updated AI service routing: +```yaml +- name: "ai" + path_prefix: "/api/v1/ai/" + target_url: "http://localhost:8091" # Changed from 8089 + strip_prefix: "/api/v1/ai" + auth_required: true + env_var: "AGENT_BOT_SERVICE_URL" # Added env var +``` + +**gateway-deployment.yaml** - Added service URL: +```yaml +- name: "AGENT_BOT_SERVICE_URL" + value: "http://agent-bot-service" +``` + +### ConfigMap Configuration + +**Service URLs**: All configured to use API Gateway +- `BASE_SERVICE_URL: "http://api-gateway/api/v1"` +- `AUTHENTICATION_SERVICE_URL: "http://api-gateway/api/v1/auth"` +- `VEHICLE_SERVICE_URL: "http://api-gateway/api/v1/vehicles"` +- `PROJECT_SERVICE_URL: "http://api-gateway/api/v1/jobs"` +- `TIME_LOGGING_SERVICE_URL: "http://api-gateway/api/v1/logs"` +- `APPOINTMENT_SERVICE_URL: "http://api-gateway/api/v1/appointments"` + +**AI Configuration**: +- `GEMINI_MODEL: "gemini-2.5-flash"` +- `PINECONE_INDEX_NAME: "techtorque-kb"` +- `PINECONE_ENVIRONMENT: "us-east-1-aws"` + +**RAG Configuration**: +- `RAG_CHUNK_SIZE: "500"` +- `RAG_CHUNK_OVERLAP: "50"` +- `MAX_CONTEXT_LENGTH: "2000"` + +## ๐Ÿš€ Deployment Instructions + +### Step 1: Prepare External Services + +#### Google Gemini API +1. Visit https://makersuite.google.com/app/apikey +2. Create a new API key +3. Save the key securely + +#### Pinecone +1. Visit https://app.pinecone.io/ +2. Create account if needed +3. Create a new index: + - Name: `techtorque-kb` + - Dimensions: 384 (for sentence-transformers/all-MiniLM-L6-v2) + - Metric: cosine + - Environment: us-east-1-aws +4. Get your API key + +### Step 2: Create Kubernetes Secrets + +```bash +cd k8s-config + +# Option 1: Use the automated script +./create-all-secrets.sh +# When prompted for "agent-bot", enter: +# - Google Gemini API key +# - Pinecone API key + +# Option 2: Manual creation +kubectl create secret generic agent-bot-secrets \ + --from-literal=GOOGLE_API_KEY='your-gemini-key-here' \ + --from-literal=PINECONE_API_KEY='your-pinecone-key-here' \ + --namespace=default +``` + +### Step 3: Apply Kubernetes Configurations + +```bash +cd k8s-config + +# Apply ConfigMap +kubectl apply -f k8s/configmaps/agent-bot-configmap.yaml + +# Apply Deployment (includes Service) +kubectl apply -f k8s/services/agent-bot-deployment.yaml + +# Update API Gateway (to include Agent Bot URL) +kubectl apply -f k8s/services/gateway-deployment.yaml +``` + +### Step 4: Verify Deployment + +```bash +# Check pods are running +kubectl get pods -l app=agent-bot-service + +# Check service is created +kubectl get svc agent-bot-service + +# View logs +kubectl logs -l app=agent-bot-service --tail=50 + +# Check health +kubectl run -it --rm test --image=curlimages/curl --restart=Never -- \ + curl http://agent-bot-service/health +``` + +### Step 5: Trigger CI/CD Pipeline + +```bash +cd Agent_Bot + +# Add and commit changes +git add . +git commit -m "feat: Add CI/CD and K8s configuration for Agent Bot" + +# Push to trigger workflows +git push origin devOps +# OR +git push origin main +``` + +### Step 6: Monitor Deployment + +```bash +# Watch GitHub Actions +# Visit: https://github.com/TechTorque-2025/Agent_Bot/actions + +# Watch Kubernetes deployment +kubectl get pods -l app=agent-bot-service -w + +# Check rollout status +kubectl rollout status deployment/agent-bot-deployment + +# View recent logs +kubectl logs -l app=agent-bot-service --tail=100 -f +``` + +## ๐Ÿงช Testing + +### Test 1: Health Check (Internal) +```bash +kubectl run -it --rm test --image=curlimages/curl --restart=Never -- \ + curl http://agent-bot-service/health +``` + +Expected response: +```json +{"status": "healthy"} +``` + +### Test 2: Service Info +```bash +kubectl run -it --rm test --image=curlimages/curl --restart=Never -- \ + curl http://agent-bot-service/ +``` + +Expected response: +```json +{ + "service": "TechTorque Unified AI Agent", + "status": "running", + "model": "gemini-2.5-flash", + "api_endpoints": "/api/v1/ai/chat", + "rag_endpoints": "/api/v1/ai/rag/status" +} +``` + +### Test 3: Chat Endpoint (Via Gateway) +```bash +# Get a valid JWT token first +TOKEN=$(curl -X POST http://api-gateway-service/api/v1/auth/login \ + -H "Content-Type: application/json" \ + -d '{"email":"user@example.com","password":"password"}' \ + | jq -r '.token') + +# Test chat endpoint +curl -X POST http://api-gateway-service/api/v1/ai/chat \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer $TOKEN" \ + -d '{ + "message": "Hello, what can you help me with?", + "session_id": "test-session-123" + }' +``` + +### Test 4: Check from Frontend +Once frontend is updated, test from browser: +```javascript +// In browser console +fetch('http://your-domain.com/api/v1/ai/chat', { + method: 'POST', + headers: { + 'Content-Type': 'application/json', + 'Authorization': 'Bearer ' + localStorage.getItem('token') + }, + body: JSON.stringify({ + message: 'Hello', + session_id: 'browser-test' + }) +}) +.then(r => r.json()) +.then(console.log) +``` + +## ๐Ÿ” Troubleshooting + +### Issue 1: Pods Not Starting + +**Symptoms:** +```bash +kubectl get pods -l app=agent-bot-service +# Shows: CrashLoopBackOff or ImagePullBackOff +``` + +**Solutions:** + +1. **ImagePullBackOff:** + ```bash + # Check image exists + docker pull ghcr.io/techtorque-2025/agent_bot:latest + + # Verify image name in deployment + kubectl describe deployment agent-bot-deployment + ``` + +2. **CrashLoopBackOff:** + ```bash + # Check logs for errors + kubectl logs -l app=agent-bot-service --tail=100 + + # Common issues: + # - Missing API keys in secrets + # - Invalid API keys + # - Pinecone index doesn't exist + ``` + +3. **Verify Secrets:** + ```bash + kubectl get secret agent-bot-secrets + kubectl describe secret agent-bot-secrets + + # Recreate if needed + kubectl delete secret agent-bot-secrets + ./create-all-secrets.sh + ``` + +### Issue 2: Health Check Failing + +**Symptoms:** +```bash +kubectl get pods -l app=agent-bot-service +# Shows: Pods restarting frequently +``` + +**Solutions:** +```bash +# Check health endpoint directly +kubectl exec -it -- curl localhost:8091/health + +# Check if port is correct +kubectl get pod -o yaml | grep containerPort + +# Increase initial delay if startup is slow +kubectl edit deployment agent-bot-deployment +# Update: initialDelaySeconds: 60 +``` + +### Issue 3: Can't Reach Other Services + +**Symptoms:** +- Chat endpoint returns errors about unable to reach services + +**Solutions:** +```bash +# Verify API Gateway is running +kubectl get svc api-gateway-service + +# Check if Agent Bot can reach gateway +kubectl exec -it -- curl http://api-gateway-service/health + +# Verify service URLs in ConfigMap +kubectl get configmap agent-bot-config -o yaml + +# Check Agent Bot logs for connection errors +kubectl logs -l app=agent-bot-service | grep -i error +``` + +### Issue 4: GitHub Actions Failing + +**Build Workflow Fails:** +```bash +# Check build.yaml syntax +cd Agent_Bot +cat .github/workflows/build.yaml + +# Test Docker build locally +docker build -t agent-bot:test . + +# Check workflow logs in GitHub Actions UI +``` + +**Deploy Workflow Fails:** +```bash +# Verify secrets are set in GitHub +# Settings > Secrets and variables > Actions +# Required: +# - REPO_ACCESS_TOKEN +# - KUBE_CONFIG_DATA + +# Check workflow logs for specific errors +``` + +### Issue 5: Gemini API Errors + +**Symptoms:** +- Chat returns errors about API quota or authentication + +**Solutions:** +```bash +# Verify API key is correct +kubectl get secret agent-bot-secrets -o jsonpath='{.data.GOOGLE_API_KEY}' | base64 -d + +# Test API key manually +curl https://generativelanguage.googleapis.com/v1/models/gemini-2.5-flash:generateContent \ + -H "Content-Type: application/json" \ + -H "x-goog-api-key: YOUR_API_KEY" \ + -d '{"contents":[{"parts":[{"text":"Hello"}]}]}' + +# Check quota limits in Google AI Studio +``` + +### Issue 6: Pinecone Errors + +**Symptoms:** +- RAG queries failing or returning errors + +**Solutions:** +```bash +# Verify Pinecone index exists +# Visit: https://app.pinecone.io/ + +# Check index name matches ConfigMap +kubectl get configmap agent-bot-config -o yaml | grep PINECONE_INDEX_NAME + +# Verify API key +kubectl get secret agent-bot-secrets -o jsonpath='{.data.PINECONE_API_KEY}' | base64 -d + +# Check embedding dimension matches (should be 384) +``` + +## ๐Ÿ“Š Monitoring + +### Key Metrics + +```bash +# Pod status +kubectl get pods -l app=agent-bot-service + +# Resource usage +kubectl top pods -l app=agent-bot-service + +# Deployment status +kubectl get deployment agent-bot-deployment + +# Service endpoints +kubectl get endpoints agent-bot-service + +# Recent events +kubectl get events --sort-by='.lastTimestamp' | grep agent-bot +``` + +### Logs + +```bash +# All logs +kubectl logs -l app=agent-bot-service --all-containers=true + +# Follow logs +kubectl logs -l app=agent-bot-service -f + +# Logs from specific pod +kubectl logs + +# Previous logs (if pod crashed) +kubectl logs --previous + +# Logs with timestamps +kubectl logs -l app=agent-bot-service --timestamps=true +``` + +### Performance + +```bash +# Check response times +kubectl exec -it -- time curl http://agent-bot-service/health + +# Check concurrent connections +kubectl describe svc agent-bot-service + +# Monitor resource usage over time +watch kubectl top pods -l app=agent-bot-service +``` + +## ๐Ÿ”„ Updating the Service + +### Update Code Only +```bash +cd Agent_Bot +# Make changes +git add . +git commit -m "feat: your changes" +git push origin main +# CI/CD will auto-deploy +``` + +### Update Configuration +```bash +cd k8s-config + +# Edit ConfigMap +kubectl edit configmap agent-bot-config +# OR +vim k8s/configmaps/agent-bot-configmap.yaml +kubectl apply -f k8s/configmaps/agent-bot-configmap.yaml + +# Restart pods to pick up changes +kubectl rollout restart deployment/agent-bot-deployment +``` + +### Update Secrets +```bash +cd k8s-config + +# Delete old secret +kubectl delete secret agent-bot-secrets + +# Create new secret +./create-all-secrets.sh + +# Restart pods +kubectl rollout restart deployment/agent-bot-deployment +``` + +### Scale Service +```bash +# Scale up +kubectl scale deployment agent-bot-deployment --replicas=3 + +# Scale down +kubectl scale deployment agent-bot-deployment --replicas=1 + +# Auto-scale (if HPA configured) +kubectl autoscale deployment agent-bot-deployment --min=2 --max=5 --cpu-percent=80 +``` + +## ๐ŸŽฏ Next Steps + +### 1. Frontend Integration +- Update frontend to call `/api/v1/ai/chat` +- Add chat UI component +- Handle streaming responses (if implemented) + +### 2. Documentation +- Add API documentation to main README +- Create user guide for AI features +- Document RAG document ingestion process + +### 3. Monitoring & Alerts +- Set up Prometheus metrics +- Configure Grafana dashboards +- Create alerts for: + - Pod restarts + - High response times + - API quota limits + - Error rates + +### 4. Performance Optimization +- Implement response caching +- Add request rate limiting +- Optimize embedding generation +- Consider GPU acceleration for ML models + +### 5. Security Enhancements +- Implement request validation +- Add rate limiting per user +- Audit API key usage +- Set up secret rotation + +## ๐Ÿ“š Related Documentation + +- [Agent Bot README](./README.md) - Service overview +- [CI/CD Deployment Guide](./CICD_K8S_DEPLOYMENT.md) - Detailed deployment info +- [Quick Reference](./QUICK_REFERENCE.md) - Command cheatsheet +- [Implementation Summary](./IMPLEMENTATION_SUMMARY.md) - What was created + +## โœ… Pre-Deployment Checklist + +- [ ] Google Gemini API key obtained +- [ ] Pinecone account created and index set up +- [ ] Kubernetes secrets created +- [ ] ConfigMap applied +- [ ] API Gateway updated and redeployed +- [ ] GitHub secrets configured (REPO_ACCESS_TOKEN, KUBE_CONFIG_DATA) +- [ ] Docker image builds successfully +- [ ] Workflows tested in GitHub Actions +- [ ] Deployment successful in Kubernetes +- [ ] Health checks passing +- [ ] Service accessible from API Gateway +- [ ] End-to-end test successful + +## ๐ŸŽ‰ Success Criteria + +Your Agent Bot deployment is successful when: + +1. โœ… GitHub Actions workflows run without errors +2. โœ… Docker image exists in GHCR: `ghcr.io/techtorque-2025/agent_bot:latest` +3. โœ… Kubernetes pods are running: `kubectl get pods -l app=agent-bot-service` +4. โœ… Health check returns 200: `curl http://agent-bot-service/health` +5. โœ… Service info endpoint works: `curl http://agent-bot-service/` +6. โœ… Chat endpoint responds: `curl http://api-gateway-service/api/v1/ai/chat` +7. โœ… No errors in pod logs: `kubectl logs -l app=agent-bot-service` +8. โœ… Gateway routes correctly to Agent Bot +9. โœ… Authentication works via gateway +10. โœ… AI responses are generated successfully + +--- + +**Status**: โœ… Ready for deployment +**Last Updated**: 2025-11-12 +**Version**: 1.0.0 diff --git a/Dockerfile b/Dockerfile new file mode 100644 index 0000000..2c0e422 --- /dev/null +++ b/Dockerfile @@ -0,0 +1,33 @@ +# Dockerfile for Agent_Bot (Python FastAPI Service) + +# Use official Python runtime as base image +FROM python:3.11-slim + +# Set working directory in container +WORKDIR /app + +# Install system dependencies +RUN apt-get update && apt-get install -y \ + gcc \ + g++ \ + && rm -rf /var/lib/apt/lists/* + +# Copy requirements first for better Docker layer caching +COPY requirements.txt . + +# Install Python dependencies +RUN pip install --no-cache-dir --upgrade pip && \ + pip install --no-cache-dir -r requirements.txt + +# Copy the application code +COPY . . + +# Expose the port the app runs on +EXPOSE 8091 + +# Health check +HEALTHCHECK --interval=30s --timeout=10s --start-period=40s --retries=3 \ + CMD python -c "import requests; requests.get('http://localhost:8091/health')" || exit 1 + +# Command to run the application +CMD ["uvicorn", "main:app", "--host", "0.0.0.0", "--port", "8091"] diff --git a/IMPLEMENTATION_SUMMARY.md b/IMPLEMENTATION_SUMMARY.md new file mode 100644 index 0000000..ab147ca --- /dev/null +++ b/IMPLEMENTATION_SUMMARY.md @@ -0,0 +1,305 @@ +# Agent Bot CI/CD Implementation Summary + +## โœ… Completed Tasks + +### 1. GitHub Workflows Created + +Created two GitHub Actions workflows following the TechTorque microservices pattern: + +#### **Build Workflow** (`.github/workflows/build.yaml`) +- โœ… Runs on push/PR to `main`, `devOps`, `dev` branches +- โœ… Job 1: `build-test` - Tests Python application + - Sets up Python 3.11 + - Installs dependencies from requirements.txt + - Runs flake8 linting + - Tests module imports +- โœ… Job 2: `build-and-push-docker` - Builds and pushes Docker image + - Only runs on pushes (not PRs) + - Tags with commit SHA and `latest` + - Pushes to `ghcr.io/techtorque-2025/agent_bot` + +#### **Deploy Workflow** (`.github/workflows/deploy.yaml`) +- โœ… Triggers after successful build workflow completion +- โœ… Only runs for `main` and `devOps` branches +- โœ… Checks out k8s-config repository +- โœ… Updates image tag in deployment manifest +- โœ… Applies to Kubernetes cluster +- โœ… Monitors rollout status + +### 2. Dockerfile Created + +โœ… Created production-ready Dockerfile for Python FastAPI service: +- Base image: `python:3.11-slim` +- Installs system dependencies (gcc, g++) +- Uses pip caching for faster builds +- Exposes port 8091 +- Includes health check +- Runs with uvicorn + +### 3. Requirements.txt Fixed + +โœ… Replaced system packages with actual project dependencies: +- FastAPI & uvicorn +- LangChain ecosystem +- Google Generative AI (Gemini) +- Pinecone client +- sentence-transformers +- httpx for async HTTP calls + +### 4. Kubernetes Configuration (k8s-config) + +#### **ConfigMap** (`k8s/configmaps/agent-bot-configmap.yaml`) +โœ… Created with non-sensitive configuration: +- Service ports and URLs +- API Gateway endpoints +- Gemini model settings +- Pinecone configuration +- RAG parameters + +#### **Secrets Template** (`k8s/secrets/agent-bot-secrets.template.yaml`) +โœ… Created template for sensitive data: +- GOOGLE_API_KEY placeholder +- PINECONE_API_KEY placeholder + +#### **Deployment** (`k8s/services/agent-bot-deployment.yaml`) +โœ… Created comprehensive deployment manifest: +- 2 replicas for high availability +- Resource limits (512Mi-1Gi memory, 250m-500m CPU) +- Health checks (liveness & readiness probes) +- Environment variables from ConfigMap and Secrets +- ClusterIP service (internal only) +- Port mapping: 80 โ†’ 8091 + +### 5. Secret Creation Script Updated + +โœ… Updated `k8s-config/create-all-secrets.sh`: +- Added agent-bot to service list +- Special handling for AI service secrets (no DB password) +- Prompts for GOOGLE_API_KEY and PINECONE_API_KEY +- Updated verification to include agent-bot-secrets + +### 6. Documentation Created + +โœ… **CICD_K8S_DEPLOYMENT.md** - Comprehensive guide covering: +- CI/CD pipeline architecture +- Docker configuration +- Kubernetes setup +- Deployment process +- Troubleshooting +- Security considerations +- Differences from Java microservices + +โœ… **QUICK_REFERENCE.md** - Quick command reference for: +- Local development +- Docker operations +- Kubernetes commands +- API testing +- Common troubleshooting + +## ๐Ÿ“‹ Key Differences from Java Microservices + +| Aspect | Java Services | Agent Bot | +|--------|--------------|-----------| +| Language | Java 17 | Python 3.11 | +| Framework | Spring Boot | FastAPI | +| Build Tool | Maven | pip | +| Base Image | eclipse-temurin:17 | python:3.11-slim | +| Server | Embedded Tomcat | uvicorn | +| Build Stage | Multi-stage with Maven | Single stage with pip | +| Database | PostgreSQL | None (stateless) | +| External Deps | PostgreSQL | Gemini API, Pinecone | + +## ๐Ÿ”„ CI/CD Flow + +``` +Developer Push (main/devOps/dev) + โ†“ + Build Workflow + โ†“ + โ”œโ”€> Test Python App + โ””โ”€> Build Docker Image + โ†“ + Push to GHCR (ghcr.io/techtorque-2025/agent_bot:SHA) + โ†“ + Deploy Workflow (triggered) + โ†“ + Update k8s-config/agent-bot-deployment.yaml + โ†“ + Apply to K3s Cluster + โ†“ + Rollout Complete โœ… +``` + +## ๐Ÿ”’ Security Implementation + +- โœ… API keys stored in Kubernetes secrets (not in code) +- โœ… Secrets template for version control (no actual keys) +- โœ… ClusterIP service (internal only, not exposed) +- โœ… GitHub secrets for deployment credentials +- โœ… No hardcoded credentials anywhere + +## ๐Ÿš€ Deployment Prerequisites + +### GitHub Secrets (Already configured at org level) +- `REPO_ACCESS_TOKEN` - For k8s-config access +- `KUBE_CONFIG_DATA` - For K3s cluster access + +### New Kubernetes Secrets (Need to create) +```bash +cd k8s-config +./create-all-secrets.sh +# When prompted for agent-bot, enter: +# - Google Gemini API key +# - Pinecone API key +``` + +### External Services (Need to setup) +1. **Google Gemini API** + - Get API key from Google AI Studio + - Model: gemini-2.5-flash + +2. **Pinecone** + - Create account and get API key + - Create index named: `techtorque-kb` + - Region: `us-east-1-aws` + +## ๐Ÿ“ Next Steps to Deploy + +1. **Create API Keys** + ```bash + # Get Google Gemini API key from: + # https://makersuite.google.com/app/apikey + + # Get Pinecone API key from: + # https://app.pinecone.io/ + ``` + +2. **Create Kubernetes Secrets** + ```bash + cd k8s-config + ./create-all-secrets.sh + # Enter API keys when prompted for agent-bot + ``` + +3. **Apply ConfigMap** + ```bash + kubectl apply -f k8s/configmaps/agent-bot-configmap.yaml + ``` + +4. **Initial Deployment** (manual first time) + ```bash + kubectl apply -f k8s/services/agent-bot-deployment.yaml + ``` + +5. **Push Code to Trigger CI/CD** + ```bash + cd Agent_Bot + git add . + git commit -m "Add CI/CD and K8s configuration" + git push origin devOps + # Workflows will run automatically + ``` + +6. **Monitor Deployment** + ```bash + kubectl get pods -l app=agent-bot-service -w + kubectl logs -l app=agent-bot-service -f + ``` + +## โœ… Verification Checklist + +- [ ] GitHub workflows visible in Actions tab +- [ ] Workflows trigger on push to main/devOps/dev +- [ ] Docker image builds successfully +- [ ] Image appears in GHCR (ghcr.io/techtorque-2025/agent_bot) +- [ ] Kubernetes secrets created +- [ ] ConfigMap applied +- [ ] Deployment creates 2 pods +- [ ] Pods pass health checks +- [ ] Service is accessible from within cluster +- [ ] API Gateway routes to agent-bot-service + +## ๐Ÿ“Š Files Created/Modified + +### Agent_Bot Repository +``` +.github/ + workflows/ + โœ… build.yaml (NEW) + โœ… deploy.yaml (NEW) +โœ… Dockerfile (NEW) +โœ… requirements.txt (MODIFIED - cleaned up) +โœ… CICD_K8S_DEPLOYMENT.md (NEW) +โœ… QUICK_REFERENCE.md (NEW) +``` + +### k8s-config Repository +``` +k8s/ + configmaps/ + โœ… agent-bot-configmap.yaml (NEW) + secrets/ + โœ… agent-bot-secrets.template.yaml (NEW) + services/ + โœ… agent-bot-deployment.yaml (NEW) +โœ… create-all-secrets.sh (MODIFIED - added agent-bot) +``` + +## ๐ŸŽฏ Integration Points + +### API Gateway +The API Gateway needs to route `/api/v1/ai/*` to: +```yaml +upstream: http://agent-bot-service:80 +``` + +### Service Dependencies +Agent_Bot communicates with: +- Authentication Service (via API Gateway) +- Vehicle Service (via API Gateway) +- Project Service (via API Gateway) +- Time Logging Service (via API Gateway) +- Appointment Service (via API Gateway) + +All service URLs are configured to use `http://api-gateway/api/v1/...` + +## ๐Ÿ”ง Testing the Setup + +### Local Test +```bash +cd Agent_Bot +source venv/bin/activate +python main.py +# Visit http://localhost:8091/health +``` + +### Docker Test +```bash +docker build -t agent-bot:test . +docker run -p 8091:8091 --env-file .env agent-bot:test +``` + +### Kubernetes Test +```bash +kubectl run -it --rm test --image=curlimages/curl --restart=Never -- \ + curl http://agent-bot-service/health +``` + +## ๐Ÿ“š References + +Pattern based on: +- Authentication Service workflows +- Vehicle Service workflows +- Standard TechTorque CI/CD practices + +Adapted for: +- Python instead of Java +- FastAPI instead of Spring Boot +- AI/ML service requirements +- No database dependency + +--- + +**Status**: โœ… Implementation Complete +**Ready for**: Testing and deployment +**Requires**: API keys for Gemini and Pinecone diff --git a/QUICK_REFERENCE.md b/QUICK_REFERENCE.md new file mode 100644 index 0000000..7466b61 --- /dev/null +++ b/QUICK_REFERENCE.md @@ -0,0 +1,221 @@ +# Agent Bot - Quick Reference + +## Service Information +- **Name**: Agent_Bot +- **Type**: Python FastAPI Microservice +- **Port**: 8091 +- **API Endpoint**: `/api/v1/ai/chat` + +## Quick Commands + +### Local Development +```bash +# Navigate to Agent_Bot directory +cd Agent_Bot + +# Activate virtual environment +source venv/bin/activate # Linux/Mac +# OR +.\venv\Scripts\activate # Windows + +# Install dependencies +pip install -r requirements.txt + +# Run locally +python main.py +# OR +uvicorn main:app --reload --port 8091 +``` + +### Docker +```bash +# Build image +docker build -t agent-bot:latest . + +# Run container +docker run -p 8091:8091 --env-file .env agent-bot:latest + +# Run with docker-compose (if configured) +docker-compose up agent-bot +``` + +### Kubernetes +```bash +# Apply configurations (from k8s-config repo) +kubectl apply -f k8s/configmaps/agent-bot-configmap.yaml +kubectl apply -f k8s/services/agent-bot-deployment.yaml + +# Check status +kubectl get pods -l app=agent-bot-service +kubectl get svc agent-bot-service + +# View logs +kubectl logs -l app=agent-bot-service --tail=100 -f + +# Scale +kubectl scale deployment agent-bot-deployment --replicas=3 + +# Restart +kubectl rollout restart deployment/agent-bot-deployment + +# Rollback +kubectl rollout undo deployment/agent-bot-deployment +``` + +### GitHub Actions +```bash +# Workflows are triggered automatically on push/PR to: +# - main +# - devOps +# - dev + +# View workflow status at: +# https://github.com/TechTorque-2025/Agent_Bot/actions +``` + +## Environment Variables + +### Required (Sensitive) +```bash +GOOGLE_API_KEY= +PINECONE_API_KEY= +``` + +### Required (Non-Sensitive) +```bash +PORT=8091 +BASE_SERVICE_URL=http://localhost:8080/api/v1 +GEMINI_MODEL=gemini-2.5-flash +PINECONE_ENVIRONMENT=us-east-1-aws +PINECONE_INDEX_NAME=techtorque-kb +``` + +### Optional (with defaults) +```bash +RAG_CHUNK_SIZE=500 +RAG_CHUNK_OVERLAP=50 +MAX_CONTEXT_LENGTH=2000 +``` + +## API Endpoints + +### Health Check +```bash +curl http://localhost:8091/health +``` + +### Root +```bash +curl http://localhost:8091/ +``` + +### Chat (Main endpoint) +```bash +curl -X POST http://localhost:8091/api/v1/ai/chat \ + -H "Content-Type: application/json" \ + -H "Authorization: Bearer " \ + -d '{ + "message": "Hello, how can you help me?", + "session_id": "test-session-123" + }' +``` + +## Troubleshooting + +### Import errors +```bash +pip install --upgrade -r requirements.txt +``` + +### Port already in use +```bash +# Find process using port 8091 +lsof -i :8091 +# Kill it +kill -9 +``` + +### API Key errors +- Verify `.env` file exists in Agent_Bot directory +- Check API keys are valid +- For Pinecone, ensure index is created + +### Docker build fails +```bash +# Clean build +docker build --no-cache -t agent-bot:latest . + +# Check logs +docker logs +``` + +### K8s pod not starting +```bash +# Check pod status +kubectl describe pod + +# Check secrets exist +kubectl get secret agent-bot-secrets +kubectl describe secret agent-bot-secrets + +# Check configmap +kubectl get configmap agent-bot-config +kubectl describe configmap agent-bot-config +``` + +## File Structure +``` +Agent_Bot/ +โ”œโ”€โ”€ .github/ +โ”‚ โ””โ”€โ”€ workflows/ +โ”‚ โ”œโ”€โ”€ build.yaml # Build and push Docker image +โ”‚ โ””โ”€โ”€ deploy.yaml # Deploy to K8s +โ”œโ”€โ”€ config/ +โ”‚ โ””โ”€โ”€ settings.py # Configuration management +โ”œโ”€โ”€ models/ +โ”‚ โ””โ”€โ”€ chat.py # Pydantic models +โ”œโ”€โ”€ routes/ +โ”‚ โ””โ”€โ”€ chatAgent.py # FastAPI routes +โ”œโ”€โ”€ services/ +โ”‚ โ”œโ”€โ”€ agent_core.py # Main agent logic +โ”‚ โ”œโ”€โ”€ agent_tools.py # LangChain tools +โ”‚ โ”œโ”€โ”€ microservice_client.py # Service integration +โ”‚ โ”œโ”€โ”€ rag.py # RAG implementation +โ”‚ โ”œโ”€โ”€ vector.py # Pinecone integration +โ”‚ โ””โ”€โ”€ embedding.py # Embedding service +โ”œโ”€โ”€ Dockerfile # Container definition +โ”œโ”€โ”€ requirements.txt # Python dependencies +โ”œโ”€โ”€ main.py # Application entry point +โ””โ”€โ”€ README.md # Service documentation +``` + +## Links +- **Repository**: https://github.com/TechTorque-2025/Agent_Bot +- **Container Registry**: ghcr.io/techtorque-2025/agent_bot +- **K8s Config**: https://github.com/TechTorque-2025/k8s-config + +## Common Issues + +| Issue | Solution | +|-------|----------| +| ModuleNotFoundError | Run `pip install -r requirements.txt` | +| API key invalid | Check `.env` or K8s secrets | +| Can't reach microservices | Verify API Gateway is running | +| Pinecone errors | Ensure index exists and API key is valid | +| Memory errors | Increase K8s resource limits | +| Slow responses | Check Gemini API rate limits | + +## Dependencies +- FastAPI +- LangChain +- Google Gemini API +- Pinecone +- sentence-transformers +- httpx + +## Notes +- Unlike Java services, this is Python-based +- Uses uvicorn instead of Spring Boot +- Requires external AI services (Gemini, Pinecone) +- No database required (stateless) +- Communicates with other services via API Gateway diff --git a/requirements.txt b/requirements.txt new file mode 100644 index 0000000..f5fda80 --- /dev/null +++ b/requirements.txt @@ -0,0 +1,25 @@ +# Core FastAPI and Web Framework +fastapi==0.109.0 +uvicorn[standard]==0.27.0 +pydantic==2.5.3 +python-dotenv==1.0.0 + +# HTTP Client +httpx==0.26.0 +requests==2.31.0 + +# LangChain and AI/ML +langchain==0.1.6 +langchain-core==0.1.23 +langchain-google-genai==0.0.9 +google-generativeai==0.3.2 + +# Vector Database +pinecone-client==3.0.0 + +# Embeddings +sentence-transformers==2.3.1 +numpy==1.24.3 + +# Logging and utilities +python-multipart==0.0.6