configuration

package
v2.0.0-rc.0+incompatible Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Apr 3, 2015 License: Apache-2.0 Imports: 11 Imported by: 0

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:

  • error
  • warn
  • info
  • debug
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.

apikey

(Required for bugsnag use) Specifies the bugnsag API Key for authenticating to your account.

releasestage

(Optional) Tracks the stage at which the registry is deployed. For example: "production", "staging", "development".

endpoint

(Optional) Used for specifying an enterprise bugsnag endpoint other than https://bugsnag.com.

newrelic

Reports heap, goroutine, and http stats to NewRelic.

licensekey

(Required for newrelic use) Specifies the NewRelic License Key for authenticating to your account.

name

(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

View Source 
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 

func (auth Auth) MarshalYAML() (interface{}, error)

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) Type 

func (auth Auth) Type() string

Type returns the storage driver type, such as filesystem or s3

func (*Auth) UnmarshalYAML 

func (auth *Auth) 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 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"`

	// Log supports setting various parameters related to the logging
	// subsystem.
	Log struct {
		// Level is the granularity at which registry operations are logged.
		Level Loglevel `yaml:"level"`

		// Formatter overrides the default formatter with another. Options
		// include "text", "json" and "logstash".
		Formatter string `yaml:"formatter"`

		// Fields allows users to specify static string fields to include in
		// the logger context.
		Fields map[string]interface{} `yaml:"fields"`
	}

	// Loglevel is the level at which registry operations are logged. This is
	// deprecated. Please use Log.Level in the future.
	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"`

	// Middleware lists all middlewares to be used by the registry.
	Middleware map[string][]Middleware `yaml:"middleware,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"`

			// Specifies the CA certs for client authentication
			// A file may contain multiple CA certificates encoded as PEM
			ClientCAs []string `yaml:"clientcas,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 Loglevel 

type Loglevel string

Loglevel is the level at which operations are logged This can be error, warn, info, or debug

func (*Loglevel) UnmarshalYAML 

func (loglevel *Loglevel) UnmarshalYAML(unmarshal func(interface{}) error) error

UnmarshalYAML implements the yaml.Umarshaler interface Unmarshals a string into a Loglevel, lowercasing the string and validating that it represents a valid loglevel

type Middleware 

type Middleware struct {
	// Name the middleware registers itself as
	Name string `yaml:"name"`
	// Flag to disable middleware easily
	Disabled bool `yaml:"disabled,omitempty"`
	// Map of parameters that will be passed to the middleware's initialization function
	Options Parameters `yaml:"options"`
}

Middleware configures named middlewares to be applied at injection points.

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 

func (p *Parser) Parse(in []byte, v interface{}) error

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 

func (storage Storage) MarshalYAML() (interface{}, error)

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) Type 

func (storage Storage) Type() string

Type returns the storage driver type, such as filesystem or s3

func (*Storage) UnmarshalYAML 

func (storage *Storage) 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 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 

func MajorMinorVersion(major, minor uint) Version

MajorMinorVersion constructs a Version from its Major and Minor components

func (Version) Major 

func (version Version) Major() uint

Major returns the major version portion of a Version

func (Version) Minor 

func (version Version) Minor() uint

Minor returns the minor version portion of a Version

func (*Version) UnmarshalYAML 

func (version *Version) UnmarshalYAML(unmarshal func(interface{}) error) error

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

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.