Test Environment Service - Guía Completa de Uso

Versión: 1.0.0 Fecha: 2025-10-06 Estado: Producción

Índice

Introducción
Requerimientos
Configuración Inicial
Guía de Uso Rápido
Tipos de Entornos
Comandos Detallados
Topologías y Templates
Casos de Uso Prácticos
Integración CI/CD
Troubleshooting

Introducción

El Test Environment Service es un sistema de testing containerizado integrado en el orquestador que permite probar:

✅ Taskservs individuales - Test aislado de un servicio
✅ Servidores completos - Simulación de servidor con múltiples taskservs
✅ Clusters multi-nodo - Topologías distribuidas (Kubernetes, etcd, etc.)

¿Por qué usar Test Environments?

Sin gestión manual de Docker - Todo automatizado
Entornos aislados - Redes dedicadas, sin interferencias
Realista - Simula configuraciones de producción
Rápido - Un comando para crear, probar y limpiar
CI/CD Ready - Fácil integración en pipelines

Requerimientos

Obligatorios

1. Docker

Versión mínima: Docker 20.10+

# Verificar instalación
docker --version

# Verificar que funciona
docker ps

# Verificar recursos disponibles
docker info | grep -E "CPUs|Total Memory"

Instalación según OS:

macOS:

# Opción 1: Docker Desktop
brew install --cask docker

# Opción 2: OrbStack (más ligero)
brew install orbstack

Linux (Ubuntu/Debian):

# Instalar Docker
curl -fsSL https://get.docker.com -o get-docker.sh
sudo sh get-docker.sh

# Añadir usuario al grupo docker
sudo usermod -aG docker $USER
newgrp docker

# Verificar
docker ps

Linux (Fedora):

sudo dnf install docker
sudo systemctl enable --now docker
sudo usermod -aG docker $USER

2. Orchestrator

Puerto por defecto: 8080

# Verificar que el orquestador está corriendo
curl http://localhost:9090/health

# Si no está corriendo, iniciarlo
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background

# Verificar logs
tail -f ./data/orchestrator.log

3. Nushell

Versión mínima: 0.107.1+

# Verificar versión
nu --version

Recursos Recomendados

Tipo de Test	CPU	Memoria	Disk
Single taskserv	2 cores	4 GB	10 GB
Server simulation	4 cores	8 GB	20 GB
Cluster 3-nodos	8 cores	16 GB	40 GB

Verificar recursos disponibles:

# En el sistema
docker info | grep -E "CPUs|Total Memory"

# Recursos usados actualmente
docker stats --no-stream

Opcional pero Recomendado

jq - Para procesar JSON: brew install jq / apt install jq
glow - Para visualizar docs: brew install glow
k9s - Para gestionar K8s tests: brew install k9s

Configuración Inicial

1. Iniciar el Orquestador

# Navegar al directorio del orquestador
cd provisioning/platform/orchestrator

# Opción 1: Iniciar en background (recomendado)
./scripts/start-orchestrator.nu --background

# Opción 2: Iniciar en foreground (para debug)
cargo run --release

# Verificar que está corriendo
curl http://localhost:9090/health
# Respuesta esperada: {"success":true,"data":"Orchestrator is healthy"}

2. Verificar Docker

# Test básico de Docker
docker run --rm hello-world

# Verificar que hay imágenes base (se descargan automáticamente)
docker images | grep ubuntu

3. Configurar Variables de Entorno (opcional)

# Añadir a tu ~/.bashrc o ~/.zshrc
export PROVISIONING_ORCHESTRATOR="http://localhost:9090"
export PROVISIONING_PATH="/ruta/a/provisioning"

4. Verificar Instalación

# Test completo del sistema
provisioning test quick redis

# Debe mostrar:
# 🧪 Quick test for redis
# ✅ Environment ready, running tests...
# ✅ Quick test completed

Guía de Uso Rápido

Test Rápido (Recomendado para empezar)

# Un solo comando: crea, prueba, limpia
provisioning test quick <taskserv>

# Ejemplos
provisioning test quick kubernetes
provisioning test quick postgres
provisioning test quick redis

Flujo Completo Paso a Paso

