Connessione SSM

A cosa serve

Questa guida porta un dev da zero a una porta AWS raggiungibile su localhost, tramite AWS Systems Manager (SSM) e il profilo SSO teddi-noprod. Tutto gira dentro un container Debian 13 gestito da distrobox, così il sistema immutabile di Fedora Silverblue resta pulito.

Prerequisiti: Fedora Silverblue con podman (già incluso), un account abilitato al portale AWS SSO e l'ID del target (istanza EC2 o nodo gestito) da raggiungere.

Nei comandi, sostituisci <username> con il tuo utente e <target> con l'ID dell'istanza (es. i-0abc123...).

1. Distrobox e container Debian 13

Su Silverblue distrobox non è preinstallato. Se distrobox --version non risponde, installalo come layer e riavvia:

rpm-ostree install distrobox
systemctl reboot

Poi crea una home dedicata e il container d13 (comandi da lanciare sull'host):

mkdir -p /home/<username>/d13-home
distrobox create --image debian:13 --name d13 --home /home/<username>/d13-home

Entra nel container:

distrobox enter d13

Da qui in poi tutti i comandi si eseguono dentro d13. La ~ del container corrisponde a /home/<username>/d13-home sull'host.

2. AWS CLI v2 e Session Manager plugin

Servono due componenti: la AWS CLI v2 e il Session Manager plugin, senza il quale aws ssm start-session fallisce. Entrambi si installano dai pacchetti ufficiali AWS.

Dipendenze di base:

sudo apt update
sudo apt install -y curl unzip

AWS CLI v2 (x86_64):

cd /tmp
curl "https://awscli.amazonaws.com/awscli-exe-linux-x86_64.zip" -o awscliv2.zip
unzip -q awscliv2.zip
sudo ./aws/install
aws --version

Session Manager plugin:

curl "https://s3.amazonaws.com/session-manager-downloads/plugin/latest/ubuntu_64bit/session-manager-plugin.deb" -o session-manager-plugin.deb
sudo dpkg -i session-manager-plugin.deb
session-manager-plugin --version

~~Su macchine ARM (aarch64) usa~~ awscli-exe-linux-aarch64.zip e ubuntu_arm64/session-manager-plugin.deb.

3. Configurazione del profilo

Crea la cartella .aws nella home del container:

mkdir -p ~/.aws

Crea il file ~/.aws/config con questo contenuto:

[default]
region = eu-south-1

[profile teddi-noprod]
sso_account_id = 269742496613
sso_role_name = AWS_SSO_NOPROD_PS
sso_region = eu-central-1
sso_start_url = https://d-9967010e56.awsapps.com/start
region = eu-south-1

Nota: il portale SSO sta in eu-central-1, mentre le risorse sono in eu-south-1 (Milano).

aws sso login --profile teddi-noprod

Il comando apre il browser sul portale AWS: autenticati e conferma il codice mostrato nel terminale. Se il browser non si apre dal container, copia a mano l'URL stampato nel terminale e incollalo nel browser dell'host.

Verifica che il login sia andato a buon fine:

aws sts get-caller-identity --profile teddi-noprod

Il token SSO scade dopo alcune ore: quando i comandi rispondono con errori di token scaduto, ripeti il login.

5. Port forwarding con SSM

Per rendere raggiungibile in locale una porta del target:

aws ssm start-session \
  --target <target> \
  --document-name AWS-StartPortForwardingSession \
  --parameters '{"portNumber":["5080"],"localPortNumber":["5080"]}' \
  --profile teddi-noprod \
  --region eu-south-1

portNumber è la porta sul target, localPortNumber quella su cui ascolti in locale. Se la porta locale è già occupata, cambia solo localPortNumber.

Lascia il terminale aperto finché ti serve il tunnel; Ctrl+C lo chiude. Distrobox condivide la rete con l'host, quindi il servizio è raggiungibile anche dall'host su http://localhost:5080.

Uso quotidiano e problemi comuni

Dopo il setup iniziale, la routine è di tre comandi: distrobox enter d13, aws sso login --profile teddi-noprod (solo se il token è scaduto), poi aws ssm start-session ....

Sintomo	Causa probabile	Soluzione
`SessionManagerPlugin is not found`	Plugin non installato nel container	Ripeti l'installazione del passo 2 dentro `d13`
`Token has expired` / `Error loading SSO Token`	Sessione SSO scaduta	`aws sso login --profile teddi-noprod`
`TargetNotConnected`	ID target errato o agente SSM non attivo sull'istanza	Controlla l'ID e la region `eu-south-1`; se persiste, avvisa il team infra
`AccessDeniedException`	Il ruolo `AWS_SSO_NOPROD_PS` non ha accesso a quel target	Chiedi l'abilitazione al team infra
`address already in use`	Porta locale già occupata	Cambia `localPortNumber` o chiudi l'altro processo
`distrobox: command not found`	Distrobox non installato o riavvio mancante	`rpm-ostree install distrobox` e riavvio