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
• ✅ 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:

# Initialize user configuration
provisioning init config

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

Step 2: Verify Your Environment

# 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

# 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

# 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

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

Step 3: Validate the Configuration

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

# Should show: ✅ Configuration validation passed!

Step 4: Deploy Infrastructure (Check Mode)

# 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

# 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:

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

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

Installing Kubernetes

For container orchestration:

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

# This may take several minutes...

Checking Service Status

# 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:

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

# 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:

# Development environment
provisioning init config dev

# Production environment
provisioning init config prod

Common Workflows

Workflow 1: Development Environment

# 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

# 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

# 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

# Start Nushell with provisioning loaded
provisioning nu

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

# Inside Nushell session
use lib_provisioning *

# Check environment
show_env

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

Useful Interactive Commands

# 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

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

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

Example customizations:

[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

# Overall system health
provisioning env

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

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

Logging and Debugging

# 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

# 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

# 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

# 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

Troubleshooting

If you encounter issues, see: Troubleshooting Guide

Real-World Example

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

Step 1: Plan Your Infrastructure

# 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

# 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

# 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

# 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
2. Learn about infrastructure management: Infrastructure Management Guide
3. Understand configuration: Configuration Guide
4. Explore examples: Examples and Tutorials

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