Referenzinformationen › Referenzhandbuch zum Anwendungskatalog › Webdienst-Anwendungen › WS_API – Webservices-API-Anwendung

WS_API – Webservices-API-Anwendung

Aktuelle Version: 2.0.0-2

Funktionsübersicht

Die "WS_API"-Anwendung bietet über einen Dienst auf REST-Basis (Representational State Transfer) eine Webservice-Schnittstelle zu einem oder mehreren Grids. In der WS_API REST-Schnittstelle kann eine beliebige der folgenden Zugriffsmethoden verwendet werden:

• HTTP: Einfache HTTP-basierte REST-API-Anrufe.
• HTTPS: Sichere HTTP-basierte REST-API-Anrufe.
• VPN: HTTP-Anfragen über einen sicheren VPN-Tunnel.

Begrenzung

Wichtig! Die IP-Adressen, die in den externen Schnittstelleneigenschaften "iface.vpn", "iface.in" und "iface.net" konfiguriert sind, müssen IP-Adressen sein, die auf Ihrem CA AppLogic®-Grid verfügbar sind. Sie finden sie zusammen mit den DNS-Servern auf dem Dashboard Ihres Grid.

Ressourcen

"WS_API"-Anwendung

Anwendungs-Volumes

Die Anwendung selbst verwendet mehrere Volumes. Sie sind Teil der Anwendung und sind bereits in die Appliance-Instanzen konfiguriert. Es gibt keine Volumes, die in der Anwendungsbegrenzung konfiguriert werden müssen.

Bedienung

Bevor die WS_API-Anwendung gestartet wird, muss sie für den Zugriff auf die Grids konfiguriert werden, die über die Webdienstschnittstelle verwaltet werden. Dies beinhaltet die Erstellung der Datei "vdcs.conf" im data-Unterverzeichnis des conf-Volumes. Ein Paar aus privaten/öffentlichen Schlüsseln muss erstellt werden, und in der Steuerung des Ziel-Grid muss ein Benutzer mit dem generierten öffentlichen Schlüssel eingerichtet werden. Information über das Auffüllen der Datei "vdcs.conf", das Einrichten von SSH-Schlüsseln und das Erstellen eines Grid-Benutzers für die Webdienst-API finden Sie im Abschnitt Konfigurieren.

WS_API kann für die Ausführung in einem oder mehreren der folgenden Modi konfiguriert werden:

HTTP verwenden

In diesem Modus kann über die reguläre HTTP-basierte Schnittstelle auf die REST-API zugegriffen werden.
Beispiel: curl "http://iface.in/api/v1/app/list?vdc=controller_name".
Um die Anwendung in diesem Modus zu starten, müssen Sie für die obligatorischen Eigenschaften entsprechende Werte und die die Eigenschaft "http_mode" den Wert "http" festlegen. Weitere Informationen über die Einrichtung der Anwendung in diesem Modus finden Sie im Abschnitt Konfigurieren.

HTTPS verwenden

In diesem Modus kann über die sichere HTTP-basierte Schnittstelle auf die REST-API zugegriffen werden.
Beispiel: curl -k -E /path/to/client_key.pem "https://usr_ip/api/v1/app/list?vdc=controller_name".
Um die Anwendung in diesem Modus zu starten, müssen Sie für die obligatorischen Eigenschaften entsprechende Werte und die die Eigenschaft "http_mode" den Wert "https" festlegen. Sie können außerdem für die Eigenschaft "opts" die in der obigen Eigenschaftentabelle angezeigten Optionen festlegen, damit Ihr Zertifikat entsprechend signiert wird. Nachdem die Anwendung erfolgreich gestartet wurde, müssen die Clientzertifikate aus dem Unterverzeichnis "ssl-keys" des conf-Volumes in die Clientanwendung oder den Browser kopiert werden, um für den Zugriff auf WS_API verwendet werden zu können. Für weitere Informationen über die Einrichtung dieses Modus für die Anwendung finden Sie im Abschnitt Konfigurieren.

Verwenden eines VPN-Tunnels

