nginxproxy/docker-gen

docker-gen

docker-gen 是一个文件生成工具，它使用 Docker 容器元数据渲染模板。

它可用于生成各类文件，适用于以下场景：

• 集中式日志 - https://github.com/nginx-proxy/docker-gen/blob/main/templates/fluentd.conf.tmpl、logstash 或其他集中式日志工具，用于监控容器的 JSON 日志文件或容器内的文件。
• 日志轮转 - https://github.com/nginx-proxy/docker-gen/blob/main/templates/logrotate.tmpl 文件，用于轮转容器的 JSON 日志文件。
• 反向代理配置 - https://github.com/nginx-proxy/docker-gen/blob/main/templates/nginx.tmpl、https://github.com/jwilder/docker-discover 等反向代理配置，用于将主机请求路由到容器。
• 服务发现 - 脚本（python、bash 等），用于在 https://github.com/jwilder/docker-register、hipache 等服务中注册容器。

安装

运行 docker-gen 有三种常见方式：

• 在主机上运行
• 与其他应用捆绑在同一个容器中
• 作为独立容器运行

主机安装

下载所需版本，解压并安装到 PATH 路径下。

console
wget https://github.com/nginx-proxy/docker-gen/releases/download/0.12.0/docker-gen-linux-amd64-0.12.0.tar.gz
tar xvzf docker-gen-linux-amd64-0.12.0.tar.gz
./docker-gen

捆绑容器安装

docker-gen 可以与应用一起捆绑在容器中。

https://hub.docker.com/r/nginxproxy/nginx-proxy 可信构建是在容器中与 nginx 一起运行 docker-gen 的示例。https://github.com/jwilder/docker-register 是在容器中运行 docker-gen 以通过 etcd 进行服务注册的示例。

独立容器安装

也可以使用 https://hub.docker.com/r/nginxproxy/docker-gen 镜像将其作为两个独立容器运行，几乎可以与任何其他镜像一起使用。

以下是运行官方 https://registry.hub.docker.com/_/nginx/ 镜像并让 docker-gen 生成反向代理配置的方法，类似于 nginx-proxy 的工作方式。这样做可以避免将 docker 套接字绑定到公开暴露的容器服务。

启动带有共享卷的 nginx：

console
docker run -d -p 80:80 --name docker.xuanyuan.run/nginx -v /tmp/nginx:/etc/nginx/conf.d -t nginx

获取模板并启动带有共享卷的 docker-gen 容器：

console
mkdir -p /tmp/templates && cd /tmp/templates
curl -o nginx.tmpl https://raw.githubusercontent.com/nginx-proxy/docker-gen/main/templates/nginx.tmpl
docker run -d --name nginx-gen --volumes-from nginx \
   -v /var/run/docker.sock:/tmp/docker.sock:rw \
   -v /tmp/templates:/etc/docker-gen/templates \
   -t docker.xuanyuan.run/nginxproxy/docker-gen -notify-sighup nginx -watch -only-exposed /etc/docker-gen/templates/nginx.tmpl /etc/nginx/conf.d/default.conf

启动容器，注意容器所需的环境变量。有关详细信息，请查看模板顶部说明。

console
docker run --env VIRTUAL_HOST='example.com' --env VIRTUAL_PORT=80 ...

使用方法

$ docker-gen
用法：docker-gen [选项] 模板 [目标文件]

从 Docker 容器元数据生成文件

