Skip to content

validate.md

Latest commit

 

History

History
324 lines (232 loc) · 9.22 KB

validate.md

File metadata and controls

324 lines (232 loc) · 9.22 KB

Validate Command

Validates environment configuration files without creating deployments. Use this command to check configuration correctness before running the actual deployment workflow.

Command Syntax

torrust-tracker-deployer validate --env-file <CONFIG_FILE>

Options

  • --env-file, -f <FILE> - Path to the environment configuration file to validate (required)

Usage Examples

Basic Usage

torrust-tracker-deployer validate --env-file envs/my-environment.json

Validate with Short Flag

torrust-tracker-deployer validate -f config/production.json

What This Command Does

The validate command performs comprehensive validation of environment configuration files:

  1. File Validation - Verifies the configuration file exists and is readable
  2. JSON Schema Validation - Checks JSON syntax and structure
  3. Domain Validation - Validates field constraints and business rules:
    • SSH key files must exist at specified paths
    • Environment names must follow naming rules (lowercase with dashes)
    • Port numbers must be valid
    • IP addresses must be well-formed
    • Domain names must follow DNS conventions
    • All required fields must be present

When to Use

  • Before Creating Environments - Catch configuration errors early before starting infrastructure provisioning
  • CI/CD Pipelines - Validate configurations as part of automated testing
  • Configuration Review - Verify configuration correctness during code review
  • Troubleshooting - Diagnose why environment creation failed
  • Learning - Understand configuration structure and requirements

When NOT to Use

  • After Environment Creation - Use show command to view existing environment details instead
  • Creating Templates - Use create template to generate valid configuration files
  • Deployment - Validate does not deploy - use full workflow commands for actual deployment

Output Details

Success Output

⏳ [1/3] Loading configuration file...
⏳   ✓ Configuration file loaded (took 0ms)
⏳ [2/3] Validating JSON schema...
⏳   ✓ Schema validation passed (took 0ms)
⏳ [3/3] Validating configuration fields...
⏳   ✓ Field validation passed (took 0ms)

✅ Configuration file 'envs/full-stack-docs.json' is valid

Environment Details:
• Name: full-stack-docs
• Provider: lxd
• Prometheus: Enabled
• Grafana: Enabled
• HTTPS: Enabled
• Backups: Enabled

JSON Output

Use --output-format json (or -o json) to get machine-readable output. Progress messages go to stderr; the JSON result goes to stdout.

torrust-tracker-deployer validate --env-file envs/my-environment.json --output-format json 2>/dev/null
{
  "environment_name": "my-environment",
  "config_file": "envs/my-environment.json",
  "provider": "lxd",
  "is_valid": true,
  "has_prometheus": true,
  "has_grafana": true,
  "has_https": false,
  "has_backup": false
}
Field Type Description
environment_name string Name of the validated environment
config_file string Path to the validated configuration file
provider string Infrastructure provider (lowercase: "lxd", "hetzner", etc.)
is_valid boolean Always true when the command succeeds
has_prometheus boolean Whether Prometheus monitoring is configured
has_grafana boolean Whether Grafana dashboard is configured
has_https boolean Whether HTTPS is configured
has_backup boolean Whether backups are configured

Error Output Examples

File Not Found:

❌ Validate command failed: Configuration file not found: /tmp/nonexistent.json

For detailed troubleshooting:
Verify the file path is correct: /tmp/nonexistent.json
Use 'create template' to generate a valid configuration file.

Invalid JSON:

❌ Validate command failed: Validation failed for configuration file: config.json

For detailed troubleshooting:
JSON parsing failed for file 'config.json'.

Error details:
key must be a string at line 1 column 3

Common issues:
- Missing or extra commas
- Unmatched braces or brackets
- Invalid escape sequences
- Comments (not allowed in JSON)

Tips:
- Use a JSON validator or editor with syntax highlighting
- Compare with a template: 'create template --provider lxd'
- Check the JSON schema in schemas/environment-config.json

