Skip to main content

Configuration Validation

Xec provides comprehensive validation capabilities to ensure your configurations are correct, secure, and optimized before deployment. This guide covers validation strategies, tools, and best practices.

Validation Levels​

1. Schema Validation​

Validates configuration structure and types:

# Validate against schema
xec config validate

# Output
✓ Schema validation passed
✓ Version: 1.0 (supported)
✓ Structure: Valid YAML
✓ Required fields present

2. Semantic Validation​

Checks logical consistency:

# Detailed validation
xec config validate --verbose

# Checks:
# - Target references exist
# - Task dependencies are valid
# - Variables are defined
# - Profiles inheritance is correct

3. Runtime Validation​

Validates execution environment:

# Test runtime compatibility
xec config validate --runtime

# Checks:
# - Target connectivity
# - Command availability
# - Resource access
# - Secret availability

Configuration Schema​

Schema Structure​

# Xec follows this schema
$schema: https://xec.sh/schema/v1.0/config.json

version: "1.0"  # Required, must match schema version
name: string    # Optional, project name
description: string  # Optional, project description

vars:           # Optional, variable definitions
  type: object
  additionalProperties: true

targets:        # Optional, target definitions
  type: object
  properties:
    defaults: object
    hosts: object
    containers: object
    pods: object

tasks:          # Optional, task definitions
  type: object
  additionalProperties:
    oneOf:
      - type: string
      - type: object

profiles:       # Optional, profile definitions
  type: object
  additionalProperties: object

Type Validation​

# Types are enforced
vars:
  port: 8080        # Must be number
  enabled: true     # Must be boolean
  name: "myapp"     # Must be string
  servers:          # Must be array
    - server1
    - server2
  config:           # Must be object
    key: value

Validation Commands​

Basic Validation​

# Validate current configuration
xec config validate

# Validate specific file
xec config validate --file custom-config.yaml

# Validate with profile
xec config validate --profile production

Detailed Validation​

# Show all validation details
xec config validate --verbose

# Show validation errors only
xec config validate --errors-only

# Output as JSON
xec config validate --json

Selective Validation​

# Validate specific sections
xec config validate --targets
xec config validate --tasks
xec config validate --variables

# Validate specific target
xec config validate --target hosts.production

Common Validation Errors​

Missing Required Fields​

# Error: version is required
name: myapp
tasks:
  deploy: echo "deploy"

# Fix: Add version
version: "1.0"
name: myapp
tasks:
  deploy: echo "deploy"

Invalid References​

# Error: Target 'hosts.nonexistent' not found
tasks:
  deploy:
    command: deploy
    target: hosts.nonexistent

# Fix: Use existing target
tasks:
  deploy:
    command: deploy
    target: hosts.production

Circular Dependencies​

# Error: Circular dependency detected
profiles:
  a:
    extends: b
  b:
    extends: a

# Fix: Remove circular reference
profiles:
  base:
    vars: {...}
  a:
    extends: base
  b:
    extends: base

Type Mismatches​

# Error: Expected number, got string
vars:
  port: "8080"  # String

tasks:
  connect:
    command: connect --port ${port + 100}  # Math operation

# Fix: Use correct type
vars:
  port: 8080  # Number

Variable Validation​

Undefined Variables​

# Detect undefined variables
vars:
  defined: value

tasks:
  test:
    command: echo ${undefined}  # Error: undefined variable

# Fix: Define or provide default
tasks:
  test:
    command: echo ${undefined:-default}

Variable Resolution​

# Test variable resolution
xec config show --vars

# Test specific variable
xec config get vars.database.host

# Test with profile
xec config get vars.database.host --profile production

Circular References​

# Detect circular variable references
vars:
  a: ${b}
  b: ${c}
  c: ${a}  # Error: circular reference

# Fix: Remove circular dependency
vars:
  a: value1
  b: ${a}
  c: ${b}

Target Validation​

Connectivity Testing​

# Test target connectivity
xec test hosts.production

# Test all targets
xec test --all-targets

# Verbose testing
xec test hosts.production --verbose

SSH Target Validation​

# Validate SSH configuration
targets:
  hosts:
    server:
      host: example.com
      username: deploy
      privateKey: ~/.ssh/id_rsa

# Validation checks:
# - Host resolves
# - Port is open
# - Key file exists
# - Key has correct permissions

Docker Target Validation​

# Validate Docker configuration
targets:
  containers:
    app:
      image: node:18

# Validation checks:
# - Docker daemon accessible
# - Image exists or can be pulled
# - Port bindings available
# - Volume paths exist

Kubernetes Target Validation​

# Validate Kubernetes configuration
targets:
  pods:
    web:
      namespace: production
      selector: app=web

# Validation checks:
# - Cluster accessible
# - Namespace exists
# - Pods match selector
# - RBAC permissions

Task Validation​

Task Structure​

# Validate task definition
tasks:
  valid-task:
    description: "Valid task"
    command: echo "test"
    target: hosts.production
    timeout: 30000

# Validation checks:
# - Command or script defined
# - Target exists if specified
# - Timeout is valid number
# - Parameters have valid types

Step Dependencies​

tasks:
  with-deps:
    steps:
      - name: step1
        command: echo "1"
        id: first
      
      - name: step2
        command: echo "2"
        dependsOn: [first]  # Validates dependency exists

Parameter Validation​

