自定义路由-使用手册

acs/proxy

自定义代理镜像，通过 FROM dockercloud/haproxy 的方式继承自镜像 dockercloud/haproxy，动态感知容器的状态，做到后端容器负载均衡代理和服务发现。特点是将 HAProxy 负载均衡软件的所有配置都参数化了，方便您自定义自己的需求和配置。

该镜像主要用于 Alibaba Cloud 容器服务的默认路由服务不能满足您需求的场景，方便您对 HAProxy 进行自定义配置。

文档中会提到 acs/proxy 和 HAProxy，均指代该镜像或者镜像中的软件 HAProxy。

动态负载均衡代理和服务发现的原理

• 镜像 acs/proxy 通过容器自身环境变量确定负载均衡的全局（GLOBAL）和默认（DEFAULT）配置。
• 镜像 acs/proxy 侦听集群中的事件，例如容器状态的变化，发生变化后重新获取集群中相关容器的信息，确定最新的负载均衡配置。
• 镜像 acs/proxy 根据最新的负载均衡配置去重新加载（reload）该配置，使得该配置生效。

如何确定负载均衡的后端容器

• 根据 acs/proxy 的环境变量 ADDITIONAL_SERVICES 来确定范围。
  • ADDITIONAL_SERVICES: "*" 表示范围为整个集群。
  • ADDITIONAL_SERVICES: "project_name1:service_name1,project_name2:service_name2" 表示范围为当前应用和指定应用的指定服务。
  • ADDITIONAL_SERVICES 不设置或者为空表示范围为当前应用的容器。
• 根据每个容器的标签来确定是否加入 acs/proxy 的后端。
  • aliyun.proxy.VIRTUAL_HOST: "www.toolchainx.com" 表示加入后端，且域名为 www.toolchainx.com。
  • aliyun.proxy.required: "true" 表示加入后端，且作为默认的后端。

如何在前端绑定负载均衡

使用自定义负载均衡标签，例如 aliyun.lb.port_80: 'tcp://proxy:80'。

关于自定义负载均衡标签的使用方法，参见 lb 标签。

示例模板

 lb:
    image:  registry.aliyuncs.com/acs/proxy:0.5
    ports:
            -  '80:80'
    restart:  always
    labels:
        # addon 使得 proxy 镜像有订阅注册中心的能力，动态加载服务的路由
        aliyun.custom_addon:  "proxy"
        # 每台 vm 部署一个该镜像的容器
        aliyun.global:  "true"
        #  使用自定义负载均衡，前端绑定负载均衡
        aliyun.lb.port_80: tcp://proxy_test:80
    environment:
        #  支持加载路由的后端容器的范围，"*"表示整个集群，默认为应用内的服务
        ADDITIONAL_SERVICES:  "*"
appone:
    expose:  # 被代理的服务一定要使用 expose 或者 ports 告诉 proxy 容器暴露哪个端口
        -  80/tcp
    image:  'nginx:latest'
    labels:
        # 此处支持 http/https/ws/wss 协议
        # 必须使用您自己的域名而不是容器服务提供的测试域名
        aliyun.proxy.VIRTUAL_HOST:  "http://appone.example.com"
    restart:  always

配置说明

通过 acs/proxy 镜像的环境变量设置全局（GLOBAL）和默认（DEFAULT）配置

注意：您需要重新部署 HAProxy 服务才能使此处的配置变更生效。该部分的配置针对的是镜像 acs/proxy 所在服务的环境变量配置。

被代理的后端服务通过相应服务镜像的标签（LABEL）进行某一后端服务的配置

即通过将标签（LABEL）写到后端服务的镜像上来进行配置。该部分的配置写在被代理的服务的模版部分

此处的设置可以覆盖 HAProxy 的设置。HAProxy 的设置仅适用于依赖的服务。如果在阿里云容器服务上运行，当服务重新部署，加入或者退出 HAProxy 服务时，HAProxy 服务会自动进行更新来应用这些变更。

有关以上内容的更多信息，参见 HAProxy 配置手册。

虚拟主机和虚拟路径

