provisioning/docs/src/examples/README.md

# Examples

Real-world infrastructure as code examples demonstrating Provisioning across
multi-cloud, Kubernetes, security, and operational scenarios.

## Overview

This section contains production-ready examples showing how to:

- **Deploy infrastructure** from basic single-cloud to complex multi-cloud environments
- **Orchestrate Kubernetes** clusters with Provisioning automation
- **Implement security** patterns including encryption, secrets management, and compliance
- **Build custom workflows** for specialized infrastructure operations
- **Handle disaster recovery** with backup strategies and failover procedures
- **Optimize costs** through resource analysis and right-sizing
- **Migrate legacy systems** from traditional infrastructure to cloud-native architectures
- **Test infrastructure as code** with validation, policy checks, and integration tests

All examples use Nickel for type-safe configuration and are designed as learning resources and templates for your own deployments.

## Quick Start Examples

### Basic Infrastructure Setup

- **[Basic Setup](./basic-setup.md)** - Single-cloud with networking,
  compute, storage - perfect starting point

- **[E-Commerce Platform](./real-world-scenario.md)** - Multi-tier
  application across AWS and UpCloud with load balancing, databases

### Multi-Cloud Deployments

- **[Multi-Cloud Deployment](./multi-cloud-deployment.md)** - Deploy across
  AWS, UpCloud, Hetzner with provider abstraction

- **[Kubernetes Deployment](./kubernetes-deployment.md)** - Kubernetes
  clusters, workloads, networking, operators via Nickel

- **[Machine Learning Infrastructure](./machine-learning-infrastructure.md)**
  - Training clusters, GPU resources, features, inference services

- **[Hybrid Cloud Setup](./hybrid-cloud-deployment.md)** - Hub-and-spoke
  architecture connecting on-premise and cloud

### Operational Examples

- **[Disaster Recovery Drills](./disaster-recovery-drills.md)** - Database failover, complete infrastructure failover, backup recovery testing procedures.

- **[FinOps Cost Governance](./finops-cost-governance.md)** - Budget frameworks, cost monitoring, chargeback models, and cost optimization strategies.

- **[Legacy System Migration](./legacy-system-migration.md)** - Zero-downtime migration with
  gradual traffic cutover (5% → 100%).

### Advanced Patterns

- **[Batch Workflow Orchestration](./advanced-workflow-orchestration.md)** - DAG scheduling,
  parallel execution, conditional logic, error handling.

- **[Advanced Networking](./advanced-networking.md)** - Load balancing, service mesh,
  DNS management, zero-trust architecture.

- **[GitOps Infrastructure Deployment](./gitops-infrastructure-deployment.md)** -
  GitHub Actions, automated reconciliation, drift detection, audit trails.

- **[Secrets Rotation Strategy](./secrets-rotation-strategy.md)** - Passwords, API keys,
  certificates with zero-downtime rotation.

### Security and Compliance

- **[Compliance and Audit](./compliance-and-audit-example.md)** - SOC2, GDPR, HIPAA,
  PCI-DSS compliance with audit logging.

- **[Security Examples](./security-examples.md)** - Encryption, authentication, MFA,
  secrets management, and audit patterns.

- **[Infrastructure as Code Testing](./iac-testing-strategies.md)** - Syntax validation,
  schema checks, policy compliance, unit and integration tests.

### Cloud Provider Specific

- **[AWS Deployment Guide](./aws-deployment-examples.md)** - EC2, RDS, S3, VPC, Load Balancers, IAM with cost optimization.

- **[UpCloud Deployment Guide](./upcloud-deployment-examples.md)** - Compute, Storage, Networking, Backups with managed services.

- **[Hetzner Deployment Guide](./hetzner-deployment-examples.md)** - Dedicated servers, cloud infrastructure, networking with cost efficiency.

- **[Kubernetes Examples](./kubernetes-examples.md)** - Deployments, StatefulSets, DaemonSets, Jobs, Custom Resources, Operators.

### Configuration and Migration

- **[Terraform to Nickel Migration](./terraform-migration.md)** - Convert existing Terraform HCL to Nickel type-safe configuration with validation examples.

- **[KCL to Nickel Migration](./kcl-to-nickel-migration.md)** - Upgrade from deprecated KCL to Nickel with schema examples and best practices.

## Example Organization

Each example follows this structure:

```text
example-name.md
├── Overview - What this example demonstrates
├── Prerequisites - Required setup
├── Architecture Diagram - Visual representation
├── Nickel Configuration - Complete, runnable configuration
├── Deployment Steps - Command-by-command instructions
├── Verification - How to validate deployment
├── Troubleshooting - Common issues and solutions
└── Next Steps - How to extend or customize
```

## Learning Paths

### I'm new to Provisioning
1. Start with [Basic Setup](./basic-setup.md)
2. Read [Real-World Scenario](./real-world-scenario.md)
3. Try [Kubernetes Deployment](./kubernetes-deployment.md)

### I need multi-cloud infrastructure
1. Review [Multi-Cloud Deployment](./multi-cloud-deployment.md)
2. Study [Hybrid Cloud Setup](./hybrid-cloud-deployment.md)
3. Implement [Advanced Networking](./advanced-networking.md)

### I need to migrate existing infrastructure
1. Start with [Legacy System Migration](./legacy-system-migration.md)
2. Add [Terraform Migration](./terraform-migration.md) if applicable
3. Set up [GitOps Deployment](./gitops-infrastructure-deployment.md)

### I need enterprise features
1. Implement [Compliance and Audit](./compliance-and-audit-example.md)
2. Set up [Disaster Recovery](./disaster-recovery-drills.md)
3. Deploy [Cost Governance](./finops-cost-governance.md)
4. Configure [Secrets Rotation](./secrets-rotation-strategy.md)

## Copy and Customize

All examples are self-contained and can be:

1. **Copied** into your workspace and adapted
2. **Extended** with additional resources and customizations
3. **Tested** using Provisioning's validation framework
4. **Deployed** directly via `provisioning apply`

Use them as templates, learning resources, or reference implementations for your own infrastructure.

## Related Documentation

- **Configuration Guide** → See `provisioning/docs/src/infrastructure/nickel-guide.md`
- **API Reference** → See `provisioning/docs/src/api-reference/`
- **Development** → See `provisioning/docs/src/development/`
- **Operations** → See `provisioning/docs/src/operations/`