Informazioni di riferimento › Guida di riferimento del catalogo delle applicazioni › Applicazioni del servizio Web › WS_API - Applicazione API dei servizi Web

WS_API - Applicazione API dei servizi Web

Ultima versione: 2.0.0-2

Panoramica funzionale

L'applicazione WS_API fornisce un'interfaccia di servizio Web per una o più griglie tramite un servizio basato su REST (Representational State Transfer). Uno dei seguenti metodi di accesso può essere utilizzato con l'interfaccia WS_API REST:

• HTTP : Chiamate semplici di API di REST basate su HTTP.
• HTTPS : Chiamate protette di API di REST basate su HTTP.
• VPN: le richieste HTTP vengono inviate tramite un tunnel VPN protetto.

Limite

Importante: gli indirizzi IP configurati nelle proprietà dell'interfaccia esterna iface.vpn, iface.in e iface.net devono essere indirizzi IP disponibili sulla griglia di CA AppLogic®. Tali indirizzi sono contenuti nel dashboard della griglia assieme ai server DNS.

Risorse

Applicazione "WS_API"

Volumi dell'applicazione

L'applicazione utilizza più volumi. Fanno parte dell'applicazione e sono già configurati nelle istanze di appliance. Non sono presenti volumi da configurare nel limite dell'applicazione.

Funzionamento

Prima di essere avviata, l'applicazione WS_API deve essere configurata per accedere alle griglie che saranno gestite tramite l'interfaccia dei servizi Web. Questo comporta la creazione di un file all'interno della sottodirectory vdcs.conf nel volume di configurazione. Deve essere creata una coppia di chiavi pubblica/privata e un utente deve essere installato nel controller della griglia di destinazione con la chiave pubblica generata. Per informazioni su come compilare vdcs.conf, sulla modalità di installazione delle chiavi ssh e sulla creazione di un utente della griglia per l'API del servizio Web, consultare la sezione configurare.

La WS_API può essere configurata per funzionare con una delle seguenti modalità o con una combinazione d'esse:

Utilizzo di HTTP

In questa modalità, può essere effettuato l'accesso all'API di REST tramite l'interfaccia HTTP ordinaria.
Ad esempio, curl "http://iface.in/api/v1/app/list?vdc=controller_name".
Per avviare l'applicazione per lavorare in questa modalità, è necessario impostare le proprietà obbligatorie sui valori appropriati e la proprietà http_mode su http. Per ulteriori informazioni su come impostare l'applicazione al fine di lavorare in questa modalità, fare riferimento alla sezione di configurazione.

Utilizzo di HTTPS

In questa modalità, può essere effettuato l'accesso all'API di REST tramite l'interfaccia HTTP protetta.
Ad esempio, curl -k -E /path/to/client_key.pem "https://usr_ip/api/v1/app/list?vdc=controller_name".
Per avviare l'applicazione per lavorare in questa modalità, è necessario impostare le proprietà obbligatorie sui valori appropriati e la proprietà http_mode su https. È anche possibile impostare la proprietà opts con le opzioni visualizzate nella tabella delle proprietà precedente per il certificato da firmare di conseguenza. Dopo che l'applicazione è stata avviata correttamente, i certificati del client devono essere copiati dalla sottodirectory ssl-keys nel volume conf per l'applicazione client o nel browser da utilizzare per accedere alla WS_API. Per ulteriori informazioni su come impostare l'applicazione fino a lavorare in questa modalità, fare riferimento alla sezione configurazione.

Utilizzo di tunnel VPN

In questa modalità, un tunnel VPN protetto viene creato tra il server VPN in_vpn all'interno dell'applicazione e un client VPN sul lato client. Una volta che il tunnel è stato creato correttamente utilizzando uno dei diversi tipi di tunneling di VPN disponibili, l'accesso all'API di REST può essere effettuato tramite l'interfaccia HTTP ordinaria.
Ad esempio, curl "http://iface.in/api/v1/app/list?vdc=controller_name".
Per avviare l'applicazione in modo che lavori in questa modalità, è necessario impostare le proprietà obbligatorie su valori appropriati, impostare la proprietà dell'interfaccia esterna iface.vpn sull'indirizzo IP scelto per l'accesso VPN e impostare vpn_standby su 0. Per impostazione predefinita, vpn_ports è impostato su 80,443 per consentire le connessioni alle porte 80 e 443 (http e https rispettivamente) e vpn_type è impostato su certificate per consentire a un client VPN di connettersi al server VPN nell'applicazione utilizzando un certificato SSL basato su tunnel. È anche possibile impostare la proprietà in_standby su 1 in modo che solo le richieste tramite il tunnel VPN siano consentite. Le richieste API dall'esterno del tunnel VPN vengono ignorate. Per ulteriori informazioni su come impostare l'applicazione fino a lavorare in questa modalità, fare riferimento alla sezione configurazione.

Architettura di applicazione

L'infrastruttura dell'applicazione 'WS_API' dei servizi Web di CA AppLogic® viene mostrato di seguito:

Contiene i seguenti componenti:

• un gateway di input con firewall - supporta le richieste basate su HTTP e HTTPS
• un server VPN - fornisce richieste API tramite un tunnel sicuro per i client VPN sul lato client
• un server Web - fornisce altre richieste API di REST
• un'archiviazione del file di configurazione centralizzata
• un log centralizzato - raccoglie e archivia log e dati temporanei
• un gateway NET con firewall per la connessione alle griglie
• un'appliance di monitoraggio

  

Configurare

Questa sezione descrive come configurare l'applicazione WS_API per l'avvio in una delle tre diverse modalità di operazione.

Per configurare l'applicazione WS_API

1. Effettuare il provisioning di WS_API utilizzando la procedura guidata app provision nella GUI di CA AppLogic® o utilizzare il comando app provision nella shell, non impostare tutte le proprietà. Verificare che la procedura guidata non sia configurata per avviare l'applicazione dopo il provisioning o utilizzare l'opzione --skipstart se la riga di comando viene utilizzata.

   app provision WS_API ws_api_instance --skipstart 
   

2. Gestire il volume di dati dell'applicazione:

   vol manage ws_api_instance:conf 
   

3. Nella sottodirectory di dati, verificare che esista un file denominato vdcs.conf.

   cd /mnt/vol/data
   ls vdcs.conf 
   

   Questo file è costituito da informazioni necessarie per l'accesso alle griglie che verranno gestite tramite l'API di REST.

4. Aprire il file di configurazione mediante l'editor di testo vi:

   vi vdcs.conf 
   

5. Modificare il file utilizzando il template come riferimento:

   vdcs
      { 
      vdc controller_name : host = controller_ip or FQDN
         { 
         location  = "city, state, country" 
         latitude  = latitude 
         longitude = longitude 
         } 
   
   #  vdc controller_name : host = controller_ip or FQDN 
   #     { 
   #     location  = "city, state, country"
   #     latitude  = latitude
   #     longitude = longitude
   #     }
      } 
   

6. Immettere le informazioni attinenti alle griglie a cui verrà effettuato l'accesso con l'API. Per aggiungere informazioni a un'ulteriore griglia, rimuovere i commenti dalle righe (rimuovere il #) e aggiungere le informazioni per la seconda griglia. Possono essere aggiunte più griglie ripetendo vdc block nella sezione vdcs {...}. Notare inoltre che l'impostazione dei valori di latitudine e longitudine è facoltativa.
7. Salvare e chiudere l'editor di testo.
8. Generare una coppia di chiavi pubblica/privata per l'accesso alle griglie configurate nella vdcs.conf.

   Per generare la coppia di chiavi:

   ssh-keygen -t dsa -f /mnt/vol/data/gridkey
   Quando viene richiesto di immettere una password premere Invio. NON IMMETTERE UNA PASSWORD.
   chmod 600 /mnt/vol/data/gridkey*
   chown 99:99 /mnt/vol/data/gridkey*
   

9. Copiare la chiave pubblica:

   cat /mnt/vol/data/gridkey.pub 
   

10. Sul controller di griglia, creare un utente API con questa chiave come sshkey su ciascuna griglia:

    user create api@domain.com pwd=- sshkey="ssh-dsa AAA.................xyz" 
    

    L'utente è creato.

11. Impostare l'accesso per l'utente appena creato:

    grid modify_acl api@domain.com=grid_administrator
    

    Nota: è possibile utilizzare altri livelli di accesso (consultare la guida RBAC per ulteriori informazioni) ma ricordare che in questo modo si limitano i comandi eseguibili da ws_api.

12. Uscire dalla gestione volume.

    Il limite delle applicazioni può essere configurato per l'utilizzo in una delle tre modalità operative.

HTTPS Mode

L'applicazione WS_API fornisce un'interfaccia di servizio Web per una o più griglie tramite un servizio basato su REST (Representational State Transfer). Il metodo di accesso HTTPS abilita chiamate dell'API di REST basate su HTTP semplice..

Per configurare l'applicazione in modalità HTTPS

1. Impostare la proprietà http_mode su https (impostazione predefinita).
2. Impostare le proprietà obbligatorie su valori appropriati.
3. Impostare la proprietà opts per generare un certificato SSL personalizzato.

   Nota: se opts è vuota, viene generato un certificato SSL generico all'avvio dell'applicazione. Le impostazioni delle proprietà http_mode e allowed_hosts possono essere lasciate sui valori predefiniti. Ad esempio:

   app config ws_api_instance iface.in=usr-ip iface.net=net-ip dns1=dns1 dns2=dns2 opts=ssl_country=Country,ssl_state=State,ssl_local=City,ssl_org_name=Organization,ssl_org_unit=Unit,ssl_common_name=Common Name,ssl_email_address=company@domain.com,ssl_export_pass=Passkey 
   

