README
¶
Docker-Registry Configuration
This document describes the registry configuration model and how to specify a custom configuration with a configuration file and/or environment variables.
Semantic-ish Versioning
The configuration file is designed with versioning in mind, such that most upgrades will not require a change in configuration files, and such that configuration files can be "upgraded" from one version to another.
The version is specified as a string of the form MajorVersion.MinorVersion, where MajorVersion and MinorVersion are both non-negative integer values. Much like semantic versioning, minor version increases denote inherently backwards-compatible changes, such as the addition of optional fields, whereas major version increases denote a restructuring, such as renaming fields or adding required fields. Because of the explicit version definition in the configuration file, it should be possible to parse old configuration files and port them to the current configuration version, although this is not guaranteed for all future versions.
File Structure (as of Version 0.1)
The configuration structure is defined by the Configuration struct in configuration.go, and is best described by the following two examples:
version: 0.1
loglevel: info
storage:
s3:
region: us-east-1
bucket: my-bucket
rootpath: /registry
encrypt: true
secure: false
accesskey: SAMPLEACCESSKEY
secretkey: SUPERSECRET
host: ~
port: ~
auth:
silly:
realm: test-realm
service: my-service
reporting:
bugsnag:
apikey: mybugsnagapikey
releasestage: development
newrelic:
licensekey: mynewreliclicensekey
name: docker-distribution
http:
addr: 0.0.0.0:5000
secret: mytokensecret
version: 0.1
loglevel: debug
storage: inmemory
version
The version is expected to remain a top-level field, as to allow for a consistent version check before parsing the remainder of the configuration file.
loglevel
This specifies the log level of the registry.
Supported values:
errorwarninfodebug
storage
This specifies the storage driver, and may be provided either as a string (only the driver type) or as a driver name with a parameters map, as seen in the first example above.
The parameters map will be passed into the factory constructor of the given storage driver type.
auth
This specifies the authorization method the registry will use, and is provided as an auth type with a parameters map.
The parameters map will be passed into the factory constructor of the given auth type.
reporting
This specifies metrics/error reporting systems which the registry will forward information about stats/errors to. There are currently two supported systems, which are documented below.
bugsnag
Reports http errors and panics to bugsnag.
(Required for bugsnag use) Specifies the bugnsag API Key for authenticating to your account.
(Optional) Tracks the stage at which the registry is deployed. For example: "production", "staging", "development".
(Optional) Used for specifying an enterprise bugsnag endpoint other than https://bugsnag.com.
newrelic
Reports heap, goroutine, and http stats to NewRelic.
(Required for newrelic use) Specifies the NewRelic License Key for authenticating to your account.
(Optional) Specifies the component name that is displayed in the NewRelic panel.
http
This is used for HTTP transport-specific configuration options.
addr
Specifies the bind address for the registry instance. Example: 0.0.0.0:5000
secret
Specifies the secret key with which query-string HMAC tokens are generated.
Notes
All keys in the configuration file must be provided as a string of lowercase letters and numbers only, and values must be string-like (booleans and numerical values are fine to parse as strings).
Environment Variables
To support the workflow of running a docker registry from a standard container without having to modify configuration files, the registry configuration also supports environment variables for overriding fields.
Any configuration field other than version can be replaced by providing an environment variable of the following form: REGISTRY_<uppercase key>[_<uppercase key>]....
For example, to change the loglevel to error, one can provide REGISTRY_LOGLEVEL=error, and to change the s3 storage driver's region parameter to us-west-1, one can provide REGISTRY_STORAGE_S3_LOGLEVEL=us-west-1.
Notes
If an environment variable changes a map value into a string, such as replacing the storage driver type with REGISTRY_STORAGE=filesystem, then all sub-fields will be erased. As such, specifying the storage type in the environment will remove all parameters related to the old storage configuration.
By restricting all keys in the configuration file to lowercase letters and numbers, we can avoid any potential environment variable mapping ambiguity.
Documentation
¶
Index ¶
Constants ¶
This section is empty.
Variables ¶
var CurrentVersion = MajorMinorVersion(0, 1)
CurrentVersion is the most recent Version that can be parsed
Functions ¶
This section is empty.
Types ¶
type Auth ¶
type Auth map[string]Parameters
Auth defines the configuration for registry authorization.
func (Auth) MarshalYAML ¶
MarshalYAML implements the yaml.Marshaler interface
func (Auth) Parameters ¶
func (auth Auth) Parameters() Parameters
Parameters returns the Parameters map for an Auth configuration
func (*Auth) UnmarshalYAML ¶
UnmarshalYAML implements the yaml.Unmarshaler interface Unmarshals a single item map into a Storage or a string into a Storage type with no parameters
type BugsnagReporting ¶
type BugsnagReporting struct {
// APIKey is the Bugsnag api key.
APIKey string `yaml:"apikey,omitempty"`
// ReleaseStage tracks where the registry is deployed.
// Examples: production, staging, development
ReleaseStage string `yaml:"releasestage,omitempty"`
// Endpoint is used for specifying an enterprise Bugsnag endpoint.
Endpoint string `yaml:"endpoint,omitempty"`
}
BugsnagReporting configures error reporting for Bugsnag (bugsnag.com).
type Configuration ¶
type Configuration struct {
// Version is the version which defines the format of the rest of the configuration
Version Version `yaml:"version"`
// Loglevel is the level at which registry operations are logged
Loglevel Loglevel `yaml:"loglevel"`
// Storage is the configuration for the registry's storage driver
Storage Storage `yaml:"storage"`
// Auth allows configuration of various authorization methods that may be
// used to gate requests.
Auth Auth `yaml:"auth,omitempty"`
// LayerHandler specifies a middleware for serving image layers.
LayerHandler LayerHandler `yaml:"layerhandler,omitempty"`
// Reporting is the configuration for error reporting
Reporting Reporting `yaml:"reporting,omitempty"`
// HTTP contains configuration parameters for the registry's http
// interface.
HTTP struct {
// Addr specifies the bind address for the registry instance.
Addr string `yaml:"addr,omitempty"`
Prefix string `yaml:"prefix,omitempty"`
// Secret specifies the secret key which HMAC tokens are created with.
Secret string `yaml:"secret,omitempty"`
// TLS instructs the http server to listen with a TLS configuration.
// This only support simple tls configuration with a cert and key.
// Mostly, this is useful for testing situations or simple deployments
// that require tls. If more complex configurations are required, use
// a proxy or make a proposal to add support here.
TLS struct {
// Certificate specifies the path to an x509 certificate file to
// be used for TLS.
Certificate string `yaml:"certificate,omitempty"`
// Key specifies the path to the x509 key file, which should
// contain the private portion for the file specified in
// Certificate.
Key string `yaml:"key,omitempty"`
} `yaml:"tls,omitempty"`
// Debug configures the http debug interface, if specified. This can
// include services such as pprof, expvar and other data that should
// not be exposed externally. Left disabled by default.
Debug struct {
// Addr specifies the bind address for the debug server.
Addr string `yaml:"addr,omitempty"`
} `yaml:"debug,omitempty"`
} `yaml:"http,omitempty"`
// Notifications specifies configuration about various endpoint to which
// registry events are dispatched.
Notifications Notifications `yaml:"notifications,omitempty"`
}
Configuration is a versioned registry configuration, intended to be provided by a yaml file, and optionally modified by environment variables
func Parse ¶
func Parse(rd io.Reader) (*Configuration, error)
Parse parses an input configuration yaml document into a Configuration struct This should generally be capable of handling old configuration format versions
Environment variables may be used to override configuration parameters other than version, following the scheme below: Configuration.Abc may be replaced by the value of REGISTRY_ABC, Configuration.Abc.Xyz may be replaced by the value of REGISTRY_ABC_XYZ, and so forth
type Endpoint ¶
type Endpoint struct {
Name string `yaml:"name"` // identifies the endpoint in the registry instance.
Disabled bool `yaml:"disabled"` // disables the endpoint
URL string `yaml:"url"` // post url for the endpoint.
Headers http.Header `yaml:"headers"` // static headers that should be added to all requests
Timeout time.Duration `yaml:"timeout"` // HTTP timeout
Threshold int `yaml:"threshold"` // circuit breaker threshold before backing off on failure
Backoff time.Duration `yaml:"backoff"` // backoff duration
}
Endpoint describes the configuration of an http webhook notification endpoint.
type LayerHandler ¶
type LayerHandler map[string]Parameters
LayerHandler defines the configuration for middleware layer serving
func (LayerHandler) MarshalYAML ¶
func (layerHandler LayerHandler) MarshalYAML() (interface{}, error)
MarshalYAML implements the yaml.Marshaler interface
func (LayerHandler) Parameters ¶
func (layerHandler LayerHandler) Parameters() Parameters
Parameters returns the Parameters map for a LayerHandler configuration
func (LayerHandler) Type ¶
func (layerHandler LayerHandler) Type() string
Type returns the layerhandler type
func (*LayerHandler) UnmarshalYAML ¶
func (layerHandler *LayerHandler) UnmarshalYAML(unmarshal func(interface{}) error) error
UnmarshalYAML implements the yaml.Unmarshaler interface Unmarshals a single item map into a Storage or a string into a Storage type with no parameters
type Loglevel ¶
type Loglevel string
Loglevel is the level at which operations are logged This can be error, warn, info, or debug
func (*Loglevel) UnmarshalYAML ¶
UnmarshalYAML implements the yaml.Umarshaler interface Unmarshals a string into a Loglevel, lowercasing the string and validating that it represents a valid loglevel
type NewRelicReporting ¶
type NewRelicReporting struct {
// LicenseKey is the NewRelic user license key
LicenseKey string `yaml:"licensekey,omitempty"`
// Name is the component name of the registry in NewRelic
Name string `yaml:"name,omitempty"`
}
NewRelicReporting configures error reporting for NewRelic (newrelic.com)
type Notifications ¶
type Notifications struct {
// Endpoints is a list of http configurations for endpoints that
// respond to webhook notifications. In the future, we may allow other
// kinds of endpoints, such as external queues.
Endpoints []Endpoint `yaml:"endpoints,omitempty"`
}
Notifications configures multiple http endpoints.
type Parameters ¶
type Parameters map[string]interface{}
Parameters defines a key-value parameters mapping
type Parser ¶
type Parser struct {
// contains filtered or unexported fields
}
Parser can be used to parse a configuration file and environment of a defined version into a unified output structure
func NewParser ¶
func NewParser(prefix string, parseInfos []VersionedParseInfo) *Parser
NewParser returns a *Parser with the given environment prefix which handles versioned configurations which match the given parseInfos
func (*Parser) Parse ¶
Parse reads in the given []byte and environment and writes the resulting configuration into the input v
Environment variables may be used to override configuration parameters other than version, following the scheme below: v.Abc may be replaced by the value of PREFIX_ABC, v.Abc.Xyz may be replaced by the value of PREFIX_ABC_XYZ, and so forth
type Reporting ¶
type Reporting struct {
// Bugsnag configures error reporting for Bugsnag (bugsnag.com).
Bugsnag BugsnagReporting `yaml:"bugsnag,omitempty"`
// NewRelic configures error reporting for NewRelic (newrelic.com)
NewRelic NewRelicReporting `yaml:"newrelic,omitempty"`
}
Reporting defines error reporting methods.
type Storage ¶
type Storage map[string]Parameters
Storage defines the configuration for registry object storage
func (Storage) MarshalYAML ¶
MarshalYAML implements the yaml.Marshaler interface
func (Storage) Parameters ¶
func (storage Storage) Parameters() Parameters
Parameters returns the Parameters map for a Storage configuration
func (*Storage) UnmarshalYAML ¶
UnmarshalYAML implements the yaml.Unmarshaler interface Unmarshals a single item map into a Storage or a string into a Storage type with no parameters
type Version ¶
type Version string
Version is a major/minor version pair of the form Major.Minor Major version upgrades indicate structure or type changes Minor version upgrades should be strictly additive
func MajorMinorVersion ¶
MajorMinorVersion constructs a Version from its Major and Minor components
func (*Version) UnmarshalYAML ¶
UnmarshalYAML implements the yaml.Unmarshaler interface Unmarshals a string of the form X.Y into a Version, validating that X and Y can represent uints
type VersionedParseInfo ¶
type VersionedParseInfo struct {
// Version is the version which this parsing information relates to
Version Version
// ParseAs defines the type which a configuration file of this version
// should be parsed into
ParseAs reflect.Type
// ConversionFunc defines a method for converting the parsed configuration
// (of type ParseAs) into the current configuration version
// Note: this method signature is very unclear with the absence of generics
ConversionFunc func(interface{}) (interface{}, error)
}
VersionedParseInfo defines how a specific version of a configuration should be parsed into the current version
Source Files