Skip to content

Latest commit

 

History

History
293 lines (196 loc) · 10.6 KB

README.md

File metadata and controls

293 lines (196 loc) · 10.6 KB

Proyecto de Aprovisionamiento de Notebooks con Ansible

Molecule CI License Ansible Platforms

🎯 Resumen Ejecutivo

Este proyecto utiliza Ansible para automatizar la configuración completa de notebooks para los distintos perfiles de trabajo en Adhoc.

✨ Nuevo: Tests automatizados con Molecule para todos los roles. Ver documentación de testing.

Para información interna más detallada sobre los objetivos, procedimientos y pendientes, consulta el documento de diseño interno.

Filosofía y Distribuciones Soportadas

Este playbook está diseñado para funcionar sobre instalaciones limpias de Debian (12+) y Ubuntu (22.04+).

Priorizamos el uso de Debian para mantener un sistema base limpio, estable y libre de las decisiones comerciales de Canonical (como la imposición de snap). Sin embargo, el playbook es totalmente compatible con las versiones LTS de Ubuntu.

Cómo Funciona: Perfiles de Provisión

El sistema está organizado en perfiles jerárquicos. Cada perfil incluye la configuración del anterior, creando un sistema incremental:

  • funcional (Base): Contiene el software y la configuración esencial para todos los miembros de la empresa (navegadores, herramientas de comunicación, seguridad básica, etc.).
  • developer: Incluye el perfil funcional y añade todas las herramientas de desarrollo (Docker, VS Code, Git, Python, kubectl, etc.).
  • freelance_developer: Perfil acotado para developers freelance. Reutiliza tareas puntuales de funcional y developer pero evita configuración corporativa (por ejemplo branding/desktop) y corre solo un subset de herramientas de desarrollo.
  • sysadmin: Incluye ambos perfiles anteriores y añade herramientas de administración de sistemas e infraestructura (pulumi, gcloud, VirtualBox, etc.).

🧭 Qué perfil elegir (rápido)

Perfil Ideal para Incluye (alto nivel) Evita / notas Ejecutar
funcional Usuarios generales Base de workstation Puede incluir desktop/branding corporativo ansible-playbook local.yml -K --verbose
developer Devs internos funcional + tooling completo de dev (VS Code, Git, Python, Docker, kubectl, etc.) Incluye desktop/branding corporativo (por herencia de funcional) ansible-playbook local.yml -e "profile_override=developer" -K --verbose
freelance_developer Devs freelance/externos Entorno de dev + cloud/containers (subset controlado) Evita desktop/branding corporativo ansible-playbook local.yml -e "profile_override=freelance_developer" -K --verbose
sysadmin SRE/infra developer + herramientas extra de infra/SRE Perfil más amplio (instala más herramientas) ansible-playbook local.yml -e "profile_override=sysadmin" -K --verbose

Más detalle (qué hace cada perfil y cómo elegirlo): docs/PROFILES.md

🚀 Uso Rápido (Método Recomendado para Equipos Nuevos)

Este es el método preferido para configurar una notebook desde cero. Un único script se encarga de todo.

  1. Descargar el script de arranque:

    curl -L -o adhoc-ansible https://raw.githubusercontent.com/ingadhoc/ansible_notebooks/main/launch_project.sh

    (El comando descarga launch_project.sh pero lo guarda como adhoc-ansible.)

  2. Darle permisos de ejecución:

    chmod +x adhoc-ansible

  3. Ejecutar el script con sudo:

    sudo ./adhoc-ansible

El script te guiará con un menú interactivo para que selecciones tu perfil. Se encargará de instalar Ansible, sus dependencias, clonar este repositorio y ejecutar el playbook por ti. Al finalizar, solo necesitarás reiniciar.

📖 Ejecución Manual y Opciones

Si necesitas volver a ejecutar el playbook en un equipo ya configurado o quieres usar opciones avanzadas, puedes hacerlo manualmente.

Requisitos previos:

  • Tener git y ansible (vía pipx) instalados.
  • Haber clonado este repositorio.

Comandos:

# Navegar al directorio del proyecto
cd ~/repositorios/ansible_notebooks

# (Opcional) Actualizar el repositorio a la última versión
git pull

# (Opcional) Instalar/actualizar las colecciones de Ansible
ansible-galaxy install -r collections/requirements.yml

# --- Ejecutar el perfil deseado ---

# Para el rol Funcional (perfil por defecto)
ansible-playbook local.yml -K --verbose

# Para el rol Developer (ejecutará funcional -> developer)
ansible-playbook local.yml -e "profile_override=developer" -K --verbose

# Para el rol Freelance Developer (perfil acotado)
ansible-playbook local.yml -e "profile_override=freelance_developer" -K --verbose

# Para el rol SysAdmin (ejecutará funcional -> developer -> sysadmin)
ansible-playbook local.yml -e "profile_override=sysadmin" -K --verbose

