Skip to content

Latest commit

 

History

History
2188 lines (2005 loc) · 51.2 KB

configuration.md

File metadata and controls

2188 lines (2005 loc) · 51.2 KB
Raw

Registry Configuration Reference

The Registry configuration is based on a YAML file, detailed below. While it comes with sane default values out of the box, you are heavily encouraged to review it exhaustively before moving your systems to production.

Override specific configuration options

In a typical setup where you run your Registry from the official image, you can specify a configuration variable from the environment by passing -e arguments to your docker run stanza, or from within a Dockerfile using the ENV instruction.

To override a configuration option, create an environment variable named REGISTRY_variable where variable is the name of the configuration option and the _ (underscore) represents indention levels. For example, you can configure the rootdirectory of the filesystem storage backend:

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

To override this value, set an environment variable like this:

REGISTRY_STORAGE_FILESYSTEM_ROOTDIRECTORY=/somewhere

This variable overrides the /var/lib/registry value to the /somewhere directory.

NOTE: It is highly recommended to create a base configuration file with which environment variables can be used to tweak individual values. Overriding configuration sections with environment variables is not recommended.

Overriding the entire configuration file

If the default configuration is not a sound basis for your usage, or if you are having issues overriding keys from the environment, you can specify an alternate YAML configuration file by mounting it as a volume in the container.

Typically, create a new configuration file from scratch, and call it config.yml, then:

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

You can (and probably should) use this as a starting point.

List of configuration options

This section lists all the registry configuration options. Some options in the list are mutually exclusive. So, make sure to read the detailed reference information about each option that appears later in this page.

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
  gcs:
    bucket: bucketname
    keyfile: /path/to/keyfile
    rootdirectory: /gcs/object/name/prefix
  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
  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: 3000
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
  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
  headers:
    X-Content-Type-Options: [nosniff]
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
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]

In some instances a configuration option is optional but it contains child options marked as required. This indicates that you can omit the parent with all its children. However, if the parent is included, you must also include all the children marked required.

version

version: 0.1

The version option is required. It specifies the configuration's version. It is expected to remain a top-level field, to allow for a consistent version check before parsing the remainder of the configuration file.

log

The log subsection configures the behavior of the logging system. The logging system outputs everything to stdout. You can adjust the granularity and format with this configuration section.

log:
  level: debug
  formatter: text
  fields:
    service: registry
    environment: staging
Parameter Required Description
level no Sets the sensitivity of logging output. Permitted values are error, warn, info and debug. The default is info.
formatter no This selects the format of logging output. The format primarily affects how keyed attributes for a log line are encoded. Options are text, json or logstash. The default is text.
fields no A map of field names to values. These are added to every log line for the context. This is useful for identifying log messages source after being mixed in other systems.

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]

The hooks subsection configures the logging hooks' behavior. This subsection includes a sequence handler which you can use for sending mail, for example. Refer to loglevel to configure the level of messages printed.

loglevel

DEPRECATED: Please use log instead.

loglevel: debug

Permitted values are error, warn, info and debug. The default is info.

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
    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
  delete:
    enabled: false
  cache:
    blobdescriptor: inmemory
  maintenance:
    uploadpurging:
      enabled: true
      age: 168h
      interval: 24h
      dryrun: false
  redirect:
    disable: false

The storage option is required and defines which storage backend is in use. You must configure one backend; if you configure more, the registry returns an error.

If you are deploying a registry on Windows, be aware that a Windows volume mounted from the host is not recommended. Instead, you can use a S3, or Azure, backing data-store. If you do use a Windows volume, you must ensure that the PATH to the mount point is within Windows' MAX_PATH limits (typically 255 characters). Failure to do so can result in the following error message:

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

Maintenance

Currently upload purging and read-only mode are the only maintenance functions available. These and future maintenance functions which are related to storage can be configured under the maintenance section.

Upload Purging

Upload purging is a background process that periodically removes orphaned files from the upload directories of the registry. Upload purging is enabled by default. To configure upload directory purging, the following parameters must be set.

Parameter Required Description
enabled yes Set to true to enable upload purging. Default=true.
age yes Upload directories which are older than this age will be deleted. Default=168h (1 week)
interval yes The interval between upload directory purging. Default=24h.
dryrun yes dryrun can be set to true to obtain a summary of what directories will be deleted. Default=false.

Note: age and interval are strings containing a number with optional fraction and a unit suffix: e.g. 45m, 2h10m, 168h (1 week).

Read-only mode

If the readonly section under maintenance has enabled set to true, clients will not be allowed to write to the registry. This mode is useful to temporarily prevent writes to the backend storage so a garbage collection pass can be run. Before running garbage collection, the registry should be restarted with readonly's enabled set to true. After the garbage collection pass finishes, the registry may be restarted again, this time with readonly removed from the configuration (or set to false).

delete

Use the delete subsection to enable the deletion of image blobs and manifests by digest. It defaults to false, but it can be enabled by writing the following on the configuration file:

delete:
  enabled: true

cache

