参考信息 › 应用目录参考指南 › Web 服务应用 › WS_API－Web 服务 API 应用

WS_API－Web 服务 API 应用

最新版本：2.0.0-2

功能概述

WS_API 应用通过基于表象化状态转变 (REST) 的服务向一个或多个网格提供 Web 服务接口。 下列任一访问方法都可用于 WS_API 接口：

• HTTP：基于 HTTP 的简单 REST API 调用。
• HTTPS：基于 HTTP 的安全 REST API 调用。
• VPN：通过安全 VPN 通道发送 HTTP 请求。

边界

重要信息！ 在 iface.vpn、iface.in 和 iface.net 外部接口属性中配置的 IP 地址必须是在 CA AppLogic® 网格上可用的 IP 地址。 您可以在您的网格显示板上发现这些地址和 DNS 服务器。

资源

“WS_API”应用

应用卷

应用本身使用多个卷。 它们是应用的一部分且已配置到组件实例中。 应用边界没有需要配置的卷。

操作

在启动 WS_API 应用之前，需要对其进行配置才能访问通过 Web 服务接口管理的网格。 这包括在 conf 卷的数据子目录内创建 vdcs.conf 文件。 需要创建一对私/公密钥，并且需要用生成的公钥在目标网格控制器上设置用户。 关于如何填充 vdcs.conf、设置 ssh 密钥以及为 Web 服务 API 创建网格用户的信息，请参阅“配置”一节。

可以通过下列模式之一或组合模式对 WS_API 进行配置：

使用 HTTP

在此模式下，可以通过基于常规 HTTP 的接口访问 REST API。
例如，curl "http://iface.in/api/v1/app/list?vdc=controller_name"。
要启动应用在此模式下工作，需要为强制性属性设置适当值并将 http_mode 属性设置为 http。 有关如何设置应用在此模式下工作的详细信息，请参阅“配置”一节。

使用 HTTPS

在此模式下，可以通过基于安全 HTTP 的接口访问 REST API。
例如，curl -k -E /path/to/client_key.pem "https://usr_ip/api/v1/app/list?vdc=controller_name"。
要启动应用在此模式下工作，需要为强制性属性设置适当值并将 http_mode 属性设置为 https。 您还可以使用上述属性表中显示的选项为要签署的证书相应设置 opts 属性。 在成功启动应用之后，必须将客户端证书从 conf 卷中的 ssl-keys 子目录复制到用于访问 WS_API 的客户端应用或浏览器中。 有关如何设置应用在此模式下运行的详细信息，请参阅“配置”一节。

使用 vpn 通道

在此模式下，在应用中的 in_vpn VPN 服务器和客户端的 VPN 客户之间创建安全 VPN 通道。 一旦使用不同 VPN 通道类型中的一种成功创建了通道，就可以通过基于常规 HTTP 的接口访问 REST API。
例如，curl "http://iface.in/api/v1/app/list?vdc=controller_name"。
要以此模式启动该应用，需要将强制性的属性设置为适当值，将 iface.vpn 外部接口属性设置为用于 VPN 访问所选择的 IP 地址并且将 vpn_standby 设置为 0。 默认情况下，vpn_ports 已设置为 80,443 以允许连接端口 80 和 443 （分别为 http 和 https），vpn_type 已设置为证书，允许 VPN 客户使用基于 SSL 证书的通道连接到应用的 VPN 服务器。 您还可以将 in_standby 属性设置为 1，仅允许通过 VPN 通道发出请求。 放弃来自 VPN 通道之外的任何 API 请求。 有关如何设置应用在此模式下运行的详细信息，请参阅“配置”一节。

应用体系结构

CA AppLogic® Web 服务“WS_API”应用基础架构显示如下：

它包含以下组件：

• 一个有防火墙的输入网关－支持基于 HTTP 和 HTTPS 的请求
• 一个 VPN 服务器－通过客户端至 VPN 客户端的安全通道处理 API 请求。
• Web 服务器－处理 REST API 请求
• 集中式配置文件存储
• 集中式日志－收集日志和存储临时数据
• 有防火墙的网络网关，用于连接网格
• 监控组件

  

配置

本节描述如何配置 WS_API 应用在下列三种不同操作模式的一种模式下启动。

配置 WS_API 应用

1. 使用 CA AppLogic® GUI 中的应用配给向导来配给 WS_API，或在 shell 中使用应用配给命令，但不设置任何属性。 确认向导已配置为在配给之后不启动应用，否则在使用该命令行时使用 --skipstart 选项。

   app provision WS_API ws_api_instance --skipstart 
   

2. 管理应用的数据卷：

   vol manage ws_api_instance:conf 
   

3. 在数据子目录中，确认存在名为 vdcs.conf 的文件。

   cd /mnt/vol/data
   ls vdcs.conf 
   

   此文件包括访问通过 REST API 管理的网格所必需的信息。

4. 使用 vi 文本编辑器打开文件。

   vi vdcs.conf 
   

5. 使用模板编辑文件作为参考：

   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. 输入使用 API 访问的网格的相关信息。 要添加其他网格的信息，请取消行注释（删除 #）并添加第二个网格的信息。 在 vdc {...} 部分内重复 vdc 程序块可以添加更多网格。 此外请注意，经纬度的设置值是可选的。
