Docker 开源项目之 registry - 配置 registry

Docker 开源项目之 registry - 配置 registry。

Registry 的配置基于 YAML 文件，下面会详细描述。虽然它带有默认值，但你应该在将系统移至生产环境之前进行详尽的检查。

1. 覆盖特定的配置选项

在从官方镜像运行 registry 的典型设置中，可以通过将 -e 参数传递环境变量到 docker run 或使用 ENV 指令从 Dockerfile 中指定一个配置变量。

要覆盖配置选项，请创建一个名为 REGISTRY_variable 的环境变量，其中 variable 是配置选项的名称，_（下划线）表示缩进级别。例如，可以配置 filesystem 存储后端的 rootdirectory：

storage:
  filesystem:
    rootdirectory: /var/lib/registry

可以设置环境变量来覆盖这些值：

REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere

该变量将 /var/lib/registry 值覆盖到 /somewhere 目录。

注意：使用可配置为调整单个值的环境变量创建基本配置文件。不建议使用环境变量覆盖配置节（section）。

2. 覆盖整个配置文件

如果默认配置不适合你的使用，或者如果覆盖环境中的 key 时遇到问题，则可以指定 YAML 配置文件并将其作为卷装载到容器中。

通常，从头开始创建一个名为 config.yml 的新配置文件，然后在 docker run 命令中指定它：

$ docker run -d -p 5000:5000 --restart=always --name registry \
             -v `pwd`/config.yml:/etc/docker/registry/config.yml \
             registry:2

以此示例 YAML 文件为起点。

3. 配置选项列表

这些都是 registry 的配置选项。列表中的某些选项是互斥的。在完成配置之前，阅读有关每个选项的详细参考信息。

version: 0.1
log:
  accesslog:
    disabled: true
  level: debug
  formatter: text
  fields:
    service: registry
    environment: staging
  hooks:
    - type: mail
      disabled: true
      levels:
        - panic
      options:
        smtp:
          addr: mail.example.com:25
          username: mailuser
          password: password
          insecure: true
        from: [e-mail]
        to:
          - [e-mail]
loglevel: debug # deprecated: use "log"
storage:
  filesystem:
    rootdirectory: /var/lib/registry
    maxthreads: 100
  azure:
    accountname: accountname
    accountkey: base64encodedaccountkey
    container: containername
  gcs:
    bucket: bucketname
    keyfile: /path/to/keyfile
    rootdirectory: /gcs/object/name/prefix
    chunksize: 5242880
  s3:
    accesskey: awsaccesskey
    secretkey: awssecretkey
    region: us-west-1
    regionendpoint: http://myobjects.local
    bucket: bucketname
    encrypt: true
    keyid: mykeyid
    secure: true
    v4auth: true
    chunksize: 5242880
    multipartcopychunksize: 33554432
    multipartcopymaxconcurrency: 100
    multipartcopythresholdsize: 33554432
    rootdirectory: /s3/object/name/prefix
  swift:
    username: username
    password: password
    authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth
    tenant: tenantname
    tenantid: tenantid
    domain: domain name for Openstack Identity v3 API
    domainid: domain id for Openstack Identity v3 API
    insecureskipverify: true
    region: fr
    container: containername
    rootdirectory: /swift/object/name/prefix
  oss:
    accesskeyid: accesskeyid
    accesskeysecret: accesskeysecret
    region: OSS region name
    endpoint: optional endpoints
    internal: optional internal endpoint
    bucket: OSS bucket
    encrypt: optional data encryption setting
    secure: optional ssl setting
    chunksize: optional size valye
    rootdirectory: optional root directory
  inmemory:  # This driver takes no parameters
  delete:
    enabled: false
  redirect:
    disable: false
  cache:
    blobdescriptor: redis
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: false
    readonly:
      enabled: false
auth:
  silly:
    realm: silly-realm
    service: silly-service
  token:
    realm: token-realm
    service: token-service
    issuer: registry-token-issuer
    rootcertbundle: /root/certs/bundle
  htpasswd:
    realm: basic-realm
    path: /path/to/htpasswd