# 1. Crear entorno
provisioning test env single kubernetes --auto-start

# Retorna: environment_id = "abc-123-def-456"

# 2. Listar entornos
provisioning test env list

# 3. Ver status
provisioning test env status abc-123-def-456

# 4. Ver logs
provisioning test env logs abc-123-def-456

# 5. Limpiar
provisioning test env cleanup abc-123-def-456

Con Auto-Cleanup

# Se limpia automáticamente al terminar
provisioning test env single redis \
  --auto-start \
  --auto-cleanup

Tipos de Entornos

1. Single Taskserv

Test de un solo taskserv en container aislado.

Cuándo usar:

Desarrollo de nuevo taskserv
Validación de configuración
Debug de problemas específicos

Comando:

provisioning test env single <taskserv> [opciones]

# Opciones
--cpu <millicores>        # Default: 1000 (1 core)
--memory <MB>             # Default: 2048 (2GB)
--base-image <imagen>     # Default: ubuntu:22.04
--infra <nombre>          # Contexto de infraestructura
--auto-start              # Ejecutar tests automáticamente
--auto-cleanup            # Limpiar al terminar

Ejemplos:

# Test básico
provisioning test env single kubernetes

# Con más recursos
provisioning test env single postgres --cpu 4000 --memory 8192

# Test completo automatizado
provisioning test env single redis --auto-start --auto-cleanup

# Con contexto de infra
provisioning test env single cilium --infra prod-cluster

2. Server Simulation

Simula servidor completo con múltiples taskservs.

Cuándo usar:

Test de integración entre taskservs
Validar dependencias
Simular servidor de producción

Comando:

provisioning test env server <nombre> <taskservs> [opciones]

# taskservs: lista entre corchetes [ts1 ts2 ts3]

Ejemplos:

# Server con stack de aplicación
provisioning test env server app-01 [containerd kubernetes cilium]

# Server de base de datos
provisioning test env server db-01 [postgres redis]

# Con auto-resolución de dependencias
provisioning test env server web-01 [kubernetes] --auto-start
# Automáticamente incluye: containerd, etcd (dependencias de k8s)

3. Cluster Topology

Cluster multi-nodo con topología definida.

Cuándo usar:

Test de clusters distribuidos
Validar HA (High Availability)
Test de failover
Simular producción real

Comando:

# Desde template predefinido
provisioning test topology load <template> | test env cluster <tipo> [opciones]

Ejemplos:

# Cluster Kubernetes 3 nodos (1 CP + 2 workers)
provisioning test topology load kubernetes_3node | \
  test env cluster kubernetes --auto-start

# Cluster etcd 3 miembros
provisioning test topology load etcd_cluster | \
  test env cluster etcd

# Cluster K8s single-node
provisioning test topology load kubernetes_single | \
  test env cluster kubernetes

Comandos Detallados

Gestión de Entornos

`test env create`

Crear entorno desde configuración custom.

provisioning test env create <config> [opciones]

# Opciones
--infra <nombre>      # Infraestructura context
--auto-start          # Iniciar tests automáticamente
--auto-cleanup        # Limpiar al finalizar

`test env list`

Listar todos los entornos activos.

provisioning test env list

# Salida ejemplo:
# id                    env_type          status    containers
# abc-123               single_taskserv   ready     1
# def-456               cluster_topology  running   3

`test env get`

Obtener detalles completos de un entorno.

provisioning test env get <env-id>

# Retorna JSON con:
# - Configuración completa
# - Estados de containers
# - IPs asignadas
# - Resultados de tests
# - Logs

`test env status`

Ver status resumido de un entorno.

provisioning test env status <env-id>

# Muestra:
# - ID y tipo
# - Status actual
# - Containers y sus IPs
# - Resultados de tests

`test env run`

Ejecutar tests en un entorno.

provisioning test env run <env-id> [opciones]

# Opciones
--tests [test1 test2]   # Tests específicos (default: todos)
--timeout <segundos>    # Timeout para tests

Ejemplo:

# Ejecutar todos los tests
provisioning test env run abc-123

# Tests específicos
provisioning test env run abc-123 --tests [connectivity health]

