18.6　使用通知系统

18.6　使用通知系统
- 18.6.1　相关配置
- 18.6.2　Notification的使用场景

Docker Registry v2还内置提供了Notification功能，提供了非常方便、快捷的集成接口，避免了v1中需要用户自己实现的麻烦。

Notification功能其实就是Registry在有事件发生的时候，向用户自己定义的地址发送webhook通知。目前的事件包括镜像manifest的push、pull，镜像层的push、pull。这些动作会被序列化成webhook事件的payload，为集成服务提供事件详情，并通过Registry v2的内置广播系统发送到用户定义的服务接口，Registry v2称这些用户服务接口为Endpoints。

Registry服务器的事件会通过HTTP协议发送到用户定义的所有Endpoints上，而且每个Registry实例的每个Endpoint都有自己独立的队列，重试选项以及HTTP的目的地址。当一个动作发生时，会被转换成对应的事件并放置到一个内存队列中。镜像服务器会依次处理队列中的事件，并向用户定义的Endpoint发送请求。事件发送处理是串行的，但是Registry服务器并不会保证其到达顺序。

18.6.1　相关配置

Notification在Docker Registry中的相关配置如下：

notifications:
    endpoints:
        -  name: cd-handler
            disabled: false
            url: http://cd-service-host/api/v1/cd-service
            headers:
                Authorization: [token ******************]
            timeout: 1s
            threshold: 5
            backoff: 10s

上面的配置会在pull或者push发生时向http://cd-service-host/api/v1/cd-service发送事件，并在HTTP请求的header中传入认证信息，可以是Basic、token、Bearer等模式，主要用于接收事件方进行身份认证。更新配置后，需要重启Registry服务器，如果配置正确，会在日志中看到对应的提示信息，比如：

configuring endpoint listener (http://cd-service-host/api/v1/cd-service), timeout=1s,
    headers=map[Authorization: [token ******]]

此时，用户再通过docker客户端去push或pull，或者查询一些manifiest信息时，就会有相应的事件发送到定义的Endpoint上。

接下来看一下事件的格式和其中的主要属性：

{
    "events": [
        {
            "id": "70f44894-c4b4-4be8-9691-d37db77074cd",
            "timestamp": "2016-06-05T01:57:04.654256149Z",
            "action": "push",
            "target": {
                "mediaType": "application/vnd.docker.distribution.manifest.v1+json",
                "size": 45765,
                "digest": "sha256:fd0af29ba2ae034449bffb18dd6db2ed90d798464cc43
                    aa81e63770713edaea8",
                "length": 45765,
                "repository": “test-user/hello-world”,
                "url": "http://registry-server/v2/test-user/hello-world/manifests/
                    sha256:fd0af29ba2ae034449bffb18dd6db2ed90d798464cc43aa81e
                    63770713edaea8"
            },
            "request": {
                "id": "9d3d837f-d7ed-4fa9-afb4-dda58687a6ce",
                "addr": “client-host:46504",
                "host": “registry-server",
                "method": "PUT",
                "useragent": "docker/1.9.1 go/go1.4.2 git-commit/a34a1d5 kernel
                    /4.2.0-35-generic os/linux arch/amd64"
            },
            "actor": {
                "name": “test-user"
            },
            "source": {
                "addr": "8e14c2a190f2:5000",
                "instanceID": "c564003e-dd9b-4a9b-8a30-fe8564e97ba9"
            }
        }
    ]
}

每个事件的payload，都是一个定义好的JSON格式的数据。

通知系统的主要属性主要包括action、target.mediaType、target.repository、target.url、request.method、request.useragent、actor.name等，参见表18-1。

表18-1　通知系统的主要属性

18.6.2　Notification的使用场景

理解了如何配置Docker Registry v2的Notification、Endpoint，以及接收到的Event的数据格式，我们就可以很方便地实现一些个性化的需求。这里简单列举两个场景，一个是如何统计镜像的上传、下载次数，方便了解镜像的使用情况，另一个场景是对服务的持续部署，方便管理镜像，参见图18-2。

图18-2　通知系统整合持续部署

1.镜像上传、下载计数

很常见的一个场景是根据镜像下载次数，向用户推荐使用最多的镜像，或者统计镜像更新的频率，以便了解用户对镜像的维护程度。

用户可以利用Notification的功能，定义自己的计数服务，并在Docker Registry上配置对应的Endpoint。在有pull、push动作发生时，对相应镜像的下载或者上传次数进行累加，达到计数效果。然后添加一个查询接口，供用户查看用户镜像的上传、下载次数，或者提供排行榜等扩展服务。

2.实现应用的自动部署

在这个场景下，可以在新的镜像push到Docker Registry服务器时候，自动创建或者更新对应的服务，这样可以快速查看新镜像的运行效果或者进行集成测试。用户还可以根据事件中的相应属性，比如用户信息、镜像名称等，调用对应的服务部署接口进行自动化部署操作。

18.6 使用通知系统