4.3.4、registry配置参考

registry配置参考

Registry 的配置是基于一个YAML文件，详情如下。虽然它里面已经提供比价完整的默认值，在把系统迁移到生产环境的之前，建议你认真的检查每一个默认值。

覆盖默认配置

一个典型的设置，当基于官方的镜像,执行 docker run 运行一个Registry的服务时，你可以通过 -e 参数向运行环境传递任何的配置参数，在Dockerfile文件中使用 ENV 达到相同的效果。

通过创建一个名为REGISTRY_variable 的环境变量，去覆盖一个配置选项。*variable* 部分的命名规则是根据配置的参数的层级以 _ 符号分割。例如，你要配置存储后台的 filesystem 的 rootdirectory 参数时：

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

为了覆盖上述的值，设置一个如下的环境变量即可：

REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere

这样就把 /var/lib/registry 替换成了 /somewhere。

注意：如果一个环境变量的变化值映射成一个字符串, 比如，把存储驱动模式修改成 REGISTRY_STORAGE=filesystem，此外所有的子配置项都将失效。换而言之，当你指定一个新的存储模式，系统将删除所有和久模式有关联的所有参数。

覆盖整个配置文件

如果默认的配置无法满足你的需求，或者覆盖出现问题的时候，你可以挂载一个数据卷到容器里，指定一个替换的YAML配置文件。

一般做法，创建一个命名为 config.yml的配置文件：

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

你可以(或许应该)使用config-example.yml作为一个开始。

配置选项列表

这里列出registry所有的配置选项。有一些选项是互斥的。所以，在使用之前务必认真的阅读它们相关的信息，在下面的内容中，我们会对每一个选项逐一的介绍。

version: 0.1
log:
  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: [email protected]
        to: 
          - [email protected]
loglevel: debug # deprecated: use "log"
storage:
  filesystem:
    rootdirectory: /var/lib/registry
  azure:
    accountname: accountname
    accountkey: base64encodedaccountkey
    container: containername
  s3:
    accesskey: awsaccesskey
    secretkey: awssecretkey
    region: us-west-1
    bucket: bucketname
    encrypt: true
    secure: true
    v4auth: true
    chunksize: 5242880
    rootdirectory: /s3/object/name/prefix
  rados:
    poolname: radospool
    username: radosuser
    chunksize: 4194304
  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
  redirect:
    disable: false
  cache:
    blobdescriptor: redis
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: 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: 3000
reporting:
  bugsnag:
    apikey: bugsnagapikey
    releasestage: bugsnagreleasestage
    endpoint: bugsnagendpoint
  newrelic:
    licensekey: newreliclicensekey
    name: newrelicname
    verbose: true
http:
  addr: localhost:5000
  prefix: /my/nested/registry/
  secret: asecretforlocaldevelopment
  tls:
    certificate: /path/to/x509/public
    key: /path/to/x509/private
    clientcas:
      - /path/to/ca.pem
      - /path/to/another/ca.pem
  debug:
    addr: localhost:5001
notifications:
  endpoints:
    - name: alistener
      disabled: false
      url: https://my.listener.com/event
      headers: 
      timeout: 500
      threshold: 5
      backoff: 1000
redis:
  addr: localhost:6379
  password: asecret
  db: 0
  dialtimeout: 10ms
  readtimeout: 10ms
  writetimeout: 10ms
  pool:
    maxidle: 16
    maxactive: 64
    idletimeout: 300s

在有些使用场景中，一些配置选项是optional ，但是其包含了被标记为required的子选项。这意味着你可以忽略这个配置项，包括它包含的所有子选项。然而，如果你设置一个这样的选项，务必设置它包含的所有标记为required子项。

version

version: 0.1

version 参数是required。它指定了配置文件版本号。它是一个顶层的属性，为解析后面的配置文件提供版本一致性的校验

log

log 是设置日志系统的各种行为。日志系统通过stdout对外输出各种日志信息，运用它可以调节日志的输出的粒度和格式。