4. Avviare l'applicazione tramite il comando app start o utilizzando il pulsante "Start Application" nella GUI.

   La prima volta che l'applicazione viene avviata, una chiave del client in formato PEM, costituita dal certificato del client e da una chiave privata denominata api_client.pem, e da una chiave equivalente in formato PKCS12 per i browser denominata api_client.p14, viene creata nella directory /mnt/config/ssl_keys/keys/ del volume di configurazione. Il file di chiave api_client.p14 può essere utilizzato per qualsiasi accesso API basato su browser e la chiave api_client.pem per ogni accesso API non basato su browser.

Per generare ulteriori certificati client

1. Accedere al componente main.api_srv di ws_api_instance in esecuzione.
2. Cambiare directory in /mnt/config/ssl_keys.
3. Generare una chiave privata per un account utente 'api'. openssl genrsa -out keys/api_client2_privkey.pem 2048
4. Generare una richiesta di firma del certificato per il CA da firmare. openssl req -new -key keys/api_client2_privkey.pem -out keys/api_client2_request.csr.
5. Firmare il CSR con CA. openssl x509 -req -days 365 -in keys/api_client2_request.csr -CA CA/CA_cert.pem -CAkey CA/private/CA_key.pem -CAserial CA/CA_cert.srl -out keys/api_client2,cer.
6. cat api_client2_a.pem e cert into one per l'utilizzo come chiave SSL/PEM della riga di comando. cat keys/api_client2_privkey.pem keys/api_client2,cer > keys/api_client2,pem.
7. Esportare la chiave in un formato che possa essere utilizzato da browser comuni del Web. openssl pkcs12 -export -in keys/api_client2.cer -inkey keys/api_client2_privkey.pem -out keys/api_client2.p14.

HTTP Mode

L'applicazione WS_API fornisce un'interfaccia di servizio Web per una o più griglie tramite un servizio basato su REST (Representational State Transfer). Il metodo di accesso HTTP abilita chiamate dell'API di REST basate su HTTP semplice.

Nota: questa modalità deve essere utilizzata con estrema attenzione. Nessun controllo di protezione è coinvolto in questa modalità e nessuno può creare una richiesta API senza autenticazione. Inoltre, tutto il traffico tra il client e l'applicazione ws_api_instance è in testo normale.

Per configurare l'applicazione in modalità HTTP, impostare la proprietà http_mode su http con l'impostazione della proprietà obbligatorie sul valore appropriato. Ad esempio:

app config ws_api_instance iface.in=usr-ip iface.net=net-ip dns1=dns1 dns2=dns2 http_mode=http 

L'applicazione può essere avviata tramite il comando app start o utilizzando il pulsante "Start Application" nella GUI.

VPN Mode

L'applicazione WS_API fornisce un'interfaccia di servizio Web per una o più griglie tramite un servizio basato su REST (Representational State Transfer). Il metodo di accesso VPN consente di inviare le richieste HTTP tramite un tunnel VPN protetto.

Per configurare l'applicazione in modalità VPN

1. Impostare l'interfaccia esterna iface.vpn su un indirizzo IP desiderato mentre vpn_standby è disabilitato, ovvero è impostato su 0.
2. Impostare in_standby su 1 per limitare l'accesso tramite l'impostazione di VPN.

   Ad esempio:

   app config ws_api_instance iface.in=usr-ip iface.vpn=vpn-ip iface.net=net-ip dns1=dns1 dns2=dns2 vpn_standby=0 in_standby=1 
   

3. Avviare l'applicazione tramite il comando app start o utilizzando il pulsante "Start Application" nella GUI.

   Dopo l'avvio dell'applicazione, l'appliance del server di VPN genera i certificati del server e i file di chiave necessari, se questi file non sono già presenti.

4. Accedere al dispositivo ed eseguire lo script security.sh situato nella directory /appliance per generare la chiave e i certificati del client.

   [ws_api_instance:main.in_vpn appliance]# ./security.sh generate_client
   Certificato di SSL client generato e file di codice.
   ==============================================
   Questi file, con il file del certificato CA, devono essere copiati nel server VPN nella
   nella sottodirectory /client/ del volume di dati o del volume montato di fs.
   Il percorso ai file dei client (client.a1c65e2bae3d0b57) dovrebbe essere specificato in auth_path property.
   Posizione dei file:
   certificato client: /mnt/data/server/client.a1c65e2bae3d0b57.crt
   file di chiave client: /mnt/data/server/client.a1c65e2bae3d0b57.key
   File del certificato CA in /mnt/data/server/ca.crt
   

   Il certificato client (ad esempio, client.xxxxxxxxxxxxxxxx.crt) e il file di chiave (ad esempio client.xxxxxxxxxxxxxxxx.key) vengono generati nella sottodirectory del client e il certificato CA (ca.crt) viene generato in una sottodirectory del server del volume di configurazione.

5. Copiare i certificati nell'appliance del client VPN remoto all'interno della sottodirectory /client/ nel volume di dati o nel volume montato nfs.

note

Software open source e di terze parti utilizzato

Il seguente software open source di terze parti è installato nel volume del codice.