• 构建你的服务
  • 概述
  • 创建你的service API
  • 验证
    • 准备条件
    • 列出可用计划
    • 创建新的实例
    • 把实例绑定到应用
    • 从应用解绑定实例
    • 白名单单元
    • 删除实例
    • 检查实例的状态
  • 创建一个服务清单
  • 提交你的service API

    构建你的服务

    概述

    本文档是将你已有的云服务变成tsuru服务的实战指南。为了创建一个服务，你需要为自己的服务实现配置API，当用户创建一个新的实例或者把应用绑定到实例上时，tsuru会通过HTTP协议调用。还需要创建一个YAML文档，作为服务的清单。我们提供一个命令行工具帮助你创建这个清单和管理你的服务。

    创建你的service API

    你可以用任意的编程语言和框架实现你的service API。本教程中我们采用Flask。

    验证

    tsuru使用最基本的验证方式来验证服务，更多关于验证的内容请查看API工作流。

    使用Flask，你可以通过这个Flask代码段中的修饰符来管理最基本的验证。

    准备条件

    首先确保Python和pip已经安装：

    1.     $ python --version
    2.     Python 2.7.2
    4.     $ pip
    5.     Usage: pip COMMAND [OPTIONS]
    7.     pip: error: You must give a command (use "pip help" to see a list of commands)

    更多关于如何安装Python的内容请查看Python 下载文档，以及如何安装pip请查看pip安装指南。安装完python和pip后，就可以使用pip去安装Flask了：

    1.     $ pip install flask

    安装完Flask后，是时候创建名为api.py的文件并且添加创建最小的Flask应用的代码：

    2.     from flask import Flask
    3.     app = Flask(__name__)
    5.     @app.route("/")
    6.     def hello():
    7.         return "Hello World!"
    9.     if __name__ == "__main__":
    10.         app.run()

    为了运行这个应用可以这么做：

    1.     $ python api.py
    2.      * Running on http://127.0.0.1:5000/

    打开浏览器访问http://127.0.0.1:5000/这个地址，会看到"Hello World!"这个消息。然后，你需要实现tsuru service API的资源，如:doc:tsuru service API workflow </services/api>所述。

    列出可用计划

    tsuru可以通过发送GET请求到/resources/plans获得可用的计划列表。让我们创建处理这个请求的视图：

    1.     import json
    4.     @app.route("/resources/plans", methods=["GET"])
    5.     def plans():
    6.         plans = [{"name": "small", "description": "small instance"},
    7.                  {"name": "medium", "description": "medium instance"},
    8.                  {"name": "big", "description": "big instance"},
    9.                  {"name": "giant", "description": "giant instance"}]
    10.         return json.dumps(plans)

    创建新的实例

    对于新的实例，tsuru会发送POST请求到/resources加上必要参数去创建一个实例。如果服务实例创建成功，你的API应该返回201状态码。让我们为这个动作创建视图：

    1.     from flask import request
    4.     @app.route("/resources", methods=["POST"])
    5.     def add_instance():
    6.         name = request.form.get("name")
    7.         plan = request.form.get("plan")
    8.         team = request.form.get("team")
    9.         # use the given parameters to create the instance
    10.         return "", 201

    把实例绑定到应用

    在绑定动作中，tsuru通过发送POST请求加上必要参数到/resources/<service-instance-name>/bind-app来调用服务去把应用绑定到服务实例。如果绑定操作成功，API返回201状态码，同时在JSON消息体中会包含应用应当设置的环境变量。让我们创建一个返回伪造的名为"SOMEVAR"变量的视图，这个变量可以被插入到应用的环境中：

    2.     import json
    4.     from flask import request
    7.     @app.route("/resources/<name>/bind-app", methods=["POST"])
    8.     def bind_app(name):
    9.         app_host = request.form.get("app-host")
    10.         # use name and app_host to bind the service instance and the #
    11.         application
    12.         envs = {"SOMEVAR": "somevalue"}
    13.         return json.dumps(envs), 201

    从应用解绑定实例

    In the unbind action, tsuru issues a DELETE request to the URL/resources/<service-instance-name>/bind-app.

    If the unbind operation succeeds, the API should return 200 as status code.Let's create the view for this action:

    1.     @app.route("/resources/<name>/bind-app", methods=["DELETE"])
    2.     def unbind_app(name):
    3.         app_host = request.form.get("app-host")
    4.         # use name and app-host to remove the bind
    5.         return "", 200

    白名单单元

    绑定和解绑定服务实例到应用时，tsuru同时会提供关于访问服务实例的单元的信息，因此service API任何需要的白名单（比如，在网络交换机写入ACL规则或者在防火墙授权访问）。

    tsuru会发送POST和DELETE请求，加上应用的主机以及单元，到路由到/resources/<name>/bind，所以API可以处理任何的访问控制：

    1.     @app.route("/resources/<name>/bind", methods=["POST", "DELETE"])
    2.     def access_control(name):
    3.         app_host = request.form.get("app-host")
    4.         unit_host = request.form.get("unit-host")
    5.         # use unit-host and app-host, according to the access control tool, and
    6.         # the request method.
    7.         return "", 201

    删除实例

    tsuru会通过发送DELETE请求到/resources/<service_name>来执行删除操作。如果服务实例成功删除，API应担返回201状态码。让我们为这个动作创建视图：

    1.     @app.route("/resources/<name>", methods=["DELETE"])
    2.     def remove_instance(name):
    3.         # remove the instance named "name"
    4.         return "", 200

    检查实例的状态

    tsuru通过发送GET请求到/resources/<service_name>/status来检查一个实例的状态。如果实例完好，这个链接应当返回204。让我们为这个动作创建视图：

    1.     @app.route("/resources/<name>/status", methods=["GET"])
    2.     def status(name):
    3.         # check the status of the instance named "name"
    4.         return "", 204

    我们用Flask开发的“伪API”的最终代码如下：

    1.     import json
    3.     from flask import Flask, request
    5.     app = Flask(__name__)
    8.     @app.route("/resources/plans", methods=["GET"])
    9.     def plans():
    10.         plans = [{"name": "small", "description": "small instance"},
    11.                  {"name": "medium", "description": "medium instance"},
    12.                  {"name": "big", "description": "big instance"},
    13.                  {"name": "giant", "description": "giant instance"}]
    14.         return json.dumps(plans)
    17.     @app.route("/resources", methods=["POST"])
    18.     def add_instance():
    19.         name = request.form.get("name")
    20.         plan = request.form.get("plan")
    21.         team = request.form.get("team")
    22.         # use the given parameters to create the instance
    23.         return "", 201
    26.     @app.route("/resources/<name>/bind-app", methods=["POST"])
    27.     def bind_app(name):
    28.         app_host = request.form.get("app-host")
    29.         # use name and app_host to bind the service instance and the #
    30.         application
    31.         envs = {"SOMEVAR": "somevalue"}
    32.         return json.dumps(envs), 201
    35.     @app.route("/resources/<name>/bind-app", methods=["DELETE"])
    36.     def unbind_app(name):
    37.         app_host = request.form.get("app-host")
    38.         # use name and app-host to remove the bind
    39.         return "", 200
    42.     @app.route("/resources/<name>", methods=["DELETE"])
    43.     def remove_instance(name):
    44.         # remove the instance named "name"
    45.         return "", 200
    48.     @app.route("/resources/<name>/bind", methods=["POST", "DELETE"])
    49.     def access_control(name):
    50.         app_host = request.form.get("app-host")
    51.         unit_host = request.form.get("unit-host")
    52.         # use unit-host and app-host, according to the access control tool, and
    53.         # the request method.
    54.         return "", 201
    57.     @app.route("/resources/<name>/status", methods=["GET"])
    58.     def status(name):
    59.         # check the status of the instance named "name"
    60.         return "", 204
    62.     if __name__ == "__main__":
    63.         app.run()

    .. _service_manifest:

    创建一个服务清单

    可以使用crane去创建一个清单的模板：

    1.     $ crane template

    这会在当前路径下创建包含如下内容的manifest.yaml文件：

    1.     id: servicename
    2.     password: abc123
    3.     endpoint:
    4.         production: production-endpoint.com

    manifest.yaml是crane用来定义ID，密码和服务的产品环境端点的文件。在清单中修改这些信息，然后提交服务：

    2.     id: servicename
    3.     username: username_to_auth
    4.     password: 1CWpoX2Zr46Jhc7u
    5.     endpoint:
    6.       production: production-endpoint.com
    7.         test: test-endpoint.com:8080

    submit your service: Submiting your service API

    提交你的service API

    可以运行下面的命令来提交service API：

    1.     $ crane create manifest.yaml

    更多内容，请查看:doc:service API workflow </services/api> and the:doc:crane usage guide </services/usage>.

    原文: http://doc.oschina.net/tsuru-paas?t=52835