distribution使用方式

本文致力于学习使用cncf项目distribution,即原docker registry

官方文档
翻译内容比较主观,请勿完全信任.

基础了解

是什么

是一个无状态、高度可扩展的服务器端应用程序,用于存储并允许您分发容器映像和其他内容,Harbor基于此开发.

基础使用

# 运行容器
docker run -d -p 5000:5000 --restart=always --name registry registry:2
# 镜像推拉使用
docker pull ubuntu
docker image tag ubuntu localhost:5000/myfirstimage
docker push localhost:5000/myfirstimage
docker pull localhost:5000/myfirstimage
# 删除容器
docker container stop registry && docker container rm -v registry

自定义配置

环境变量覆盖性配置

storage:
  filesystem:
    rootdirectory: /path

创建环境变量REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/path即可实现同样的作用。
环境变量规则：以REGISTRY_variable为主体，以_代表缩进级别。

注意：环境变量形式会覆盖配置文件形式，为保证稳定性所以不建议用环境变量的形式。

配置清单

官方提供，且某些选项互斥，需要自行调整。

参数为多个可选时,示例参数即为默认值.
所有未强调必选则为可选.

一级配置块

在配置清单中总共有以下一级配置块，各自又包含明细配置。

version: 0.1 # 必需;便于解析文件前的一致性版本检查.
log: # 指定日志系统行为.
loglevel: # 弃用,请使用log.level.
storage: # 必需;设置后端存储相关且只能设置一个后端存储.
auth: # 身份认证
middleware: # 指定插入中间件钩子
http: # 注册表的http服务配置
notifications: # 通知选项
redis: # 使用外部redis
health:
proxy:
validation:

log

用于指定日志系统行为,默认输出至stderr.

Combined Log Format

log:
  accesslog: # 访问日志系统的行为,输出格式为Combined Log Format.
    disabled: true 
  level: debug # 日志级别，提供`error`,`warn`,`info`,`debug`.
  formatter: text # 输出格式,提供`text`,`json`,`logstash`.
  fields: # 设置字典键值对,会被添加至日志上下文中,常用于混合日志采集系统中区分日志来源.
    service: registry
    environment: staging
  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    

storage

必需;设置后端存储相关且只能设置一个后端存储.
配置链接
filesystem
azure
Amazon Simple Storage Service