# Para instalar solo herramientas de deploy rápido (ej. kubectl)
ansible-playbook local.yml --tags "deploy" -K --verbose

👩‍💻 Guía para Developers Freelance (perfil freelance_developer)

Este perfil está pensado para developers externos que necesitan un entorno de desarrollo completo, pero sin configuraciones corporativas (por ejemplo branding/desktop) ni tareas que no aportan al trabajo diario.

Qué hace (resumen):

  • Instala herramientas de desarrollo y CLI: Git, Python, VS Code, Docker, kubectl, gcloud, GH CLI, etc.
  • Aplica un subconjunto de tareas de funcional y developer de forma controlada.

Qué NO hace (intencionalmente):

  • No aplica branding corporativo.
  • No fuerza configuración de GNOME/extensiones de escritorio.

Recomendado (bootstrap):

curl -L -o adhoc-ansible https://raw.githubusercontent.com/ingadhoc/ansible_notebooks/main/launch_project.sh
chmod +x adhoc-ansible
sudo ./adhoc-ansible

Luego elegir Freelance Developer en el menú.

Manual (si ya tiene el repo):

cd ~/repositorios/ansible_notebooks
ansible-playbook local.yml -e "profile_override=freelance_developer" -K --verbose

Para una guía lista para copiar/pegar y enviar a externos, ver: docs/FREELANCE_DEVELOPER.md

✅ Tareas Post-Instalación (Manuales)

Después de que Ansible termine, hay algunas acciones que requieren tu intervención para iniciar sesión en servicios específicos.

  1. Configurar SSH en GitHub:

    • La CLI de gh ya estará instalada. Inicia sesión con:

      gh auth login

    • Sube tu nueva clave SSH. El playbook la creó con el formato id_rsa_TU_USUARIO@NOMBRE_HOST.pub.

      # Reemplaza 'dib' y 'dib-adhoc-nb-debian' con tu usuario y hostname
gh ssh-key add ~/.ssh/id_rsa_dib@dib-adhoc-nb-debian.pub

  2. Iniciar sesión en Docker Hub:

    docker login
# username: adhocsa
# password: (usar un token generado en Docker Hub)

  3. Iniciar sesión en Google Cloud (si aplica):

    gcloud auth login

🧪 Testing y Desarrollo

Este proyecto utiliza Molecule con Docker para tests automatizados. Los tests se ejecutan automáticamente en GitHub Actions para cada push y pull request.

Ejecutar tests localmente

# Crear un entorno virtual (recomendado, evita PEP 668 en Debian/Ubuntu)
python3 -m venv .venv
source .venv/bin/activate

# Instalar dependencias de testing
pip install -r requirements-dev.txt

# Instalar colecciones
ansible-galaxy install -r collections/requirements.yml

# Ejecutar tests de un rol específico
./test-role.sh funcional

# Ejecutar todos los tests
./test-role.sh all

# Solo verificar requisitos
./test-role.sh --check

# Solo ejecutar linting
./test-role.sh --lint

Testing con múltiples distribuciones

Por defecto, los tests ejecutan en Debian 12 y Ubuntu 22.04. Para probar con distribuciones adicionales:

# Usar el Makefile para comandos específicos
make test-ubuntu2404      # Test solo Ubuntu 24.04 LTS
make test-debian13        # Test solo Debian 13 (si disponible)
make test-all-distros     # Test todas las distros configuradas

# Ver plataformas disponibles
make list-platforms

# Descargar imágenes Docker necesarias
make docker-pull-images

Distribuciones soportadas:

  • ✅ Debian 12 (Bookworm) - Producción, por defecto
  • ✅ Ubuntu 22.04 LTS (Jammy) - Producción, por defecto
  • 🟡 Debian 13 (Trixie) - Testing (algunas limitaciones)
  • ✅ Ubuntu 24.04 LTS (Noble) - Producción, estable

Para agregar más distribuciones a tus tests, consulta:

Para más información sobre testing, consulta docs/TESTING.md.

🔧 Troubleshooting

Debian: usuario is not in the sudoers file

En una instalación mínima de Debian, es posible que tu usuario no sea añadido al grupo sudo. Para arreglarlo:

# 1. Conviértete en root
su -

# 2. Añade tu usuario al grupo sudo (reemplaza 'tu_usuario')
gpasswd -a tu_usuario sudo

# 3. Sal de la sesión de root y reinicia la máquina
exit
sudo reboot

Error: Paquete no disponible en Debian 13

# Solución: Agregar a packages_exclude_debian_13 en vars.yml
packages_exclude_debian_13:
  - nombre-paquete-problemático

Error: "Image not found" en Molecule

# Verificar que la imagen existe
docker search geerlingguy/docker-debian13

# Si no existe, comentar esa plataforma en molecule.yml

📚 Documentación Adicional