验证Docker日志记录插件

预计阅读时间：17分钟

介绍

符合Docker认证资格的内容必须符合最佳做法并通过某些基准测试。

Docker Hub允许您发布经过认证的映像以及用于日志记录，卷和网络的插件。您必须使用这些文档中说明的工具来认证自己的图像和日志记录插件inspect。当前，Docker Hub在提交时会为您认证您的卷和网络插件。

本页说明发布者如何成功测试其Docker日志记录插件。也可用：验证Docker映像。

需要未经认证的基础架构环境的内容无法发布为已认证。

在提交产品进行发布之前，您应该执行此自我认证测试。

验证您的日志记录插件

您必须使用工具，inspectDockerLoggingPlugin通过确保您的Docker日志记录插件符合最佳实践来认证您的内容以在Docker Hub上发布。

该inspectDockerLoggingPlugin命令验证您的Docker日志记录插件可以安装并且可以在Docker Enterprise Edition上运行。它还从Docker的官方镜像运行容器，alpine:latest并输出名为quotes.txt（可下载）的文件的内容。总之，inspectDockerLoggingPlugin命令：

检查并显示Docker日志记录插件。
在Docker EE上安装Docker日志记录插件。
使用Docker日志记录插件运行Docker服务容器，读取名为的文件quotes.txt，将其内容回显至stdout，并记录该文件的内容。
显示容器日志并将其与进行比较quotes.txt。如果它们匹配，则测试成功。

该inspectDockerLoggingPlugin工具将检测问题并将其输出为警告或错误。必须修正错误才能进行认证。不需要解决警告就可以进行认证，但是您应该尝试解决它们。

如果要发布和认证Docker日志记录插件的多个版本，则需要inspectDockerLoggingPlugin在每个Docker日志记录插件上运行该工具，并将每个结果发送到Docker Hub。

运行特定日志记录插件的语法为docker container run --log-driver。

没有参数传递到日志插件。如果需要参数才能使Docker日志记录插件正常工作，则必须编写并使用自定义测试脚本。默认docker container run命令是：

  docker container run -it --log-driver xxxxxxxxxxxxxxxxxxxxx \
  --volume \"$(pwd)/quotes.txt:/quotes.txt\" alpine:latest \
  sh -c 'cat /quotes.txt;sleep 20

自定义脚本必须记录quotes.txt文件的内容。它还应该清理（删除容器和docker映像）。请参考--test-script命令帮助中的命令参数。

Docker容器日志

最佳实践要求Docker日志记录插件支持ReadLogs API，以便可以使用docker container logs命令来检索日志。如果ReadLogs不支持该API，则需要一个自定义脚本来检索日志并将其打印到stdout。请参考--get-logs-script命令帮助中的命令参数。

先决条件

您的Docker Engine-Enterprise安装必须在用于验证提交的服务器上运行。如有必要，请请求获得特定Docker Enterprise Edition的权利。

Docker Engine-Enterprise（在服务器上用于验证提交）
git客户端
inspectDockerLoggingPlugin工具

设置测试环境

有两个步骤：（1）配置凭据，和（2）配置端点。

通过定义环境变量 或 将它们作为参数传递给来配置Docker Registry凭据inspectDockerLoggingPlugin。

一种。为注册表凭据定义环境变量，DOCKER_USER并DOCKER_PASSWORD：

的Linux

export DOCKER_USER="my_docker_registry_user_account"
export DOCKER_PASSWORD="my_docker_registry_user_account_password"

Windows命令提示符

set DOCKER_USER="my_docker_registry_user_account"
set DOCKER_PASSWORD="my_docker_registry_user_account_password"

Windows Powershell

$env:DOCKER_USER="my_docker_registry_user_account"
$env:DOCKER_PASSWORD="my_docker_registry_user_account_password"

b。将参数传递给inspectDockerLoggingPlugin（或提示输入）：

--docker-user
--docker-password

配置端点（和覆盖默认值）或者通过定义环境变量 或者 将它们作为参数来inspectDockerLoggingPlugin。

默认情况下，inspectDockerLoggingPlugin使用以下两个端点与Docker Hub注册表进行通信：
- 注册表身份验证端点：https : //auth.docker.io
- 注册表API端点：https : //registry-1.docker.io
您可能要使用私有注册表进行初始测试，并覆盖默认设置。