storage:
  filesystem: # 使用本地磁盘
    rootdirectory: /var/lib/registry # 数据目录,不存在则以umask创建对应权限的目录,否则默认0777.
    maxthreads: 100 # 允许最大同时执行的的文件系统阻塞操作线程,如果同时多个线程操作可能导致线程耗尽问题,不能低于25.
  azure: # Microsoft Azure storage
    accountname: accountname # 必需;Azure存储账户名.
    accountkey: base64encodedaccountkey # 必需;对应密码.
    container: containername # 必需;存储数据表的目录名.
    realm: # 存储服务域名后端
    copy_status_poll_max_retry: # 轮询复制操作最大重试次数,默认5.-1代表禁用重试.
    copy_status_poll_delay: # 轮询复制操作间重试等待时间,默认100ms.
    credentials:
      type: client_secret
      clientid: client_id_string
      tenantid: tenant_id_string
      secret: secret_string    
  gcs: # Google Cloud Storage
    bucket: bucketname # 必需;存储桶名称
    keyfile: /path/to/keyfile # 私钥路径
    credentials:
      type: service_account
      project_id: project_id_string
      private_key_id: private_key_id_string
      private_key: private_key_string
      client_email: client@example.com
      client_id: client_id_string
      auth_uri: http://example.com/auth_uri
      token_uri: http://example.com/token_uri
      auth_provider_x509_cert_url: http://example.com/provider_cert_url
      client_x509_cert_url: http://example.com/client_cert_url
    rootdirectory: /gcs/object/name/prefix # 目录树结构
    chunksize: 5242880 # 上传大blobs块的大小,必需262144的倍数,默认5242880
  s3: # Amazon Simple Storage Service
    accesskey: awsaccesskey # AWS Access Key
    secretkey: awssecretkey #  AWS Secret Key
    region: us-west-1 # 必需,存储桶所在区域
    regionendpoint: http://myobjects.local # s3兼容存储服务端点
    forcepathstyle: true # 启用路径样式寻址,默认false
    accelerate: false # 启用s3传输加速
    bucket: bucketname # 必需,存储桶名称
    encrypt: true # 启用加密格式存储镜像,默认false
    keyid: mykeyid # 加密KMS密钥ID,需要encrypt为true否则忽略
    secure: true # 启用https
    v4auth: true # 启用v4版本认证
    chunksize: 5242880 # 分段上传块大小,最少5MB
    multipartcopychunksize: 33554432 # 复制存储对象时除最后一个块外其他的块大小设置
    multipartcopymaxconcurrency: 100 # 复制存储对象时并发上传线程
    multipartcopythresholdsize: 33554432 # 默认存储大小,超过时启用分段上传
    rootdirectory: /s3/object/name/prefix # 存储路径前缀
    loglevel: debug # 日志级别,默认off
  inmemory: # 存储在内存中,建议仅在测试使用
  tag: 
    concurrencylimit: 8 # 通过标签查找结果的并发限制;未提供或未0时采用GOMAXPROCS
  delete: 
    enabled: false # 启用通过摘要删除镜像 blobs manifests
  cache: # 设置缓存图像元数据快速访问
    blobdescriptor: inmemory # 可选redis,inmemory
    blobdescriptorsize: 10000 # 当前者为redis时不可用;缓存限制梳理,默认10000;0则不限制
  maintenance: # 维护状态
    uploadpurging: # 上传目录清理孤立文件.一个后台进程
      enabled: true # 必需;启用上传清理,默认true
      age: 168h # 必需;孤立文件保留时长,默认168h
      interval: 24h # 必需;上传清理任务运行间隔,默认24h
      dryrun: false # 必需;预执行获取会删除的信息统计
    readonly: # 开启则不允许客户端在注册表维护状态下推送数据以安全运行垃圾收集
      enabled: false # 建议先修改为true重启注册表执行垃圾收集再还原配置重启注册表
  redirect: # 管理后端的重定向配置
    disable: false

在 2 的老版本中还曾有 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

配置endpoint后端点完整地址为 [bucket].[region].aliyuncs.com，如果设置 intenal为 true，则端点为 [bucket].[region]-internal.aliyuncs.com。参见： https://github.com/distribution/distribution/blob/9cc7c94e4e4dd7e8dd85d7698561c737e3c1733f/docs/configuration.md?spm=a2c6h.12873639.article-detail.8.d2a57e5dDYVccI&file=configuration.md 。

auth

可选,认证模块

auth:
  silly: # 低级认证,建议测试使用;仅检查请求是否包含Authorization头;否则反馈被拒绝的领域和范围
    realm: silly-realm # 必需;认证的领域
    service: silly-service # 必需;认证的服务
  token: # 基于令牌的验证
    realm: token-realm # 必需;认证的领域
    service: token-service # 必需;认证的服务
    issuer: registry-token-issuer # 必需;令牌发行者
    rootcertbundle: /root/certs/bundle # 必需;根证书路径
  htpasswd: # 身份验证;要求文件bcrypt格式;只在启动时加载一次;未提供则自动创建并日志输出密码;
    realm: basic-realm # 必需;认证的领域
    path: /path/to/htpasswd # 必需;密钥文件路径

middleware

可选,指定插入中间件钩子.一般情况不会用到,本文不陈述.

http

可选,注册表的http服务配置