Missing SSH Keys:

❌ Validate command failed: Validation failed for configuration file: config.json

For detailed troubleshooting:
Configuration validation failed.

Error: SSH private key file not found: /tmp/nonexistent-key

This means the configuration file has valid JSON syntax but violates
domain constraints or business rules.

Common issues:
- SSH key files don't exist at specified paths
- Invalid environment name (must be lowercase with dashes)
- Invalid port numbers or IP addresses
- Missing required fields
- HTTPS configured but no services have TLS enabled

Common Scenarios

Scenario 1: Pre-Deployment Validation

Before starting a deployment, validate your configuration:

# Create configuration from template
torrust-tracker-deployer create template -p lxd > envs/my-env.json

# Edit configuration...
# vim envs/my-env.json

# Validate before deploying
torrust-tracker-deployer validate -f envs/my-env.json

# If valid, proceed with deployment
torrust-tracker-deployer create environment -f envs/my-env.json

Scenario 2: CI/CD Pipeline Integration

Add validation as a CI test:

#!/bin/bash
# .github/workflows/validate-configs.sh

for config in envs/*.json; do
    echo "Validating $config..."
    torrust-tracker-deployer validate -f "$config"

    if [ $? -ne 0 ]; then
        echo "❌ Validation failed for $config"
        exit 1
    fi
done

echo "✅ All configurations valid"

Scenario 3: Troubleshooting Configuration Issues

When environment creation fails, use validate to diagnose:

# Creation fails
torrust-tracker-deployer create environment -f envs/broken.json
# Error: SSH key not found...

# Use validate for detailed error messages
torrust-tracker-deployer validate -f envs/broken.json
# Shows: SSH private key file not found: /path/to/key
#        With troubleshooting tips...

# Fix issue and re-validate
vim envs/broken.json
torrust-tracker-deployer validate -f envs/broken.json
# ✅ Configuration valid

# Retry creation
torrust-tracker-deployer create environment -f envs/broken.json

Troubleshooting

Error: Configuration file not found

Cause: The file path is incorrect or the file doesn't exist.

Solution: Verify the file path and ensure the file exists:

# Check if file exists
ls -l envs/my-config.json

# Use absolute path if relative path fails
torrust-tracker-deployer validate -f /full/path/to/envs/my-config.json

# Generate a template if starting fresh
torrust-tracker-deployer create template -p lxd > envs/new-config.json

Error: JSON parsing failed

Cause: The JSON syntax is invalid (missing commas, unmatched braces, etc.).

Solution: Use a JSON validator or IDE with JSON support:

# Use jq to validate and format
jq . envs/my-config.json

# Use Python's JSON tool
python -m json.tool < envs/my-config.json

# Compare with template
torrust-tracker-deployer create template -p lxd | jq . > valid-template.json
diff envs/my-config.json valid-template.json

Error: SSH key file not found

Cause: The SSH key paths in the configuration don't exist.

Solution: Generate SSH keys or update paths to existing keys:

# Option 1: Generate new SSH keys
ssh-keygen -t rsa -b 4096 -f ~/.ssh/torrust_deployer -N ""

# Option 2: Update configuration with correct paths
vim envs/my-config.json
# Update "private_key_path" and "public_key_path"

# Validate
torrust-tracker-deployer validate -f envs/my-config.json

Error: Invalid environment name

Cause: Environment name doesn't follow naming rules.

Solution: Use valid naming format (lowercase letters, numbers, dashes):

# Invalid names:
# - "MyEnv" (uppercase)
# - "my_env" (underscores)
# - "123-env" (starts with number)
# - "my-env-" (ends with dash)

# Valid names:
# - "my-env"
# - "production"
# - "dev-01"
# - "staging-2025"

# Fix in configuration
vim envs/my-config.json
# Change "name": "MyEnv" to "name": "my-env"

torrust-tracker-deployer validate -f envs/my-config.json

Related Commands

See Also