选项：
  -config 路径
      包含模板指令的配置文件。如果多次指定此选项，配置文件将被合并。（默认 []）
  -container-filter key=value
      用于包含容器的过滤条件。可多次指定以组合多个 AND 条件。
      https://docs.docker.com/engine/reference/commandline/ps/#filter
  -endpoint 字符串
      Docker API 端点（tcp|unix://..）。默认 unix:///var/run/docker.sock
  -event-filter key=value
      用于过滤 docker-gen 监控事件的附加条件（例如 -event-filter event=connect -event-filter event=disconnect）。
      可多次指定以组合条件。默认情况下，docker-gen 监控容器的 start、stop、die 和 health_status 事件。
      https://docs.docker.com/engine/reference/commandline/events/#filtering-events
  -include-stopped
      包含已停止的容器。如果指定了容器状态过滤条件（-container-filter status=foo），则此选项失效。
  -interval 整数
      通知命令的间隔时间（秒）
  -keep-blank-lines
      保留输出文件中的空行
  -notify restart xyz
      模板重新生成后运行的命令（例如 restart xyz）
  -notify-container 容器ID
      向容器发送 -notify-signal 指定的信号（默认 1/HUP）。可多次指定以通知多个容器。
  -notify-filter key=value
      用于通知的容器过滤条件（例如 -notify-filter name=foo）。可多次指定以组合多个 AND 条件。
      https://docs.docker.com/engine/reference/commandline/ps/#filter
  -notify-output
      记录通知命令的输出（stdout/stderr）
  -notify-sighup 容器ID
      向容器发送 HUP 信号。相当于 'docker kill -s HUP 容器ID' 或 '-notify-container 容器ID -notify-signal 1'。可多次指定以向多个容器发送 HUP 信号。
  -notify-signal 信号
      发送给 -notify-container 和 -notify-filter 的信号。-1 表示调用 docker restart。默认 1（即 HUP）。
      所有可用信号请参见 dockerclient：https://github.com/fsouza/go-dockerclient/blob/main/signal.go
  -only-exposed
      仅包含已暴露端口的容器。如果使用暴露端口过滤条件（-container-filter exposed=foo），则此选项失效。
  -only-published
      仅包含已发布端口的容器（隐含 -only-exposed）。如果指定了容器发布端口过滤条件（-container-filter published=foo），则此选项失效。
  -tlscacert 字符串
      TLS CA 证书文件路径（默认 "~/.docker/ca.pem"）
  -tlscert 字符串
      TLS 客户端证书文件路径（默认 "~/.docker/cert.pem"）
  -tlskey 字符串
      TLS 客户端密钥文件路径（默认 "~/.docker/key.pem"）
  -tlsverify
      验证 Docker 守护进程的 TLS 证书
  -version
      显示版本信息
  -wait 字符串
      触发生成前等待的最小和最大时长（例如 "500ms:2s"）
  -watch
      监控容器变化

参数：
  template - 要生成的模板路径
  dest - 模板输出路径。如果未指定，输出到 STDOUT

环境变量：
  DOCKER_HOST - -endpoint 的默认值
  DOCKER_CERT_PATH - 包含 key.pem、cert.pem 和 ca.pem 的目录路径
  DOCKER_TLS_VERIFY - 启用客户端 TLS 验证
  DOCKER_CONTAINER_FILTERS - 逗号分隔的容器包含过滤条件列表。如果指定了 -container-filter，则此变量中的过滤条件将被忽略。

如果未指定 <dest> 文件，输出将发送到 stdout，主要用于调试。

配置文件

使用上述 -config 标志可以指定配置文件，而非命令行选项。配置文件中可定义多个模板，它们将按出现顺序执行。

示例配置文件 docker-gen.cfg 可在 examples 文件夹中找到。

配置文件语法

ini
[[config]]
# 开始一个配置段

dest = "path/to/a/file"
# 生成的模板输出路径。如果未指定，则输出到 STDOUT

notifycmd = "/etc/init.d/foo reload"
# 模板重新生成后运行的命令（例如 restart xyz）

onlyexposed = true
# 仅包含已暴露端口的容器

template = "/path/to/a/template/file.tmpl"
# 要生成的模板路径

watch = true
# 监控容器变化

wait = "500ms:2s"
# 防抖等待时长（最小:最大）。仅在 watch = true 时适用


[config.NotifyContainers]
# 开始一个通知容器段

containername = 1
# 容器名称后接要发送的信号

container_id = 1
# 或使用容器 ID 后接要发送的信号

以下是完整的配置文件示例：

ini
[[config]]
template = "/etc/nginx/nginx.conf.tmpl"
dest = "/etc/nginx/sites-available/default"
onlyexposed = true
notifycmd = "/etc/init.d/nginx reload"

[[config]]
template = "/etc/logrotate.conf.tmpl"
dest = "/etc/logrotate.d/docker"
watch = true

[[config]]
template = "/etc/docker-gen/templates/nginx.tmpl"
dest = "/etc/nginx/conf.d/default.conf"
watch = true
wait = "500ms:2s"

[config.NotifyContainers]
nginx = 1  # 1 是要发送的信号编号，此处为 SIGHUP
e75a60548dc9 = 1  # 键可以是容器名称（nginx）或 ID

模板

docker-gen 使用的模板基于 Go http://golang.org/pkg/text/template/ 语言编写。除了 Go 提供的 http://golang.org/pkg/text/template/#hdr-Functions，docker-gen 还使用 https://masterminds.github.io/sprig/ 和一些额外函数，以便更简单地生成所需输出。部分模板依赖容器内的环境变量来决定生成内容。

可使用分号（;）分隔 template 值来同时解析多个模板，这可作为 Golang 嵌套模板功能的替代方案。在所有情况下，主渲染模板应放在首位。

ini
[[config]]
template = "/etc/docker-gen/templates/nginx.tmpl;/etc/docker-gen/templates/header.tmpl"
dest = "/etc/nginx/conf.d/default.conf"
watch = true
wait = "500ms:2s"