log:
  level: debug
  formatter: text
  fields:
    service: registry
    environment: staging

Parameter	Required	Description
level	no	设置日志输出等级。可选参数： error,warn, info 和debug. 默认为： info.
formatter	no	设置日志输出格式。这个参数会影响日志行的键值对的格式。可选项有： text, json ，logstash.默认值： text.
fields	no	一个键值对映射集合。这些键值会被添加到每个日志行中的上下文中。在跟其他系统混合使用的时候很有用，可以标识日志的源头。

hooks

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

hooks参数设置日志的钩子行为。 它包含了一个顺序处理器，你可以用它发送邮件。例如，参考 loglevel 设置打印信息的级别。

loglevel

弃用: 请使用 log 代替。

loglevel: debug

可选的值有： error, warn, info and debug.默认值为 info.

storage

storage:
  filesystem:
    rootdirectory: /var/lib/registry
  azure:
    accountname: accountname
    accountkey: base64encodedaccountkey
    container: containername
  s3:
    accesskey: awsaccesskey
    secretkey: awssecretkey
    region: us-west-1
    bucket: bucketname
    encrypt: true
    secure: true
    v4auth: true
    chunksize: 5242880
    rootdirectory: /s3/object/name/prefix
  rados:
    poolname: radospool
    username: radosuser
    chunksize: 4194304
  swift:
    username: username
    password: password
    authurl: 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
  cache:
    blobdescriptor: inmemory
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: false
  redirect:
    disable: false

这个参数是required ，定义使用哪个存储后端。你只能设置一个后端；如果你配置多个，registry会报错。

如果你在window系统上安装一个registry，请注意，这里不建议其上面用数据卷进行挂在。你可以使用一个S3，或者Azure承载数据的存储。如果使用了window的数据卷，请确保你挂载的路径PATH 不要超过window的MAX_PATH 限制。这个操作可能导致下面的错误：

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

cache

使用 cache 参数可以缓存访问存储后端的数据。目前，只允许缓存层的元数据。如果要设置，使用 blobdescriptor 字段。

你可以设置 blobdescriptor 的值为 redis 或 inmemory。redis 值表示使用Redis池去缓存层的元数据。 inmemory 使用内存映射。

注意： 在旧版本中, blobdescriptor 被称为 layerinfo.虽然它们都是等级的，但是 layerinfo 已经被标记为弃用，建议使用

  blobdescriptor  。

redirect

redirect 为存储后端程序提供管理重定向的配置。对支持重定向的后端，重定向默认是允许的。在某一些部署的场景里，跟喜欢通过路由来处理进过registry的所有数据，而不去做后端的重定向。当后端没有托管或者registry实例灭有做积极的缓存时，使用路由的方式效率会更高。

配置Redirects很简单，只需添加 disable,设置它的值为true即可开启：

redirect:
  disable: true

filesystem

filesystem 存储后端使用本地磁盘去存储registry的文件。它是用于典型的开发和可能适用一些小型的生产应用程序。

它只有一个必选的子参数 rootdirectory 。这个参数指定一个绝对的路径。registry的说有数据都存储在这里，所以在指定路径之前要确保改文件夹下是否有足够的空间。

azure

这种存储后端使用微软Azure Blob Storage。

Parameter	Required	Description
accountname	yes	Azure账户名。
accountkey	yes	Azure 账户key.
container	yes	Azure存储数据容器的的名字
realm	no	存储服务端的域名后缀。默认是： core.windows.net.

rados

这个存储后端使用 Ceph Object Storage

Parameter	Required	Description
poolname	yes	Ceph 池名字。
username	no	Ceph cluster user to connect as (i.e. admin, not client.admin).
chunksize	no	可写RADOS 对象的大小。默认是：4MB (4194304)。

S3

这个是后端使用亚马逊的S3(Simple Storage Service，简单存储服务)