tasks:
  parameterized:
    params:
      - name: count
        type: number
        required: true
        min: 1
        max: 100
      
      - name: environment
        type: enum
        values: [dev, staging, prod]
        required: true

# Validation enforces:
# - Required parameters provided
# - Type constraints met
# - Value ranges respected

Profile Validation​

Inheritance Chain​

profiles:
  base:
    vars:
      region: us-east-1
  
  staging:
    extends: base  # Validates base exists
    vars:
      environment: staging
  
  production:
    extends: staging  # Validates chain
    vars:
      environment: production

Profile Merging​

# Test profile merging
xec config show --profile production

# Validate merged configuration
xec config validate --profile production

Custom Validation​

Validation Scripts​

tasks:
  validate-custom:
    script: |
      // Custom validation logic
      const errors = [];
      
      // Check custom requirements
      if (!vars.apiKey || vars.apiKey.length < 32) {
        errors.push('API key must be at least 32 characters');
      }
      
      if (vars.replicas < 2 && profile === 'production') {
        errors.push('Production must have at least 2 replicas');
      }
      
      if (errors.length > 0) {
        throw new Error(errors.join('\n'));
      }

Pre-execution Validation​

tasks:
  deploy:
    hooks:
      before:
        - task: validate-environment
        - task: validate-permissions
        - task: validate-resources
    command: deploy-application

Validation Rules​

# Define validation rules
vars:
  validation:
    rules:
      - field: database.host
        required: true
        pattern: "^[a-z0-9.-]+$"
      
      - field: database.port
        type: number
        min: 1024
        max: 65535
      
      - field: apiKey
        required: true
        minLength: 32
        maxLength: 64

Environment Validation​

Environment Checks​

tasks:
  validate-environment:
    script: |
      // Check environment
      const checks = {
        'Node.js': () => process.version,
        'Docker': () => $`docker --version`,
        'kubectl': () => $`kubectl version --client`,
        'SSH': () => $`ssh -V`
      };
      
      for (const [name, check] of Object.entries(checks)) {
        try {
          const version = await check();
          console.log(`✓ ${name}: ${version}`);
        } catch {
          console.error(`✗ ${name}: Not found`);
        }
      }

Resource Validation​

tasks:
  validate-resources:
    script: |
      // Check resources
      const required = {
        diskSpace: 10 * 1024 * 1024 * 1024,  // 10GB
        memory: 4 * 1024 * 1024 * 1024,       // 4GB
        cpus: 2
      };
      
      const available = await getSystemResources();
      
      for (const [resource, required] of Object.entries(required)) {
        if (available[resource] < required) {
          throw new Error(`Insufficient ${resource}`);
        }
      }

Continuous Validation​

Pre-commit Hooks​

#!/bin/bash
# .git/hooks/pre-commit

# Validate configuration before commit
xec config validate || {
  echo "Configuration validation failed"
  exit 1
}

CI/CD Integration​

# .github/workflows/validate.yml
name: Validate Configuration
on: [push, pull_request]

jobs:
  validate:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v2
      - name: Install Xec
        run: npm install -g @xec-sh/cli
      - name: Validate configuration
        run: xec config validate --strict

Automated Testing​

tasks:
  test-configuration:
    steps:
      - name: Schema validation
        command: xec config validate
      
      - name: Target connectivity
        command: xec test --all-targets
      
      - name: Task dry-run
        command: xec run deploy --dry-run
      
      - name: Security scan
        command: xec security scan

Validation Reports​

Generate Reports​

# Generate validation report
xec config validate --report validation-report.json

# Generate HTML report
xec config validate --report validation-report.html

Report Format​

{
  "timestamp": "2024-01-15T10:00:00Z",
  "version": "1.0",
  "status": "passed",
  "checks": {
    "schema": { "status": "passed" },
    "variables": { "status": "passed" },
    "targets": { 
      "status": "warning",
      "warnings": ["hosts.backup: Connection timeout"]
    },
    "tasks": { "status": "passed" }
  }
}

Best Practices​

1. Validate Early and Often​

# Add to development workflow
alias xec-save='xec config validate && git add .xec/'

2. Use Strict Mode​

# Fail on warnings in production
xec config validate --strict --profile production

3. Automate Validation​

# Add validation task
tasks:
  ci:
    steps:
      - command: xec config validate --strict
      - command: xec test --all-targets
      - command: xec run test-suite

4. Document Validation Rules​

# Document requirements
vars:
  _validation:
    description: |
      Required environment variables:
      - API_KEY: API authentication key
      - DB_PASSWORD: Database password
      
      Required commands:
      - docker: Container management
      - kubectl: Kubernetes management

5. Progressive Validation​

# Start lenient, increase strictness
profiles:
  development:
    validation:
      strict: false
      warnOnly: true
  
  production:
    validation:
      strict: true
      failOnWarning: true

Troubleshooting​

Validation Failures​

# Debug validation issues
xec config validate --debug

# Show configuration after resolution
xec config show --resolved

# Test specific component
xec config validate --tasks --verbose

Common Solutions​

ErrorSolution
Schema version mismatchUpdate version field to "1.0"
Undefined variableAdd variable definition or use default
Target not foundCheck target name and definition
Invalid YAMLValidate YAML syntax with linter
Circular dependencyBreak circular reference chain
Type mismatchEnsure correct type in definition

Next Steps​

See Also​