# Con timeout
provisioning test env run abc-123 --timeout 300

`test env logs`

Ver logs del entorno.

provisioning test env logs <env-id>

# Muestra:
# - Logs de creación
# - Logs de containers
# - Logs de tests
# - Errores si los hay

`test env cleanup`

Limpiar y destruir entorno.

provisioning test env cleanup <env-id>

# Elimina:
# - Containers
# - Red dedicada
# - Volúmenes
# - Estado del orquestador

Topologías

`test topology list`

Listar templates disponibles.

provisioning test topology list

# Salida:
# name
# kubernetes_3node
# kubernetes_single
# etcd_cluster
# containerd_test
# postgres_redis

`test topology load`

Cargar configuración de template.

provisioning test topology load <nombre>

# Retorna configuración JSON/TOML
# Se puede usar con pipe para crear cluster

Quick Test

`test quick`

Test rápido todo-en-uno.

provisioning test quick <taskserv> [opciones]

# Hace:
# 1. Crea entorno single taskserv
# 2. Ejecuta tests
# 3. Muestra resultados
# 4. Limpia automáticamente

# Opciones
--infra <nombre>   # Contexto de infraestructura

Ejemplos:

# Test rápido de kubernetes
provisioning test quick kubernetes

# Con contexto
provisioning test quick postgres --infra prod-db

Topologías y Templates

Templates Predefinidos

El sistema incluye 5 templates listos para usar:

1. kubernetes_3node - Cluster K8s HA

# Configuración:
# - 1 Control Plane: etcd, kubernetes, containerd (2 cores, 4GB)
# - 2 Workers: kubernetes, containerd, cilium (2 cores, 2GB cada uno)
# - Red: 172.20.0.0/16

# Uso:
provisioning test topology load kubernetes_3node | \
  test env cluster kubernetes --auto-start

2. kubernetes_single - K8s All-in-One

# Configuración:
# - 1 Nodo: etcd, kubernetes, containerd, cilium (4 cores, 8GB)
# - Red: 172.22.0.0/16

# Uso:
provisioning test topology load kubernetes_single | \
  test env cluster kubernetes

3. etcd_cluster - Cluster etcd

# Configuración:
# - 3 Miembros etcd (1 core, 1GB cada uno)
# - Red: 172.21.0.0/16
# - Cluster configurado automáticamente

# Uso:
provisioning test topology load etcd_cluster | \
  test env cluster etcd --auto-start

4. containerd_test - Containerd standalone

# Configuración:
# - 1 Nodo: containerd (1 core, 2GB)
# - Red: 172.23.0.0/16

# Uso:
provisioning test topology load containerd_test | \
  test env cluster containerd

5. postgres_redis - Stack de DBs

# Configuración:
# - 1 PostgreSQL: (2 cores, 4GB)
# - 1 Redis: (1 core, 1GB)
# - Red: 172.24.0.0/16

# Uso:
provisioning test topology load postgres_redis | \
  test env cluster databases --auto-start

Crear Template Custom

Crear archivo TOML:

# /path/to/my-topology.toml

[mi_cluster]
name = "Mi Cluster Custom"
description = "Descripción del cluster"
cluster_type = "custom"

[[mi_cluster.nodes]]
name = "node-01"
role = "primary"
taskservs = ["postgres", "redis"]
[mi_cluster.nodes.resources]
cpu_millicores = 2000
memory_mb = 4096
[mi_cluster.nodes.environment]
POSTGRES_PASSWORD = "secret"

[[mi_cluster.nodes]]
name = "node-02"
role = "replica"
taskservs = ["postgres"]
[mi_cluster.nodes.resources]
cpu_millicores = 1000
memory_mb = 2048

[mi_cluster.network]
subnet = "172.30.0.0/16"
dns_enabled = true

Copiar a config:

cp my-topology.toml provisioning/config/test-topologies.toml

Usar:

provisioning test topology load mi_cluster | \
  test env cluster custom --auto-start

Casos de Uso Prácticos

Desarrollo de Taskservs

Escenario: Desarrollando nuevo taskserv

# 1. Test inicial
provisioning test quick my-new-taskserv

