provisioning/docs/src/user/getting-started.md

# Getting Started Guide

Welcome to Infrastructure Automation! This guide will walk you through your first steps with infrastructure automation, from basic setup to deploying your first infrastructure.

## What You'll Learn

- Essential concepts and terminology
- How to configure your first environment
- Creating and managing infrastructure
- Basic server and service management
- Common workflows and best practices

## Prerequisites

Before starting this guide, ensure you have:

- ✅ Completed the [Installation Guide](installation-guide.md)
- ✅ Verified your installation with `provisioning --version`
- ✅ Basic familiarity with command-line interfaces

## Essential Concepts

### Infrastructure as Code (IaC)

Provisioning uses **declarative configuration** to manage infrastructure. Instead of manually creating resources, you define what you want in configuration files, and the system makes it happen.

```
You describe → System creates → Infrastructure exists
```

### Key Components

| Component | Purpose | Example |
|-----------|---------|---------|
| **Providers** | Cloud platforms | AWS, UpCloud, Local |
| **Servers** | Virtual machines | Web servers, databases |
| **Task Services** | Infrastructure software | Kubernetes, Docker, databases |
| **Clusters** | Grouped services | Web cluster, database cluster |

### Configuration Languages

- **KCL**: Main configuration language for infrastructure definitions
- **TOML**: User preferences and system settings
- **YAML**: Kubernetes manifests and service definitions

## First-Time Setup

### Step 1: Initialize Your Configuration

Create your personal configuration:

```bash
# Initialize user configuration
provisioning init config

# This creates ~/.provisioning/config.user.toml
```

### Step 2: Verify Your Environment

```bash
# Check your environment setup
provisioning env

# View comprehensive configuration
provisioning allenv
```

You should see output like:
```
✅ Configuration loaded successfully
✅ All required tools available
📁 Base path: /usr/local/provisioning
🏠 User config: ~/.provisioning/config.user.toml
```

### Step 3: Explore Available Resources

```bash
# List available providers
provisioning list providers

# List available task services
provisioning list taskservs

# List available clusters
provisioning list clusters
```

## Your First Infrastructure

Let's create a simple local infrastructure to learn the basics.

### Step 1: Create a Workspace

```bash
# Create a new workspace directory
mkdir ~/my-first-infrastructure
cd ~/my-first-infrastructure

# Initialize workspace
provisioning generate infra --new local-demo
```

This creates:
```
local-demo/
├── settings.k          # Main infrastructure definition
├── kcl.mod            # KCL module configuration
└── keys.yaml          # Key management (if needed)
```

### Step 2: Examine the Configuration

```bash
# View the generated configuration
provisioning show settings --infra local-demo
```

### Step 3: Validate the Configuration

```bash
# Validate syntax and structure
provisioning validate config --infra local-demo

# Should show: ✅ Configuration validation passed!
```

### Step 4: Deploy Infrastructure (Check Mode)

```bash
# Dry run - see what would be created
provisioning server create --infra local-demo --check

# This shows planned changes without making them
```

### Step 5: Create Your Infrastructure

```bash
# Create the actual infrastructure
provisioning server create --infra local-demo

# Wait for completion
provisioning server list --infra local-demo
```

## Working with Services

### Installing Your First Service

Let's install a containerized service:

```bash
# Install Docker/containerd
provisioning taskserv create containerd --infra local-demo

# Verify installation
provisioning taskserv list --infra local-demo
```

### Installing Kubernetes

For container orchestration:

```bash
# Install Kubernetes
provisioning taskserv create kubernetes --infra local-demo

# This may take several minutes...
```

### Checking Service Status

```bash
# Show all services on your infrastructure
provisioning show servers --infra local-demo

# Show specific service details
provisioning show servers web-01 taskserv kubernetes --infra local-demo
```

## Understanding Commands

### Command Structure

All commands follow this pattern:
```bash
provisioning [global-options] <command> [command-options] [arguments]
```

### Global Options

| Option | Short | Description |
|--------|-------|-------------|
| `--infra` | `-i` | Specify infrastructure |
| `--check` | `-c` | Dry run mode |
| `--debug` | `-x` | Enable debug output |
| `--yes` | `-y` | Auto-confirm actions |

### Essential Commands

| Command | Purpose | Example |
|---------|---------|---------|
| `help` | Show help | `provisioning help` |
| `env` | Show environment | `provisioning env` |
| `list` | List resources | `provisioning list servers` |
| `show` | Show details | `provisioning show settings` |
| `validate` | Validate config | `provisioning validate config` |

## Working with Multiple Environments

### Environment Concepts

The system supports multiple environments:
- **dev** - Development and testing
- **test** - Integration testing
- **prod** - Production deployment

### Switching Environments

```bash
# Set environment for this session
export PROVISIONING_ENV=dev
provisioning env

# Or specify per command
provisioning --environment dev server create
```

### Environment-Specific Configuration

Create environment configs:

```bash
# Development environment
provisioning init config dev

# Production environment
provisioning init config prod
```

## Common Workflows

### Workflow 1: Development Environment

```bash
# 1. Create development workspace
mkdir ~/dev-environment
cd ~/dev-environment

# 2. Generate infrastructure
provisioning generate infra --new dev-setup

# 3. Customize for development
# Edit settings.k to add development tools

# 4. Deploy
provisioning server create --infra dev-setup --check
provisioning server create --infra dev-setup

# 5. Install development services
provisioning taskserv create kubernetes --infra dev-setup
provisioning taskserv create containerd --infra dev-setup
```

