Skip to main content

o8 doctor

Diagnose Orchestr8 environment and prerequisites with comprehensive system checks.

Synopsis​

o8 doctor [OPTIONS]

Description​

The doctor command performs comprehensive environment diagnostics to ensure your system is ready for Orchestr8 deployment. It checks:

  • CLI Tools - Required and optional command-line tools
  • Kubernetes - Cluster connectivity and access
  • Docker - Container runtime status (for local development)
  • Cloud Providers - Authentication status for AWS, GCP, Azure
  • Orchestr8 Configuration - Platform configuration files

This is the most thorough diagnostic command and should be your first step when troubleshooting issues.

Options​

OptionShortDescriptionDefault
--verbose-vShow detailed information and versionsfalse
--fixShow installation instructions for missing toolsfalse

Prerequisites​

None - the doctor command is designed to check prerequisites and will work even with minimal system setup.

Examples​

Basic Diagnostics​

# Quick environment check
o8 doctor

Detailed Information​

# Verbose output with versions and details  
o8 doctor --verbose

Get Fix Instructions​

# Show how to install missing tools
o8 doctor --fix

Output Sections​

CLI Tools Status​

CLI Tools
┏━━━━━━━━━━━━┳━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Tool       ┃ Status      ┃ Version                                  ┃ Purpose                   ┃
┡━━━━━━━━━━━━╇━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ ✅ kubectl │ Installed   │ v1.28.2                                  │ Kubernetes management     │
│ ✅ helm    │ Installed   │ v3.12.3                                  │ Package management        │  
│ ✅ git     │ Installed   │ git version 2.42.0                      │ Version control           │
│ ✅ docker  │ Installed   │ Docker version 24.0.6                   │ Container runtime (local) │
│ ⚠️ terraform│ Not found   │ -                                       │ Infrastructure provision   │
│ ✅ gcloud  │ Installed   │ Google Cloud SDK 445.0.0                │ GCP management            │
│ ❌ aws     │ Missing     │ -                                       │ AWS management            │
└────────────┴─────────────┴──────────────────────────────────────────┴───────────────────────────┘

Kubernetes Status​

Kubernetes Status
✅ Connected to cluster: docker-desktop
   Kubernetes master is running at https://kubernetes.docker.internal:6443

Docker Status​

Docker Status
✅ Docker is running
   Kubernetes support detected

Cloud Provider Authentication​

Cloud Provider Authentication
✅ GCP: Authenticated as user@example.com
⚠️ AWS: Not authenticated (run: aws configure)
⚠️ AWS: AWS CLI not installed

Orchestr8 Configuration​

Orchestr8 Configuration
✅ Configuration directory exists: ~/.orchestr8
   Config files: 2 found
   Terraform state: 1 workspace found

Example Commands (with --fix)​

Next Steps
1. Local development:    o8 setup --provider local
2. GCP with infra:      o8 setup --provider gcp --provision-infrastructure --gcp-project-id PROJECT

Missing Tools Installation:
AWS CLI:
  macOS: brew install awscli  
  Ubuntu: sudo apt-get install awscli
  Windows: choco install awscli

Tool Categories​

Required Tools ✅❌​

These tools are required for all Orchestr8 deployments:

  • kubectl - Kubernetes cluster management
  • helm - Package management for Kubernetes
  • git - Version control for GitOps workflows

Optional Tools ⚠️​

These tools are optional but required for specific providers or features:

  • docker - Local development (kind, minikube, Docker Desktop)
  • terraform - Infrastructure provisioning (GCP only currently)
  • gcloud - Google Cloud Platform management
  • aws - Amazon Web Services management
  • az - Microsoft Azure management

Detailed Checks Performed​

CLI Tools​

  • Checks if command is available in PATH
  • Attempts to get version information
  • Validates tool functionality with simple commands

Kubernetes​

  • Tests kubectl config current-context
  • Validates cluster connectivity with kubectl cluster-info
  • Checks if cluster is accessible

Docker​

  • Verifies Docker daemon is running
  • Checks Docker version and functionality
  • Detects Kubernetes support (Docker Desktop)

Cloud Authentication​

  • GCP: Runs gcloud auth list to check active accounts
  • AWS: Runs aws sts get-caller-identity to verify credentials
  • Azure: Runs az account show to check subscription access

Orchestr8 Configuration​

  • Checks for ~/.orchestr8/ directory
  • Lists configuration files
  • Counts Terraform workspaces
  • Validates configuration file formats

Exit Codes​

CodeDescription
0All checks passed or completed
1Critical tools missing (kubectl, helm, git)

Verbose Mode Details​

With --verbose, the doctor shows additional information:

  • Full version strings for all tools
  • Cluster information including master URL and versions
  • Docker details like total containers and images
  • Cloud account details including project IDs and regions
  • Configuration file contents (sanitized)

Fix Mode Instructions​

With --fix, the doctor provides platform-specific installation commands:

Package Manager Commands​

# macOS (Homebrew)
brew install kubectl helm terraform

# Ubuntu/Debian  
sudo apt-get install kubectl helm

# Windows (Chocolatey)  
choco install kubernetes-cli kubernetes-helm terraform

# CentOS/RHEL/Fedora
sudo yum install kubectl helm
  • Direct download URLs for each tool
  • Platform-specific installation guides
  • Environment setup instructions

Use Cases​

Pre-Setup Validation​

# Before running setup, ensure environment is ready
o8 doctor --fix
# Install missing tools
o8 setup --provider gcp

Troubleshooting​

# When something isn't working
o8 doctor --verbose

# Get specific error details
kubectl config current-context
gcloud auth list

CI/CD Pipeline Validation​

# In deployment scripts
#!/bin/bash
if ! o8 doctor; then
    echo "Environment not ready"
    exit 1
fi

o8 setup --non-interactive --provider gcp

Regular Health Checks​

# Scheduled system validation
o8 doctor --verbose > system-check-$(date +%Y%m%d).log

Common Issues and Solutions​

kubectl Not Found​

# Install kubectl
curl -LO "https://dl.k8s.io/release/$(curl -L -s https://dl.k8s.io/release/stable.txt)/bin/linux/amd64/kubectl"
chmod +x kubectl
sudo mv kubectl /usr/local/bin/

Docker Not Running​

# Start Docker service (Linux)
sudo systemctl start docker

# Start Docker Desktop (Windows/macOS)
# Open Docker Desktop application

Cloud Authentication Issues​

# GCP authentication
gcloud auth login
gcloud auth application-default login

# AWS authentication  
aws configure

# Azure authentication
az login

Kubernetes Connection Issues​

# Check kubectl configuration
kubectl config view
kubectl config current-context

# Switch context if needed
kubectl config use-context my-cluster
  • o8 validate - Lightweight prerequisite check
  • o8 status - Platform deployment status
  • o8 setup - Platform deployment (run after doctor passes)