# 2. Si falla, debug con logs
provisioning test env single my-new-taskserv --auto-start
ENV_ID=$(provisioning test env list | tail -1 | awk '{print $1}')
provisioning test env logs $ENV_ID

# 3. Iterar hasta que funcione

# 4. Cleanup
provisioning test env cleanup $ENV_ID

Validación Pre-Despliegue

Escenario: Validar taskserv antes de producción

# 1. Test con configuración de producción
provisioning test env single kubernetes \
  --cpu 4000 \
  --memory 8192 \
  --infra prod-cluster \
  --auto-start

# 2. Revisar resultados
provisioning test env status <env-id>

# 3. Si pasa, desplegar a producción
provisioning taskserv create kubernetes --infra prod-cluster

Test de Integración

Escenario: Validar stack completo

# Test server con stack de aplicación
provisioning test env server app-stack [nginx postgres redis] \
  --cpu 6000 \
  --memory 12288 \
  --auto-start \
  --auto-cleanup

# El sistema:
# 1. Resuelve dependencias automáticamente
# 2. Crea containers con recursos especificados
# 3. Configura red aislada
# 4. Ejecuta tests de integración
# 5. Limpia todo al terminar

Test de Clusters HA

Escenario: Validar cluster Kubernetes

# 1. Crear cluster 3-nodos
provisioning test topology load kubernetes_3node | \
  test env cluster kubernetes --auto-start

# 2. Obtener env-id
ENV_ID=$(provisioning test env list | grep kubernetes | awk '{print $1}')

# 3. Ver status del cluster
provisioning test env status $ENV_ID

# 4. Ejecutar tests específicos
provisioning test env run $ENV_ID --tests [cluster-health node-ready]

# 5. Logs si hay problemas
provisioning test env logs $ENV_ID

# 6. Cleanup
provisioning test env cleanup $ENV_ID

Troubleshooting de Producción

Escenario: Reproducir issue de producción

# 1. Crear entorno idéntico a producción
# Copiar config de prod a topology custom

# 2. Cargar y ejecutar
provisioning test topology load prod-replica | \
  test env cluster app --auto-start

# 3. Reproducir el issue

# 4. Debug con logs detallados
provisioning test env logs <env-id>

# 5. Fix y re-test

# 6. Cleanup
provisioning test env cleanup <env-id>

Integración CI/CD

GitLab CI

# .gitlab-ci.yml

stages:
  - test
  - deploy

variables:
  ORCHESTRATOR_URL: "http://orchestrator:9090"

# Test stage
test-taskservs:
  stage: test
  image: nushell:latest
  services:
    - docker:dind
  before_script:
    - cd provisioning/platform/orchestrator
    - ./scripts/start-orchestrator.nu --background
    - sleep 5  # Wait for orchestrator
  script:
    # Quick tests
    - provisioning test quick kubernetes
    - provisioning test quick postgres
    - provisioning test quick redis
    # Cluster test
    - provisioning test topology load kubernetes_3node | test env cluster kubernetes --auto-start --auto-cleanup
  after_script:
    # Cleanup any remaining environments
    - provisioning test env list | tail -n +2 | awk '{print $1}' | xargs -I {} provisioning test env cleanup {}

# Integration test
test-integration:
  stage: test
  script:
    - provisioning test env server app-stack [nginx postgres redis] --auto-start --auto-cleanup

# Deploy only if tests pass
deploy-production:
  stage: deploy
  script:
    - provisioning taskserv create kubernetes --infra production
  only:
    - main
  dependencies:
    - test-taskservs
    - test-integration

GitHub Actions

# .github/workflows/test.yml

name: Test Infrastructure

on:
  push:
    branches: [ main, develop ]
  pull_request:
    branches: [ main ]

