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: sender@example.com
to:
- errors@example.com
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: <http.Header>
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: name@sendhost.com
to:
- name@receivehost.com
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 options
field 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: <http.Header>
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:
|
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:
|
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.
|
下面举例说明了这些参数:
middleware:
storage:
- name: cloudfront
disabled: false
options:
baseurl: http://d111111abcdef8.cloudfront.net
privatekey: /path/to/asecret.pem
keypairid: asecret
duration: 60
Note: 想了解更多关于cloudfront的信息,请移步到cloudfront的官方文档。