Parameter	Required	Description
accesskey	yes	你的AWS Access Key.
secretkey	yes	你的AWS Secret Key.
region	yes	The AWS region in which your bucket exists. For the moment, the Go AWS library in use does not use the newer DNS based bucket routing.
bucket	yes	The bucket name in which you want to store the registry's data.
encrypt	no	Specifies whether the registry stores the image in encrypted format or not. A boolean value. The default is false.
secure	no	Indicates whether to use HTTPS instead of HTTP. A boolean value. The default is false.
v4auth	no	Indicates whether the registry uses Version 4 of AWS's authentication. Generally, you should set this to true. By default, this is false.
chunksize	no	The S3 API requires multipart upload chunks to be at least 5MB. This value should be a number that is larger than 5*1024*1024.
rootdirectory	no	This is a prefix that will be applied to all S3 keys to allow you to segment data in your bucket if necessary.

Maintenance

目前，registry提供一种维护功能：上传清除。配置详情请看下一节。    

Upload Purging

上传清除是一个后台的处理程序，它会定时的删除registry的上传目录中孤立的文件。上传清除默认是开启的。如果需要配置它，一定要设置下面的参数。

Parameter	Required	Description
enabled	yes	设置true允许上载清除。默认为：true。
age	yes	上载文件夹存在的时间超过设置age下限值会被删除。默认：168h (1 周)。
interval	yes	清除的时间间隔。默认：24h。
dryrun	yes	设置为true是，可以获得待删除的目录概要。默认：false。

注意： age 和 interval 的值是一个包含一个数字和一个单位后缀的字符串。例如：45m、2h10m、168h(1周)

Swift.

这个是使用Openstack Swift 。

Parameter	Required	Description
authurl	yes	URL for obtaining an auth token. https://storage.myprovider.com/v2.0 or https://storage.myprovider.com/v3/auth
username	yes	Your Openstack user name.
password	yes	Your Openstack password.
region	no	The Openstack region in which your container exists.
container	yes	The container name in which you want to store the registry's data.
tenant	no	Your Openstack tenant name.
tenantid	no	Your Openstack tenant id.
domain	no	Your Openstack domain name for Identity v3 API.
domainid	no	Your Openstack domain id for Identity v3 API.
insecureskipverify	no	true to skip TLS verification, false by default.
chunksize	no	Size of the data segments for the Swift Dynamic Large Objects. This value should be a number (defaults to 5M).
rootdirectory	no	This is a prefix that will be applied to all Swift keys to allow you to segment data in your container if necessary.

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 项是optional。这里提供3中认证方式，silly, token 和htpasswd。你只需配置其中一个 auth 即可。

silly

 silly 适合在用在开发的阶段。因为它只是简单的检查一下HTTP请求头中是否带有 Authorization ，不做值的校验。如果不存在， silly 回返回一个带有realm、service和scope信息的响应来拒绝访问。

响应配置参数：

Parameter	Required	Description
realm	yes	The realm in which the registry server authenticates.
service	yes	The service being authenticated.

token

基于令牌的验证允许验证系统和registry解耦。这是一种良好的验证模式且具有很高的安全性。

Parameter	Required	Description
realm	yes	The realm in which the registry server authenticates.
service	yes	The service being authenticated.
issuer	yes	The name of the token issuer. The issuer inserts this into the token so it must match the value configured for the issuer.
rootcertbundle	yes	The absolute path to the root certificate bundle. This bundle contains the public part of the certificates that is used to sign authentication tokens.

更多关于基于令牌(Token)认证配置信息，请看[手册]。

htpasswd

htpasswd认证是用Apache HTPasswd文件构建的。仅仅支持bcrypt 格式的密码。其他类型的哈希条目会被忽略。htpasswd文件只会在registry启动时候加载一次。如果文件无效，registry将会打印错误信息和停止启动。

警告: 这种认证方案只用在TLS配置，因为在这种情况下，认证发送密码会作为http请求头的一部分。

Parameter	Required	Description
realm	yes	The realm in which the registry server authenticates.
path	yes	Path to htpasswd file to load at startup.

middleware