middleware:
  registry:
    - name: ARegistryMiddleware
      options:
        foo: bar
  repository:
    - name: ARepositoryMiddleware
      options:
        foo: bar
  storage:
    - name: cloudfront
      options:
        baseurl: https://my.cloudfronted.domain.com/
        privatekey: /path/to/pem
        keypairid: cloudfrontkeypairid
        duration: 3000s
  storage:
    - name: redirect
      options:
        baseurl: https://example.com/
reporting:
  bugsnag:
    apikey: bugsnagapikey
    releasestage: bugsnagreleasestage
    endpoint: bugsnagendpoint
  newrelic:
    licensekey: newreliclicensekey
    name: newrelicname
    verbose: true
http:
  addr: localhost:5000
  prefix: /my/nested/registry/
  host: https://myregistryaddress.org:5000
  secret: asecretforlocaldevelopment
  relativeurls: false
  tls:
    certificate: /path/to/x509/public
    key: /path/to/x509/private
    clientcas:
      - /path/to/ca.pem
      - /path/to/another/ca.pem
    letsencrypt:
      cachefile: /path/to/cache-file
      email: [e-mail]
  debug:
    addr: localhost:5001
  headers:
    X-Content-Type-Options: [nosniff]
  http2:
    disabled: false
notifications:
  endpoints:
    - name: alistener
      disabled: false
      url: https://my.listener.com/event
      headers: 
      timeout: 500
      threshold: 5
      backoff: 1000
      ignoredmediatypes:
        - application/octet-stream
redis:
  addr: localhost:6379
  password: asecret
  db: 0
  dialtimeout: 10ms
  readtimeout: 10ms
  writetimeout: 10ms
  pool:
    maxidle: 16
    maxactive: 64
    idletimeout: 300s
health:
  storagedriver:
    enabled: true
    interval: 10s
    threshold: 3
  file:
    - file: /path/to/checked/file
      interval: 10s
  http:
    - uri: http://server.to.check/must/return/200
      headers:
        Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==]
      statuscode: 200
      timeout: 3s
      interval: 10s
      threshold: 3
  tcp:
    - addr: redis-server.domain.com:6379
      timeout: 3s
      interval: 10s
      threshold: 3
proxy:
  remoteurl: https://registry-1.docker.io
  username: [username]
  password: [password]
compatibility:
  schema1:
    signingkeyfile: /etc/registry/key.json
validation:
  enabled: true
  manifests:
    urls:
      allow:
        - ^https?://([^/]+\.)*example\.com/
      deny:
        - ^https?://www\.example\.com/

在某些情况下，配置选项是可选的，但它包含标记为必需的子选项。在这些情况下，可以忽略父选项及其所有子选项。但是，如果使用了父选项，则必须包括所有必选的子选项。

4. version

version: 0.1

version 选项是必需的。它指定配置的版本。它必须是*域，以便在解析配置文件的其余部分之前进行一致的版本检查。

5. log

日志子部分配置日志记录系统的行为。日志记录系统将所有内容输出到标准输出。可以使用此配置部分调整粒度和格式。

log:
  accesslog:
    disabled: true
  level: debug
  formatter: text
  fields:
    service: registry
    environment: staging

参数	是否必须	描述
level	否	设置记出日志的灵敏度。允许的值有 error，warn，info 和 debug。默认是 info。
formatter	否	选择日志输出的格式。该格式主要影响对日志行的键控属性进行编码的方式。选项是 text，json 和 logstash。默认值是 text。
fields	否	字段名称到值的映射。这些被添加到上下文的每个日志行。这对于在其他系统中混合后识别日志消息源很有用。

5.1 accesslog

accesslog:
  disabled: true

在 log 内，accesslog 配置访问日志记录系统的行为。默认情况下，访问日志记录系统以组合日志格式输出到标准输出。可以通过将布尔标志 disabled 设置为 true 来禁用访问日志记录。

6. hooks

hooks:
  - type: mail
    levels:
      - panic
    options:
      smtp:
        addr: smtp.sendhost.com:25
        username: sendername
        password: password
        insecure: true
      from: [e-mail]
      to:
        - [e-mail]

hooks 子部分配置日志 hooks 的行为。例如，该小节包含一个序列处理程序，可以使用它来发送邮件。请参阅 loglevel 以配置打印的消息级别。

7. loglevel

废弃：请使用 log。

loglevel: debug