In diesem Modus wird ein sicherer VPN-Tunnel zwischen dem VPN-Server "in_vpn" innerhalb der Anwendung und einem VPN-Client auf der Clientseite erstellt. Sobald der Tunnel mithilfe einer der verfügbaren VPN-Tunnel-Typen erstellt wurde, kann über die reguläre HTTP-basierte Schnittstelle auf die REST-API zugegriffen werden.
Beispiel: curl "http://iface.in/api/v1/app/list?vdc=controller_name".
Um die Anwendung in diesem Modus zu starten, müssen Sie für die obligatorischen Eigenschaften entsprechende Werte festlegen und die externe Schnittstelleneigenschaft "iface.vpn" auf die IP-Adresse festlegen, die für den VPN-Zugriff ausgewählt wurde, und Sie müssen "vpn_standby" auf 0 festlegen. Standardmäßig wird "vpn_ports" auf den Wert "80,443" festgelegt, um Verbindungen zu den Ports 80 und 443 (http und https) zuzulassen. Für die Eigenschaft "vpn_type" wird "certificate" eingestellt, um die Verbindung des VPN-Clients mit dem VPN-Server in der Anwendung über einen auf einem SSL-Zertifikat basierenden Tunnel zu ermöglichen. Sie können außerdem die Eigenschaft "in_standby" auf den Wert 1 festlegen, sodass nur Anfragen über den VPN-Tunnel zulässig sind. Alle API-Anfragen von außerhalb des VPN-Tunnels werden übergangen. Für weitere Informationen über die Einrichtung dieses Modus für die Anwendung finden Sie im Abschnitt Konfigurieren.

Anwendungsarchitektur

Die WS_API-Anwendungsinfrastruktur der CA AppLogic®-Webdienste ist nachfolgend dargestellt:

Es umfasst die folgenden Komponenten:

• Ein Eingabe-Gateway mit Firewall, die HTTP- und HTTPS-basierte Anfragen unterstützt
• Ein VPN-Server, der API-Anfragen über einen sicheren Tunnel zum VPN-Client auf Clientseite sendet
• Ein Webserver, der REST-API-Anfragen verarbeitet
• Ein zentralisierter Konfigurationsdateispeicher
• ein zentralisiertes Protokoll, in dem Protokolle und temporäre Daten erfasst werden
• Ein Netz-Gateway mit Firewall für die Verbindung mit Grids
• Eine Überwachungs-Appliance

  

Konfigurieren

In diesem Abschnitt wird beschrieben, wie Sie die WS_API-Anwendung so konfigurieren, dass sie in einem der drei Betriebsmodi gestartet wird.

So konfigurieren Sie die WS_API-Anwendung

1. Stellen Sie die WS_API-Anwendung mithilfe des Assistenten für die Anwendungsbereitstellung in der CA AppLogic®-GUI bereit, oder verwenden Sie den Befehl "app provision" in der Shell. Legen Sie zu diesem Zeitpunkt noch keine Eigenschaften fest. Überprüfen Sie, dass der Assistent so konfiguriert ist, dass die Anwendung nach der Bereitstellung nicht gestartet wird, oder geben Sie bei Verwendung der Befehlszeile die Option "--skipstart" an.

   app provision WS_API ws_api_instance --skipstart 
   

2. Verwalten Sie das Daten-Volume der Anwendung:

   vol manage ws_api_instance:conf 
   

3. Überprüfen Sie im Datenunterverzeichnis, dass die Datei "vdcs.conf" vorhanden ist.

   cd /mnt/vol/data
   ls vdcs.conf 
   

   Diese Datei enthält erforderliche Informationen für den Zugriff auf die Grids, die über die REST-API verwaltet werden.

4. Öffnen Sie die Datei im vi-Texteditor:

   vi vdcs.conf 
   