一种。定义环境变量，DOCKER_REGISTRY_AUTH_ENDPOINT并 DOCKER_REGISTRY_API_ENDPOINT：

Linux或MacOS
```
export DOCKER_REGISTRY_AUTH_ENDPOINT="https://my_docker_registry_authentication_endpoint"
export DOCKER_REGISTRY_API_ENDPOINT="https://my_docker_registry_api_enpoint"
```
Windows命令提示符
```
set DOCKER_REGISTRY_AUTH_ENDPOINT="https://my_docker_registry_authentication_endpoint"
set DOCKER_REGISTRY_API_ENDPOINT="https://my_docker_registry_api_enpoint"
```
Windows Powershell
```
$env:DOCKER_REGISTRY_AUTH_ENDPOINT="https://my_docker_registry_authentication_endpoint"
$env:DOCKER_REGISTRY_API_ENDPOINT="https://my_docker_registry_api_enpoint"
```
b。将您的端点作为参数传递给inspectDockerLoggingPlugin：
```
--docker-registry-auth-endpoint
--docker-registry-api-endpoint
```

如果需要更多详细信息以调试与Docker Registry进行通信时遇到的调试问题，则可以导出以下环境变量，该变量将生成详细的调试输出到./dockerAPI.go.log运行命令的目录中的文件中。
- Linux或MacOS
```
  export DOCKER_REGISTRY_API_DEBUG="true"
```
- 视窗
  - Windows命令提示符
    set DOCKER_REGISTRY_API_DEBUG="true"
  - Windows Powershell
    $env:DOCKER_REGISTRY_API_DEBUG="true"

句法

下载inspectDockerLoggingPlugin命令。

操作系统/架构	下载链接
Windows / X86	https://s3.amazonaws.com/store-logos-us-east-1/certification/windows/inspectDockerLoggingPlugin.exe
Linux / X86	https://s3.amazonaws.com/store-logos-us-east-1/certification/linux/inspectDockerLoggingPlugin
Linux / IBMZ	https://s3.amazonaws.com/store-logos-us-east-1/certification/zlinux/inspectDockerLoggingPlugin
Linux / IBMPOWER	https://s3.amazonaws.com/store-logos-us-east-1/certification/power/inspectDockerLoggingPlugin

设置inspectDockerLoggingPluginlinux，zlinux和power的许可权，以便它是可执行的：
```
chmod u+x inspectDockerLoggingPlugin
```

下载http_api_endpoint命令

操作系统/架构	下载链接
Windows / X86	https://s3.amazonaws.com/store-logos-us-east-1/certification/windows/http_api_endpoint.exe
Linux / X86	https://s3.amazonaws.com/store-logos-us-east-1/certification/linux/http_api_endpoint
Linux / IBMZ	https://s3.amazonaws.com/store-logos-us-east-1/certification/zlinux/http_api_endpoint
Linux / IBMPOWER	https://s3.amazonaws.com/store-logos-us-east-1/certification/power/http_api_endpoint

设置http_api_endpointlinux，zlinux和power的许可权，以便它是可执行的：
```
chmod u+x http_api_endpoint
```
下载quotes.txt并将其放在同一目录中。

从您要参考的计划页面中获取产品ID，以进行认证测试。确保选中此复选框，然后首先保存计划。

产品编号

Inspects a Docker logging plugin to see if it conforms to best practices.

Syntax: inspectDockerLoggingPlugin [options] dockerLoggingPlugin

Options:
  -docker-password string
    	 Docker Password.  This overrides the DOCKER_PASSWORD environment variable.
  -docker-registry-api-endpoint string
    	 Docker Registry API Endpoint. This overrides the DOCKER_REGISTRY_API_ENDPOINT environment variable. (default "https://registry-1.docker.io")
  -docker-registry-auth-endpoint string
    	 Docker Registry Authentication Endpoint. This overrides the DOCKER_REGISTRY_AUTH_ENDPOINT environment variable. (default "https://auth.docker.io")
  -docker-user string
    	 Docker User ID.  This overrides the DOCKER_USER environment variable.
  -get-logs-script string
    	 An optional custom script used to retrieve the logs.
  -insecure-skip-verify
       Optional. Specifies to disable SSL verification for an insecure private Docker Registry.         
  -help
    	 Help on the command.
  -html
    	 Generate HTML output.
  -json
    	 Generate JSON output.
  -product-id string
    	 Optional Product identifier from Docker Hub for this plugin. Please include it when you want the output sent to Docker Hub for certification.
  -test-script string
    	 An optional custom script used to test the Docker logging plugin. The script gets passed 1 parameter - the Docker logging plugin name.
  -verbose
    	 Displays more verbose output.