允许值有 error, warn, info 和 debug。默认是 info。

8. storage

storage:
  filesystem:
    rootdirectory: /var/lib/registry
  azure:
    accountname: accountname
    accountkey: base64encodedaccountkey
    container: containername
  gcs:
    bucket: bucketname
    keyfile: /path/to/keyfile
    rootdirectory: /gcs/object/name/prefix
  s3:
    accesskey: awsaccesskey
    secretkey: awssecretkey
    region: us-west-1
    regionendpoint: http://myobjects.local
    bucket: bucketname
    encrypt: true
    keyid: mykeyid
    secure: true
    v4auth: true
    chunksize: 5242880
    multipartcopychunksize: 33554432
    multipartcopymaxconcurrency: 100
    multipartcopythresholdsize: 33554432
    rootdirectory: /s3/object/name/prefix
  swift:
    username: username
    password: password
    authurl: https://storage.myprovider.com/auth/v1.0 or https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth
    tenant: tenantname
    tenantid: tenantid
    domain: domain name for Openstack Identity v3 API
    domainid: domain id for Openstack Identity v3 API
    insecureskipverify: true
    region: fr
    container: containername
    rootdirectory: /swift/object/name/prefix
  oss:
    accesskeyid: accesskeyid
    accesskeysecret: accesskeysecret
    region: OSS region name
    endpoint: optional endpoints
    internal: optional internal endpoint
    bucket: OSS bucket
    encrypt: optional data encryption setting
    secure: optional ssl setting
    chunksize: optional size valye
    rootdirectory: optional root directory
  inmemory:
  delete:
    enabled: false
  cache:
    blobdescriptor: inmemory
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: false
    readonly:
      enabled: false
  redirect:
    disable: false

存储选项是必需的，它定义了哪个存储后端正在使用中。必须完全配置一个后端。如果配置了多个存储后端，则 registry 会返回错误。可以选择以下任何后端存储驱动程序：

存储驱动程序	描述
filesystem	使用本地磁盘来存储 registry 文件。它非常适合开发，可能适用于一些小规模生产应用。请参阅 驱动程序的参考文档。
azure	使用 Microsoft Azure Blob Storage。参考 驱动程序的手册。
gcs	使用 Google Cloud Storage。参考 驱动程序的手册。
s3	使用 Amazon Simple Storage Service (S3) 和 compatible Storage Services。参考 驱动程序的手册。
swift	使用 Openstack Swift object storage。参考 驱动程序的手册。
oss	使用 Aliyun OSS for object storage。参考 驱动程序的手册。

仅用于测试的话，可以使用 inmemory 存储驱动程序。如果你想从易失性存储器运行 registry，请在 ramdisk 上使用 文件系统驱动程序。

如果在 Windows 上部署 registry，则不推荐从主机挂载 Windows 卷。相反，可以使用 S3 或 Azure 支持数据存储。如果确实使用 Windows 卷，则到安装点的 PATH 长度必须在 MAX_PATH 限制（通常为255个字符）内，否则会发生此错误：

mkdir /XXX protocol error and your registry will not function properly.

8.1 maintenance

目前，上传清除和只读模式是唯一可用的 maintenance（维护）功能。

8.2 uploadpurging

上传清除（uploadpurging）是一个后台进程，可以定期从 registry 的上传目录中删除孤立的文件。上传清除默认情况下处于启用状态。要配置上传目录清除，必须设置以下参数。

参数	是否必须	描述
enabled	是	默认 true。设置为 true 则开启上传清除。
age	是	默认 168 小时，即 1 周。上传目录大于这个时间后，删除上传目录。interval
dryrun	是	将 dryrun 设置为 true 以获取要删除的目录的摘要。默认为 false。

注意：age 和 interval 是包含具有可选的分数和单位后缀的数字的字符串。例如：45m，2h10m，168h。

8.3 readonly

如果将 maintenance 下的 readonly 部分的 enabled 设置为 true，则不允许客户端写入 registry。此模式对于临时阻止写入后端存储非常有用，此时可以运行垃圾回收。在运行垃圾回收之前，registry 应该在 readonly 的 enabled 设置为 true 的情况下重新启动。垃圾收集过程完成后，registry 可能会重新启动，这次只能从配置中只读取（或设置为 false）。