jobs:
  test-taskservs:
    runs-on: ubuntu-latest

    services:
      docker:
        image: docker:dind

    steps:
      - uses: actions/checkout@v3

      - name: Setup Nushell
        run: |
          cargo install nu

      - name: Start Orchestrator
        run: |
          cd provisioning/platform/orchestrator
          cargo build --release
          ./target/release/provisioning-orchestrator &
          sleep 5
          curl http://localhost:9090/health

      - name: Run Quick Tests
        run: |
          provisioning test quick kubernetes
          provisioning test quick postgres
          provisioning test quick redis

      - name: Run Cluster Test
        run: |
          provisioning test topology load kubernetes_3node | \
            test env cluster kubernetes --auto-start --auto-cleanup

      - name: Cleanup
        if: always()
        run: |
          for env in $(provisioning test env list | tail -n +2 | awk '{print $1}'); do
            provisioning test env cleanup $env
          done

Jenkins Pipeline

// Jenkinsfile

pipeline {
    agent any

    environment {
        ORCHESTRATOR_URL = 'http://localhost:9090'
    }

    stages {
        stage('Setup') {
            steps {
                sh '''
                    cd provisioning/platform/orchestrator
                    ./scripts/start-orchestrator.nu --background
                    sleep 5
                '''
            }
        }

        stage('Quick Tests') {
            parallel {
                stage('Kubernetes') {
                    steps {
                        sh 'provisioning test quick kubernetes'
                    }
                }
                stage('PostgreSQL') {
                    steps {
                        sh 'provisioning test quick postgres'
                    }
                }
                stage('Redis') {
                    steps {
                        sh 'provisioning test quick redis'
                    }
                }
            }
        }

        stage('Integration Test') {
            steps {
                sh '''
                    provisioning test env server app-stack [nginx postgres redis] \
                      --auto-start --auto-cleanup
                '''
            }
        }

        stage('Cluster Test') {
            steps {
                sh '''
                    provisioning test topology load kubernetes_3node | \
                      test env cluster kubernetes --auto-start --auto-cleanup
                '''
            }
        }
    }

    post {
        always {
            sh '''
                # Cleanup all test environments
                provisioning test env list | tail -n +2 | awk '{print $1}' | \
                  xargs -I {} provisioning test env cleanup {}
            '''
        }
    }
}

Troubleshooting

Problemas Comunes

1. “Failed to connect to Docker”

Error:

Error: Failed to connect to Docker daemon

Solución:

# Verificar que Docker está corriendo
docker ps

# Si no funciona, iniciar Docker
# macOS
open -a Docker

# Linux
sudo systemctl start docker

# Verificar que tu usuario está en el grupo docker
groups | grep docker
sudo usermod -aG docker $USER
newgrp docker

2. “Connection refused (port 8080)”

Error:

Error: Connection refused

Solución:

# Verificar orquestador
curl http://localhost:9090/health

# Si no responde, iniciar
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --background

# Verificar logs
tail -f ./data/orchestrator.log

# Verificar que el puerto no está ocupado
lsof -i :9090

3. “Out of memory / resources”

Error:

Error: Cannot allocate memory

Solución:

# Verificar recursos disponibles
docker info | grep -E "CPUs|Total Memory"
docker stats --no-stream

# Limpiar containers antiguos
docker container prune -f

# Limpiar imágenes no usadas
docker image prune -a -f

# Limpiar todo el sistema
docker system prune -af --volumes

# Ajustar límites de Docker (Docker Desktop)
# Settings → Resources → Aumentar Memory/CPU

4. “Network already exists”

Error:

Error: Network test-net-xxx already exists

Solución:

# Listar redes
docker network ls | grep test

# Eliminar red específica
docker network rm test-net-xxx

# Eliminar todas las redes de test
docker network ls | grep test | awk '{print $1}' | xargs docker network rm

5. “Image pull failed”

Error:

Error: Failed to pull image ubuntu:22.04

Solución:

# Verificar conexión a internet
ping docker.io

# Pull manual
docker pull ubuntu:22.04

# Si persiste, usar mirror
# Editar /etc/docker/daemon.json
{
  "registry-mirrors": ["https://mirror.gcr.io"]
}

# Reiniciar Docker
sudo systemctl restart docker

6. “Environment not found”

Error:

Error: Environment abc-123 not found

Solución:

# Listar entornos activos
provisioning test env list

# Verificar logs del orquestador
tail -f provisioning/platform/orchestrator/data/orchestrator.log

# Reiniciar orquestador si es necesario
cd provisioning/platform/orchestrator
./scripts/start-orchestrator.nu --stop
./scripts/start-orchestrator.nu --background