middleware 项是optional。使用这个配置项可在指定的钩子点注入中间件。所有的中间件必须实现相同的对象包装接口。这意味着，一个registry中间件必须实现distribution.Namespace 接口，repository中间件必须实现distribution.Repository接口，storage 中间件必须实现tdistribution.Repository接口。

目前只有一个存储中间件cloudfront，对registry提供支持。

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: 3000

Each middleware entry has name and options entries. The name must correspond to the name under which the middleware registers itself. The optionsfield is a map that details custom configuration required to initialize the middleware. It is treated as a map[string]interface{}. As such, it supports any interesting structures desired, leaving it up to the middleware initialization function to best determine how to handle the specific interpretation of the options.

每个中间条目都包含 name 和options 这两个子条目。 name 的命名必须对应中间件注册器。(译者注：registry -> ARegistryMiddleware；repository -> ARepositoryMiddleware) options是一个map，里面承载着中间件初始化的配置参数。它的数据 map[string]interface{}。由此看出，它可以支持任何你需要的数据结构。

cloudfront

Parameter	Required	Description
baseurl	yes	SCHEME://HOST[/PATH] at which Cloudfront is served.
privatekey	yes	Private Key for Cloudfront provided by AWS.
keypairid	yes	Key pair ID provided by AWS.
duration	no	Duration for which a signed URL should be valid.

reporting

reporting:
  bugsnag:
    apikey: bugsnagapikey
    releasestage: bugsnagreleasestage
    endpoint: bugsnagendpoint
  newrelic:
    licensekey: newreliclicensekey
    name: newrelicname
    verbose: true

reporting 选项是optional 的，设置错误和度量报告工具。目前仅支持两个服务。 New Relic 和Bugsnag，在一个有效的配置中可能两个包含。

bugsnag

Parameter	Required	Description
apikey	yes	API Key provided by Bugsnag
releasestage	no	Tracks where the registry is deployed, for example,production,staging, or development.
endpoint	no	Specify the enterprise Bugsnag endpoint.

newrelic

Parameter	Required	Description
licensekey	yes	License key provided by New Relic.
name	no	New Relic application name.
verbose	no	Enable New Relic debugging output on stdout.

http

http:
  addr: localhost:5000
  net: tcp
  prefix: /my/nested/registry/
  secret: asecretforlocaldevelopment
  tls:
    certificate: /path/to/x509/public
    key: /path/to/x509/private
    clientcas:
      - /path/to/ca.pem
      - /path/to/another/ca.pem
  debug:
    addr: localhost:5001

 http 选项是配置registry宿主机的HTTP服务。

Parameter	Required	Description
addr	yes	The address for which the server should accept connections. The form depends on a network type (see net option): HOST:PORT for tcp andFILE for a unix socket.
net	no	The network which is used to create a listening socket. Known networks are unix and tcp. The default empty value means tcp.
prefix	no	If the server does not run at the root path use this value to specify the prefix. The root path is the section before v2. It should have both preceding and trailing slashes, for example /path/.
secret	yes	A random piece of data. This is used to sign state that may be stored with the client to protect against tampering. For production environments you should generate a random piece of data using a cryptographically secure random generator. This configuration parameter may be omitted, in which case the registry will automatically generate a secret at launch. WARNING: If you are building a cluster of registries behind a load balancer, you MUST ensure the secret is the same for all registries.

tls

tls 是 http 的子项，是optional。用它配置服务的TLS(传输安全)。如果你已经运行了一个像Nginx或者Apache服务，在registry的宿主机上。你可能更加喜欢用它充当一个TLS代理registry服务。

Parameter	Required	Description
certificate	yes	Absolute path to x509 cert file
key	yes	Absolute path to x509 private key file.
clientcas	no	An array of absolute paths to a x509 CA file

debug

debug 是optional 。使用它设置一个帮助跟踪问题的bebug的服务。debug终端可以用来监控registry健康指数，和性能分析。通过debug终端可以得到一些敏感的信息。在生产环境中，确保访问debug终端的安全性。

debug 持有一个单一，必须的参数 addr 。这个参数 HOST:PORT 的对外服务地址。

