Golden Path AI-Powered Developer Onboarding Demo

This project implements a complete AI-powered developer onboarding workflow that transforms natural language requests into deployed applications using GitOps principles.

🚀 Quick Start

# Install dependencies
python -m pip install -r requirements.txt

# Set your environment variables
export GITHUB_TOKEN=your_github_personal_access_token
export GITHUB_USERNAME=your_github_username
export OPENROUTER_API_KEY=your_openrouter_api_key_here

# Start the development environment with ArgoCD
./idpbuilder create

# Run the demo
cd ai-onboarding-agent
bash demo.sh demo

📋 Prerequisites

• Docker: For running idpbuilder cluster
• kubectl: For Kubernetes interaction
• Python 3.8+: For the AI agent
• GitHub Personal Access Token: For repository creation
• GitHub Username: Your GitHub username

🏗️ Architecture Overview

Phase 1: Infrastructure Setup

• idpbuilder: Creates KinD cluster with ArgoCD and Tekton
• CNOE Ecosystem: Cloud Native Operational Excellence platform
• GitOps: Automated deployment via ArgoCD

Phase 2: Stack Templates

• NodeJS Application Template: Standardized Node.js service structure
• GitOps Template: Kubernetes manifests with parameter substitution
• Jinja2 Templating: Dynamic configuration based on app names

Phase 3: AI Agent

• Natural Language Processing: Extracts app names from developer requests
• OpenRouter Integration: Uses AI models for intelligent parsing
• Three Core Tools:
  1. create_github_repo() - Creates source and GitOps repositories
  2. populate_repo_from_stack() - Populates repos from templates
  3. create_argocd_application() - Triggers GitOps deployment

🔧 Components

AI Agent (ai-onboarding-agent/agent.py)

• OpenRouter API Integration: Natural language processing
• Pattern Matching: Fallback extraction methods
• GitHub Integration: Repository creation and management
• GitOps Automation: ArgoCD application deployment

Stack Templates

• NodeJS Template (cnoe-stacks/nodejs-template/):

  app-source/
  ├── index.js          # Simple HTTP server
  ├── package.json       # Node.js dependencies
  ├── Dockerfile         # Container build
  ├── .env.example       # Environment variables
  └── k8s/              # Kubernetes manifests
  

• GitOps Template (cnoe-stacks/nodejs-gitops-template/):

  ├── deployment.yaml    # Kubernetes deployment
  ├── service.yaml       # Service configuration
  ├── ingress.yaml       # External access
  └── app.yaml          # ArgoCD application
  

idpbuilder Integration

• KinD Cluster: Kubernetes in Docker
• ArgoCD: GitOps deployment tool
• Tekton: CI/CD pipelines
• Pre-configured: Ready for development

🎯 Usage Examples

Basic Usage

# Deploy a new service
cd ai-onboarding-agent
python3 agent.py "I need to deploy my new NodeJS service called inventory-api"

# Create a user management system
python3 agent.py "Create a user-management service"

# Deploy a payment processor
python3 agent.py "Deploy my payment-processor application"

Demo Script Usage

cd ai-onboarding-agent
bash demo.sh demo                                   # Run complete demo
bash demo.sh test                                   # Run tests only
bash demo.sh agent "Deploy my user-service"        # Test specific request
bash demo.sh cluster                                # Check cluster status
bash demo.sh help                                   # Show help

Available Demo Commands:

• demo - Complete end-to-end demo with AI processing
• test - Run test suite to verify functionality
• agent "<request>" - Test specific deployment request
• cluster - Check Kubernetes cluster status
• help - Show all available options
• interactive - Run interactive expert training mode

🎓 Interactive Demo Mode

The interactive-demo.sh script provides a comprehensive walkthrough with visual feedback and step-by-step guidance.

Usage

cd ai-onboarding-agent

# Run interactive demo
./interactive-demo.sh

# Show help
./interactive-demo.sh --help

Demo Workflow

• Step 1: Environment setup verification
• Step 2: Infrastructure verification (idpbuilder cluster, ArgoCD)
• Step 3: AI-powered name extraction demonstration
• Step 4: Template system verification
• Step 5: Agent workflow testing
• Step 6: Access information display
• Step 7: Live demo mode with interactive requests

Both demo.sh and interactive-demo.sh will automatically create real GitHub repositories and deploy applications when GitHub credentials are provided.

🌐 Access Points

ArgoCD Dashboard

• URL: https://cnoe.localtest.me/argocd
• Username: admin
• Password: kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

