clusterhq/powerstrip

Powerstrip：Docker扩展原型工具

重要提示：此工具已弃用

在https://github.com/docker/docker/blob/master/CHANGELOG.md#180-2015-08-11%E4%B8%AD%EF%BC%8CDocker%E5%BC%95%E6%93%8E%E5%A2%9E%E5%8A%A0%E4%BA%86%E5%AF%B9https://docs.docker.com/engine/extend/plugins_volume/%E7%9A%84%E6%94%AF%E6%8C%81%EF%BC%8C%E7%BD%91%E7%BB%9C%E9%A9%B1%E5%8A%A8%E5%9C%A8https://github.com/docker/docker/blob/master/CHANGELOG.md#190-2015-11-03%E4%B8%AD%E8%B7%9F%E8%BF%9B%E6%94%AF%E6%8C%81%E3%80%82%E7%8E%B0%E5%9C%A8%EF%BC%8C%E8%BF%99%E6%98%AF%E4%BD%BF%E7%94%A8%E7%AC%AC%E4%B8%89%E6%96%B9%E6%8F%92%E4%BB%B6%E6%89%A9%E5%B1%95Docker%E5%8A%9F%E8%83%BD%E7%9A%84%E9%A6%96%E9%80%89%E6%96%B9%E5%BC%8F%E3%80%82

Powerstrip现已弃用，ClusterHQ不再对其进行开发，但我们将继续审核和合并社区提交的补丁。

https://github.com/ClusterHQ/powerstrip#goal-of-project%E5%B7%B2%E5%AE%9E%E7%8E%B0%EF%BC%8C%E6%88%91%E4%BB%AC%E8%A6%81%E6%84%9F%E8%B0%A2Docker%E5%8F%8A%E6%9B%B4%E5%B9%BF%E6%B3%9B%E7%94%9F%E6%80%81%E7%B3%BB%E7%BB%9F%E4%B8%AD%E6%89%80%E6%9C%89%E4%B8%BADocker%E6%89%A9%E5%B1%95%E9%A1%B9%E7%9B%AE%E5%81%9A%E5%87%BA%E8%B4%A1%E7%8C%AE%E7%9A%84%E4%BA%BA%E3%80%82

什么是Powerstrip？

Powerstrip是一个可配置、可插拔的Docker API HTTP代理，允许将多个Docker扩展原型插入同一Docker守护进程。

例如，您可以同时运行存储适配器（如Flocker）和网络适配器（如Weave），且都能与您选择的编排框架良好协作。

对社区而言，这一点至关重要，它立即实现了Docker扩展原型的组合。

其目的是允许快速原型设计，以确定需要哪些集成点，才能将此类原型适配器转变为https://github.com/docker/docker/issues/9983%E3%80%82

工作原理

Powerstrip通过为任意Docker API调用实现链式阻塞webhook来工作。

这一设计灵感来自https://github.com/docker/docker/issues/6982%E3%80%82

术语说明：我们将插入Powerstrip的组件称为"适配器"，因为这符合其隐喻，且有助于区分Powerstrip适配器与其所原型化的Docker扩展。

目标受众

本项目的目标受众是希望编写Docker扩展的人员，而非最终用户。有关可与Docker一起使用的适配器列表，请参见下面的"Powerstrip适配器"部分。

项目目标

最终应能运行例如启用Powerstrip的Docker Swarm，并同时加载Flocker和Weave作为扩展。

yaml
version: 1
endpoints:
  "POST /*/containers/create":
    pre: [flocker, weave]
  "POST /*/containers/*/start":
    post: [weave]
adapters:
  weave: http://weave/extension
  flocker: http://flocker/flocker-adapter

此示例可能允许编排框架迁移（重新调度）有状态容器，同时其Weave IP和Flocker卷随之移动。

Powerstrip配置文件可匹配任何Docker API端点。

这使您能够修改任何Docker行为，并意味着Powerstrip将轻松适应Docker HTTP API未来的变化。

试用

Powerstrip以Docker镜像形式提供，适配器可以是任何HTTP端点，包括其他链接的Docker容器。

https://github.com/clusterhq/powerstrip-slowreq%E6%98%AF%E4%B8%80%E4%B8%AA%E7%AE%80%E5%8D%95%E7%9A%84Powerstrip%E9%80%82%E9%85%8D%E5%99%A8%EF%BC%88%E5%AE%B9%E5%99%A8%EF%BC%89%EF%BC%8C%E5%AE%83%E4%B8%BA%E6%89%80%E6%9C%89%E5%88%9B%E5%BB%BA%E5%91%BD%E4%BB%A4%E6%B7%BB%E5%8A%A01%E7%A7%92%E5%BB%B6%E8%BF%9F%E3%80%82

按以下方式试用（假设已登录Ubuntu Docker主机）。

如果使用boot2docker，请去掉sudo并取消设置DOCKER_TLS_VERIFY。