7. 保存并退出文本编辑器。
8. 为了通过 ssh 访问在 vdcs.conf 中配置的网格，需要生成公/私密钥对。

   要生成密钥对：

   ssh-keygen -t dsa -f /mnt/vol/data/gridkey
   在提示输入密码时，按 Enter 键。 请勿输入密码。
   chmod 600 /mnt/vol/data/gridkey*
   chown 99:99 /mnt/vol/data/gridkey*
   

9. 复制公钥：

   cat /mnt/vol/data/gridkey.pub 
   

10. 在网格控制器上，使用此密钥作为每个网格的 sshkey 来创建 API 用户：

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

    用户已创建。

11. 新建用户的设置访问：

    grid modify_acl api@domain.com=grid_administrator
    

    注意：可以使用其他访问级别（有关详细信息，请参阅 RBAC 指南），但请注意这将限制 ws_api 可以运行的命令。

12. 退出卷管理器。

    现在可以用三种操作模式之一配置应用边界。

HTTPS 模式

WS_API 应用通过基于表象化状态转变 (REST) 的服务向一个或多个网格提供 Web 服务接口。 HTTPS 访问方法启用基于安全 HTTP 的 REST API 调用。

以 HTTPS 模式配置应用

1. 将 http_mode 属性设置为 https（默认）。
2. 将置为适当值。
3. 设置 opts 属性以生成自定义 SSL 证书。

   注意：如果将 opts 留空，则会在应用启动时生成通用 SSL 证书。 http_mode 和 allowed_hosts 属性设置可仍设为默认值。 例如：

   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. 使用 app start 命令或 GUI 中的“启动应用”按钮启动应用。

   第一次启动应用时，在 conf 卷的 /mnt/config/ssl_keys/keys/ 目录中将创建由客户端证书和名为 api_client.pem 的私钥构成的 PEM 格式的客户端密钥，以及名为 api_client.p14 的浏览器的 PKCS12 格式的等效密钥。 api_client.p14 密钥文件可用于任何基于浏览器的 API 访问，api_client.pem 密钥可用于任何非基于浏览器的 API 访问。

生成任何其他客户端证书

1. 登录到运行 ws_api_instance 的 main.api_srv 组件。
2. 转到 /mnt/config/ssl_keys 目录。
3. 生成“api”用户帐户的私钥。 openssl genrsa -out keys/api_client2_privkey.pem 2048
4. 生成证书签名请求让 CA 签名。 openssl req -new -key keys/api_client2_privkey.pem -out keys/api_client2_request.csr
5. 使用我们的 CA 为 CSR 签名。 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. 将 api_client2_a.pem 与 cert 串联为一，用作命令行 SSL/PEM 私钥。 cat keys/api_client2_privkey.pem keys/api_client2.cer > keys/api_client2.pem
7. 导出通过普通 Web 浏览器可使用格式的密钥。 openssl pkcs12 -export -in keys/api_client2.cer -inkey keys/api_client2_privkey.pem -out keys/api_client2.p14。

HTTP 模式

WS_API 应用通过基于表象化状态转变 (REST) 的服务向一个或多个网格提供 Web 服务接口。 HTTP 访问方法启用基于简单 HTTP 的 REST API 调用。

注意：使用此模式时应非常小心。 此模式没有安全检查，任何人都可以在没有进行任何身份验证的情况下创建 API 请求。 此外，客户端和 ws_api_instance 应用之间的所有流量都是明文。

要在 HTTP 模式下配置应用，需要将 http_mode 属性设置为 http 并将强制性属性设置为适当值。 例如：

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

现在可以使用 app start 命令或 GUI 中的“启动应用”按钮启动应用。

VPN 模式

WS_API 应用通过基于表象化状态转变 (REST) 的服务向一个或多个网格提供 Web 服务接口。 VPN 访问方法使 HTTP 请求能够通过安全 VPN 通道发送。

以 VPN 模式配置应用

1. 将 iface.vpn 外部接口设置为所需 IP 地址并禁用 vpn_standby，即将其设置为 0。
2. 将 in_standby 设置为 1 以限制通过 VPN 设置访问。

   例如：

   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. 使用应用启动命令或 GUI 中的“启动应用”按钮启动应用。

   在应用启动之后，VPN 服务器组件会生成必要的服务器证书和密钥文件（如果不存在这些文件）。

4. 登录到组件并执行位于 /appliance 目录中的 security.sh 脚本以生成客户端证书和密钥。

   [ws_api_instance:main.in_vpn appliance]# ./security.sh generate_client
   生成的客户端 SSL 证书和密钥文件。
   ==============================================
   这些文件以及 CA 证书文件应复制到 VPN 服务器的 
   数据卷或 fs 挂接卷的 /client/ 子目录。
   在 auth_path 属性中应指定到客户端文件（client.a1c65e2bae3d0b57）的路径。
   文件的位置：
   客户端证书：/mnt/data/server/client.a1c65e2bae3d0b57.crt
   客户端密钥文件：/mnt/data/server/client.a1c65e2bae3d0b57.key
   CA 证书文件位于 /mnt/data/server/ca.crt
   

   在客户端子目录中生成客户端证书（例如：client.xxxxxxxxxxxxxxxx.crt）和密钥文件（例如：client.xxxxxxxxxxxxxxxx.key），在 conf 卷的服务器子目录中生成 CA 证书（ca.crt）。

5. 将证书复制到远程 VPN 客户端组件的数据卷或 NFS 安装卷的 /client/ 子目录中。

注释

使用的开源软件和第三方软件

下面的第三方开源软件已安装在代码卷上。