构建你的服务

概述

本文档是将你已有的云服务变成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