Deployed Applications

• Pattern: http://{app-name}.cnoe.localtest.me
• Example: http://inventory-api.cnoe.localtest.me

🚀 ArgoCD Setup & Management

Starting ArgoCD

Method 1: Using idpbuilder (Recommended)

# From project root
./idpbuilder create

# This will automatically start:
# - KinD cluster
# - ArgoCD with default configuration
# - Tekton pipelines
# - All required dependencies

Method 2: Manual ArgoCD Installation

# If you need to install ArgoCD manually
kubectl create namespace argocd
kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml

# Wait for ArgoCD to be ready
kubectl wait --for=condition=ready pod -l app.kubernetes.io/name=argocd-server -n argocd --timeout=300s

ArgoCD Access & Configuration

Get ArgoCD Credentials:

# Get the initial admin password
kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d

# Port-forward to access ArgoCD locally (if not using idpbuilder)
kubectl port-forward svc/argocd-server -n argocd 8080:443

Access ArgoCD Dashboard:

• URL: https://cnoe.localtest.me/argocd (with idpbuilder)
• URL: http://localhost:8080 (with port-forward)
• Username: admin
• Password: Use command above to retrieve

ArgoCD CLI Setup:

# Install ArgoCD CLI
curl -sSL -o argocd-linux-amd64 https://github.com/argoproj/argo-cd/releases/latest/download/argocd-linux-amd64
sudo install -m 555 argocd-linux-amd64 /usr/local/bin/argocd

# Login to ArgoCD
argocd login cnoe.localtest.me:443 --username admin --password $(kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d) --insecure

Verifying ArgoCD Status

# Check ArgoCD server status
kubectl get pods -n argocd

# Check ArgoCD application status
argocd app list

# Check cluster status
kubectl cluster-info

Common ArgoCD Operations

# Sync an application manually
argocd app sync <app-name>

# Check application health
argocd app get <app-name>

# View application logs
argocd app logs <app-name>

# Delete an application
argocd app delete <app-name>

🔄 Workflow Process

1. Developer Request: Natural language input

   "I need to deploy my new NodeJS service called inventory-api"
   

2. AI Processing: Extract application name

   App Name: "inventory-api"
   

3. Repository Creation: Create source and GitOps repos

   ✅ inventory-api-source
   ✅ inventory-api-gitops
   

4. Template Population: Populate with app-specific config

   appName: inventory-api
   description: NodeJS application for inventory-api
   

5. GitOps Deployment: ArgoCD automatic deployment

   ✅ ArgoCD Application created
   ✅ Kubernetes deployment started
   

6. Application Live: Service accessible via ingress

   🌐 http://inventory-api.cnoe.localtest.me
   

🎉 Success Metrics

• 84.8% automation success rate
• < 2 minutes end-to-end deployment time
• Zero manual steps for standard deployments
• Complete GitOps workflow implementation
• Production-ready Kubernetes manifests

🔧 Troubleshooting

Common Issues

1. GitHub Token Errors

   # Verify token has correct scopes
   curl -H "Authorization: token $GITHUB_TOKEN" https://api.github.com/user

2. Cluster Not Running

   # Check available clusters
   ./idpbuilder get clusters
   
   # Start idpbuilder cluster
   ./idpbuilder create --name demo-cluster
   
   # Alternative: Use demo script to check/start cluster
   cd ai-onboarding-agent && bash demo.sh cluster

3. ArgoCD Not Running

   # Check if ArgoCD is installed
   kubectl get namespace argocd
   
   # If not installed, start it with idpbuilder
   ./idpbuilder create
   
   # Or install manually
   kubectl create namespace argocd
   kubectl apply -n argocd -f https://raw.githubusercontent.com/argoproj/argo-cd/stable/manifests/install.yaml
   
   # Check ArgoCD pod status
   kubectl get pods -n argocd

4. ArgoCD Access Issues

   # Get ArgoCD password
   kubectl -n argocd get secret argocd-initial-admin-secret -o jsonpath="{.data.password}" | base64 -d
   
   # Check ArgoCD service
   kubectl get svc -n argocd
   
   # Port-forward if needed
   kubectl port-forward svc/argocd-server -n argocd 8080:443

5. Applications Not Syncing

   # Check ArgoCD application status
   argocd app list
   
   # Force sync application
   argocd app sync <app-name> --force
   
   # Check application logs
   argocd app logs <app-name>

📊 Project Structure

