ai-playbook 1.0.0

package/roles/devops/examples.md

@@ -0,0 +1,775 @@
+# Examples
+
+This document provides concrete examples of DevOps work, architecture patterns, and
+implementation approaches that demonstrate the expected quality and approach.
+
+---
+
+## Infrastructure as Code Example
+
+### Example: Terraform Module for AWS VPC with High Availability
+
+**Purpose:** Demonstrates IaC best practices for networking infrastructure.
+
+```hcl
+# modules/networking/vpc/main.tf
+terraform {
+  required_version = ">= 1.0"
+  required_providers {
+    aws = {
+      source  = "hashicorp/aws"
+      version = "~> 5.0"
+    }
+  }
+}
+
+provider "aws" {
+  region = var.aws_region
+}
+
+# VPC with DNS enabled for service discovery
+resource "aws_vpc" "main" {
+  cidr_block           = var.vpc_cidr
+  enable_dns_hostnames = true
+  enable_dns_support   = true
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-vpc"
+  })
+}
+
+# Internet Gateway for public subnets
+resource "aws_internet_gateway" "main" {
+  vpc_id = aws_vpc.main.id
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-igw"
+  })
+}
+
+# Public subnets across multiple availability zones
+resource "aws_subnet" "public" {
+  count                   = length(var.public_subnets)
+  vpc_id                  = aws_vpc.main.id
+  cidr_block              = var.public_subnets[count.index]
+  availability_zone       = data.aws_availability_zones.available.names[count.index]
+  map_public_ip_on_launch = true
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-public-subnet-${count.index + 1}"
+  })
+}
+
+# Private subnets across multiple availability zones
+resource "aws_subnet" "private" {
+  count             = length(var.private_subnets)
+  vpc_id            = aws_vpc.main.id
+  cidr_block        = var.private_subnets[count.index]
+  availability_zone = data.aws_availability_zones.available.names[count.index]
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-private-subnet-${count.index + 1}"
+  })
+}
+
+# NAT Gateway for private subnet egress
+resource "aws_nat_gateway" "main" {
+  count         = length(var.public_subnets)
+  allocation_id = aws_eip.nat[count.index].id
+  subnet_id     = aws_subnet.public[count.index].id
+
+  # NAT Gateway needs Internet Gateway to exist first
+  depends_on = [aws_internet_gateway.main]
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-nat-${count.index + 1}"
+  })
+}
+
+# Elastic IP for NAT Gateway
+resource "aws_eip" "nat" {
+  count  = length(var.public_subnets)
+  domain = "vpc"
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-eip-nat-${count.index + 1}"
+  })
+}
+
+# Route tables for public subnets
+resource "aws_route_table" "public" {
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block      = "0.0.0.0/0"
+    gateway_id      = aws_internet_gateway.main.id
+  }
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-public-rt"
+  })
+}
+
+# Route table associations for public subnets
+resource "aws_route_table_association" "public" {
+  count          = length(aws_subnet.public)
+  subnet_id      = aws_subnet.public[count.index].id
+  route_table_id = aws_route_table.public.id
+}
+
+# Route tables for private subnets (one per AZ for high availability)
+resource "aws_route_table" "private" {
+  count  = length(var.private_subnets)
+  vpc_id = aws_vpc.main.id
+
+  route {
+    cidr_block     = "0.0.0.0/0"
+    nat_gateway_id = aws_nat_gateway.main[count.index].id
+  }
+
+  tags = merge(var.tags, {
+    Name = "${var.environment}-private-rt-${count.index + 1}"
+  })
+}
+
+# Route table associations for private subnets
+resource "aws_route_table_association" "private" {
+  count          = length(aws_subnet.private)
+  subnet_id      = aws_subnet.private[count.index].id
+  route_table_id = aws_route_table.private[count.index].id
+}
+
+# Data source for available AZs
+data "aws_availability_zones" "available" {
+  state = "available"
+}
+```
+
+```hcl
+# modules/networking/vpc/variables.tf
+variable "aws_region" {
+  description = "AWS region for VPC"
+  type        = string
+}
+
+variable "vpc_cidr" {
+  description = "CIDR block for VPC"
+  type        = string
+  default     = "10.0.0.0/16"
+
+  validation {
+    condition     = can(cidrhost(var.vpc_cidr, 0))
+    error_message = "vpc_cidr must be a valid CIDR block."
+  }
+}
+
+variable "public_subnets" {
+  description = "CIDR blocks for public subnets (one per AZ)"
+  type        = list(string)
+  default     = ["10.0.1.0/24", "10.0.2.0/24", "10.0.3.0/24"]
+
+  validation {
+    condition     = length(var.public_subnets) >= 2
+    error_message = "At least 2 public subnets required for high availability."
+  }
+}
+
+variable "private_subnets" {
+  description = "CIDR blocks for private subnets (one per AZ)"
+  type        = list(string)
+  default     = ["10.0.11.0/24", "10.0.12.0/24", "10.0.13.0/24"]
+
+  validation {
+    condition     = length(var.private_subnets) >= 2
+    error_message = "At least 2 private subnets required for high availability."
+  }
+}
+
+variable "environment" {
+  description = "Environment name (dev, staging, prod)"
+  type        = string
+  default     = "dev"
+}
+
+variable "tags" {
+  description = "Common tags to apply to all resources"
+  type        = map(string)
+  default     = {}
+}
+```
+
+```hcl
+# modules/networking/vpc/outputs.tf
+output "vpc_id" {
+  description = "VPC ID"
+  value       = aws_vpc.main.id
+}
+
+output "public_subnet_ids" {
+  description = "Public subnet IDs"
+  value       = aws_subnet.public[*].id
+}
+
+output "private_subnet_ids" {
+  description = "Private subnet IDs"
+  value       = aws_subnet.private[*].id
+}
+
+output "nat_gateway_ips" {
+  description = "NAT Gateway Elastic IPs"
+  value       = aws_eip.nat[*].public_ip
+}
+```
+
+**Key Patterns Demonstrated:**
+- Modular design for reusability
+- High availability across multiple AZs
+- Clear variable naming and documentation
+- Input validation for correctness
+- Resource tagging for cost tracking and management
+- Proper dependency management
+- Security-first (private subnets, NAT gateways)
+
+---
+
+## Kubernetes Deployment Example
+
+### Example: Helm Chart for Stateless Application with Auto-scaling
+
+**Purpose:** Demonstrates Kubernetes deployment best practices with monitoring and high availability.
+
+```yaml
+# chart/templates/deployment.yaml
+apiVersion: apps/v1
+kind: Deployment
+metadata:
+  name: {{ include "myapp.fullname" . }}
+  labels:
+    {{- include "myapp.labels" . | nindent 4 }}
+spec:
+  replicas: {{ .Values.replicaCount }}
+  strategy:
+    type: RollingUpdate
+    rollingUpdate:
+      maxSurge: 1
+      maxUnavailable: 0
+  selector:
+    matchLabels:
+      {{- include "myapp.selectorLabels" . | nindent 6 }}
+  template:
+    metadata:
+      annotations:
+        prometheus.io/scrape: "true"
+        prometheus.io/port: "{{ .Values.service.metricsPort }}"
+        prometheus.io/path: "/metrics"
+      labels:
+        {{- include "myapp.selectorLabels" . | nindent 8 }}
+    spec:
+      securityContext:
+        runAsNonRoot: true
+        runAsUser: 1000
+      containers:
+      - name: {{ .Chart.Name }}
+        securityContext:
+          allowPrivilegeEscalation: false
+          readOnlyRootFilesystem: true
+          capabilities:
+            drop:
+            - ALL
+        image: "{{ .Values.image.repository }}:{{ .Values.image.tag }}"
+        imagePullPolicy: {{ .Values.image.pullPolicy }}
+        ports:
+        - name: http
+          containerPort: {{ .Values.service.port }}
+          protocol: TCP
+        - name: metrics
+          containerPort: {{ .Values.service.metricsPort }}
+          protocol: TCP
+        
+        # Health checks for kubernetes orchestration
+        livenessProbe:
+          httpGet:
+            path: /health/live
+            port: http
+          initialDelaySeconds: 30
+          periodSeconds: 10
+          timeoutSeconds: 5
+          failureThreshold: 3
+        
+        readinessProbe:
+          httpGet:
+            path: /health/ready
+            port: http
+          initialDelaySeconds: 10
+          periodSeconds: 5
+          timeoutSeconds: 3
+          failureThreshold: 2
+        
+        # Resource requests and limits
+        resources:
+          requests:
+            cpu: {{ .Values.resources.requests.cpu }}
+            memory: {{ .Values.resources.requests.memory }}
+          limits:
+            cpu: {{ .Values.resources.limits.cpu }}
+            memory: {{ .Values.resources.limits.memory }}
+        
+        # Environment configuration from ConfigMap
+        env:
+        - name: LOG_LEVEL
+          valueFrom:
+            configMapKeyRef:
+              name: {{ include "myapp.fullname" . }}-config
+              key: log_level
+        
+        # Secrets from Kubernetes secrets (never hardcoded)
+        - name: DATABASE_PASSWORD
+          valueFrom:
+            secretKeyRef:
+              name: {{ include "myapp.fullname" . }}-secrets
+              key: db_password
+        
+        # Temporary volume for application logs
+        volumeMounts:
+        - name: tmp
+          mountPath: /tmp
+        - name: logs
+          mountPath: /var/log/app
+      
+      volumes:
+      - name: tmp
+        emptyDir: {}
+      - name: logs
+        emptyDir: {}
+```
+
+```yaml
+# chart/templates/hpa.yaml
+apiVersion: autoscaling/v2
+kind: HorizontalPodAutoscaler
+metadata:
+  name: {{ include "myapp.fullname" . }}
+  labels:
+    {{- include "myapp.labels" . | nindent 4 }}
+spec:
+  scaleTargetRef:
+    apiVersion: apps/v1
+    kind: Deployment
+    name: {{ include "myapp.fullname" . }}
+  minReplicas: {{ .Values.autoscaling.minReplicas }}
+  maxReplicas: {{ .Values.autoscaling.maxReplicas }}
+  metrics:
+  - type: Resource
+    resource:
+      name: cpu
+      target:
+        type: Utilization
+        averageUtilization: {{ .Values.autoscaling.targetCPUUtilizationPercentage }}
+  - type: Resource
+    resource:
+      name: memory
+      target:
+        type: Utilization
+        averageUtilization: {{ .Values.autoscaling.targetMemoryUtilizationPercentage }}
+  behavior:
+    scaleDown:
+      stabilizationWindowSeconds: 300
+      policies:
+      - type: Percent
+        value: 50
+        periodSeconds: 15
+    scaleUp:
+      stabilizationWindowSeconds: 60
+      policies:
+      - type: Percent
+        value: 100
+        periodSeconds: 15
+      - type: Pods
+        value: 2
+        periodSeconds: 15
+      selectPolicy: Max
+```
+
+```yaml
+# chart/values.yaml
+replicaCount: 3
+
+image:
+  repository: myapp
+  tag: "1.0.0"
+  pullPolicy: IfNotPresent
+
+service:
+  port: 8080
+  metricsPort: 9090
+
+resources:
+  requests:
+    cpu: 100m
+    memory: 128Mi
+  limits:
+    cpu: 500m
+    memory: 512Mi
+
+autoscaling:
+  enabled: true
+  minReplicas: 3
+  maxReplicas: 10
+  targetCPUUtilizationPercentage: 70
+  targetMemoryUtilizationPercentage: 80
+```
+
+**Key Patterns Demonstrated:**
+- Security best practices (non-root user, read-only filesystem, dropped capabilities)
+- Health checks for self-healing
+- Resource requests/limits for reliability
+- Horizontal pod autoscaling based on metrics
+- Environment variables from ConfigMaps
+- Secrets management (not hardcoded)
+- Monitoring annotations for Prometheus integration
+- Rolling update strategy
+
+---
+
+## CI/CD Pipeline Example
+
+### Example: GitHub Actions Pipeline
+
+**Purpose:** Demonstrates automated testing, security scanning, and deployment workflow.
+
+```yaml
+# .github/workflows/deploy.yml
+name: Build, Test, and Deploy
+
+on:
+  push:
+    branches:
+      - main
+      - develop
+  pull_request:
+    branches:
+      - main
+
+env:
+  REGISTRY: ghcr.io
+  IMAGE_NAME: ${{ github.repository }}
+
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    permissions:
+      contents: read
+      packages: write
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Docker Buildx
+      uses: docker/setup-buildx-action@v3
+    
+    - name: Log in to Container Registry
+      if: github.event_name != 'pull_request'
+      uses: docker/login-action@v3
+      with:
+        registry: ${{ env.REGISTRY }}
+        username: ${{ github.actor }}
+        password: ${{ secrets.GITHUB_TOKEN }}
+    
+    - name: Extract metadata
+      id: meta
+      uses: docker/metadata-action@v5
+      with:
+        images: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
+        tags: |
+          type=ref,event=branch
+          type=semver,pattern={{version}}
+          type=sha,prefix={{branch}}-
+    
+    - name: Build and push Docker image
+      uses: docker/build-push-action@v5
+      with:
+        context: .
+        push: ${{ github.event_name != 'pull_request' }}
+        tags: ${{ steps.meta.outputs.tags }}
+        labels: ${{ steps.meta.outputs.labels }}
+        cache-from: type=gha
+        cache-to: type=gha,mode=max
+
+  test:
+    runs-on: ubuntu-latest
+    needs: build
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Set up Go
+      uses: actions/setup-go@v4
+      with:
+        go-version: '1.21'
+        cache: 'go'
+    
+    - name: Run unit tests
+      run: go test -v -race -coverprofile=coverage.out ./...
+    
+    - name: Upload coverage to Codecov
+      uses: codecov/codecov-action@v3
+      with:
+        files: ./coverage.out
+        flags: unittests
+        fail_ci_if_error: true
+
+  security-scan:
+    runs-on: ubuntu-latest
+    needs: build
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Run Trivy vulnerability scanner
+      uses: aquasecurity/trivy-action@master
+      with:
+        scan-type: 'fs'
+        scan-ref: '.'
+        format: 'sarif'
+        output: 'trivy-results.sarif'
+    
+    - name: Upload Trivy results to GitHub Security tab
+      uses: github/codeql-action/upload-sarif@v3
+      with:
+        sarif_file: 'trivy-results.sarif'
+    
+    - name: Check for high severity vulnerabilities
+      run: |
+        if grep -q "HIGH\|CRITICAL" trivy-results.sarif; then
+          echo "High/Critical vulnerabilities found"
+          exit 1
+        fi
+
+  deploy-staging:
+    runs-on: ubuntu-latest
+    needs: [test, security-scan]
+    if: github.ref == 'refs/heads/develop' && github.event_name == 'push'
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Deploy to staging
+      run: |
+        echo "Deploying to staging environment..."
+        # Use kubectl or deployment tool to deploy
+        kubectl set image deployment/myapp myapp=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
+          -n staging \
+          --record
+        kubectl rollout status deployment/myapp -n staging
+
+  deploy-production:
+    runs-on: ubuntu-latest
+    needs: [test, security-scan]
+    if: github.ref == 'refs/heads/main' && github.event_name == 'push'
+    environment:
+      name: production
+      url: https://myapp.example.com
+    
+    steps:
+    - uses: actions/checkout@v4
+    
+    - name: Deploy to production
+      run: |
+        echo "Deploying to production environment..."
+        kubectl set image deployment/myapp myapp=${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}:${{ github.sha }} \
+          -n production \
+          --record
+        kubectl rollout status deployment/myapp -n production
+    
+    - name: Run smoke tests
+      run: |
+        ./scripts/smoke-tests.sh https://myapp.example.com
+    
+    - name: Notify deployment
+      if: always()
+      uses: 8398a7/action-slack@v3
+      with:
+        status: ${{ job.status }}
+        text: "Production deployment ${{ job.status }}"
+        webhook_url: ${{ secrets.SLACK_WEBHOOK }}
+```
+
+**Key Patterns Demonstrated:**
+- Automated build pipeline with Docker
+- Unit tests with coverage reporting
+- Security scanning (Trivy, dependency checking)
+- Separate staging and production deployments
+- Approval gates for production (environment)
+- Smoke tests after deployment
+- Notifications for team awareness
+- Proper secret handling (GitHub secrets)
+
+---
+
+## Monitoring & Alerting Example
+
+### Example: Prometheus + Grafana Dashboard
+
+**Purpose:** Demonstrates observability setup with meaningful metrics and alerting.
+
+```yaml
+# prometheus-values.yaml
+prometheus:
+  prometheusSpec:
+    retention: 30d
+    
+    # Service monitors for scraping targets
+    serviceMonitorSelectorNilUsesHelmValues: false
+    podMonitorSelectorNilUsesHelmValues: false
+    
+    # Persistent storage
+    storageSpec:
+      volumeClaimTemplate:
+        spec:
+          accessModes: ["ReadWriteOnce"]
+          resources:
+            requests:
+              storage: 50Gi
+    
+    # Resource requests
+    resources:
+      requests:
+        cpu: 500m
+        memory: 2Gi
+      limits:
+        cpu: 2
+        memory: 4Gi
+
+# Alert rules
+alertmanager:
+  enabled: true
+  config:
+    route:
+      group_by: ['alertname', 'cluster']
+      group_wait: 10s
+      group_interval: 10s
+      repeat_interval: 12h
+      receiver: 'default'
+      routes:
+      - match:
+          severity: critical
+        receiver: 'critical'
+        continue: true
+      - match:
+          severity: warning
+        receiver: 'warning'
+    
+    receivers:
+    - name: 'default'
+      slack_configs:
+      - api_url: '${SLACK_WEBHOOK_URL}'
+        channel: '#alerts'
+    
+    - name: 'critical'
+      pagerduty_configs:
+      - service_key: '${PAGERDUTY_KEY}'
+      slack_configs:
+      - api_url: '${SLACK_WEBHOOK_URL}'
+        channel: '#critical-alerts'
+
+# Grafana dashboards
+grafana:
+  persistence:
+    enabled: true
+    size: 10Gi
+  
+  datasources:
+    datasources.yaml:
+      apiVersion: 1
+      datasources:
+      - name: Prometheus
+        type: prometheus
+        url: http://prometheus-operated:9090
+```
+
+```yaml
+# prometheus-rules.yaml
+groups:
+- name: kubernetes.rules
+  interval: 30s
+  rules:
+  
+  # Availability SLO alerts
+  - alert: ServiceUnavailable
+    expr: up{job="myapp"} == 0
+    for: 1m
+    labels:
+      severity: critical
+    annotations:
+      summary: "Service {{ $labels.instance }} is down"
+      description: "Service has been down for more than 1 minute"
+  
+  # Resource utilization alerts
+  - alert: HighCPUUsage
+    expr: |
+      (sum(rate(container_cpu_usage_seconds_total{pod=~"myapp-.*"}[5m])) by (pod)
+       / sum(container_spec_cpu_quota{pod=~"myapp-.*"} / container_spec_cpu_period{pod=~"myapp-.*"}) by (pod))
+      > 0.8
+    for: 5m
+    labels:
+      severity: warning
+    annotations:
+      summary: "High CPU usage for pod {{ $labels.pod }}"
+  
+  - alert: HighMemoryUsage
+    expr: |
+      (sum(container_memory_usage_bytes{pod=~"myapp-.*"}) by (pod)
+       / sum(container_spec_memory_limit_bytes{pod=~"myapp-.*"}) by (pod))
+      > 0.8
+    for: 5m
+    labels:
+      severity: warning
+    annotations:
+      summary: "High memory usage for pod {{ $labels.pod }}"
+  
+  # Disk space alerts
+  - alert: DiskSpaceLow
+    expr: |
+      (node_filesystem_avail_bytes{mountpoint="/"} / node_filesystem_size_bytes{mountpoint="/"})
+      < 0.1
+    for: 5m
+    labels:
+      severity: critical
+    annotations:
+      summary: "Disk space low on {{ $labels.instance }}"
+  
+  # Application error rate alerts
+  - alert: HighErrorRate
+    expr: |
+      (sum(rate(http_requests_total{status=~"5.."}[5m])) by (job)
+       / sum(rate(http_requests_total[5m])) by (job))
+      > 0.05
+    for: 5m
+    labels:
+      severity: warning
+    annotations:
+      summary: "High error rate for {{ $labels.job }}"
+```
+
+**Key Patterns Demonstrated:**
+- Long-term metrics retention for capacity planning
+- Service monitoring with auto-discovery
+- Persistent storage for metrics
+- Multi-channel alerting (Slack, PagerDuty)
+- SLO-focused alerts (availability, latency, error rates)
+- Resource utilization alerts
+- Meaningful alert thresholds and durations
+- Clear alert messages with context
+
+---
+
+## Summary
+
+These examples demonstrate:
+
+1. **Infrastructure as Code:** Modular, reusable, well-documented, secure
+2. **Kubernetes Deployments:** High availability, auto-scaling, security-first
+3. **CI/CD Pipelines:** Automated testing, security scanning, safe deployments
+4. **Monitoring:** SLO-focused alerts, meaningful metrics, multi-channel notifications
+
+Use these as templates when designing new infrastructure, deployments, or monitoring systems.