您可以在 VIRTUAL_HOST 环境变量中同时指定虚拟主机和虚拟路径。该变量的值由 URL 组成，多个 URL 之前用逗号分隔，格式为 [scheme://]domain[:port][/path]。

匹配示例

注意：

• 基于 VIRTUAL_HOST 所生成的 ACL 规则的顺序是随机的。在 HAProxy 中，当范围较窄的规则（比如 web.domain.com）被放置在范围较宽的规则（比如 *.domain.com）之后时， 系统永远不会达到范围较窄的规则。因此，如果您所设置的虚拟主机包含相互重叠的范围时，您需要使用 VIRTUAL_HOST_WEIGHT 来手动设置 ACL 规则的顺序，为范围较窄的虚拟主机设置高于范围较宽的虚拟主机的权重。
• 所有带有相同 VIRTUAL_HOST 环境变量设置的服务将被看做并合并为一个服务。这对于一些测试场景比较适用。

SSL termination

acs/proxy 支持证书的 SSL ternimation。您只需要为每一个需要使用 SSL ternimation 的应用设置 SSL_CERT 和 VIRTUAL_HOST 即可。然后，HAProxy 会读取依赖环境中的证书并开启 SSL ternimation。

注意： 当环境变量的值中包含等号（=）时（这种情况在 SSL_CERT中很普遍），Docker 会跳过该环境变量。因此，您只能在 Docker 1.7.0 或更高版本上使用多 SSL ternimation。

在以下情况下会启用 SSL ternimation：

• 至少设置了一个 SSL 证书。
• 没有设置 VIRTUAL_HOST 或者设置为使用 HTTPS 协议。

您可以通过以下方法设置 SSL 证书：

• 在 acs/proxy 中设置 DEFAULT_SSL_CERT。
• 在依赖于 acs/proxy 的应用服务中设置 aliyun.proxy.SSL_CERT 和/或 DEFAULT_SSL_CERT。

aliyun.proxy.SSL_CERT 和 DEFAULT_SSL_CERT 的区别在于 SSL_CERT 指定的多个证书保存为 cert1.pem, cert2.pem, ...，而 DEFAULT_SSL_CERT 指定的证书通常保存为 cert0.pem。在这种情况下，当没有设置 SNI 匹配时，HAProxy 会将 cert0.pem 用作默认证书。然而，当提供了多个 DEFAULT_SSL_CERTIFICATE 时，仅有其中一个证书可以保存为 cert0.pem，其它的证书将被弃用。

PEM 文件

acs/proxy 或依赖的应用服务所指定的证书为一个 pem 文件。该文件包含私钥和公钥（其中，私钥必须放在公钥和其它许可证书的前面）。您可以运行下面的脚本生成一个自签名证书。

openssl req -x509 -newkey rsa:2048 -keyout key.pem -out ca.pem -days 1080 -nodes -subj '/CN=*/O=My Company Name LTD./C=US'
cp key.pem cert.pem
cat ca.pem >> cert.pem

您获取 pem 文件之后，可以运行下面的命令将文件转化为一行内容。

awk 1 ORS='\\n' cert.pem

拷贝转换后的内容并将其设置为 aliyun.proxy.SSL_CERT 或 DEFAULT_SSL_CERT 的值。

亲和性和会话保持

您可以通过以下任一方法设置亲和性和会话保持。

• 在您的应用服务中设置 aliyun.proxy.BALANCE=source。当设置了 source 负载均衡方法时， HAProxy 会对客户端 IP 地址进行哈希并确保同一个 IP 总是连接到同一个后端服务容器上。
• 设置 aliyun.proxy.APPSESSION=<value>。使用应用会话来确定客户端应该连接到哪一个服务容器上。<value> 可以设置为 JSESSIONID len 52 timeout 3h。
• 设置 aliyun.proxy.COOKIE=<value>。使用应用 cookie 来确定客户端应该连接到哪一个后端服务容器上。<value> 可以设置为 SRV insert indirect nocache。

更多详细信息，参见 HAProxy:appsession 和 HAProxy:cookie。

TCP 负载均衡

默认情况下，acs/proxy 运行在 http 模式下。如果您希望依赖的服务运行在 tcp 模式下，您可以指定 TCP_PORTS 环境变量。该变量的值为以逗号分隔的端口号（9000, 9001）。

例如，如果您运行以下命令：

docker --name app-1 --expose 9000 --expose 9001 -e TCP_PORTS="9000, 9001" your_app
docker --name app-2 --expose 9000 --expose 9001 -e TCP_PORTS="9000, 9001" your_app
docker run --link app-1:app-1 --link app-2:app-2 -p 9000:9000, 9001:9001 acs/proxy

HAProxy 将分别在 9000 端口和 9001 端口上对 app-1 和 app-2 进行负载均衡。

此外，如果您所暴露的端口多于 TCP_PORTS 中所设置的端口，剩余的端口将会使用 http 模式进行负载均衡。

例如，如果您运行以下命令：

docker --name app-1 --expose 80 --expose 22 -e TCP_PORTS=22 your_app
docker --name app-2 --expose 80 --expose 22 -e TCP_PORTS=22 your_app
docker run --link app-1:app-2 --link app-2:app-2 -p 80:80 -p 22:22 acs/proxy

HAProxy 会在 80 端口使用 http 模式进行负载均衡，在 22 端口使用 tcp 模式进行负载均衡。

通过这种方法，您可以同时使用 tcp 模式和 http 模式进行负载均衡。

如果您在 TCP_PORTS 中设置了以 /ssl 结尾的端口，比如 2222/ssl，HAProxy 会在 2222 端口上设置 SSL termination。

注意：

• 您可以同时设置 VIRTUAL_HOST 和 TCP_PORTS，以便为 http 模式提供更多的管控。
• tcp 端口上的负载均衡适用于所有的服务。因此，如果您依赖了两个或多个使用同一 TCP_PORTS 设置的不同服务，acs/proxy 会将这些服务看做同一个服务。

WebSocket 支持

您可以通过以下任一方法启用 websocket 支持：

• 鉴于 Websocket 使用 HTTP 协议进行启动，您可以使用虚拟主机来指定使用 ws 或 wss 协议。比如，-e VIRTUAL_HOST="ws://ws.domain.com, wss://wss.domain.com"。
• 鉴于 Websocket 本身为 TCP 连接，因此您可以尝试使用本文档前面所介绍的 TCP 负载均衡。

使用场景示例

注意：

• 一下示例中的acs/proxy镜像均是registry.aliyuncs.com/acs/proxy:0.5的简写形式，请做相应替换。

我的 webapp 容器暴露了 8080 端口（或任意其它端口），我希望 proxy 监听 80 端口

使用下面的命令：

docker run -d --expose 80 --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -p 80:80 acs/proxy

我的 webapp 容器暴露了 80 端口和 8083/8086 数据库端口，我希望 proxy 监听 80 端口并且不希望将数据库端口加入 acs/proxy

docker run -d -e EXCLUDE_PORTS=8803,8806 --expose 80 --expose 8033 --expose 8086 --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -p 80:80 acs/proxy

我的容器暴露了 8080 端口（或任意其它端口），我希望 acs/proxy 监听 8080 端口

使用下面的命令：

docker run -d --expose 8080 --name webapp your_app
docker run -d --link webapp:webapp -p 8080:80 acs/proxy

我希望 acs/proxy 处理 SSL 连接并将我的普通 HTTP 请求转发到端口 8080（或任意其它端口）

使用下面的命令：

docker run -d -e SSL_CERT="YOUR_CERT_TEXT" --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -p 443:443 -p 80:80 acs/proxy

或者

docker run -d --link webapp:webapp -p 443:443 -p 80:80 -e DEFAULT_SSL_CERT="YOUR_CERT_TEXT" acs/proxy

YOUR_CERT_TEXT 中的证书包含私钥和公钥（其中，私钥在前，公钥在后）。您需要在证书的行与行之间加上 \n。假设您的证书保存在 ~/cert.pem 中，您可以运行以下命令。

docker run -d --link webapp:webapp -p 443:443 -p 80:80 -e DEFAULT_SSL_CERT="$(awk 1 ORS='\\n' ~/cert.pem)" acs/proxy

我希望 acs/proxy 终结 SSL 连接并将 HTTP 请求重定向为 HTTPS 请求

使用下面的命令：

docker run -d -e FORCE_SSL=yes -e SSL_CERT="YOUR_CERT_TEXT" --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -p 443:443 acs/proxy

我希望从数据卷中加载我的 SSL 证书，而不是通过环境变量来传递证书内容

您可以使用 CERT_FOLDER 环境变量来指定证书挂载在容器的哪个文件夹中。使用以下命令。

docker run -d --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -e CERT_FOLDER="/certs/" -v $(pwd)/cert1.pem:/certs/cert1.pem -p 443:443 acs/proxy

我希望通过域名设置虚拟主机路由

可以通过 proxy 读取依赖的容器的环境变量（VIRTUAL_HOST）来配置虚拟主机。

示例：

docker run -d -e VIRTUAL_HOST="www.webapp1.com, www.webapp1.org" --name webapp1 dockercloud/hello-world
docker run -d -e VIRTUAL_HOST=www.webapp2.com --name webapp2 your/webapp2
docker run -d --link webapp1:webapp1 --link webapp2:webapp2 -p 80:80 acs/proxy

在上面的例子中，当您访问 http://www.webapp1.com 或 http://www.webapp1.org 时，将显示运行于容器 webapp1 上的服务，http://www.webapp2.com 会连接到容器 webapp2。

如果您使用下面的命令：

docker run -d -e VIRTUAL_HOST=www.webapp1.com --name webapp1 dockercloud/hello-world
docker run -d -e VIRTUAL_HOST=www.webapp2.com --name webapp2-1 dockercloud/hello-world
docker run -d -e VIRTUAL_HOST=www.webapp2.com --name webapp2-2 dockercloud/hello-world
docker run -d --link webapp1:webapp1 --link webapp2-1:webapp2-1 --link webapp2-2:webapp2-2 -p 80:80 acs/proxy

当您访问 http://www.webapp1.com 时，将显示运行于容器 webapp1 上的服务， http://www.webapp2.com 将基于轮询调度算法（或者任何其它 BALANCE 指定的算法）连接到容器 webapp2-1 和 webapp2-2 上。

我希望我所有的 *.node.io 域名均指向我的服务

docker run -d -e VIRTUAL_HOST="*.node.io" --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -p 80:80 acs/proxy

我希望 web.domain.com 连接到一个服务， *.domain.com 连接到另外一个服务

docker run -d -e VIRTUAL_HOST="web.domain.com" -e VIRTUAL_HOST_WEIGHT=1 --name webapp dockercloud/hello-world
docker run -d -e VIRTUAL_HOST="*.domain.com" -e VIRTUAL_HOST_WEIGHT=0 --name app dockercloud/hello-world
docker run -d --link webapp:webapp --link app:app -p 80:80 acs/proxy

我希望所有到 /path 路径的请求均指向我的服务

docker run -d -e VIRTUAL_HOST="*/path, */path/*" --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -p 80:80 acs/proxy

我希望所有的静态 html 请求均指向我的服务

docker run -d -e VIRTUAL_HOST="*/*.htm, */*.html" --name webapp dockercloud/hello-world
docker run -d --link webapp:webapp -p 80:80 acs/proxy

我希望查看 HAProxy stats

docker run -d --link webapp:webapp -e STATS_AUTH="auth:auth" -e STATS_PORT=1936 -p 80:80 -p 1936:1936 acs/proxy

我希望将我的日志发送到 papertrailapp

用与您的 papertrailapp 账号相匹配的值替换 <subdomain> 和 <port>。

docker run -d --name web1 dockercloud/hello-world
docker run -d --name web2 dockercloud/hello-world
docker run -it --env RSYSLOG_DESTINATION='<subdomain>.papertrailapp.com:<port>' -p 80:80 --link web1:web1 --link web2:web2 acs/proxy

使用虚拟主机的拓扑图

阿里云容器服务代理拓扑图

手动重新加载 HAProxy

在大多数情况下，当依赖的服务发生变化时，acs/proxy 会自动进行配置。但是如果需要的话，您也可以按照下面的方法手动重新加载 acs/proxy。

docker exec <acs/proxy_container_id> /reload.sh