sh
$ cd ~/
$ mkdir powerstrip-demo
$ cat > powerstrip-demo/adapters.yml <<EOF
version: 1
endpoints:
  "POST /*/containers/create":
    pre: [slowreq]
adapters:
  slowreq: http://slowreq/slowreq-adapter
EOF

$ sudo docker run -d --name powerstrip-slowreq \
           --expose 80 \
           clusterhq/powerstrip-slowreq:v0.0.1
$ sudo docker run -d --name powerstrip \
           -v /var/run/docker.sock:/var/run/docker.sock \
           -v $PWD/powerstrip-demo/adapters.yml:/etc/powerstrip/adapters.yml \
           --link powerstrip-slowreq:slowreq \
           -p 2375:2375 \
           clusterhq/powerstrip:v0.0.1

# 注意第二个命令比第一个命令多花大约1秒时间
$ time sudo docker run ubuntu echo hello
$ time DOCKER_HOST=localhost:2375 docker run ubuntu echo hello

警告：Powerstrip在2375端口上未受保护地暴露Docker API。仅在私有、安全的开发环境中使用。

问题：如果使用SELinux并遇到问题，请禁用它或运行以下命令：

sh
$ sudo grep docker /var/log/audit/audit.log | audit2allow -M mypol
$ sudo semodule -i mypol.pp

Powerstrip适配器

以下是当前和即将推出的Powerstrip适配器列表。提交拉取请求以添加您的适配器：

• powerstrip-flocker：Docker容器的可移植数据卷 - https://github.com/clusterhq/powerstrip-flocker
• powerstrip-weave：使用Weave进行容器网络 - https://github.com/binocarlos/powerstrip-weave
• powerstrip-logfiles：从容器内部收集日志文件 - https://github.com/raychaser/powerstrip-logfiles

继续阅读以获取编写自己的适配器的详细信息。

编写适配器

适配器只是一个HTTP POST API端点。使用您喜欢的框架和语言编写。

Pre-hook适配器端点接收如下POST请求

Pre-hook在客户端向代理发送请求后、但请求传递到Docker守护进程之前被调用。这使适配器有机会修改或延迟请求。

POST /adapter HTTP/1.1
Content-type: application/json
Content-length: ...

{
    PowerstripProtocolVersion: 1,
    Type: "pre-hook",
    ClientRequest: {
        Method: "POST",
        Request: "/v1.16/container/create",
        Body: "{ ... }" 或 null
    }
}

它们的响应如下：

HTTP 200 OK
Content-type: application/json

{
    PowerstripProtocolVersion: 1,
    ModifiedClientRequest: {
        Method: "POST",
        Request: "/v1.16/container/create",
        Body: "{ ... }" 或 null
    }
}

例如，它们可以重写GET请求字符串，或修改POST主体中的JSON。

或者，pre-hook可以返回HTTP错误代码，在这种情况下，调用永远不会传递到Docker守护进程，而是将错误直接返回给客户端。

Pre-hook不得更改所匹配端点的范围 - 重写Request应仅用于修改GET参数（例如URL中'?'之后的部分）。

Post-hook适配器端点接收如下POST请求

Post-hook在Docker的响应完成后、但尚未发送回客户端之前被调用。POST主体中包含初始请求和Docker响应。

因此，插件有机会修改或延迟从Docker到客户端的响应。

POST /adapter HTTP/1.1

{
    PowerstripProtocolVersion: 1,
    Type: "post-hook",
    ClientRequest: {
        Method: "POST",
        Request: "/v1.16/containers/create",
        Body: "{ ... }"
    }
    ServerResponse: {
        ContentType: "text/plain",
        Body: "{ ... }" 响应字符串或 null（如果是GET请求）,
        Code: 404
    }
}

适配器的响应如下：

{
    PowerstripProtocolVersion: 1,
    ModifiedServerResponse: {
        ContentType: "application/json",
        Body: "{ ... }",
        Code: 200
    }
}

这使post-hook有机会在认为可以的情况下将Docker错误转换为成功。

链式调用

Pre-hook和post-hook都可以链式调用：根据YAML配置中的列表顺序，第N个钩子的响应作为第N+1个钩子的请求传入。

如果任何钩子返回HTTP错误响应，链的其余部分将被取消，错误返回给客户端。您可以将其视为类似于Twisted Deferred链，其中钩子类似于回调。例外情况是当Docker API返回错误时：post-hook仍会运行，因为我们认为适配器作者希望了解Docker错误消息。

定义端点

端点使用类UNIX shell的通配符定义。请求POST /v1.16/container/create将被以下所有端点定义匹配：

