|
1 | 1 | --- |
2 | 2 | id: DOC-ARQ-DEVCONTAINER-HOST-VAGRANT |
3 | | -estado: propuesta |
| 3 | +estado: activo |
4 | 4 | propietario: equipo-plataforma-devops |
5 | | -ultima_actualizacion: 2025-11-19 |
| 5 | +ultima_actualizacion: 2025-11-20 |
6 | 6 | relacionados: ["DOC-DEVOPS-INDEX", "DOC-INFRA-INDEX", "DOC-ARQ-INFRA"] |
7 | 7 | --- |
8 | | -# Canvas técnico — DevContainer Host con Vagrant |
| 8 | +# Canvas de Arquitectura — DevContainer Host con Vagrant (sin Docker en el host físico) |
9 | 9 |
|
10 | | -Documento de referencia para estandarizar el host de DevContainers y pipelines CI/CD en una VM gestionada por Vagrant cuando el equipo no puede instalar Docker en sus laptops. |
| 10 | +Documento de referencia para operar DevContainers y pipelines CI/CD en una VM gestionada por Vagrant cuando el workstation no puede instalar Docker. Esta versión consolida el modelo de arquitectura, flujo operativo y ejemplos base para reproducir el host. |
11 | 11 |
|
12 | | -## 1. Identificación |
13 | | -- **Nombre del artefacto:** DevContainer Host con Vagrant |
| 12 | +## 1. Identificación del artefacto |
| 13 | +- **Nombre:** Arquitectura del DevContainer Host con Vagrant |
| 14 | +- **Propósito:** Definir la arquitectura técnica para ejecutar DevContainers sin instalar Docker en el host físico del desarrollador. |
14 | 15 | - **Proyecto:** IACT / Plataforma de Desarrollo y CI/CD |
| 16 | +- **Autor:** Equipo de Plataforma / DevOps |
15 | 17 | - **Versión:** 1.0 |
16 | | -- **Responsable:** Equipo de Plataforma / DevOps |
17 | | -- **Estado:** Propuesta técnica inicial |
18 | | - |
19 | | -## 2. Propósito del DevContainer Host |
20 | | -- Centralizar la ejecución de DevContainers y pipelines CI/CD en una sola VM. |
21 | | -- Mantener un único lugar donde se instala el runtime de contenedores (Podman rootless o Docker dentro de la VM). |
22 | | -- Servir como fuente de verdad del entorno (SO, toolchains, dependencias del sistema, configuración de usuario y permisos). |
23 | | -- Permitir que el host físico (workstation) opere sin Docker, conectándose por SSH. |
24 | | - |
25 | | -## 3. Descripción general |
26 | | -### 3.1 Topología lógica |
| 18 | +- **Estado:** Activo |
| 19 | + |
| 20 | +## 2. Descripción general |
| 21 | +Esta arquitectura define un modelo donde: |
| 22 | +- Los desarrolladores **no instalan Docker** en su máquina física. |
| 23 | +- Todo el entorno de contenedores se ejecuta dentro de una **VM administrada por Vagrant**. |
| 24 | +- La VM (DevContainer Host) es la **fuente de verdad del entorno**, donde viven toolchains, runtime de contenedores (Podman o Docker dentro de la VM), DevContainers y, opcionalmente, el runner de CI/CD. |
| 25 | +- VS Code se conecta a la VM por **Remote SSH** para abrir y ejecutar el DevContainer. |
| 26 | +- Los repositorios se ubican en `/srv/projects` y las imágenes/configuración de contenedores en `/srv/devcontainers`, con almacenamiento de runtime en `/var/lib/containers`. |
| 27 | + |
| 28 | +## 3. Objetivo técnico |
| 29 | +Asegurar **environmental consistency**, **operational equivalence**, **deterministic execution** y **unified toolchain** entre el DevContainer de desarrollo, los pipelines de CI/CD y la VM DevContainer Host, todo sin instalar Docker en el host físico. |
| 30 | + |
| 31 | +## 4. Componentes de la arquitectura |
| 32 | +### 4.1 Workstation del desarrollador |
| 33 | +- SO: Windows / macOS / Linux |
| 34 | +- Software: VS Code + Remote SSH + Dev Containers |
| 35 | +- Restricción: **No tiene Docker instalado** |
| 36 | + |
| 37 | +### 4.2 DevContainer Host (VM gestionada por Vagrant) |
| 38 | +- SO: Ubuntu Server LTS (20.04 o 22.04) |
| 39 | +- Recursos: 4 vCPUs, 8 GB RAM, disco 80–120 GB dinámico |
| 40 | +- Funciones: |
| 41 | + - Ejecuta el runtime de contenedores (Podman rootless o Docker dentro de la VM) |
| 42 | + - Aloja DevContainers, toolchains y repositorios |
| 43 | + - Puede ejecutar el runner de CI/CD (self-hosted) |
| 44 | + |
| 45 | +### 4.3 Runtime de contenedores dentro de la VM |
| 46 | +- **Opción recomendada:** Podman rootless |
| 47 | +- **Opción alternativa:** Docker solo dentro de la VM |
| 48 | +- Compatibilidad: imágenes OCI, DevContainer CLI, integración estable con VS Code |
| 49 | + |
| 50 | +### 4.4 DevContainer |
| 51 | +- Definido por `devcontainer.json`, Dockerfile (si aplica) y scripts de bootstrap |
| 52 | +- Incluye toolchain completo, dependencias de sistema y de aplicación |
| 53 | +- Reutilizado tanto por desarrollo como por CI/CD |
| 54 | + |
| 55 | +### 4.5 Runner CI/CD (opcional) |
| 56 | +- GitHub Actions Self-Hosted Runner o GitLab Runner |
| 57 | +- Ejecuta pruebas unitarias, integración, builds y análisis estático |
| 58 | +- Usa la misma imagen base y runtime que los DevContainers |
| 59 | + |
| 60 | +## 5. Flujo de trabajo |
| 61 | +### 5.1 Desarrollo local (workstation sin Docker) |
| 62 | +1. El desarrollador ejecuta `vagrant up iact-devcontainer-host` para provisionar la VM. |
| 63 | +2. VS Code se conecta por SSH a `dev@iact-devcontainer-host` usando Remote SSH. |
| 64 | +3. Se abre el proyecto en `/srv/projects/iact` dentro de la VM y se inicia el DevContainer. |
| 65 | +4. Pruebas, builds y depuración se ejecutan dentro del contenedor en la VM. |
| 66 | + |
| 67 | +### 5.2 CI/CD |
| 68 | +1. El runner CI/CD está instalado dentro de la VM. |
| 69 | +2. El pipeline utiliza la misma imagen e instrucciones del DevContainer. |
| 70 | +3. Las pipelines se ejecutan dentro del mismo entorno que desarrollo, reutilizando caches y toolchains. |
| 71 | + |
| 72 | +## 6. Diagrama de arquitectura (ASCII) |
27 | 73 | ``` |
28 | | -+---------------------------+ |
29 | | -| Workstation desarrollador | |
30 | | -| (Windows / macOS / Linux) | |
31 | | -| | |
32 | | -| - VS Code | |
33 | | -| - Ext. Remote SSH | |
34 | | -| - Ext. Dev Containers | |
35 | | -| | |
36 | | -| SIN Docker en el host | |
37 | | -+-------------+-------------+ |
| 74 | ++-----------------------------------------------------------+ |
| 75 | +| Workstation del Desarrollador (sin Docker) | |
| 76 | +|-----------------------------------------------------------| |
| 77 | +| VS Code + Remote SSH | |
| 78 | +| VS Code + Dev Containers | |
| 79 | ++-------------+---------------------------------------------+ |
38 | 80 | | |
39 | 81 | | SSH |
40 | 82 | v |
41 | | -+---------------------------+ |
42 | | -| Vagrant VM (DevContainer Host) | |
43 | | -| SO: Ubuntu Server LTS | |
44 | | -| | |
45 | | -| - Runtime contenedores: | |
46 | | -| Podman rootless o | |
47 | | -| Docker (solo en la VM) | |
48 | | -| - Toolchains compartidos | |
49 | | -| - Runner CI/CD (self-hosted) | |
50 | | -+---------------------------+ |
| 83 | ++-----------------------------------------------------------+ |
| 84 | +| Vagrant VM: DevContainer Host | |
| 85 | +|-----------------------------------------------------------| |
| 86 | +| SO: Ubuntu Server | |
| 87 | +| Runtime Contenedores (Podman rootless / Docker en VM) | |
| 88 | +| | |
| 89 | +| +----------------------+ +-----------------------+ | |
| 90 | +| | DevContainer | | Runner CI/CD | | |
| 91 | +| | - toolchain | | - usa misma imagen | | |
| 92 | +| | - dependencias | | - ejecuta pruebas | | |
| 93 | +| +----------------------+ +-----------------------+ | |
| 94 | ++-----------------------------------------------------------+ |
| 95 | +``` |
| 96 | + |
| 97 | +## 7. Ejemplos de código |
| 98 | +### 7.1 Ejemplo de `Vagrantfile` |
| 99 | +```ruby |
| 100 | +Vagrant.configure("2") do |config| |
| 101 | + config.vm.define "iact-devcontainer-host" do |vm| |
| 102 | + vm.vm.box = "ubuntu/focal64" |
| 103 | + vm.vm.hostname = "iact-devcontainer-host" |
| 104 | + vm.vm.network "private_network", ip: "192.168.56.10" |
| 105 | + |
| 106 | + vm.vm.provider "virtualbox" do |vb| |
| 107 | + vb.memory = "8192" |
| 108 | + vb.cpus = 4 |
| 109 | + end |
| 110 | + |
| 111 | + vm.vm.provision "shell", path: "provision.sh" |
| 112 | + end |
| 113 | +end |
| 114 | +``` |
| 115 | + |
| 116 | +### 7.2 Ejemplo de `provision.sh` |
| 117 | +```bash |
| 118 | +#!/usr/bin/env bash |
| 119 | +set -e |
| 120 | + |
| 121 | +apt update |
| 122 | +apt install -y git curl build-essential uidmap |
| 123 | + |
| 124 | +# Instalación de Podman rootless |
| 125 | +apt install -y podman |
| 126 | + |
| 127 | +# Crear usuario dev |
| 128 | +useradd -m -s /bin/bash dev || true |
| 129 | +echo "dev ALL=(ALL) NOPASSWD:ALL" >> /etc/sudoers.d/dev |
| 130 | + |
| 131 | +# Configuración del entorno rootless |
| 132 | +loginctl enable-linger dev |
| 133 | +``` |
| 134 | + |
| 135 | +### 7.3 Estructura base de DevContainer |
| 136 | +```json |
| 137 | +{ |
| 138 | + "name": "IACT Dev Container", |
| 139 | + "image": "localhost/iact-devcontainer:latest", |
| 140 | + "remoteUser": "dev", |
| 141 | + "postCreateCommand": "./bootstrap.sh" |
| 142 | +} |
51 | 143 | ``` |
52 | 144 |
|
53 | | -### 3.2 Rol operativo |
54 | | -- La VM aloja imágenes e instancias de DevContainer para desarrollo y CI/CD. |
55 | | -- Los repositorios viven en `/srv/projects` dentro de la VM y se montan en los contenedores. |
56 | | -- Los artefactos de runtime se almacenan en `/var/lib/containers` (Podman) o el directorio equivalente de Docker dentro de la VM. |
57 | | - |
58 | | -## 4. Especificación de la Vagrant VM como DevContainer Host |
59 | | -### 4.1 Características de la VM |
60 | | -- **Nombre lógico:** `iact-devcontainer-host` |
61 | | -- **Proveedor:** VirtualBox, Libvirt o Hyper-V (según el entorno del desarrollador). |
62 | | -- **Sistema operativo:** Ubuntu 20.04 LTS o 22.04 LTS (alineado con CI/CD). |
63 | | -- **Recursos mínimos:** 4 vCPUs, 8 GB RAM (ajustable), disco dinámico 80–120 GB. |
64 | | - |
65 | | -### 4.2 Roles dentro de la VM |
66 | | -- **DevContainer Host:** Ejecuta el runtime de contenedores y aloja imágenes/instancias de DevContainer. |
67 | | -- **CI/CD Execution Node (opcional recomendado):** Runner self-hosted (GitHub Actions o GitLab CI) que reutiliza las mismas imágenes que el DevContainer de desarrollo. |
68 | | - |
69 | | -## 5. Componentes dentro de la Vagrant VM |
70 | | -### 5.1 Runtime de contenedores |
71 | | -- **Opción preferida:** Podman rootless para minimizar dependencias privilegiadas. |
72 | | -- **Opción alternativa:** Docker instalado únicamente dentro de la VM. |
73 | | -- **Requisitos:** Compatibilidad OCI y soporte de DevContainer CLI/VS Code. |
74 | | - |
75 | | -### 5.2 Toolchain base |
76 | | -- Paquetes: `build-essential`, `git`, `curl`, `wget`, `python3`, `python3-venv` (extensible según el proyecto, p. ej. Node/Go). |
77 | | -- Usuario de trabajo: `dev` o equivalente para sesiones SSH y contenedores rootless. |
78 | | - |
79 | | -### 5.3 Almacenamiento |
80 | | -- Directorios clave: `/srv/devcontainers` (imágenes/configs base), `/srv/projects` (repositorios), `/var/lib/containers` (runtime). |
81 | | -- Recomendación: discos virtuales separados si se requiere aislamiento adicional o mayor rendimiento de I/O. |
82 | | - |
83 | | -## 6. Flujo de trabajo con Vagrant |
84 | | -### 6.1 Provisión inicial |
85 | | -1. El desarrollador clona el repositorio de infra que incluye `Vagrantfile` y scripts de provisión. |
86 | | -2. Ejecuta `vagrant up iact-devcontainer-host`. |
87 | | -3. Vagrant crea la VM, instala el SO base y aplica los scripts de provisión para: |
88 | | - - Instalar el runtime de contenedores. |
89 | | - - Configurar el usuario `dev`. |
90 | | - - Instalar toolchains base. |
91 | | -4. Resultado: VM lista para usarse como host de DevContainer. |
92 | | - |
93 | | -### 6.2 Uso diario (desarrollo) |
94 | | -1. El desarrollador abre VS Code en su host físico. |
95 | | -2. Con Remote SSH se conecta a `dev@iact-devcontainer-host`. |
96 | | -3. Dentro de la VM abre el repo en `/srv/projects/iact` y lanza el DevContainer definido en `devcontainer.json`. |
97 | | -4. Desarrollo, pruebas y depuración ocurren dentro del DevContainer. |
98 | | - |
99 | | -### 6.3 Uso en CI/CD |
100 | | -1. Registrar un runner self-hosted dentro de la misma VM (servicio `runner-iact-devcontainer`). |
101 | | -2. El pipeline usa el mismo runtime de contenedores e imágenes base que el DevContainer de desarrollo. |
102 | | -3. Ejecuta pruebas unitarias, de integración, builds y análisis estático con el mismo toolchain. |
103 | | - |
104 | | -## 7. Objetivos técnicos |
105 | | -- **Environmental consistency:** VM provisionada con configuración versionada para replicar CI/CD. |
106 | | -- **Operational equivalence:** Mismo runtime de contenedores y misma imagen base para desarrollo y pipelines. |
107 | | -- **Deterministic execution:** Scripts de bootstrap idempotentes reutilizados por dev y CI/CD. |
108 | | -- **Unified toolchain:** Toolchain definido una sola vez en la VM e imagen DevContainer. |
109 | | - |
110 | | -## 8. Riesgos específicos con Vagrant |
111 | | -- Desfase de versiones de la VM entre desarrolladores y CI/CD. |
112 | | -- Overhead de recursos en la workstation (RAM/CPU) al ejecutar la VM. |
113 | | -- Complejidad para sincronizar cambios en los scripts de provisión. |
114 | | - |
115 | | -## 9. Mitigaciones |
116 | | -- Versionar estrictamente `Vagrantfile` y scripts de provisión (p. ej. `provision.sh`, Ansible). |
117 | | -- Política de actualización clara: cuándo regenerar la VM (`vagrant destroy && vagrant up`). |
118 | | -- Documentar comandos estándar y troubleshooting básico de la VM. |
119 | | - |
120 | | -## 10. Checklist mínimo de implementación |
121 | | -- [ ] Definir `Vagrantfile` para `iact-devcontainer-host`. |
122 | | -- [ ] Definir scripts de provisión (runtime contenedores, usuario `dev`, toolchains base). |
123 | | -- [ ] Probar creación de VM en una workstation de desarrollo. |
124 | | -- [ ] Configurar acceso SSH desde VS Code (Remote SSH). |
125 | | -- [ ] Probar DevContainer de desarrollo en la VM. |
126 | | -- [ ] Registrar y probar runner de CI/CD dentro de la VM. |
127 | | -- [ ] Documentar el flujo completo en este archivo. |
| 145 | +## 8. Objetivos de calidad |
| 146 | +- **Reproducibilidad:** mismo entorno para desarrollo y CI/CD. |
| 147 | +- **Aislamiento:** el host físico no maneja contenedores; solo la VM. |
| 148 | +- **Portabilidad:** workstation sin dependencias pesadas. |
| 149 | +- **Extensibilidad:** se puede añadir runner CI/CD fácilmente. |
| 150 | +- **Mantenibilidad:** `Vagrantfile` y scripts de provisión versionados. |
| 151 | + |
| 152 | +## 9. Riesgos y mitigaciones |
| 153 | +- **Inconsistencia entre VMs:** versionar `Vagrantfile` y provisioners; programar regeneración (`vagrant destroy && vagrant up`). |
| 154 | +- **Degradación de rendimiento:** ajustar RAM/CPU; evitar Docker Desktop; preferir Podman rootless. |
| 155 | +- **Configuración duplicada:** el DevContainer define el toolchain una sola vez para desarrollo y CI/CD. |
| 156 | + |
| 157 | +## 10. Checklist de implementación |
| 158 | +- [ ] Crear `Vagrantfile` para `iact-devcontainer-host`. |
| 159 | +- [ ] Crear `provision.sh` (runtime OCI y usuario `dev`). |
| 160 | +- [ ] Instalar runtime OCI (Podman) dentro de la VM. |
| 161 | +- [ ] Configurar VS Code Remote SSH. |
| 162 | +- [ ] Crear DevContainer base y validarlo en la VM. |
| 163 | +- [ ] Registrar runner de CI/CD usando la misma imagen. |
| 164 | +- [ ] Documentar flujo completo y troubleshooting de la VM. |
| 165 | +- [ ] Automatizar actualización/rotación de la VM. |
0 commit comments