Use the cache subsection to enable caching of data accessed in the storage backend. Currently, the only available cache provides fast access to layer metadata. This, if configured, uses the blobdescriptor field.

You can set blobdescriptor field to redis or inmemory. The redis value uses a Redis pool to cache layer metadata. The inmemory value uses an in memory map.

NOTE: Formerly, blobdescriptor was known as layerinfo. While these are equivalent, layerinfo has been deprecated, in favor or blobdescriptor.

redirect

The redirect subsection provides configuration for managing redirects from content backends. For backends that support it, redirecting is enabled by default. Certain deployment scenarios may prefer to route all data through the Registry, rather than redirecting to the backend. This may be more efficient when using a backend that is not colocated or when a registry instance is doing aggressive caching.

Redirects can be disabled by adding a single flag disable, set to true under the redirect section:

redirect:
  disable: true

filesystem

The filesystem storage backend uses the local disk to store registry files. It is ideal for development and may be appropriate for some small-scale production applications.

This backend has a single, required rootdirectory parameter. The parameter specifies the absolute path to a directory. The registry stores all its data here so make sure there is adequate space available.

azure

This storage backend uses Microsoft's Azure Blob Storage.

Parameter Required Description
accountname yes Azure account name.
accountkey yes Azure account key.
container yes Name of the Azure container into which to store data.
realm no Domain name suffix for the Storage Service API endpoint. By default, this is core.windows.net.

gcs

This storage backend uses Google Cloud Storage.

Parameter Required Description
bucket yes Storage bucket name.
keyfile no A private service account key file in JSON format. Instead of a key file Google Application Default Credentials can be used.
rootdirectory no This is a prefix that will be applied to all Google Cloud Storage keys to allow you to segment data in your bucket if necessary.

rados

This storage backend uses Ceph Object Storage.

Parameter Required Description
poolname yes Ceph pool name.
username no Ceph cluster user to connect as (i.e. admin, not client.admin).
chunksize no Size of the written RADOS objects. Default value is 4MB (4194304).

S3

This storage backend uses Amazon's Simple Storage Service (S3).

Parameter Required Description
accesskey yes Your AWS Access Key.
secretkey yes Your 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 true.
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.

Openstack Swift

This storage backend uses Openstack Swift object storage.

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 name of your Swift container where you wish to store the registry's data. The driver creates the named container during its initialization.
tenant no Your Openstack tenant name. You can either use tenant or tenantid.
tenantid no Your Openstack tenant id. You can either use tenant or tenantid.
domain no Your Openstack domain name for Identity v3 API. You can either use domain or domainid.
domainid no Your Openstack domain id for Identity v3 API. You can either use domain or domainid.
trustid no Your Openstack trust 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).
prefix no This is a prefix that will be applied to all Swift keys to allow you to segment data in your container if necessary. Defaults to the empty string which is the container's root.
secretkey no The secret key used to generate temporary URLs.
accesskey no The access key to generate temporary URLs. It is used by HP Cloud Object Storage in addition to the `secretkey` parameter.

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

The auth option is optional. There are currently 3 possible auth providers, silly, token and htpasswd. You can configure only one auth provider.

silly

The silly auth is only for development purposes. It simply checks for the existence of the Authorization header in the HTTP request. It has no regard for the header's value. If the header does not exist, the silly auth responds with a challenge response, echoing back the realm, service, and scope that access was denied for.

The following values are used to configure the response:

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

token

Token based authentication allows the authentication system to be decoupled from the registry. It is a well established authentication paradigm with a high degree of security.

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.

For more information about Token based authentication configuration, see the specification.

htpasswd

The htpasswd authentication backed allows one to configure basic auth using an Apache HTPasswd File. Only bcrypt format passwords are supported. Entries with other hash types will be ignored. The htpasswd file is loaded once, at startup. If the file is invalid, the registry will display an error and will not start.

WARNING: This authentication scheme should only be used with TLS configured, since basic authentication sends passwords as part of the http header.

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

middleware

The middleware option is optional. Use this option to inject middleware at named hook points. All middlewares must implement the same interface as the object they're wrapping. This means a registry middleware must implement the distribution.Namespace interface, repository middleware must implement distribution.Repository, and storage middleware must implement driver.StorageDriver.

Currently only one middleware, cloudfront, a storage middleware, is supported in the registry implementation.

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.

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

The reporting option is optional and configures error and metrics reporting tools. At the moment only two services are supported, New Relic and Bugsnag, a valid configuration may contain both.

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/
  host: https://myregistryaddress.org:5000
  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
  headers:
    X-Content-Type-Options: [nosniff]

The http option details the configuration for the HTTP server that hosts the registry.

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 and FILE 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/.
host no This parameter specifies an externally-reachable address for the registry, as a fully qualified URL. If present, it is used when creating generated URLs. Otherwise, these URLs are derived from client requests.
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

The tls struct within http is optional. Use this to configure TLS for the server. If you already have a server such as Nginx or Apache running on the same host as the registry, you may prefer to configure TLS termination there and proxy connections to the registry server.

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