dockerLoggingPlugin
  	The Docker logging plugin to inspect. This argument is required.

检查输出

默认情况下，将inspectDockerLoggingPlugin输出显示为本地stdout（默认），JSON和HTML。您还可以将输出上传到Docker Hub，建议管理员进行验证。

上传到Docker Hub（通过product-id在命令行中输入）。
传送讯息给stdout。这是默认值。
JSON发送到stdout。使用该--json选项可以覆盖和替换发送给的消息stdout。
HTML本地文件。使用该--html选项生成HTML报告。双方--json并--html可以同时指定。

使用发送到stdout的消息检查Docker日志记录插件

要检查Docker日志记录插件“ gforghetti / docker-log-driver-test：latest”，并将结果上传到Docker Hub（`-product-id`如果只是进行测试，则忽略该参数）：

gforghetti:~:$ ./inspectDockerLoggingPlugin -product-id=<store-product-id> gforghetti/docker-log-driver-test:latest

输出：

**************************************************************************************************************************************************************************************************
* Docker Logging Plugin: gforghetti/docker-log-driver-test:latest
**************************************************************************************************************************************************************************************************

**************************************************************************************************************************************************************************************************
* Step #1 Inspecting the Docker Logging Plugin: gforghetti/docker-log-driver-test:latest ...
**************************************************************************************************************************************************************************************************
Passed:   Docker Logging Plugin image gforghetti/docker-log-driver-test:latest has been inspected.

**************************************************************************************************************************************************************************************************
* Step #2 Docker Logging Plugin information
**************************************************************************************************************************************************************************************************
+-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+
| Docker Logging Plugin:  | gforghetti/docker-log-driver-test:latest                                                                                                                             |
| Description:            | jsonfilelog as plugin                                                                                                                                                |
| Documentation:          | -                                                                                                                                                                    |
| Digest:                 | sha256:1cdd79202a7a9f9a53524e904d9f89ed0a6bf6673717bc955ef55744f0826d4c                                                                                              |
| Base layer digest:      | sha256:fda008d4a2b0d2c0a9d2e5dc952aefb0188f7a9c96c04e159662fd56b507c174                                                                                              |
| Docker version:         | 17.12.0-ce                                                                                                                                                           |
| Interface Socket:       | jsonfile.sock                                                                                                                                                        |
| Interface Socket Types: | docker.logdriver/1.0                                                                                                                                                 |
| IpcHost:                | false                                                                                                                                                                |
| PidHost:                | false                                                                                                                                                                |
| Entrypoint:             | /usr/bin/docker-log-driver                                                                                                                                           |
| WorkDir:                |                                                                                                                                                                      |
| User:                   |                                                                                                                                                                      |
+-------------------------+----------------------------------------------------------------------------------------------------------------------------------------------------------------------+

Warning:  Docker logging plugin was not built using Docker Enterprise Edition!

**************************************************************************************************************************************************************************************************
* Step #3 Installing the Docker logging plugin gforghetti/docker-log-driver-test:latest ...
**************************************************************************************************************************************************************************************************
Passed:   Docker logging plugin gforghetti/docker-log-driver-test:latest has been installed successfully.

**************************************************************************************************************************************************************************************************
* Step #4 Testing the Docker logging plugin: gforghetti/docker-log-driver-test:latest ...
**************************************************************************************************************************************************************************************************
Starting a Docker container to test the docker logging plugin gforghetti/docker-log-driver-test:latest

**************************************************************************************************************************************************************************************************
* Step #5 Retrieving the Docker Logs ...
**************************************************************************************************************************************************************************************************
Retrieving the Docker logs using the "docker container logs 4dc3e699dbf3d050a5b582a245c9a4718bb0300d7d55380887c74741d09bd730" command

**************************************************************************************************************************************************************************************************
* Step #6 Verifying that the contents retrieved matches what was sent to the Docker Logging plugin.
**************************************************************************************************************************************************************************************************
Passed:   Docker Logging Plugin Test was successful.

**************************************************************************************************************************************************************************************************
* Step #7 Removing the Docker container and any associated volumes.
**************************************************************************************************************************************************************************************************
Passed:   Docker container and any associated volumes removed.