输出结构

模板中，docker-gen 输出的对象结构由以下 Go 结构体组成：

go
type RuntimeContainer struct {
    ID           string
    Created      time.Time
    Addresses    []Address
    Networks     []Network
    Gateway      string
    Name         string
    Hostname     string
    Image        DockerImage
    Env          map[string]string
    Volumes      map[string]Volume
    Node         SwarmNode
    Labels       map[string]string
    IP           string
    IP6LinkLocal string
    IP6Global    string
    Mounts       []Mount
    State        State
}

type Address struct {
    IP           string
    IP6LinkLocal string
    IP6Global    string
    Port         string
    HostPort     string
    Proto        string
    HostIP       string
}

type Network struct {
    IP                  string
    Name                string
    Gateway             string
    EndpointID          string
    IPv6Gateway         string
    GlobalIPv6Address   string
    MacAddress          string
    GlobalIPv6PrefixLen int
    IPPrefixLen         int
    Internal            bool
}

type DockerImage struct {
    Registry   string
    Repository string
    Tag        string
}

type Mount struct {
  Name        string
  Source      string
  Destination string
  Driver      string
  Mode        string
  RW          bool
}

type Volume struct {
    Path      string
    HostPath  string
    ReadWrite bool
}

type SwarmNode struct {
    ID      string
    Name    string
    Address Address
}

type State struct {
	Running bool
	Health  Health
}

type Health struct {
	Status string
}

// 在模板中可通过 .Docker 访问
type Docker struct {
    Name                 string
    NumContainers        int
    NumImages            int
    Version              string
    ApiVersion           string
    GoVersion            string
    OperatingSystem      string
    Architecture         string
    CurrentContainerID   string
}

// 主机环境变量在模板中可通过 .Env 访问

例如，以下是 RuntimeContainer 结构体的 JSON 示例：

json
{
  "ID": "71e9768075836eb38557adcfc71a207386a0c597dbeda240cf905df79b18cebf",
  "Addresses": [
    {
      "IP": "172.17.0.4",
      "Port": "22",
      "Proto": "tcp",
      "HostIP": "192.168.10.24",
      "HostPort": "2222"
    }
  ],
  "Gateway": "172.17.42.1",
  "Node": {
    "ID": "I2VY:P7PF:TZD5:PGWB:QTI7:QDSP:C5UD:DYKR:XKKK:TRG2:M2BL:DFUN",
    "Name": "docker-test",
    "Address": {
      "IP": "192.168.10.24"
    }
  },
  "Labels": {
    "operatingsystem": "Ubuntu 14.04.2 LTS",
    "storagedriver": "devicemapper",
    "anything_foo": "something_bar"
  },
  "IP": "172.17.0.4",
  "Name": "docker_register",
  "Hostname": "71e976807583",
  "Image": {
    "Registry": "jwilder",
    "Repository": "docker-register"
  },
  "Env": {
    "ETCD_HOST": "172.17.42.1:4001",
    "PATH": "/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin",
    "DOCKER_HOST": "unix:///var/run/docker.sock",
    "HOST_IP": "172.17.42.1"
  },
  "Volumes": {
    "/mnt": {
      "Path": "/mnt",
      "HostPath": "/Users/joebob/tmp",
      "ReadWrite": true
    }
  }
}

函数

• https://pkg.go.dev/text/template#hdr-Functions
• https://masterminds.github.io/sprig/，但与以下函数同名的 Sprig 函数除外。
• closest $array $value：返回 $array 中与 $value 匹配的最长子字符串。
• coalesce ...：返回第一个非 nil 参数。
• comment $delimiter $string：返回每行前缀为 $delimiter 的 $string（结合 Sprig 的 toPrettyJson 用于调试很有用：{{ toPrettyJson $ | comment "#" }}）。
• contains $map $key：如果 $map 包含 $key，返回 true。接受 string 到任意类型的映射。
• dir $path：返回指定 $path 中的文件名数组。
• exists $path：如果 $path 指向现有文件或目录，返回 true。接受字符串参数。
• eval $templateName [$data]：像 Go 内置的 template 操作一样计算命名模板，但将结果作为字符串返回以便后续处理。可省略 $data 参数，相当于传递 nil。
• groupBy $containers $fieldPath：基于 $fieldPath 字段路径表达式的值对 RuntimeContainer 实例数组进行分组。字段路径表达式是点分隔的映射键或结构体成员名列表，指定从容器到嵌套字符串值的路径。返回从字段路径表达式值到具有该值的容器数组的映射。没有字段路径值的容器将被忽略