The debug option is optional . Use it to configure a debug server that can be helpful in diagnosing problems. The debug endpoint can be used for monitoring registry metrics and health, as well as profiling. Sensitive information may be available via the debug endpoint. Please be certain that access to the debug endpoint is locked down in a production environment.

The debug section takes a single, required addr parameter. This parameter specifies the HOST:PORT on which the debug server should accept connections.

headers

The headers option is optional . Use it to specify headers that the HTTP server should include in responses. This can be used for security headers such as Strict-Transport-Security.

The headers option should contain an option for each header to include, where the parameter name is the header's name, and the parameter value a list of the header's payload values.

Including X-Content-Type-Options: [nosniff] is recommended, so that browsers will not interpret content as HTML if they are directed to load a page from the registry. This header is included in the example configuration files.

notifications

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

The notifications option is optional and currently may contain a single option, endpoints.

endpoints

Endpoints is a list of named services (URLs) that can accept event notifications.

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. Each header's name should be a key underneath headers, and each value is a list of payloads for that header name. Note that values must always be lists.
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

Declare parameters for constructing the redis connections. Registry instances may use the Redis instance for several applications. The current purpose is caching information about immutable blobs. Most of the options below control how the registry connects to redis. You can control the pool's behavior with the pool subsection.

It's advisable to configure Redis itself with the allkeys-lru eviction policy as the registry does not set an expire value on keys.

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

Configure the behavior of the Redis connection pool.

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.

health

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

The health option is optional. It may contain preferences for a periodic health check on the storage driver's backend storage, and optional periodic checks on local files, HTTP URIs, and/or TCP servers. The results of the health checks are available at /debug/health on the debug HTTP server if the debug HTTP server is enabled (see http section).

storagedriver

storagedriver contains options for a health check on the configured storage driver's backend storage. enabled must be set to true for this health check to be active.

Parameter Required Description
enabled yes "true" to enable the storage driver health check or "false" to disable it.
interval no The length of time to wait between repetitions of the check. 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. The default value is 10 seconds if this field is omitted.
threshold no An integer specifying the number of times the check must fail before the check triggers an unhealthy state. If this filed is not specified, a single failure will trigger an unhealthy state.

file

file is a list of paths to be periodically checked for the existence of a file. If a file exists at the given path, the health check will fail. This can be used as a way of bringing a registry out of rotation by creating a file.

Parameter Required Description
file yes The path to check for the existence of a file.
interval no The length of time to wait between repetitions of the check. 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. The default value is 10 seconds if this field is omitted.

http

http is a list of HTTP URIs to be periodically checked with HEAD requests. If a HEAD request doesn't complete or returns an unexpected status code, the health check will fail.

Parameter Required Description
uri yes The URI to check.
headers no Static headers to add to each request. Each header's name should be a key underneath headers, and each value is a list of payloads for that header name. Note that values must always be lists.
statuscode no Expected status code from the HTTP URI. Defaults to 200.
timeout no The length of time to wait before timing out the HTTP request. 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.
interval no The length of time to wait between repetitions of the check. 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. The default value is 10 seconds if this field is omitted.
threshold no An integer specifying the number of times the check must fail before the check triggers an unhealthy state. If this filed is not specified, a single failure will trigger an unhealthy state.

tcp

tcp is a list of TCP addresses to be periodically checked with connection attempts. The addresses must include port numbers. If a connection attempt fails, the health check will fail.

Parameter Required Description
addr yes The TCP address to connect to, including a port number.
timeout no The length of time to wait before timing out the TCP connection. 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.
interval no The length of time to wait between repetitions of the check. 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. The default value is 10 seconds if this field is omitted.
threshold no An integer specifying the number of times the check must fail before the check triggers an unhealthy state. If this filed is not specified, a single failure will trigger an unhealthy state.

Proxy

proxy:
  remoteurl: https://registry-1.docker.io
  username: [username]
  password: [password]

Proxy enables a registry to be configured as a pull through cache to the official Docker Hub. See mirror for more information. Pushing to a registry configured as a pull through cache is currently unsupported.

Parameter Required Description
remoteurl yes The URL of the official Docker Hub
username no The username of the Docker Hub account
password no The password for the official Docker Hub account

To enable pulling private repositories (e.g. batman/robin) a username and password for user batman must be specified. Note: These private repositories will be stored in the proxy cache's storage and relevant measures should be taken to protect access to this.

Example: Development configuration

The following is a simple example you can use for local development:

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

The above configures the registry instance to run on port 5000, binding to localhost, with the debug server enabled. Registry data storage is in the /var/lib/registry directory. Logging is in debug mode, which is the most verbose.

A similar simple configuration is available at config-example.yml. Both are generally useful for local development.

Example: Middleware configuration

This example illustrates how to configure storage middleware in a registry. Middleware allows the registry to serve layers via a content delivery network (CDN). This is useful for reducing requests to the storage layer.

Currently, the registry supports Amazon Cloudfront. You can only use Cloudfront in conjunction with the S3 storage driver.

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.

The following example illustrates these values:

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

Note: Cloudfront keys exist separately to other AWS keys. See the documentation on AWS credentials for more information.