http:
  addr: localhost:5000 # 服务器暴露地址,tcp或socket文件路径
  net: tcp # 可选tcp,socket
  prefix: /my/nested/registry/ # 如果要求不以根路径运行,则指定前缀(生效在/v2前);要求以/开头结尾
  host: https://myregistryaddress.org:5000 # 暴露外部连接的完全限定URL;
  secret: asecretforlocaldevelopment # 数据加密码,防止篡改;集群模式时需要该部分统一
  relativeurls: false # 启用则反馈相对路径,由客户端自行适配完整路径,docker 1.7及之前版本无法支持
  draintimeout: 60s # 注册表收到sigterm信号时处理余下HTTP请求的时间
  tls: # 可选
    certificate: /path/to/x509/public # 必需;证书文件绝对路径
    key: /path/to/x509/private # 必需;私钥文件绝对路径
    clientcas: # 以数组形式组合ca文件绝对路径
      - /path/to/ca.pem
      - /path/to/another/ca.pem
    minimumtls: tls1.2 # 最低tls版本,可选tls1.0、tls1.1、tls1.2、tls1.3
    ciphersuites: # 指定允许可用的密码套件
      - TLS_ECDHE_ECDSA_WITH_AES_256_GCM_SHA384
      - TLS_ECDHE_RSA_WITH_AES_256_GCM_SHA384
    letsencrypt: # 自动续期证书服务
      cachefile: /path/to/cache-file # 必需;缓存目录
      email: emailused@letsencrypt.com # 必需;注册邮件
      hosts: [myregistryaddress.org] # 续期域名
      directoryurl: https://acme-v02.api.letsencrypt.org/directory # 用于续期的api服务
  debug: # 暴露调试问题服务
    addr: localhost:5001 # 必需;暴露地址
    prometheus: 
      enabled: true # 启用promehteus,默认false
      path: /metrics # 访问路径   
  headers: # 指定HTTP请求应包含的请求头
    X-Content-Type-Options: [nosniff]
  http2: # 启用http2协议,若tls为配置则忽略;若必需且不愿tls则配置h2c部分
    disabled: false
  h2c:
    enabled: false

notifications

notifications:
  events:
    includereferences: true
  endpoints:
    - name: alistener
      disabled: false
      url: https://my.listener.com/event
      headers: <http.Header>
      timeout: 1s
      threshold: 10
      backoff: 1s
      ignoredmediatypes:
        - application/octet-stream
      ignore:
        mediatypes:
           - application/octet-stream
        actions:
           - pull

redis

使用外部redis

redis:
  addr: localhost:6379 # 必需;redis地址
  password: asecret # redis密码
  db: 0 # 数据库名称
  dialtimeout: 10ms # 链超时时间
  readtimeout: 10ms # 读超时时间
  writetimeout: 10ms # 写超时时间
  pool: # 设置链接池
    maxidle: 16 # 最大空闲链接数量
    maxactive: 64 # 阻止链接前最大连接数
    idletimeout: 300s # 关闭非活动链接前等待时间
  tls:
    enabled: false

health

可选,健康检查

health: # 如果http.debug开启则数据反馈在 /debug/health
  storagedriver: # 后端存储健康检查
    enabled: true # 默认启用
    interval: 10s # 检查间隔
    threshold: 3 # 至少多少次失败才算不健康;不设置则单次失败就算不健康
  file: # 判断文件存在性,如果有则失败
    - file: /path/to/checked/file 
      interval: 10s
  http: # 以head请求具体url,请求失败或非期望反馈码即失败
    - uri: http://server.to.check/must/return/200 # 必需;指定url
      headers: # 添加标头
        Authorization: [Basic QWxhZGRpbjpvcGVuIHNlc2FtZQ==]
      statuscode: 200 # 期望反馈码,默认200
      timeout: 3s # 等待反馈超时时间
      interval: 10s # 间隔时间
      threshold: 3 # 累计失败次数即为不健康;不写则单次失败为不健康
  tcp: # tcp链接检查
    - addr: redis-server.domain.com:6379 # 链接对象
      timeout: 3s # 链接超时
      interval: 10s 
      threshold: 3

proxy

可选,配置后以拉取式缓存镜像仓库运行

proxy:
  remoteurl: https://registry-1.docker.io # 必需;远端对象
  username: [username] # 仓库账号
  password: [password] # 仓库密码
  ttl: 168h # 缓存数据生命周期「仅v3版本生效」

validation

配置注册表对内容的验证

看了官网说明有点糊涂,不考虑配置

validation:
  disabled: false # 开启后禁用同级的其他配置
  manifests: 
    urls:
      allow:
        - ^https?://([^/]+\.)*example\.com/
      deny:
        - ^https?://www\.example\.com/
    indexes:
      platforms: List
      platformlist:
      - architecture: amd64
        os: linux