**************************************************************************************************************************************************************************************************
* Step #8 Removing the Docker logging plugin
**************************************************************************************************************************************************************************************************
Passed:   Docker logging plugin gforghetti/docker-log-driver-test:latest was removed.
Passed:   This test was performed on Docker Enterprise Edition.

**************************************************************************************************************************************************************************************************
* Summary of the inspection for the Docker Logging Plugin: gforghetti/docker-log-driver-test:latest
**************************************************************************************************************************************************************************************************

Report Date: Mon May 21 14:40:41 2018
Operating System: Operating System: Ubuntu 16.04.4 LTS
Architecture: amd64
Docker Client Version: 17.06.2-ee-11
Docker Server Version: 17.06.2-ee-11

There were 1 warnings detected!

Passed:   Docker Logging Plugin image gforghetti/docker-log-driver-test:latest has been inspected.
Warning:  Docker logging plugin was not built using Docker Enterprise Edition!
Passed:   Docker logging plugin gforghetti/docker-log-driver-test:latest has been installed successfully.
Passed:   Docker Logging Plugin Test was successful.
Passed:   Docker container and any associated volumes removed.
Passed:   Docker logging plugin gforghetti/docker-log-driver-test:latest was removed.
Passed:   This test was performed on Docker Enterprise Edition.

The inspection of the Docker logging plugin gforghetti/docker-log-driver-test:latest has completed.

If -product-id is specified on command line:
**************************************************************************************************************************************************************************************************
* Step #9 Upload the test result to Docker Hub.
**************************************************************************************************************************************************************************************************
Passed:   The test results are uploaded to Docker Hub.

gforghetti:~/$

使用JSON输出检查Docker日志记录插件

要`gforghetti/docker-log-driver-test:latest`使用JSON输出检查Docker日志记录插件，请执行以下操作：

gforghetti:~:$ ./inspectDockerLoggingPlugin --json gforghetti/docker-log-driver-test:latest | jq

注意：输出已通过管道传递到jq命令以“很好地”显示它。

输出：

 {
  "Date": "Mon May 21 14:38:28 2018",
  "SystemOperatingSystem": "Operating System: Ubuntu 16.04.4 LTS",
  "SystemArchitecture": "amd64",
  "SystemDockerClientVersion": "17.06.2-ee-11",
  "SystemDockerServerVersion": "17.06.2-ee-11",
  "DockerLogginPlugin": "gforghetti/docker-log-driver-test:latest",
  "Description": "jsonfilelog as plugin",
  "Documentation": "-",
  "DockerLoggingPluginDigest": "sha256:1cdd79202a7a9f9a53524e904d9f89ed0a6bf6673717bc955ef55744f0826d4c",
  "BaseLayerImageDigest": "sha256:fda008d4a2b0d2c0a9d2e5dc952aefb0188f7a9c96c04e159662fd56b507c174",
  "DockerVersion": "17.12.0-ce",
  "Entrypoint": "/usr/bin/docker-log-driver",
  "InterfaceSocket": "jsonfile.sock",
  "InterfaceSocketTypes": "docker.logdriver/1.0",
  "WorkDir": "",
  "User": "",
  "IpcHost": false,
  "PidHost": false,
  "Errors": 0,
  "Warnings": 1,
  "HTMLReportFile": "",
  "VulnerabilitiesScanURL": "",
  "Results": [
    {
      "Status": "Passed",
      "Message": "Docker Logging Plugin image gforghetti/docker-log-driver-test:latest has been inspected."
    },
    {
      "Status": "Warning",
      "Message": "Docker logging plugin was not built using Docker Enterprise Edition!"
    },
    {
      "Status": "Passed",
      "Message": "Docker logging plugin gforghetti/docker-log-driver-test:latest has been installed successfully."
    },
    {
      "Status": "Passed",
      "Message": "Docker Logging Plugin Test was successful."
    },
    {
      "Status": "Passed",
      "Message": "Docker container and any associated volumes removed."
    },
    {
      "Status": "Passed",
      "Message": "Docker logging plugin gforghetti/docker-log-driver-test:latest was removed."
    },
    {
      "Status": "Passed",
      "Message": "This test was performed on Docker Enterprise Edition."
    }
  ]
}

检查具有HTML输出的Docker日志记录插件

要检查`gforghetti/docker-log-driver-test:latest`具有HTML输出的Docker日志记录插件，请执行以下操作：