### Workflow 2: Service Updates

```bash
# Check for service updates
provisioning taskserv check-updates

# Update specific service
provisioning taskserv update kubernetes --infra dev-setup

# Verify update
provisioning taskserv versions kubernetes
```

### Workflow 3: Infrastructure Scaling

```bash
# Add servers to existing infrastructure
# Edit settings.k to add more servers

# Apply changes
provisioning server create --infra dev-setup

# Install services on new servers
provisioning taskserv create containerd --infra dev-setup
```

## Interactive Mode

### Starting Interactive Shell

```bash
# Start Nushell with provisioning loaded
provisioning nu
```

In the interactive shell, you have access to all provisioning functions:

```nushell
# Inside Nushell session
use lib_provisioning *

# Check environment
show_env

# List available functions
help commands | where name =~ "provision"
```

### Useful Interactive Commands

```nushell
# Show detailed server information
find_servers "web-*" | table

# Get cost estimates
servers_walk_by_costs $settings "" false false "stdout"

# Check task service status
taskservs_list | where status == "running"
```

## Configuration Management

### Understanding Configuration Files

1. **System Defaults**: `config.defaults.toml` - System-wide defaults
2. **User Config**: `~/.provisioning/config.user.toml` - Your preferences
3. **Environment Config**: `config.{env}.toml` - Environment-specific settings
4. **Infrastructure Config**: `settings.k` - Infrastructure definitions

### Configuration Hierarchy

```
Infrastructure settings.k
    ↓ (overrides)
Environment config.{env}.toml
    ↓ (overrides)
User config.user.toml
    ↓ (overrides)
System config.defaults.toml
```

### Customizing Your Configuration

```bash
# Edit user configuration
provisioning sops ~/.provisioning/config.user.toml

# Or using your preferred editor
nano ~/.provisioning/config.user.toml
```

Example customizations:

```toml
[debug]
enabled = true        # Enable debug mode by default
log_level = "debug"   # Verbose logging

[providers]
default = "aws"       # Use AWS as default provider

[output]
format = "json"       # Prefer JSON output
```

## Monitoring and Observability

### Checking System Status

```bash
# Overall system health
provisioning env

# Infrastructure status
provisioning show servers --infra dev-setup

# Service status
provisioning taskserv list --infra dev-setup
```

### Logging and Debugging

```bash
# Enable debug mode for troubleshooting
provisioning --debug server create --infra dev-setup --check

# View logs for specific operations
provisioning show logs --infra dev-setup
```

### Cost Monitoring

```bash
# Show cost estimates
provisioning show cost --infra dev-setup

# Detailed cost breakdown
provisioning server price --infra dev-setup
```

## Best Practices

### 1. Configuration Management

- ✅ Use version control for infrastructure definitions
- ✅ Test changes in development before production
- ✅ Use `--check` mode to preview changes
- ✅ Keep user configuration separate from infrastructure

### 2. Security

- ✅ Use SOPS for encrypting sensitive data
- ✅ Regular key rotation for cloud providers
- ✅ Principle of least privilege for access
- ✅ Audit infrastructure changes

### 3. Operational Excellence

- ✅ Monitor infrastructure costs regularly
- ✅ Keep services updated
- ✅ Document custom configurations
- ✅ Plan for disaster recovery

### 4. Development Workflow

```bash
# 1. Always validate before applying
provisioning validate config --infra my-infra

# 2. Use check mode first
provisioning server create --infra my-infra --check

# 3. Apply changes incrementally
provisioning server create --infra my-infra

# 4. Verify results
provisioning show servers --infra my-infra
```

## Getting Help

### Built-in Help System

```bash
# General help
provisioning help

# Command-specific help
provisioning server help
provisioning taskserv help
provisioning cluster help

# Show available options
provisioning generate help
```

### Command Reference

For complete command documentation, see: [CLI Reference](cli-reference.md)

### Troubleshooting

If you encounter issues, see: [Troubleshooting Guide](troubleshooting-guide.md)

## Real-World Example

Let's walk through a complete example of setting up a web application infrastructure:

### Step 1: Plan Your Infrastructure

```bash
# Create project workspace
mkdir ~/webapp-infrastructure
cd ~/webapp-infrastructure

# Generate base infrastructure
provisioning generate infra --new webapp
```

### Step 2: Customize Configuration

Edit `webapp/settings.k` to define:
- 2 web servers for load balancing
- 1 database server
- Load balancer configuration

### Step 3: Deploy Base Infrastructure

```bash
# Validate configuration
provisioning validate config --infra webapp

# Preview deployment
provisioning server create --infra webapp --check

# Deploy servers
provisioning server create --infra webapp
```

### Step 4: Install Services

```bash
# Install container runtime on all servers
provisioning taskserv create containerd --infra webapp

# Install load balancer on web servers
provisioning taskserv create haproxy --infra webapp

# Install database on database server
provisioning taskserv create postgresql --infra webapp
```

### Step 5: Deploy Application

```bash
# Create application cluster
provisioning cluster create webapp --infra webapp

# Verify deployment
provisioning show servers --infra webapp
provisioning cluster list --infra webapp
```

## Next Steps

Now that you understand the basics:

1. **Set up your workspace**: [Workspace Setup Guide](workspace-setup.md)
2. **Learn about infrastructure management**: [Infrastructure Management Guide](infrastructure-management.md)
3. **Understand configuration**: [Configuration Guide](configuration.md)
4. **Explore examples**: [Examples and Tutorials](examples/)

You're ready to start building and managing cloud infrastructure with confidence!