Ansible playbook para configurar workstations de Mikroways

Este repositorio es un playbook de ansible que deja listo un desktop para trabajar inmediatamente luego de correrlo. Al momento, depende de dos roles:

• mikroways.workstation: role público con aplicaciones usadas y configuración del shell
• mikroways.tools: role privado con un set de herramientas que usamos a diario y fueron exclusivamente desarrolladas por Mikroways. Es opcional.

Instalar roles y requerimientos

Para correr los playbooks se necesita Ansible instalado en un entorno virtual Python, gestionado con uv. El procedimiento varía según el estado del equipo:

Primera vez en una máquina nueva

Si uv no está instalado todavía (el propio playbook lo instala via asdf), instalalo directamente y luego instalá las dependencias:

curl -LsSf https://astral.sh/uv/install.sh | sh
uv sync

Opcionalmente, para evitar errores por rate limiting de GitHub durante la instalación de plugins de asdf, exportá el token antes de correr el playbook (ver Token de GitHub):

export GITHUB_API_TOKEN=...

Equipo con asdf y direnv

Si ya corriste este playbook antes, uv y direnv estarán instalados. Al entrar al directorio, direnv activa el entorno automáticamente:

## Opcional: configurar token de GitHub para evitar rate limiting
cp .envrc.private.sample .envrc.private
# editar .envrc.private y completar GITHUB_API_TOKEN

direnv allow    # solo la primera vez o cuando cambie el .envrc
uv sync

Esto deja ansible-playbook disponible en el PATH sin necesidad de activar el venv manualmente. Vagrant también funciona directamente.

Luego de instalar ansible, instalar los roles. roles-mw.yml ya incluye todo lo de roles.yml, por lo que los miembros de Mikroways solo necesitan correr un comando:

## Si no pertenece a Mikroways:
uv run ansible-galaxy role install -r ansible/requirements/roles.yml

## Si pertenece a Mikroways (incluye el comando anterior):
uv run ansible-galaxy role install -r ansible/requirements/roles-mw.yml

Nota: Ansible ignora el ansible.cfg del repositorio si el directorio tiene permisos de escritura para todos (world-writable). Para evitar el warning y que se cargue la configuración correctamente, correr una vez:

chmod o-w .

Para actualizar los roles:

git pull
uv sync

## Si no pertenece a Mikroways:
uv run ansible-galaxy role install -r ansible/requirements/roles.yml --force-with-deps --force

## Si pertenece a Mikroways (incluye el comando anterior):
uv run ansible-galaxy role install -r ansible/requirements/roles-mw.yml --force-with-deps --force

Ejecutar playbook en local

Antes de continuar, es recomendable realizar resguardos de toda configuración del usuario donde se ejecute el playbook o realizarlo en un usuario nuevo.

Para ejecutar el playbook en caso de que instalemos desde 0 o que realizemos una actualización debemos ejecutar el siguiente comando:

## Si no pertenece a Mikroways:
uv run ansible-playbook ansible/playbooks/vm-setup.yml -i ansible/inventory/localhost.yml -K

## Si pertenece a Mikroways (incluye el playbook anterior):
uv run ansible-playbook ansible/playbooks/vm-setup-mw.yml -i ansible/inventory/localhost.yml -K

Si ya tenés la workstation configurada y solo querés instalar o actualizar las herramientas privadas de Mikroways:

uv run ansible-playbook ansible/playbooks/vm-setup-mw.yml -i ansible/inventory/localhost.yml -K \
  -e mw_tools_only=true

Consideraciones

• Si se está utilizando Pop!_Os se debe agregar además -e ansible_distribution=Ubuntu

• Se aconseja probar el playbook con vagrant para verificar si el SO utilizado funcionará con el playbook.

• Si ya utilizabas dotfiles, considerá subir tus cambios porque podrías perder alguna de tus personalizaciones.

Funcionamiento

El playbook sigue la siguiente serie de pasos:

1. Instala paquetes en el sistema tales como docker o podman utilizando el gestor de paquetes.
2. Instala herramientas especificas en el directorio: ~/.mikroways/bin con un wrapper para descargar binarios.
3. Configura asdf y prepara una serie de plugins y versiones de productos.
4. Crea las configuraciones propias del entorno dejándolas a disposición en el directorio ~/.mikroways/dotfiles.
5. (opcional) Si se indico la instalación de las herramientas de Mikroways, entonces estas se instalaran en la carpeta ~/.mikroways/tools.

Recomendaciones

Una vez instalado tu desktop con este playbook, te recomendamos que agregues en $HOME/.envrc la siguiente configuración:

use asdf

De esta forma, la performance del uso de asdf se ve mejorada por no usar los shims sino la resolución del shim correspondiente.

Por otro lado, si trabajando con kubectl deja de funcionar el autocomplete, entonces proveemos el alias mw-fix-kube-completion que debería actualizar el autocomplete que se suele romper entre diferentes versiones de kubectl que se manejan con asdf.

Token de GitHub

El token puede ser Classic o Fine-grained. Para este uso no se necesita ningún scope ni permiso — solo autenticación.

Nota: La organización Mikroways bloquea fine-grained tokens con lifetime mayor a 366 días. Si usás fine-grained, configurá máximo 365 días de expiración.

• Classic: github.com/settings/tokens/new

  • Note: mw-asdf-rate-limit
  • Expiration: No expiration
  • Sin seleccionar ningún scope

• Fine-grained: github.com/settings/personal-access-tokens/new

  • Token name: mw-asdf-rate-limit
  • Description: Token para evitar rate limiting de GitHub al instalar plugins de asdf
  • Expiration: 365 days
  • Repository access: Public repositories
  • Sin permisos adicionales

Usar este playbook en un bastion

Ansible corre desde tu equipo y se conecta al destino vía SSH. El equipo destino no necesita tener Ansible instalado.

Si querés usar directamente este playbook en una vm determinada, proponemos usar el siguiente comando:

uv run ansible-playbook ansible/playbooks/vm-setup.yml [-K] \
  -i SOME_USER@10.10.10.10, \
  -e ansible_user=SOME_USER

Dependiendo del usuario remoto, en el ejemplo SOME_USER, debe ser especificado tanto en la opción -i como en ansible_user. Además, para usar un inventario inline es fundamental el uso de la coma al final de la IP.

¿Como probar el entorno en Vagrant?

## Para crear la maquina virtual
vagrant up

## Para ingresar y verificar el entorno
vagrant ssh

Si no tenés direnv activo, ansible-playbook no estará en el PATH. En ese caso activá el venv antes: source .venv/bin/activate && vagrant up

Para probar también las herramientas privadas de Mikroways (vm-setup-mw.yml), una vez que la VM esté levantada:

vagrant provision --provision-with mw