5. Bearbeiten Sie die Datei mithilfe der Vorlage als Referenz:

   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. Geben Sie die relevanten Informationen für die Grids ein, auf die über die API zugegriffen wird. Um Informationen für ein weiteres Grid hinzuzufügen, kommentieren Sie die Zeilen aus (entfernen Sie das Zeichen #), und fügen Sie die Informationen für das zweite Grid hinzu. Weitere Grid fügen Sie hinzu, indem Sie den vdc-Block im Abschnitt "vdcs {...}" wiederholen. Beachten Sie außerdem, dass das Festlegen von werten für Breite ("latitude") und Länge ("longitude") optional ist.
7. Speichern Sie die Datei, und beenden Sie den Texteditor.
8. Generieren Sie ein Paar aus öffentlichen/privaten Schlüsseln für den SSH-Zugriff auf die in der Datei "vdcs.conf" konfigurierten Grids.

   So generieren Sie das Schlüsselpaar:

   ssh-keygen -t dsa -f /mnt/vol/data/gridkey
   Drücken Sie an der Aufforderung zur Eingabe eines Kennworts die Eingabetaste. GEBEN SIE KEIN KENNWORT EIN.
   chmod 600 /mnt/vol/data/gridkey*
   chown 99:99 /mnt/vol/data/gridkey*
   

9. Kopieren Sie den öffentlichen Schlüssel:

   cat /mnt/vol/data/gridkey.pub 
   

10. Erstellen Sie auf der Grid-Steuerung einen API-Benutzer mit diesem Schlüssel als "sshkey" auf jedem Grid:

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

    Der Benutzer wird erstellt.

11. Richten Sie den Zugriff für den neu erstellten Benutzer ein:

    grid modify_acl api@domain.com=grid_administrator
    

    Hinweis: Andere Zugriffsebenen können verwendet werden (weitere Informationen finden Sie im RBAC-Handbuch). Beachten Sie jedoch, dass dies die Befehle einschränken wird, die "ws_api" ausführen kann.

12. Beenden Sie den Volume-Manager.

    Die Anwendungsbegrenzung kann jetzt so konfiguriert werden, dass sie in einem der drei Betriebsmodi ausgeführt wird.

HTTPS Mode

Die "WS_API"-Anwendung bietet über einen Dienst auf REST-Basis (Representational State Transfer) eine Webservice-Schnittstelle zu einem oder mehreren Grids. Die HTTPS-Zugriffsmethode unterstützt sichere HTTP-basierte Aufrufe der REST-API.

So konfigurieren Sie die Anwendung in HTTPS-Modus

1. Legen Sie für die Eigenschaft "http_mode" den Wert "https" fest (Standardeinstellung).
2. Legen Sie für die obligatorischen Eigenschaften geeignete Werte fest.
3. Legen Sie die Eigenschaft "opts" so fest, dass ein benutzerdefiniertes SSL-Zertifikat generiert wird.

   Hinweis: Wenn Sie für die Eigenschaft "opts" keinen Wert eingeben, wird beim Start der Anwendung ein generisches SSL-Zertifikat erzeugt. Für die Eigenschaften "http_mode" und "allowed_hosts" können Sie die Standardwerte übernehmen. Beispiel:

   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. Starten Sie die Anwendung mit dem Befehl "app start" oder über die Schaltfläche "Anwendung starten" in der GUI.

   Beim ersten Anwendungsstart werden ein Clientschlüssel im PEM-Format bestehend aus dem Clientzertifikat und einem privaten Schlüssel namens "api_client.pem" und ein entsprechender Schlüssel im PKCS12-Format für Browser namens "api_client.p14" im Verzeichnis "/mnt/config/ssl_keys/keys/" des conf-Volumes erstellt. Die Schlüsseldatei "api_client.p14" kann für alle browserbasierte API-Zugriffe und die Schlüsseldatei "api_client.pem" für alle nicht browserbasierten API-Zugriffe verwendet werden.

So generieren Sie zusätzliche Clientzertifikate

1. Melden Sie sich an der Komponente "main.api_srv" der aktuell ausgeführten ws_api_instance an.
2. Ändern Sie das Verzeichnis in /mnt/config/ssl_keys.
3. Generieren Sie einen privaten Schlüssel für ein Benutzerkonto "api". openssl genrsa -out keys/api_client2_privkey.pem 2048
4. Generieren Sie eine Certificate Signing Request (CSR), die der CA signieren muss. openssl req -new -key keys/api_client2_privkey.pem -out keys/api_client2_request.csr.
5. Signieren Sie die CSR mit unserer 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. Kombinieren Sie "api_client2_a.pem" und "cert", um dies als SSL/PEM-Schlüssel in der Befehlszeile verwenden zu können. cat keys/api_client2_privkey.pem keys/api_client2.cer > keys/api_client2.pem.
7. Exportieren Sie den Schlüssel in einem Format, das von herkömmlichen Webbrowsern verwendet werden kann. openssl pkcs12 -export -in keys/api_client2.cer -inkey keys/api_client2_privkey.pem -out keys/api_client2.p14.

HTTP Mode

Die "WS_API"-Anwendung bietet über einen Dienst auf REST-Basis (Representational State Transfer) eine Webservice-Schnittstelle zu einem oder mehreren Grids. Die HTTP-Zugriffsmethode unterstützt einfache HTTP-basierte Aufrufe der REST-API.

Hinweis: Dieser Modus sollte mit äußerster Vorsicht verwendet werden. Er beinhaltet keine Sicherheitsprüfung, d. h. jeder kann eine API-Anfrage ohne jegliche Authentifizierung erstellen. Darüber hinaus erfolgt der gesamte Datenverkehr zwischen dem Client und der Anwendung "ws_api_instance" in Form von unverschlüsseltem Text.

Um die Anwendung im HTTP-Modus zu konfigurieren, legen Sie für die Eigenschaft "http_mode" den Wert "http" und für die obligatorischen Eigenschaften geeignete Werte fest. Beispiel:

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

Die Anwendung kann nun mit dem Befehl "app start" oder über die Schaltfläche "Anwendung starten" in der GUI aufgerufen werden.

VPN Mode

Die "WS_API"-Anwendung bietet über einen Dienst auf REST-Basis (Representational State Transfer) eine Webservice-Schnittstelle zu einem oder mehreren Grids. Die VPN-Zugriffsmethode ermöglicht, HTTP-Anfragen über einen sicheren VPN-Tunnel zu senden.

So konfigurieren Sie die Anwendung im VPN-Modus

1. Legen Sie für die externe Schnittstelle "iface.vpn" die gewünschte IP-Adresse fest. Die Eigenschaft "vpn_standby" ist deaktiviert, d. h. auf 0 festgelegt.
2. Legen Sie für die Eigenschaft "in_standby" den Wert "1" fest, um den Zugriff über das VPN einzuschränken.

   Zum Beispiel:

   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. Starten Sie die Anwendung mit dem Befehl "app start" oder über die Schaltfläche "Anwendung starten" in der GUI.

   Nach dem Anwendungsstart generiert die VPN-Server-Appliance die erforderlichen Serverzertifikate und Schlüsseldateien, wenn diese Dateien nicht bereits vorhanden sind.

4. Melden Sie sich bei die Appliance an, und führen Sie das Skript "security.sh" im Verzeichnis "/appliance" aus, um die Clientzertifikate und den Schlüssel zu generieren.

   [ws_api_instance:main.in_vpn appliance]# ./security.sh generate_client
   Generiertes SSL-Client-Zertifikat und Schlüsseldatei.
   ==============================================
   Kopieren Sie diese Dateien zusammen mit der CA-Zertifikatsdatei auf den VPN-Server im Unterverzeichnis 
   "/client/" des Daten-Volumes oder des in FS bereitgestellten Volumes.
   Geben Sie den Pfad zu den Clientdateien (client.a1c65e2bae3d0b57) in der Eigenschaft "auth_path" an.
   Speicherort der Dateien:
   Clientzertifikat: /mnt/data/server/client.a1c65e2bae3d0b57.crt
   Clientschlüsseldatei: /mnt/data/server/client.a1c65e2bae3d0b57.key
   CA-Zertifikatsdatei in "/mnt/data/server/ca.crt"
   

   Das Clientzertifikat (z. B. client.xxxxxxxxxxxxxxxx.crt) und die Schlüsseldatei (z. B. client.xxxxxxxxxxxxxxxx.key) werden im Unterverzeichnis "client" und das CA-Zertifikat (ca.crt) wird im Unterverzeichnis "server" des conf-Volumes generiert.

5. Kopieren Sie die Zertifikate in das Unterverzeichnis "/client/" der entfernten VPN-Client-Appliance auf dem Daten-Volume oder in NFS bereitgestellten Volume.

Hinweise

Verwendete Open-Source- und Drittanbieter-Software

Auf dem code-Volume wird die folgende Open-Source- bzw. Drittanbieter-Software installiert.