Tower CLI 3.3.11 - Supporto AAP 2.6

🎯 Sommario Modifiche

Questa versione di ansible-tower-cli (v3.3.11) aggiunge supporto completo per Ansible Automation Platform (AAP) 2.6 con:

Auto-rilevamento API - Rileva automaticamente se usa /api/v2/ (legacy) o /api/controller/v2/ (AAP 2.x)
Instance Resource Estesa - Supporto completo per nodi control, execution e hop con nuovi comandi
Gateway Resource - Nuova risorsa per gestire Gateway Service Nodes di AAP 2.6

🏗️ Architettura AAP 2.6

AAP 2.6 introduce una nuova architettura API con due componenti separati:

1. Controller API (`/api/controller/v2/`)

Gestisce l'automation controller (ex Ansible Tower):

Instances (nodi control, execution, hop)
Instance Groups
Jobs, Job Templates
Inventories, Projects
Credentials, Organizations
Workflows

2. Gateway API (`/api/gateway/v1/`)

Gestisce il gateway service (nuovo in AAP 2.x):

Service Nodes - Nodi del gateway
Service Clusters - Cluster di servizi
Services - Servizi registrati
Routes - Route tra servizi
Authenticators - Autenticazione

✅ Cosa è Stato Modificato

File Modificati:

1. `tower_cli/api.py`

Modifiche:

Aggiunto metodo _detect_api_type() per auto-rilevamento AAP 2.x
Modificato get_prefix() per supportare /api/controller/v2/
Cache del tipo API rilevato per performance

Come funziona:

# Al primo accesso, rileva automaticamente:
# 1. Prova /api/controller/v2/ping/ (AAP 2.x)
# 2. Se fallisce, usa /api/v2/ (Legacy Tower)
# 3. Caches il risultato per richieste successive

2. `tower_cli/resources/instance.py`

Modifiche:

Aggiunti campi mesh topology: node_type, node_state, listener_port
Aggiunti campi monitoring: cpu, memory, last_seen
Nuovo comando: tower-cli instance health - Verifica salute istanza/gateway
Nuovo comando: tower-cli instance jobs - Elenca job in esecuzione

Campi Aggiunti:

node_type              # control, execution, hop (gateway)
node_state             # ready, unavailable, installed
listener_port          # Porta receptor mesh (default: 27199)
cpu                    # Utilizzo CPU %
memory                 # Utilizzo memoria bytes
last_seen              # Timestamp ultimo contatto

3. `tower_cli/resources/gateway.py` ⭐ NUOVO

Nuova Risorsa per Gateway Service Nodes di AAP 2.6:

Comandi Disponibili:

tower-cli gateway list           # Lista service nodes
tower-cli gateway get            # Dettagli service node
tower-cli gateway clusters       # Lista service clusters
tower-cli gateway routes         # Lista routes
tower-cli gateway services       # Lista services
tower-cli gateway status         # Status gateway complessivo

Note: Richiede permessi RBAC elevati su AAP 2.6

4. `tower_cli/constants.py`

Modifica: Versione aggiornata a 3.3.11

🚀 Come Usare con AAP 2.6

Configurazione Base

# Nessuna configurazione speciale necessaria!
# Il CLI rileva automaticamente AAP 2.6

tower-cli config host https://aap.example.com
tower-cli config oauth_token YOUR_TOKEN
# oppure
tower-cli config username admin
tower-cli config password mypass

Comandi Instance (Controller API)

Lista Istanze per Tipo

# Tutte le istanze
tower-cli instance list

# Solo control nodes
tower-cli instance list --node-type control

# Solo execution nodes
tower-cli instance list --node-type execution

# Solo hop nodes (gateway mesh)
tower-cli instance list --node-type hop

Dettagli Istanza

# Per hostname
tower-cli instance get --hostname aip-controller-prod-01.myDomain

# Output mostra tutti i campi AAP 2.6:
# - node_type, node_state
# - listener_port, protocol
# - cpu, memory, last_seen
# - peers, reverse_peers
# - jobs_running, jobs_total

Health Check (Nuovo)

# Verifica salute di un nodo
tower-cli instance health --id 1
tower-cli instance health --hostname aip-exnode-prod-01

# Output formato JSON
tower-cli instance health --id 3 --format json

Jobs Running (Nuovo)

# Elenca job in esecuzione su un nodo
tower-cli instance jobs --id 3
tower-cli instance jobs --hostname aip-exnode-prod-01

# Con formato JSON
tower-cli instance jobs --id 3 --format json

Comandi Gateway (Gateway API)

Service Nodes

# Lista service nodes del gateway
tower-cli gateway list

# Dettagli service node
tower-cli gateway get --id 1
tower-cli gateway get --name gateway-node-01

Gateway Services

# Lista tutti i servizi
tower-cli gateway services

# Lista clusters
tower-cli gateway clusters

# Lista routes
tower-cli gateway routes

# Status complessivo gateway
tower-cli gateway status

⚠️ Nota: I comandi gateway richiedono permessi RBAC elevati. Se ricevi "403 Forbidden", contatta l'amministratore AAP.

📊 Differenze tra Tower Legacy e AAP 2.6

