Proyecto de Aprovisionamiento de Notebooks con Ansible

🎯 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 Distribución Soportada

Este playbook está diseñado para funcionar sobre instalaciones limpias de Debian 13 (Trixie).

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).

⚠️ Entorno de escritorio requerido: GNOME Los perfiles funcional, developer y sysadmin configuran extensiones, ajustes visuales y comportamientos específicos de GNOME. El playbook asume que GNOME está instalado y activo como entorno de escritorio. Instalar sobre KDE u otro entorno producirá errores en las tareas de configuración de escritorio. El perfil freelance_developer omite intencionalmente estas configuraciones de escritorio.

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`

Árbol de decisión rápido:

¿Necesitás herramientas de infra/SRE (Pulumi/Helm/VPN/KVM/etc.)? → sysadmin
¿Sos freelance/externo y querés evitar branding/escritorio corporativo? → freelance_developer
¿Vas a desarrollar y necesitás tooling completo (VS Code, Git, Python, Docker, kubectl)? → developer
Si nada de lo anterior, lo mínimo común → funcional

🚀 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.

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.)

Darle permisos de ejecución:
```
chmod +x adhoc-ansible
```
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 Funcional + Wine + MicroSIP (asistencia telefónica)
ansible-playbook local.yml -e "asistencia=true" -K --verbose

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

ℹ️ Nota sobre Asistencia: Agregar -e "asistencia=true" a cualquier perfil instala Wine + MicroSIP automáticamente. Ejemplo:
# Developer + asistencia
ansible-playbook local.yml -e "profile_override=developer" -e "asistencia=true" -K --verbose

Volver a correr el playbook en una notebook ya aprovisionada

Los ajustes personales se aplican solo en el primer aprovisionamiento: escritorio (GNOME, atajos, dock, fondo, teclado), ~/.ssh/config, la configuración de VS Code y los dotfiles (.bash_aliases, .tmux). Después cada persona los ajusta, y una corrida nueva no los pisa. La marca queda en /etc/ansible/facts.d/provisioned.fact.

Variable	Por defecto	Para qué
`reset_user_prefs=true`	`false`	Vuelve a aplicar los ajustes personales.
`adhoc_battery_thresholds=false`	`true`	No instala el límite de carga (75–80 %). Para quien usa la notebook casi siempre sin cargador.
`funcional_sysadmin_access=false`	`false` en el perfil `sysadmin`, `true` en el resto	No crea el usuario `sysadmin` de IT ni abre SSH.

Para ver qué cambiaría antes de aplicarlo:

ansible-playbook local.yml -e "profile_override=sysadmin" --check --diff -K

👩‍💻 Developers Freelance (perfil `freelance_developer`)

Perfil acotado para developers externos.

Instala: entorno de desarrollo (Git, Python, VS Code, GH CLI) + tooling de contenedores/cloud (Docker, kubectl, gcloud).
NO instala (a propósito): branding corporativo ni configuración de escritorio GNOME.

# Bootstrap interactivo (elegir "Freelance Developer" en el menú) — ver "Uso Rápido"
# o, si ya tenés el repo:
ansible-playbook local.yml -e "profile_override=freelance_developer" -K --verbose

Post-instalación según necesidad: gh auth login, docker login, gcloud auth login.

✅ 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.

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
```

Iniciar sesión en Docker Hub:

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

Iniciar sesión en Google Cloud (si aplica):
```
gcloud auth login
```

🔄 Reasignación de Laptop

Cuando una notebook con el usuario genérico adhoc se asigna a un empleado nuevo, el playbook assign_laptop.yml renombra el usuario (y su grupo, home y sudoers) y cambia el hostname de forma remota, sin necesidad de reinstalar el sistema.

Prerrequisitos:

La clave privada que corresponde a roles/funcional/files/sysadmin.pub, que el perfil funcional autoriza para el usuario sysadmin de cada notebook. Para confirmar que es la correcta, las dos huellas tienen que coincidir:
```
ssh-keygen -lf roles/funcional/files/sysadmin.pub
ssh-keygen -lf ~/.ssh/<clave_privada>
```
Estar en la red interna: el firewall (UFW) del perfil funcional solo acepta SSH desde 192.168.2.0/24 (la red de la oficina).
La notebook encendida y accesible en la red. La IP se consulta en la notebook con hostname -I.
Una primera conexión SSH manual, para aceptar la huella del host. Sin ese paso Ansible falla con Host key verification failed:
```
ssh -i ~/.ssh/<clave_privada> sysadmin@<ip>
```

⚠️ Conviene conectar la notebook por cable. El playbook mueve el home del usuario: si la conexión se corta a mitad de camino, el usuario queda renombrado a medias y hay que arreglarlo a mano.

Comando:

ansible-playbook assign_laptop.yml \
  -i <ip>, \
  -e "old_user=adhoc new_user=<usuario> full_name='Nombre Apellido' hostname=<usuario>-adhoc-nb" \
  --private-key ~/.ssh/<clave_privada> \
  -u sysadmin

⚠️ Nota la coma después de <ip> — es requerida por Ansible para inventarios inline.

Qué hace:

Cierra la sesión y mata los procesos del usuario anterior (loginctl, pkill).
Renombra el usuario y mueve su home (usermod).
Renombra el grupo primario (groupmod).
Actualiza el archivo sudoers si existe.
Mueve la preferencia de sesión (Xorg) de AccountsService al nuevo usuario.
Actualiza los bookmarks de GTK y el wallpaper al nuevo home.
Configura el user.name de Git globalmente.
Cambia el hostname, también en /etc/hosts.

Autoservicio (sin server)

Las notebooks de repuesto que se preparan con un usuario genérico (adhoc o adhoc-adhoc-nb, ver funcional_asignar_generic_users) quedan con el autoservicio instalado por roles/funcional/tasks/asignar.yml (tag asignar). Quien recibe la notebook la prende, entra con el genérico y completa usuario y nombre completo en la ventana que aparece. No hace falta nadie de DevOps ni estar en la oficina.

Qué pasa por detrás:

asignar-pc.sh (autostart de GNOME) pide los datos y llama por sudo a asignar-run.sh, el único comando que el genérico puede correr sin clave (/etc/sudoers.d/asignar).
asignar-run.sh valida new_user (minúsculas, números y -; no puede existir como usuario ni como grupo) y arma hostname=<new_user>-adhoc-nb, y lanza ansible-pull en una unit transitoria de systemd (asignar-pc) que corre como root fuera de la sesión.
asignar.yml bloquea la cuenta y pone el cartel en GDM, corre assign_laptop.yml, borra el autostart y el sudoers del autoservicio, desbloquea la cuenta y cambia el cartel a "Listo". No reinicia. El mantenimiento (apt upgrade y limpieza) no va acá: lo corre fleet-health como job asignado desde Odoo.

Repo y rama que usa ansible-pull salen de /etc/default/asignar-pc (funcional_asignar_repo_url, funcional_asignar_repo_branch). Mientras dura la asignación la cuenta queda bloqueada y GDM muestra el cartel "Configurando tu equipo" sin lista de usuarios; al terminar dice "Listo" con el usuario para ingresar (funcional_asignar_banner, activado por defecto). El cartel desaparece y la lista de usuarios vuelve en el próximo arranque.

Si la asignación falla a mitad de camino o tarda más de 30 minutos, asignar-unit.sh desbloquea la cuenta y el login avisa que hay que contactar a DevOps y con qué usuario se puede entrar. Si la notebook se apaga en el medio, hace lo mismo al arrancar (asignar-recuperar.service, condicionada a la marca /var/lib/asignar/en-curso). Sin internet, la ventana lo dice y no cierra la sesión.

Los scripts quedan fijos en la imagen y ansible-pull baja el main del momento, que corre como root: main tiene que seguir protegida, y las variables que asignar-run.sh pasa por -e no se cambian sin pensar en las notebooks ya preparadas.

Diagnóstico en la notebook: journalctl -u asignar-pc y /var/log/asignar.log.

🔋 Energía y Batería

El playbook configura esto solo, en cualquier perfil (tag power). Se saltea entero en equipos sin batería.

Umbrales de carga 75/80%: la batería deja de cargar al 80% y no reanuda hasta bajar del 75%. Es deliberado — mantener una batería al 100% permanentemente la degrada mucho más rápido. Si necesitás autonomía completa para un viaje:
```
echo 100 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold
```
Eso vuelve a 80 en el próximo boot. Para cambiarlo de forma permanente, pasale -e "adhoc_battery_charge_stop=100" al playbook.

Si usás la notebook casi siempre sin cargador, pasale -e "adhoc_battery_thresholds=false" y el playbook no instala los umbrales. No saca los que ya están instalados; para eso:
```
sudo systemctl disable --now adhoc-battery-thresholds.service
echo 100 | sudo tee /sys/class/power_supply/BAT0/charge_control_end_threshold
```
Salud de la batería: queda expuesta como fact de Ansible, consultable en cualquier momento:
```
sudo /etc/ansible/facts.d/battery.fact
# {"full": 35800000, "design": 45730000, "cycle_count": 504, "health_pct": 78.3}
```
health_pct es la capacidad actual contra la de fábrica. Por debajo del 80% conviene evaluar el reemplazo; el playbook lo avisa al correr.

Si el equipo tiene TLP instalado (no lo instala el playbook), además se asegura de que el turbo boost se restaure al enchufar, y en equipos que cargan por USB-C se instala un timer que conmuta el perfil de TLP según la fuente de energía.

