Skip to content

test.md

Latest commit

 

History

History
352 lines (240 loc) · 7.83 KB

test.md

File metadata and controls

352 lines (240 loc) · 7.83 KB

test - Verify Infrastructure Configuration

Verify that provisioned and configured infrastructure meets all requirements.

Purpose

Validates infrastructure readiness by running comprehensive tests against the configured environment. This command confirms the environment is in a working state and ready for deployment.

Command Syntax

torrust-tracker-deployer test <ENVIRONMENT>

Arguments

  • <ENVIRONMENT> (required) - Name of the environment to test

Prerequisites

  1. Environment configured - Must run configure first
  2. VM running - Instance must be accessible
  3. Docker installed - Docker and Docker Compose must be available
  4. SSH connectivity - Network access to VM

State Validation

Tests verify the environment is in "Configured" state and all components work correctly.

What Happens

When you test an environment:

  1. Validates environment state - Ensures environment is configured
  2. Checks VM connectivity - Verifies SSH access
  3. Tests Docker installation - Validates Docker daemon
  4. Tests Docker Compose - Validates Docker Compose plugin
  5. Verifies user permissions - Confirms non-root Docker access
  6. Runs infrastructure tests - Executes comprehensive test suite
  7. Reports results - Provides detailed pass/fail status

Examples

Basic testing

# Test the environment
torrust-tracker-deployer test my-environment

# Output:
# ✓ Validating environment state...
# ✓ Checking VM connectivity...
# ✓ Testing Docker installation...
# ✓ Testing Docker Compose...
# ✓ Verifying user permissions...
# ✓ Running infrastructure tests...
# ✓ All tests passed

Complete workflow

# Full setup and verification
torrust-tracker-deployer create environment -f config.json
torrust-tracker-deployer provision my-environment
torrust-tracker-deployer configure my-environment
torrust-tracker-deployer test my-environment

# If all tests pass, environment is ready

CI/CD verification

#!/bin/bash
set -e

ENV_NAME="ci-${BUILD_ID}"

# Setup
torrust-tracker-deployer create environment -f ci.json
torrust-tracker-deployer provision ${ENV_NAME}
torrust-tracker-deployer configure ${ENV_NAME}

# Verify infrastructure readiness
if torrust-tracker-deployer test ${ENV_NAME}; then
    echo "Infrastructure ready for deployment"
    # Deploy your application...
else
    echo "Infrastructure tests failed"
    exit 1
fi

# Cleanup
torrust-tracker-deployer destroy ${ENV_NAME}

Test Categories

Connectivity Tests

  • SSH Access - Verifies SSH connection to VM
  • Network Reachability - Confirms VM can reach internet
  • DNS Resolution - Validates DNS configuration

Docker Tests

  • Docker Daemon - Checks Docker service is running
  • Docker CLI - Verifies Docker commands work
  • Docker Info - Validates Docker system information
  • Docker Version - Confirms Docker version

Docker Compose Tests

  • Compose Plugin - Verifies Docker Compose is installed
  • Compose Version - Confirms Docker Compose version
  • Compose Functionality - Tests basic Compose operations

Permission Tests

  • Non-root Access - Confirms user can run Docker without sudo
  • Docker Group - Verifies user is in docker group
  • Socket Access - Validates docker socket permissions

Output

The test command provides:

  • Test results - Pass/fail status for each test
  • Detailed logs - Information about any failures
  • Exit code - 0 for success, non-zero for failure

Test logs are written to:

  • data/logs/test-<timestamp>.log

Next Steps

After testing:

# If tests pass, environment is ready
# Deploy your application

# SSH into the environment
ssh -i <private-key> torrust@<vm-ip>

# Or proceed with application deployment
# (application deployment features coming in future releases)

Troubleshooting

Environment not configured

Problem: Cannot test an environment that hasn't been configured

Solution: Configure the environment first

# Check environment state
cat data/my-environment/state.json

# If state is "Provisioned", configure first
torrust-tracker-deployer configure my-environment

SSH connectivity test fails

Problem: Cannot establish SSH connection to VM

Solution: Check VM status and network

# Verify VM is running
lxc list

# Get VM IP
lxc list --format json | jq -r '.[].state.network.eth0.addresses[0].address'

# Try manual SSH
ssh -i <private-key> torrust@<vm-ip>

# Check SSH key permissions
ls -l <private-key>
chmod 600 <private-key>

Docker daemon test fails

Problem: Docker service is not running

Solution: Check Docker service status on VM

# SSH into VM
ssh -i <private-key> torrust@<vm-ip>

# Check Docker status
sudo systemctl status docker

# Start Docker if needed
sudo systemctl start docker

# Enable Docker to start on boot
sudo systemctl enable docker

Docker Compose test fails

Problem: Docker Compose is not installed or not in PATH

Solution: Verify Docker Compose installation

# SSH into VM
ssh -i <private-key> torrust@<vm-ip>

# Check Docker Compose
docker compose version

# If not found, reconfigure
exit
torrust-tracker-deployer configure my-environment

Permission test fails

Problem: User cannot run Docker without sudo

Solution: Verify user is in docker group

# SSH into VM
ssh -i <private-key> torrust@<vm-ip>

# Check groups
groups

# If docker group missing, add it
sudo usermod -aG docker $USER

# Log out and back in
exit
ssh -i <private-key> torrust@<vm-ip>

# Verify
docker ps

Network connectivity test fails

Problem: VM cannot reach external networks

Solution: Check LXD network configuration

# Check LXD network
lxc network list

# Check instance network config
lxc config device show <instance-name>

# Check VM network inside
lxc exec <instance-name> -- ip addr
lxc exec <instance-name> -- ping -c 3 8.8.8.8

Common Use Cases

Automated validation

#!/bin/bash
set -e

# Setup infrastructure
./scripts/setup-environment.sh my-environment

# Run comprehensive tests
if torrust-tracker-deployer test my-environment; then
    echo "✓ Infrastructure validated successfully"

    # Deploy application
    ./scripts/deploy-app.sh my-environment
else
    echo "✗ Infrastructure validation failed"

    # Collect diagnostics
    ./scripts/collect-logs.sh my-environment

    exit 1
fi

Development workflow

# After making infrastructure changes
torrust-tracker-deployer configure my-environment

# Verify changes didn't break anything
torrust-tracker-deployer test my-environment

# If tests pass, continue development

Pre-deployment checklist

# Staging environment verification
torrust-tracker-deployer test staging

# Production environment verification
torrust-tracker-deployer test production

# Only deploy if both pass

Technical Details

Test Implementation

Tests are implemented using:

  • SSH Client - Remote command execution
  • Assertions - Validates expected outcomes
  • Error Handling - Provides detailed failure messages

Test Execution Flow

  1. State Validation - Checks environment JSON state
  2. SSH Connection - Establishes connection to VM
  3. Docker Checks - Runs docker commands remotely
  4. Compose Checks - Runs docker compose commands remotely
  5. Permission Checks - Validates non-root access
  6. Result Aggregation - Collects all test results
  7. Reporting - Outputs pass/fail status

Exit Codes

  • 0 - All tests passed
  • 1 - One or more tests failed
  • 2 - Invalid environment state
  • 3 - SSH connection failed

See Also