8.4 delete

使用 delete 可以通过摘要删除镜像的 blob 和清单（Use the delete structure to enable the deletion of image blobs and manifests by digest）。默认是 false，但可以通过在配置文件中写入以下内容来启用它：

delete:
  enabled: true

8.5 cache

使用 cache 来启用在存储后端访问的数据的缓存。目前，唯一可用的缓存提供对层元数据（layer metadata）的快速访问，层元数据使用 blobdescriptor 字段（如果已配置）。

可以将 blobdescriptor 字段设置为 redis 或 inmemory。如果设置为 redis，则 Redis 池会缓存层元数据。如果设置为 inmemory，则内存映射会缓存层元数据。

注意：以前，blobdescriptor 被称为 layerinfo。虽然这是一样的，但 layerinfo 已被弃用。

8.6 redirect

redirect 子部分提供了用于管理来自内容后端的重定向的配置。对于支持它的后端，默认情况下启用重定向。在某些部署方案中，你可能决定将所有数据路由到 registry，而不是重定向到后端。当使用不共存的后端或者当 registry 实例积极缓存时，这可能会更有效（This may be more efficient when using a backend that is not co-located or when a registry instance is aggressively caching）。

要禁用重定向，请在 redirect 下添加一个 disable 标志，将其设置为 true：

redirect:
  disable: true

9. auth

auth:
  silly:
    realm: silly-realm
    service: silly-service
  token:
    realm: token-realm
    service: token-service
    issuer: registry-token-issuer
    rootcertbundle: /root/certs/bundle
  htpasswd:
    realm: basic-realm
    path: /path/to/htpasswd

auth 选项是可选的。可能的 auth provider 包括：

silly token htpasswd

只能配置一个 auth provider 。

9.1 silly

silly 身份验证程序只适合开发。它只是检查 HTTP 请求中是否存在 Authorization 标头。它不检查 header 的值。如果 header 不存在，那么 silly 认证返回 challenge 响应，回应拒绝访问的 realm，service 和 scope。

以下值用于配置响应：

参数	是否必须	描述
realm	是	注册表服务器进行身份验证的 realm （领域）。
service	是	进行身份验证的服务。

9.2 token

基于 token 令牌的身份验证允许你将身份验证系统与 registry 分离。这是一个高度安全的认证范例。

参数	是否必须	描述
realm	是	注册表服务器进行身份验证的 realm （领域）。
service	是	进行身份验证的服务。
issuer	是	token 令牌发行者的名称。发行者将其插入令牌，因此它必须匹配为发行者配置的值（The issuer inserts this into the token so it must match the value configured for the issuer）。
rootcertbundle	是	根证书包的绝对路径。该捆绑包（bundle）包含用于签署认证令牌的证书的公共部分。

有关基于令牌的认证配置的更多信息，请参阅 规范。

9.3 htpasswd

支持的 htpasswd 认证允许使用 Apache htpasswd 文件 配置基本认证。唯一支持的密码格式是 bcrypt。其他散列类型的条目将被忽略。htpasswd文件在启动时加载一次。如果文件无效，registry 将显示错误并且不会启动。

警告：由于基本身份验证将密码作为 HTTP header 的一部分发送，因此只能使用配置了 TLS 的 htpasswd 身份验证方案。

参数	是否必须	描述
realm	是	注册表服务器进行身份验证的 realm （领域）。
path	是	启动时加载的 htpasswd 文件的路径。

10. middleware

middleware 部分是可选的。使用此选项在指定的 hook point 处注入中间件。每个中间件都必须实现与它所包装的对象相同的接口。例如，registry 中间件必须实现 distribution.Namespace 接口，repository 中间件必须实现distribution.Repository，而 storage 中间件必须实现 driver.StorageDriver。

这是 cloudfront 中间件（存储中间件）的示例配置：

middleware:
  registry:
    - name: ARegistryMiddleware
      options:
        foo: bar
  repository:
    - name: ARepositoryMiddleware
      options:
        foo: bar
  storage:
    - name: cloudfront
      options:
        baseurl: https://my.cloudfronted.domain.com/
        privatekey: /path/to/pem
        keypairid: cloudfrontkeypairid
        dur