🧪 Testing y Desarrollo

Este proyecto utiliza Molecule con Docker para tests automatizados sobre Debian 13 (Trixie), que corren en GitHub Actions para cada push y pull request.

make setup              # entorno de testing (venv + dependencias + colecciones)
./test-role.sh funcional   # test de un rol (o: developer | sysadmin | all)
make help               # listar todos los comandos disponibles

Guía completa (setup, flujo iterativo, cómo agregar tests, troubleshooting, CI): 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

La batería no carga más allá del 80%

Es intencional, no es una falla. Ver Energía y Batería para el motivo y cómo subir el tope si necesitás autonomía completa.

Error: Paquete no disponible en Debian 13

# Solución: Agregar a funcional_packages_exclude_debian_13 en vars/main.yml
funcional_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

Errores relacionados a GNOME (dconf, extensiones, GDM)

Si el playbook falla con errores como dconf error, gnome-shell not found o similares, la causa es que el entorno de escritorio GNOME no está instalado. Este proyecto requiere GNOME para los perfiles funcional, developer y sysadmin.

Solución: Reinstalar el sistema operativo seleccionando GNOME como entorno de escritorio.

# En Debian, si ya tenés el sistema base podés instalar GNOME:
sudo apt install task-gnome-desktop

Si necesitás correr el playbook en un entorno sin GNOME (por ejemplo, un servidor headless), podés saltear las tareas de escritorio:

ansible-playbook local.yml -K -e "skip_gnome_tasks=true"

📚 Documentación Adicional

docs/TESTING.md — Guía completa de testing con Molecule
specifications.md — Arquitectura, patrones y reglas de contribución
Makefile — Todos los comandos disponibles

Name		Name	Last commit message	Last commit date
.devcontainer		.devcontainer
.github		.github
collections		collections
docs		docs
roles		roles
.gitignore		.gitignore
.markdownlint.json		.markdownlint.json
.pre-commit-config.yaml		.pre-commit-config.yaml
.secrets.baseline		.secrets.baseline
.yamllint		.yamllint
CHANGELOG.md		CHANGELOG.md
LICENSE		LICENSE
Makefile		Makefile
README.md		README.md
ansible.cfg		ansible.cfg
asignar.yml		asignar.yml
assign_laptop.yml		assign_laptop.yml
hosts		hosts
launch_project.sh		launch_project.sh
local.yml		local.yml
requirements-dev.txt		requirements-dev.txt
specifications.md		specifications.md
test-role.sh		test-role.sh

Navigation Menu

Repository navigation

About

Repository files navigation

Proyecto de Aprovisionamiento de Notebooks con Ansible

🎯 Resumen Ejecutivo

Filosofía y Distribución Soportada

Cómo Funciona: Perfiles de Provisión

🧭 Qué perfil elegir (rápido)

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

📖 Ejecución Manual y Opciones

Volver a correr el playbook en una notebook ya aprovisionada

👩‍💻 Developers Freelance (perfil `freelance_developer`)

✅ Tareas Post-Instalación (Manuales)

🔄 Reasignación de Laptop

Autoservicio (sin server)

🔋 Energía y Batería

🧪 Testing y Desarrollo

🔧 Troubleshooting

Debian: `usuario is not in the sudoers file`

La batería no carga más allá del 80%

Error: Paquete no disponible en Debian 13

Error: "Image not found" en Molecule

Errores relacionados a GNOME (dconf, extensiones, GDM)

📚 Documentación Adicional

About

Releases

Packages

Used by

Contributors

Languages

Latest commit

History

Folders and files

Repository files navigation

Proyecto de Aprovisionamiento de Notebooks con Ansible

🎯 Resumen Ejecutivo

Filosofía y Distribución Soportada

Cómo Funciona: Perfiles de Provisión

🧭 Qué perfil elegir (rápido)

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

📖 Ejecución Manual y Opciones

Volver a correr el playbook en una notebook ya aprovisionada

👩‍💻 Developers Freelance (perfil freelance_developer)

✅ Tareas Post-Instalación (Manuales)

🔄 Reasignación de Laptop

Autoservicio (sin server)

🔋 Energía y Batería

🧪 Testing y Desarrollo

🔧 Troubleshooting

Debian: usuario is not in the sudoers file

La batería no carga más allá del 80%

Error: Paquete no disponible en Debian 13

Error: "Image not found" en Molecule

Errores relacionados a GNOME (dconf, extensiones, GDM)

📚 Documentación Adicional

About

Resources

Stars

Watchers

Forks

Releases

Packages

Used by

Contributors

Languages

👩‍💻 Developers Freelance (perfil `freelance_developer`)

Debian: `usuario is not in the sudoers file`