gforghetti:~:$ ./inspectDockerLoggingPlugin --html gforghetti/docker-log-driver-test:latest

输出：

注意：下面已故意省略了大多数stdout消息输出。

The inspection of the Docker logging plugin cpuguy83/docker-logdriver-test:latest has completed.
An HTML report has been generated in the file cpuguy83-docker-logdriver-test-latest_inspection_report.html
gforghetti:~/$

HTML输出图像

将数据发送到外部服务器上的API端点

介绍

http_api_endpoint是一个HTTP服务器，可用于测试不支持读取日志api的docker日志记录插件，而是将数据发送到在外部服务器上运行的API端点。在相扑逻辑记录插件就是一个例子。

您可以配置这些Docker日志记录插件，以将其日志记录数据发送到http_api_endpoint HTTP Server进行测试，然后使用curl命令编写脚本以检索日志。

下载

句法

./http_api_endpoint [options]

选项：

--port （http_api_endpoint HTTP Server用来侦听的端口。默认为端口80）
--debug （写调试信息）
--help （显示命令帮助）

使用和测试http_api_endpoint HTTP服务器

的卷曲命令可用于测试，并使用http_api_endpoint HTTP服务器。

发出以下curl命令以将新数据发送到http_api_endpoint：
```
# DATA='Hello World!'
# curl -s -X POST -d "${DATA}" http://127.0.0.1:80
```
注意：如果以前发送过任何数据，它将被替换。
发出以下curl命令，将数据发送到http_api_endpoint并将该数据附加到已收集的数据中：
```
# DATA='Hello World!'
# curl -s -X POST -d "${DATA}" http://127.0.0.1:80
```
发出以下curl命令以从http_api_endpoint检索数据：
```
# curl -s -X GET http://127.0.0.1:80
```
```
Hello World!
```
发出以下curl命令以清除http_api_endpoint当前收集的所有数据：
```
# curl -s -X DELETE http://127.0.0.1:80
```
终止：
```
# curl -s http://127.0.0.1:80/EXIT
```

将http_api_endpoint HTTP Server用作日志记录插件的示例

运行容器以测试日志插件的脚本

# cat test_new_plugin.sh

#!/usr/bin/env bash

#######################################################################################################################################
# This bash script tests a Docker logging plugin that does not support the read log api and instead sends data to an API Endpoint running on an external server.
#
#######################################################################################################################################
# Docker Inc.
#######################################################################################################################################

#######################################################################################################################################
# Make sure the Docker logging plugin was specified on the command line
#######################################################################################################################################
DOCKER_LOGGING_PLUGIN=$1
if [[ -z $DOCKER_LOGGING_PLUGIN ]]; then
    printf 'You must specify the Docker Loggin Plugin!\n'
    exit 1
fi

HTTP_API_ENDPOINT='http://localhost:80'

#######################################################################################################################################
# Check to make sure the http_api_endpoint HTTP Server is running
#######################################################################################################################################
curl -s -X POST "${HTTP_API_ENDPOINT}"
if [[ $? -ne 0 ]]; then
    printf 'Unable to connect to the HTTP API Endpoint: '"${HTTP_API_ENDPOINT}"'!\n'
    exit 1
fi

#######################################################################################################################################
# Run an alpine container with the plugin and send data to it
#######################################################################################################################################
docker container run \
--rm \
--log-driver="${DOCKER_LOGGING_PLUGIN}" \
--log-opt sumo-url="${HTTP_API_ENDPOINT}" \
--log-opt sum-sending-interval=5s \
--log-opt sumo-compress=false \
--volume $(pwd)/quotes.txt:/quotes.txt \
alpine:latest \
sh -c 'cat /quotes.txt;sleep 10'

exit $?

从http_api_endpoint HTTP Server检索日志记录数据的脚本

# cat get_plugin_logs.sh

#!/usr/bin/env sh

#######################################################################################################################################
# This bash script retrieves any data logged to the http_api_endpoint HTTP Server.
#######################################################################################################################################
# Docker Inc.
#######################################################################################################################################

curl -s -X GET http://127.0.0.1:80

测试Docker日志记录插件

./inspectDockerLoggingPlugin --verbose --html --test-script ./test_plugin.sh --get-logs-script ./get_plugin_logs.sh myNamespace/docker-logging-driver:1.0.2

码头工人，码头工人，轮毂，认证的内容，记录