Debug Avanzado

Ver logs de container específico

# 1. Obtener environment
provisioning test env get <env-id>

# 2. Copiar container_id del output

# 3. Ver logs del container
docker logs <container-id>

# 4. Ver logs en tiempo real
docker logs -f <container-id>

Ejecutar comandos dentro del container

# Obtener container ID
CONTAINER_ID=$(provisioning test env get <env-id> | jq -r '.containers[0].container_id')

# Entrar al container
docker exec -it $CONTAINER_ID bash

# O ejecutar comando directo
docker exec $CONTAINER_ID ps aux
docker exec $CONTAINER_ID cat /etc/os-release

Inspeccionar red

# Obtener network ID
NETWORK_ID=$(provisioning test env get <env-id> | jq -r '.network_id')

# Inspeccionar red
docker network inspect $NETWORK_ID

# Ver containers conectados
docker network inspect $NETWORK_ID | jq '.[0].Containers'

Verificar recursos del container

# Stats de un container
docker stats <container-id> --no-stream

# Stats de todos los containers de test
docker stats $(docker ps --filter "label=type=test_container" -q) --no-stream

Mejores Prácticas

1. Siempre usar Auto-Cleanup en CI/CD

# ✅ Bueno
provisioning test quick kubernetes

# ✅ Bueno
provisioning test env single postgres --auto-start --auto-cleanup

# ❌ Malo (deja basura si falla el pipeline)
provisioning test env single postgres --auto-start

2. Ajustar Recursos según Necesidad

# Development: recursos mínimos
provisioning test env single redis --cpu 500 --memory 512

# Integration: recursos medios
provisioning test env single postgres --cpu 2000 --memory 4096

# Production-like: recursos completos
provisioning test env single kubernetes --cpu 4000 --memory 8192

3. Usar Templates para Clusters

# ✅ Bueno: reutilizable, documentado
provisioning test topology load kubernetes_3node | test env cluster kubernetes

# ❌ Malo: configuración manual, propenso a errores
# Crear config manual cada vez

4. Nombrar Entornos Descriptivamente

# Al crear custom configs, usar nombres claros
{
  "type": "server_simulation",
  "server_name": "prod-db-replica-test",  # ✅ Descriptivo
  ...
}

5. Limpiar Regularmente

# Script de limpieza (añadir a cron)
#!/usr/bin/env nu

# Limpiar entornos viejos (>1 hora)
provisioning test env list |
  where created_at < (date now | date subtract 1hr) |
  each {|env| provisioning test env cleanup $env.id }

# Limpiar Docker
docker system prune -f

Referencia Rápida

Comandos Esenciales

# Quick test
provisioning test quick <taskserv>

# Single taskserv
provisioning test env single <taskserv> [--auto-start] [--auto-cleanup]

# Server simulation
provisioning test env server <name> [taskservs]

# Cluster from template
provisioning test topology load <template> | test env cluster <type>

# List & manage
provisioning test env list
provisioning test env status <id>
provisioning test env logs <id>
provisioning test env cleanup <id>

REST API

# Create
curl -X POST http://localhost:9090/test/environments/create \
  -H "Content-Type: application/json" \
  -d @config.json

# List
curl http://localhost:9090/test/environments

# Status
curl http://localhost:9090/test/environments/{id}

# Run tests
curl -X POST http://localhost:9090/test/environments/{id}/run

# Logs
curl http://localhost:9090/test/environments/{id}/logs

# Cleanup
curl -X DELETE http://localhost:9090/test/environments/{id}

Recursos Adicionales

Documentación de Arquitectura: docs/architecture/test-environment-architecture.md
API Reference: docs/api/test-environment-api.md
Topologías: provisioning/config/test-topologies.toml
Código Fuente: provisioning/platform/orchestrator/src/test_*.rs

Soporte

Issues: https://github.com/tu-org/provisioning/issues Documentación: provisioning help test Logs: provisioning/platform/orchestrator/data/orchestrator.log

Versión del documento: 1.0.0 Última actualización: 2025-10-06

Keyboard shortcuts

Provisioning Platform Documentation