L'API (RaaS) fa riferimento al server applicazioni a cui si connettono i client di SaltStack Config. Questi client includono il componente dell'interfaccia utente di SaltStack Config, i Master configurati in modo appropriato e altri utenti di RaaS. Il server applicazioni è anche noto come server eAPI.

RaaS è organizzato in moduli (denominati "risorse") e funzioni (denominate "metodi"). Nella chiamata API test.echo('hello, world'), la risorsa è test e il metodo è echo(). Gli argomenti possono essere passati ai metodi in base alla posizione o alla parola chiave.

È possibile accedere a RaaS in due modi, ovvero tramite un client RPC e tramite un bridge HTTP (o HTTPS).

Per connettersi a RaaS, impostare queste opzioni in client = APIClient():

  • server
  • username
  • password
  • config_name='internal' Usare il nome del back-end di autenticazione se si utilizza LDAP
  • timeout=60 # Richiede al massimo 60 secondi per eseguire qualsiasi operazione
  • ssl_key=None
  • ssl_cert=None
  • ssl_context=None
  • ssl_validate_cert=True = Impostare su False se si utilizzano certificati autofirmati

Esempio:

from sseapiclient import APIClient
client = APIClient('https://localhost', 'root', 'PASSWORD', ssl_validate_cert=False)
Nota:

Nelle versioni precedenti alla 6.2, la connessione API veniva effettuata utilizzando SyncClient.connect(), che è ancora compatibile con la versione 6.2 e successive. Se si utilizza SyncClient.connect(), non è necessaria alcuna modifica.

Sintassi dell'API

client.api.<interface>.<method>(parameter=parameter_value)

Esempio:

from sseapiclient import APIClient
client = APIClient('https://localhost', 'root', 'PASSWORD')
client.api.sec.download_content(auto_ingest=True)

Utilizzo dell'API (RaaS) con Curl

È inoltre possibile utilizzare RaaS direttamente con HTTP e JSON. Nell'esempio seguente l'API viene utilizzata con curl. Si tenga presente che quando xsrf è abilitato, è innanzitutto necessario ottenere un token e un cookie xsrf. Vedere Bridge HTTP per informazioni su come ottenere e utilizzare un token e un cookie xsrf. Quando si utilizza il client API Python, questa operazione viene eseguita automaticamente per impostazione predefinita.

Esempio:

curl --user 'root:PASSWORD' --url 'https://localhost/rpc' \
  --data '{
    "resource": "sec",
    "method": "download_content",
    "kwarg": {"auto_ingest": true}
  }'

Gestione delle licenze

Nell'interfaccia utente di SaltStack Config vengono visualizzate notifiche che avvisano quando la licenza sta per scadere. In qualità di utente RaaS, è necessario utilizzare l'area di lavoro Licenza per monitorare lo stato della licenza e garantire che rimanga attivo. Se la licenza scade, il servizio RaaS viene arrestato.

Client RPC

I client RPC programmatici nel modulo sseapiclient funzionano con Python versione 2.7 e Python 3.5 o successive. I client si connettono a SSE tramite HTTP o HTTPS ed effettuano l'autenticazione. L'utilizzo del client RPC ha il vantaggio di essere più semplice rispetto all'utilizzo del bridge HTTP.

Bridge HTTP

Il bridge HTTP (o HTTPS) accetta payload JSON di cui è stato effettuato il POST in un endpoint esposto da SSE, converte i payload in chiamate RPC e quindi restituisce il risultato come JSON. L'endpoint supporta l'autenticazione basata su cookie e quindi le credenziali di autenticazione devono essere passate una sola volta per sessione. Il bridge consente inoltre di inviare più chiamate in un unico payload.

Se xsrf è abilitato (impostazione predefinita con installazione basata sullo stato) in tornado_xsrf_cookies_enabled /etc/raas/raas.conf: True è necessario specificare X-Xsrftoken: nell'intestazione della chiamata rest. Il modo migliore è salvare un cookie con una chiamata get e quindi utilizzare il cookie per fornire il token dell'intestazione. Questo cookie viene salvato nella directory $HOME (home utenti). Il payload è un dizionario.

Esempio di chiamata curl con intestazione xsrf:

curl -k -c $HOME/eAPICookie.txt -u root:PASSWORD 'https://localhost/account/login' >/dev/null
curl -k -u root:PASSWORD -b $HOME/eAPICookie.txt \
  -H 'X-Xsrftoken: '$(grep -w '_xsrf' $HOME/eAPICookie.txt | cut -f7)'' \
  -X POST https://localhost/rpc \
  -d '{
    "resource": "sec",
    "method": "download_content",
    "kwarg": {"auto_ingest": true}
  }'

Gli esempi presuppongono quanto segue:

  • client=APIClient(<addr>,<user>, <pwd>)
  • Installazione di eAPI basata sullo stato predefinito
  • SSL abilitato
  • Importazione di sseapiclient. Esempio:
    from sseapiclient import APIClient