notifications

notifications:
  endpoints:
    - name: alistener
      disabled: false
      url: https://my.listener.com/event
      headers: 
      timeout: 500
      threshold: 5
      backoff: 1000

notifications 选项是optional ，目前只包含一个子项endpoints。

endpoints

Endpoints 是一个可以接收事件通知的命令服务(URLs)列表。

Parameter	Required	Description
name	yes	A human readable name for the service.
disabled	no	A boolean to enable/disable notifications for a service.
url	yes	The URL to which events should be published.
headers	yes	Static headers to add to each request.
timeout	yes	An HTTP timeout value. This field takes a positive integer and an optional suffix indicating the unit of time. Possible units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) If you omit the suffix, the system interprets the value as nanoseconds.
threshold	yes	An integer specifying how long to wait before backing off a failure.
backoff	yes	How long the system backs off before retrying. This field takes a positive integer and an optional suffix indicating the unit of time. Possible units are: ns (nanoseconds) us (microseconds) ms (milliseconds) s (seconds) m (minutes) h (hours) If you omit the suffix, the system interprets the value as nanoseconds.

redis

redis:
  addr: localhost:6379
  password: asecret
  db: 0
  dialtimeout: 10ms
  readtimeout: 10ms
  writetimeout: 10ms
  pool:
    maxidle: 16
    maxactive: 64
    idletimeout: 300s

为构造redis连接声明参数。registry实例可能利用redis实例为多个运用提供服务。目前主要用于缓存不可变的二进制大对象信息。下面的大多数选项都是控制registry怎样连接到redis。你可以使用它的子项 pool控制池的行为。

Parameter	Required	Description
addr	yes	Address (host and port) of redis instance.
password	no	A password used to authenticate to the redis instance.
db	no	Selects the db for each connection.
dialtimeout	no	Timeout for connecting to a redis instance.
readtimeout	no	Timeout for reading from redis connections.
writetimeout	no	Timeout for writing to redis connections.

pool

pool:
  maxidle: 16
  maxactive: 64
  idletimeout: 300s

配置Redis连接池的行为。

Parameter	Required	Description
maxidle	no	Sets the maximum number of idle connections.
maxactive	no	sets the maximum number of connections that should be opened before blocking a connection request.
idletimeout	no	sets the amount time to wait before closing inactive connections.

案例1：开发配置

下面有一个简单的例子，你可以把它用在本地开发阶段：

version: 0.1
log:
  level: debug
storage:
    filesystem:
        rootdirectory: /var/lib/registry
http:
    addr: localhost:5000
    secret: asecretforlocaldevelopment
    debug:
        addr: localhost:5001

分析一下上面的配置文件的意思。registry实例运行监听 5000端口，绑定到localhost,开启 debug 服务。registry数据存储路径/var/lib/registry 。日志输级别 debug ，这种模式得到最详细的日志信息。

config-example.yml也类似，都是在本地开发阶段很有用的配置文件。

实例2:中间件配置

这个例子介绍如何配置registry的存储中间件。中间件允许registry通过一个内容分发网络(CDN)为存储层提供服务。这样大大减少registry和存储层的通信。

目前，registry支持 Amazon Cloudfront。你只能使用Cloudfront 和S3存储驱动协同工作。

Parameter	Description
name	The storage middleware name. Currently cloudfront is an accepted value.
disabled	Set to false to easily disable the middleware.
options:	A set of key/value options to configure the middleware. baseurl: The Cloudfront base URL. privatekey: The location of your AWS private key on the filesystem. keypairid: The ID of your Cloudfront keypair. duration: The duration in minutes for which the URL is valid. Default is 20.

下面举例说明了这些参数：

middleware:
    storage:
        - name: cloudfront
          disabled: false
          options:
             baseurl: http://d111111abcdef8.cloudfront.net
             privatekey: /path/to/asecret.pem
             keypairid: asecret
             duration: 60

Note: 想了解更多关于cloudfront的信息，请移步到cloudfront的官方文档。

来源： >