Aspetto	Tower 3.x (Legacy)	AAP 2.6
API Endpoint	`/api/v2/`	`/api/controller/v2/` + `/api/gateway/v1/`
Instances	Solo execution nodes	control, execution, hop
Gateway	Non disponibile	Service Nodes, Routes, Clusters
Mesh Topology	Limitata	Completa (receptor-based)
Auto-detect	No	✅ Sì

🔍 Verifica Tipo API

Per vedere quale API viene rilevata:

# Con verbose mode, mostra il tipo rilevato
tower-cli instance list -v

# Output include:
# "Detected AAP 2.x API (/api/controller/v2/)"
# oppure
# "Using legacy API (/api/v2/)"

🐛 Troubleshooting

Problema: "The requested object could not be found" su instance list

Causa: Stai usando AAP 2.6 ma tower-cli non rileva il nuovo API Soluzione:

# Verifica che l'host sia corretto
tower-cli config host https://correct-aap-host

# Testa l'endpoint manualmente
curl -k "https://your-aap/api/controller/v2/ping/"

Problema: "403 Forbidden" su comandi gateway

Causa: Permessi RBAC insufficienti per Gateway API Soluzione: Contatta l'amministratore AAP per richiedere permessi gateway

Problema: Il CLI usa ancora /api/v2/

Causa: Il cache del tipo API è settato su legacy Soluzione:

# Riavvia il CLI o cancella il cache Python
python -c "from tower_cli.conf import settings; settings._api_type = None"

# Oppure usa una nuova sessione shell

📝 Output Esempio AAP 2.6

Instance List

== ================================== ======== ================= =========
id              hostname              capacity node_type         enabled
== ================================== ======== ================= =========
 1 aip-controller-prod-01.myDomain      136 control              true
 2 aip-controller-prod-02.myDomain      136 control              true
 3 aip-exnode-prod-01.myDomain          136 execution            true
 4 aip-exnode-prod-02.myDomain          136 execution            true
== ================================== ======== ================= =========

Instance Get (JSON)

{
  "id": 3,
  "hostname": "aip-exnode-prod-01.myDomain",
  "node_type": "execution",
  "node_state": "ready",
  "capacity": 136,
  "consumed_capacity": 0,
  "enabled": true,
  "listener_port": 27199,
  "protocol": "tcp",
  "cpu": "4.0",
  "memory": 16494313472,
  "last_seen": "2026-01-21T10:10:37.278401Z",
  "jobs_running": 0,
  "jobs_total": 543,
  "peers": [],
  "reverse_peers": [1, 2]
}

Instance Health

{
  "id": 3,
  "hostname": "aip-exnode-prod-01.myDomain",
  "capacity": 136,
  "consumed_capacity": 0,
  "enabled": true,
  "node_type": "execution",
  "node_state": "ready"
}

✅ Compatibilità

Versione	Supporto	Note
AAP 2.6+	✅ Completo	Auto-detect, tutte le funzionalità
AAP 2.0-2.5	✅ Parziale	Controller API, no gateway API
Tower 3.8+	✅ Completo	Usa legacy API automaticamente
Tower < 3.6	✅ Base	Campi mesh non disponibili

Backward Compatible: Funziona con tutte le versioni precedenti!

🎓 Best Practices

1. Usa OAuth Token per AAP 2.6

tower-cli config oauth_token YOUR_TOKEN
# Più sicuro di username/password

2. Filtra per Tipo di Nodo

# Invece di fare parse manuale dell'output
tower-cli instance list --node-type execution --format json | jq '.results[].hostname'

3. Verbose Mode per Debug

# Mostra URL chiamati e risposte
tower-cli instance list -vvv

4. Format JSON per Script

# Più facile da parsare
tower-cli instance list --format json | jq '.results[] | {id, hostname, node_type}'

📚 Documentazione Aggiuntiva

QUICK_START.md - Guida rapida utilizzo
DEVELOPMENT_GUIDE.md - Guida sviluppo
GATEWAY_SUPPORT.md - Supporto gateway mesh (Tower 3.6+)
README_IT.md - Introduzione italiano

🔄 Migration da Versioni Precedenti

Nessuna migrazione necessaria! Aggiorna semplicemente:

cd /myData/git/pythonVENV/ansible-tower-cli-3.3.9
pip install --upgrade .

# Verifica versione
tower-cli --version
# Output: Tower CLI 3.3.11

⚠️ Limitazioni Conosciute

Gateway API richiede permessi elevati - Service nodes, routes, clusters richiedono ruoli amministrativi
Cache API type - Il tipo API viene cachato; riavvia il CLI se cambi host
Mesh visualizer - Disponibile nell'API ma non ancora implementato in tower-cli

🚀 Prossimi Sviluppi

Comando mesh-visualizer per visualizzare la topologia
Supporto completo per receptor addresses
Comandi avanzati gateway (create/modify service_nodes)
Integration con Execution Environments AAP 2.x

Versione: 3.3.11 Data: 2026-01-21 Compatibilità: AAP 2.x, Tower 3.x, AWX Richiede: Python 3.6+, requests, click

FilesExpand file tree

AAP_2.6_SUPPORT.md

Latest commit

History