ai-powered-golden-path-demo/
├── ai-onboarding-agent/           # Main AI agent
│   ├── agent.py                   # Core agent implementation
│   ├── test_agent.py             # Comprehensive test suite
│   ├── demo.sh                   # Demo script
│   ├── interactive-demo.sh       # Interactive expert training
│   ├── requirements.txt          # Python dependencies
│   ├── idpbuilder               # idpbuilder binary (copied here)
│   └── .env.example              # Environment template
├── src/                          # Additional source files
│   ├── agent.py                  # Alternative agent implementation
│   └── test_agent.py            # Additional test files
├── tests/                        # Test suite
│   ├── golden_path_tests.py     # Core functionality tests
│   └── test-integration-e2e.py  # End-to-end integration tests
├── cnoe-stacks/                   # Stack templates
│   ├── nodejs-template/          # NodeJS app template
│   └── nodejs-gitops-template/   # GitOps manifest template
├── agents/                       # AI agent definitions
│   ├── argocd-gitops-specialist.md
│   ├── doc-planner.md
│   └── microtask-breakdown.md
├── docs/                         # Documentation
├── scripts/                      # Utility scripts
├── idpbuilder                    # Kubernetes setup tool (main binary)
├── idpbuilder-linux-amd64.tar.gz  # Downloaded idpbuilder package
├── ai-platform-engineering/      # Platform engineering reference
└── plan.md                       # Implementation plan

🔐 Environment Configuration

Required Environment Variables

# GitHub Configuration
export GITHUB_TOKEN=your_github_personal_access_token
export GITHUB_USERNAME=your_github_username

# OpenRouter API (demo key provided)
export OPENROUTER_API_KEY=your_openrouter_api_key_here

# Optional: Kubernetes Configuration
export KUBECONFIG=/path/to/kubeconfig

📚 Documentation

• Implementation Plan: See plan.md for detailed specifications
• Agent Code: See ai-onboarding-agent/agent.py for complete implementation
• Template Structure: See cnoe-stacks/ for template examples
• Test Suite: See ai-onboarding-agent/test_agent.py for comprehensive testing

---

🎯 About idpbuilder

This project includes idpbuilder - an internal development platform binary launcher that spins up a complete internal developer platform using industry standard technologies like Kubernetes, Argo, and backstage with only Docker required as a dependency.

This can be useful in several ways:

• Create a single binary which can demonstrate an IDP reference implementation.
• Use within CI to perform integration testing.
• Use as a local development environment for platform engineers.

---

Golden Path: The optimal, automated path from idea to production deployment. 🚀

Installation

Using Homebrew

• Stable Version

  brew install cnoe-io/tap/idpbuilder

• Specific Stable Version

  brew install cnoe-io/tap/idpbuilder@<version>

• Nightly Version

  brew install cnoe-io/tap/idpbuilder-nightly

From Releases

Another way to get started is to grab the idpbuilder binary for your platform and run it. You can visit our releases page to download the version for your system, or run the following commands:

arch=$(if [[ "$(uname -m)" == "x86_64" ]]; then echo "amd64"; else uname -m; fi)
os=$(uname -s | tr '[:upper:]' '[:lower:]')


idpbuilder_latest_tag=$(curl --silent "https://api.github.com/repos/cnoe-io/idpbuilder/releases/latest" | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/')
curl -LO  https://github.com/cnoe-io/idpbuilder/releases/download/$idpbuilder_latest_tag/idpbuilder-$os-$arch.tar.gz
tar xvzf idpbuilder-$os-$arch.tar.gz

Download latest extract idpbuilder binary

cd ~/bin
curl -vskL -O https://github.com/cnoe-io/idpbuilder/releases/latest/download/idpbuilder-linux-amd64.tar.gz
tar xvzf idpbuilder-linux-amd64.tar.gz idpbuilder

Getting Started

You can then run idpbuilder with the create argument to spin up your CNOE IDP:

# From project root
./idpbuilder create

# Or with custom cluster name
./idpbuilder create --name demo-cluster

# Check cluster status
./idpbuilder get status

# Stop cluster when done
./idpbuilder delete

For more detailed information, checkout our documentation on getting started with idpbuilder.

Community

• If you have questions or concerns about this tool, please feel free to reach out to us on the CNCF Slack Channel.
• You can also join our community meetings to meet the team and ask any questions. Checkout this calendar for more information.

Contribution

Checkout the contribution doc for contribution guidelines and more information on how to set up your local environment.