• POST /v1.16/containers/create
• POST /v1*/containers/create
• POST /*/containers/create
• POST /*/*/create
• * /*/containers/create
• POST /v[12]/containers/create

注意：查询参数在匹配时被剥离。

可以匹配任何Docker端点 - 例如，以下路由完全有效：

• POST /*/containers/create
• POST /*/containers/*/start
• POST /*/containers/*/stop
• POST /*/containers/*/kill

定义端点时的有用资源是https://docs.docker.com/reference/api%E3%80%82

限制

Powerstrip不支持以下情况，并会静默跳过某些类型的钩子：

• 对于内容类型不是application/json的请求体的pre-hook，例如在build API调用中POST的构建上下文。
• 对于内容类型为application/vnd.docker.raw-stream的响应的post-hook，例如attach API调用中的"劫持"响应。

对于从Docker守护进程流式返回且没有适当帧的响应（如build和pull API调用响应）：

• 如果未添加post-hook：
  • 响应将在从Docker守护进程接收时流式传输到客户端。
• 否则，如果添加了post-hook：
  • 响应将被缓冲，然后作为单个主体传递给post-hook链。

推荐部署

目前，Powerstrip不支持TLS，但考虑到它应仅用于本地开发环境中的原型设计，这是可以接受的。

建议适配器在与代理容器链接（使用Docker链接）的容器中运行。插件应监听80端口。

然后，您可以使用例如http://adapter/指定URL，假设"adapter"是链接别名（参见"试用"下的示例）。

贡献

我们希望您能为Powerstrip提供帮助。如果您有任何问题或需要帮助，除了提交GitHub issue提出功能请求或错误报告外，您还可以加入irc.freenode.net IRC网络上的#clusterhq或#docker-extensions频道。

我们计划使用https://drone.io/%E8%BF%9B%E8%A1%8C%E5%8D%95%E5%85%83%E6%B5%8B%E8%AF%95%E7%9A%84CI%EF%BC%8C%E6%88%96%E8%80%85%E5%8F%AF%E8%83%BD%E4%BD%BF%E7%94%A8Travis-CI%E3%80%82%E9%9B%86%E6%88%90%E6%B5%8B%E8%AF%95%E5%B0%86%E5%AD%98%E5%9C%A8%EF%BC%8C%E4%BD%86%E7%9B%AE%E5%89%8D%E4%BB%85%E6%89%8B%E5%8A%A8%E8%BF%90%E8%A1%8C%E3%80%82

请求的可能路径

HTTP请求有几种不同的路径。

以下是其中一些：

• 客户端请求 => 插件pre-hook返回OK => Docker => 插件post-hook => 客户端响应
• 客户端请求 => 插件pre-hook返回错误代码 => 错误响应给客户端（不将请求传递给Docker）
• 客户端请求 => 插件pre-hook => Docker => Docker错误响应到适配器post-hook => 将错误响应传递给客户端
• 客户端请求 => 插件pre-hook => Docker => 插件post-hook => 错误响应给客户端

可能的改进

• 可以添加Continue响应参数，以允许使用非错误响应取消链。
• 可选参数/YAML配置标志的详细日志（输出到stdout），以帮助适配器作者调试适配器。
  • 定义日志/可追溯性方案（适配器和powerstrip输出到stdout？）。
• 所有已知Powerstrip钩子的公共列表（GitHub链接 + Docker Hub名称）。
• 对webhook和配置进行版本控制。
• 发布适配器的标准测试框架。
• 暴露头信息以及（代替）仅内容类型。适用于pre-hook和post-hook。
• 在错误情况下运行所有钩子，给它们机会 unwind 操作。
• 为pre-hook提供显式的"unwinder"钩子类型，以区分错误处理post-hook与常规post-hook。

变更日志

master分支中已修复：

• 添加针对真实Docker的run、build和pull的集成测试，并修复其中暴露的各种错误。
• 特别是修复docker attach、无post-hook时的流式响应、GET请求、跳过具有application/tar处理的pre-hook、attach的stdin处理。

v0.0.1：

• 初始版本

额外的适配器想法

• 容器 => start的post-hook，将阻塞直到容器完全连接到weave桥
• 容器 => create的pre-hook，将从https://github.com/hashicorp/consul%E6%88%96https://github.com/coreos/etcd%E5%8A%A0%E8%BD%BD%E7%9A%84ENV%E5%8F%98%E9%87%8F%E6%B3%A8%E5%85%A5
• 容器 => {start,stop}的post-hook，将使用容器公开的端点更新https://github.com/hashicorp/consul%E6%88%96https://github.com/coreos/etcd

许可证

Copyright 2015 ClusterHQ, Inc

根据Apache许可证2.0版（"许可证"）授权；除非符合许可证，否则您不得使用此文件。您可以在以下位置获取许可证副本：

http://www.apache.org/licenses/LICENSE-2.0

除非适用***要求或书面同意，否则根据许可证分发的软件按"原样"分发，不附带任何明示或暗示的担保或条件。有关许可证下权限和限制的具体语言，请参见许可证。