proxmox/docs/archive/DEPLOYMENT_VALIDATION_REQUIREMENTS.md

Deployment Validation Requirements

This document outlines the comprehensive validation requirements to ensure deployment correctness.

1. Node and Config Files Accuracy

Requirements

• All configuration files must be copied to correct locations
• File permissions must be correct (owned by besu:besu)
• File contents must be valid (JSON/TOML syntax)
• Files must be consistent across all nodes of the same type

Validation Checks

• ✅ Verify all required files exist at expected paths
• ✅ Verify correct config file type per node type:
  • Validators: config-validator.toml (NOT sentry or RPC config)
  • Sentries: config-sentry.toml
  • RPC: config-rpc-public.toml
• ✅ Verify file ownership and permissions
• ✅ Verify files are identical across nodes (genesis.json, permissions-nodes.toml, static-nodes.json)

Scripts

• validate-deployment-comprehensive.sh - Comprehensive file validation
• check-prerequisites.sh - Pre-deployment file existence check

---

2. Validator Information in Genesis.json

Requirements

• Genesis.json must have valid QBFT configuration
• For dynamic validators: No validators array in QBFT config
• extraData field must exist and be properly formatted (hex string)
• Genesis.json must be identical across all nodes

Validation Checks

• ✅ QBFT configuration present
• ✅ extraData field exists and is valid hex format
• ✅ For dynamic validators: No static validators array
• ✅ Genesis.json is consistent across all containers

Scripts

• check-prerequisites.sh - Validates genesis.json structure before deployment
• validate-deployment-comprehensive.sh - Validates genesis.json after deployment

---

3. Correct Number of Nodes and Templates

Requirements

• Exactly 5 validators (VMID 106-110)
• Exactly 4 sentries (VMID 111-114)
• Exactly 3 RPC nodes (VMID 115-117)
• All nodes use correct OS template (Ubuntu 22.04)
• Each node type uses correct configuration template

Validation Checks

• ✅ Node count matches expected (5 validators, 4 sentries, 3 RPC)
• ✅ Validators use config-validator.toml
• ✅ Sentries use config-sentry.toml
• ✅ RPC nodes use config-rpc-public.toml
• ✅ No incorrect config files present (e.g., sentry config on validator)

Scripts

• validate-deployment-comprehensive.sh - Validates node count and template usage
• deploy-besu-nodes.sh - Ensures correct template is used during deployment

---

4. No Inconsistencies or Gaps

Requirements

• All files must be consistent across nodes
• No missing files that should be present
• No incorrect files that shouldn't be present
• Configuration files must be valid and parseable

Validation Checks

• ✅ All required files present on all nodes
• ✅ Configuration files are identical where expected
• ✅ No orphaned or incorrect files
• ✅ File syntax validation (JSON/TOML)
• ✅ Validator keys present and properly formatted

Scripts

• validate-deployment-comprehensive.sh - Comprehensive consistency check
• copy-besu-config-with-nodes.sh - Ensures files are copied correctly

---

5. Genesis.json Changes Minimal and Validated

Requirements

• Genesis.json should not be unnecessarily modified
• If extraData is modified, it must be valid hex format
• Changes must be required (not arbitrary)
• Changes must be validated before deployment

Validation Checks

• ✅ Genesis.json syntax is valid JSON
• ✅ extraData field format is valid (hex string or empty)
• ✅ QBFT configuration is present and correct
• ✅ Genesis.json matches expected structure
• ✅ No unnecessary modifications detected

Scripts

• check-prerequisites.sh - Validates genesis.json before deployment
• validate-deployment-comprehensive.sh - Validates genesis.json after deployment

---

Validation Flow

Pre-Deployment (check-prerequisites.sh)

1. Validate all source files exist
2. Validate genesis.json structure and content
3. Validate validator keys count and format
4. Validate configuration file existence

Post-Deployment (validate-deployment-comprehensive.sh)

1. Validate node count and types
2. Validate correct templates used
3. Validate all files copied to correct locations
4. Validate genesis.json consistency and content
5. Validate validator keys
6. Validate configuration file consistency

---

Error Handling

• Errors: Prevent deployment or require fixes
• Warnings: Allow deployment but notify for review

Error Examples

• Missing required files
• Wrong config file type for node
• Invalid genesis.json structure
• Node count mismatch
• Invalid validator address format

Warning Examples

• Optional file missing
• Configuration difference that doesn't block deployment
• Non-critical validation issue

---

Usage

# Pre-deployment validation
./scripts/validation/check-prerequisites.sh /path/to/smom-dbis-138

# Post-deployment validation
./scripts/validation/validate-deployment-comprehensive.sh

---

Integration with Deployment

The comprehensive validation is automatically run in Phase 4 of deploy-validated-set.sh:

./scripts/deployment/deploy-validated-set.sh --source-project /path/to/smom-dbis-138

If validation fails, deployment stops and errors are reported.

---

Last Updated: $(date)