Configuring The Server¶
The server will accept configuration on the command line, or via a configuration yaml file. Most of the configuration file settings map directly to the command line. The exceptions are the pruneConfig, registries, and serverTlsConfig entries which are only accepted in the configuration file at this time, being too complex to easily represent as command line args.
Note
As of server version 2.0.0, strict parsing of the config yaml is implemented. A parse error will prevent the server from running.
As one would expect the following values provide configuration with the lowest priority on the bottom and the highest priority on the top:
block
columns 1
a["Command line"]
b["Config file"]
c["Hard-coded defaults in the Go code"]
To provide full configuration in a file, run the server this way:
bin/ociregistry --config-file <some file> serve
But this is also valid:
bin/ociregistry --config-file <some file> serve --port 9999
Defaults¶
The yaml document below shows a config.yaml file specifying the defaults that are implemented in the Go code. In other words, running the server with this exact configuration file is the same as running with no configuration file:
imagePath: /var/lib/ociregistry
logLevel: error
logFile:
preloadImages:
imageFile:
resolveRef:
port: 8080
#os: omit to use the server OS
#arch: omit to use the server architecture
pullTimeout: 60000
alwaysPullLatest: false
noCache: []
airGapped: false
helloWorld: false
defaultNs:
host: 0.0.0.0
health:
metrics:
registries: []
pruneConfig:
enabled: false
serverTlsConfig: {}
Config file keys and values¶
| Key | Type | Default | Command line arg | Description |
|---|---|---|---|---|
imagePath |
Path spec | /var/lib/ociregistry | --image-path |
The base path for the image cache. The server will create sub-directories under this for blobs and manifests. |
logLevel |
keyword | error | --log-level |
Error level logging. See help for valid values. |
logFile |
Path spec | - | --log-file |
Empty means log to stderr. If you specify a file, the logging is directed to the file. |
preloadImages |
Path spec | - | --preload-images |
Used by the serve subcommand to pre-load images before starting the server. See "Loading Images" below. |
imageFile |
Path spec | - | --image-file |
Used by the load subcommand to load images while the server is not running (expects exclusive access to the image cache.) See "Loading Images" below. |
resolveRef |
string | n/a | --resolve-ref |
Don't use this field in the configuration yaml file. This is a very narrow use case for single-image tarballs. See the load sub-command, e.g. ociregistry load --help |
port |
Integer | 8080 | --port |
The port to serve on |
os |
keyword | runtime.GOOS | --os |
If loading or preloading, the OS and arch. If empty, then defaults to the host running the server. So usually comment these out. |
arch |
keyword | runtime.GOARCH | --arch |
" |
pullTimeout |
Integer | 60000 | --pull-timeout |
Number of milliseconds before a pull from an upstream will time out. |
alwaysPullLatest |
Boolean | false | --always-pull-latest |
As of version 2.0.0, this is internally implemented as --no-cache ':latest$'. See the No Cache section below. |
noCache |
String list | [] |
--no-cache pattern [--no-cache pattern] |
See the No Cache section below. |
airGapped |
Boolean | false | --air-gapped |
If true, will not attempt to pull from an upstream when an image is requested that is not cached. |
helloWorld |
Boolean | false | --hello-world |
For testing. Only serves 'docker.io/hello-world:latest' from embedded blobs and manifests |
defaultNs |
String | Empty | --default-ns |
Allows pulling without an explicit namespace. Otherise, a namespace is required either in-path (docker pull ociregistry:8080/docker.io/hello-world) or as a query param the way containerd does it when registry mirroring is configured in the containerd config.toml. E.g. if --default-ns=docker.io then docker pull ociregistry:8080/hello-world will pull from docker.io, otherwise it is an error. |
host |
String | 0.0.0.0 | --host |
E.g. "127.0.0.1". |
health |
Integer | - | --health |
A port number to run a /health endpoint on for Kubernetes liveness and readiness. By default, the server doesn't listen on a health port. The Helm chart enables this by default when running the server as a cluster workload. |
metrics |
Integer | - | --metrics |
A port number to run a /metrics endpoint on for Prometheus. By default, the server doesn't enable or expose metrics. |
registries |
List of dictionary | [] |
n/a | Upstream registries configuration. See further down for registry configuration. |
pruneConfig |
Dictionary | see below | n/a | Prune configuration. Pruning is disabled by default. See further down for prune configuration. |
serverTlsConfig |
Dictionary | {} |
n/a | Configures TLS with downstream (client) pullers, e.g. containerd. By default, serves over HTTP. See server tls configuration further down. |
No Cache¶
The noCache config entry (or --no-cache arg) works as follows:
- The value is a Go regex. In the config yaml it's a list, and on the command line it's a repeatable arg, e.g.
--no-cache foo --no-cache bar - It's only available in the
servesub-command - Each arg value is matched against the canonical URLs cached in the server or some subset, including digest URLs. The server canonicalizes urls on intake. Meaning you can pull by alias but pruning requires the
--no-cachearg to use the canonical url. E.g. if you pulldocker.io/hello-world:latest, to always re-pull requires--no-cache docker.io/library/hello-world:latestor some matching subset. - The patterns provided on the command line replace those in the config file rather than being merged
- An invalid regex is a startup error
- The cached copy is served if the upstream pull fails
Loading Images¶
The following methods are supported to load the server with images.
- By specifying a plain text file containing a list of image urls. The server reads the file and pulls each image from the upstream.
- By specifying an image tarball created by
docker save,ctr images export, etc. The server extracts all images from the tarball into cache.
The --preload-images and --image-file arg values are as follows:
- A single filename like
foo.txtorbar.tar - A glob expression enclosed in single quotes to prevent shell expansion, e.g.
'*.tar', or'image-list-*.txt' - A comma-separated expression containing all of the above. E.g.:
'foo.txt,bar.tar,image-list*.txt',multi*.tar
The load command also supports --resolve-ref which is an edge-case arg. If you are loading a single-image tarball and you know that the image ref is not correct you can override the image ref like --resolve-ref docker.io/theright/repo:v1.2.3.
Here is an example of an image list file:
cat <<EOF >| imagelist
quay.io/jetstack/cert-manager-cainjector:v1.11.2
quay.io/jetstack/cert-manager-controller:v1.11.2
quay.io/jetstack/cert-manager-webhook:v1.11.2
registry.k8s.io/metrics-server/metrics-server:v0.6.2
registry.k8s.io/ingress-nginx/controller:v1.8.1
registry.k8s.io/pause:3.8
docker.io/kubernetesui/dashboard-api:v1.0.0
docker.io/kubernetesui/metrics-scraper:v1.0.9
docker.io/kubernetesui/dashboard-web:v1.0.0
EOF
Registry Configuration¶
The OCI Distribution server may need configuration to connect to upstream registries. If run with no configuration for a given registry, the server will default to anonymous insecure HTTPS access. You specify registry configuration using the registries list:
registries:
- name: upstream one
description: foo
scheme: https
auth: {}
tls: {}
- name: upstream two
description: bar
scheme: http
auth: {}
tls: {}
- etc...
Each entry supports the following configuration structure overall. Not all values are required. More detail is presented on that below. This shows the full structure:
- name: my-upstream # or my-upstream:PORT, e.g. index.docker.io
description: Something that makes sense to you (or omit it - it is optional)
scheme: https # (the default), also accepts http
auth:
user: theuser
password: thepass
passwordFromEnv: THEPASS_ENV_VAR
token: {}
tls:
ca: /my/ca.crt
cert: /my/client.cert
key: /my/client.key
insecureSkipVerify: true/false # defaults to false
Since scheme defaults to https you can omit that entirely. The tls key is optional. If omitted and scheme is https then the Ociregistry server attempts insecure 1-way TLS. The default for tls.insecureSkipVerify is false if omitted (and tls is specified.) Similarly, description is ignored by the server and can be omitted.
The auth section implements basic auth, just like your ~/.docker/config.json file.
Note
The auth.token configuration element supports token-based authentication using an external service and is documented in the Authentication section.
The name value is the upstream host name that you will pull from. For example say you're running the server on your desktop in test mode on localhost:8080. Let's also say that you have an in-house corporate registry that serves proprietary images on my-corp-registry.myco.org:8888. You run this command to pull through the Ociregistry server from your corporate registry server this way:
docker pull localhost:8080/my-corp-registry.myco.org:8888/my-proprietary-app:v1.0.0
registries entry in the Ociregistry server config file like this:
- name: my-corp-registry.myco.org:8888
auth:
user: theuser
password: thepass
To read the password from an environment variable, use the passwordFromEnv key:
- name: my-corp-registry.myco.org:8888
auth:
user: theuser
passwordFromEnv: THEPASS_ENV_VAR
Here's another scenario. Let's say your corp DNS resolves index.docker.io to an in-house registry mirror that requires an NPE cert. Then your registry entry might look like:
- name: index.docker.io
tls:
cert: npe.crt
key: npe.key
The tls section can implement multiple scenarios:
- One-way insecure TLS, in which client certs are not provided to the remote, and the remote server cert is not validated:
tls: insecureSkipVerify: true - One-way secure TLS, in which client certs are not provided to the remote, and the remote server cert is validated using the OS trust store:
tls: insecureSkipVerify: false # (or omit, since it defaults to false) - One-way secure TLS, in which client certs are not provided to the remote, and the remote server cert is validate using a provided CA cert:
tls: ca: /my/ca.crt - mTLS (client certs are provided to the remote):
mTLS can be implemented with and without remote server cert validation as described above in the various one-way TLS scenarios. Examples:
tls: cert: /my/client.cert key: /my/client.key- name: foo.bar.1.io description: mTLS, don't verify server cert tls: cert: /my/client.cert key: /my/client.key insecureSkipVerify: true - name: foo.bar.2.io description: mTLS, verify server cert from OS trust store tls: cert: /my/client.cert key: /my/client.key insecureSkipVerify: false - name: foo.bar.3.io description: mTLS, verify server cert from provided CA tls: cert: /my/client.cert key: /my/client.key ca: /remote/ca.crt insecureSkipVerify: false
Server TLS configuration¶
By default, the server serves over HTTP. The serverTlsConfig section in the config file configures the Ociregistry server to serve over TLS.
The cert, key, and ca are expected to be PEM encoded files. Example:
serverTlsConfig:
cert: /path/to/pem/encoded/server.crt
key: /path/to/pem/encoded/server.private.key
ca: /path/to/pem/encoded/ca.crt
clientAuth: none # or verify
Server TLS permutations¶
The following permutations are supported or serving over HTTPS:
| Configuration | Description |
|---|---|
cert and key populated |
The server will provide the cert to the client to establish 1-way TLS. |
clientAuth: none |
Client cert is not requested and will be ignored if provided. |
clientAuth: verify |
mTLS: Client cert is required and verified. See the ca key below. |
ca populated |
Client cert is validated against the provided CA. |
ca omitted |
Client cert is validated against the OS trust store. |
Prune Configuration¶
Pruning configures the server to remove images as a background process based on create date or recency of a pull. (Each time an image is pulled the server updates the pull date/time for the image.) Pruning is disabled by default. An example full prune configuration is as follows:
pruneConfig:
enabled: true
duration: 30d
type: accessed
expr:
frequency: 1d
count: -1
dryRun: true
Prune configuration keys and values¶
| Key | Type | Description |
|---|---|---|
enabled |
Boolean | If true, enables background pruning. |
duration |
Duration expression | E.g.: 30d. The value is interpreted based on the prune type below. Valid time units are ns (nanoseconds), us or µs (microseconds), ms (milliseconds), s (seconds), m (minutes), h (hours), and d (days). |
type |
Keyword | Valid values are pattern, accessed and created. If accessed, then the server prunes images that have not been pulled in duration amount of time. If created, then the server prunes images whose create date is older than duration time ago. If pattern, then expr has the pattern value. |
expr |
URL regex | E.g. calico. Only used if type is pattern. |
frequency |
Duration expression | E.g.: 1d. Run the background pruner with this frequency. The time units are the same as for duration. |
count |
Integer | The number of images to prune on each run of the background pruner. A value of -1 means no limit to the number of images pruned. If 0, then the server interprets this as undefined and defaults to 5. |
dryRun |
Boolean | Defaults to true: just logs messages but doesn't actually prune. For testing and troubleshooting. Set dryRun: false to actually prune. |
Important about prune¶
- A prune blocks new upstream pulls while it runs. Cached pulls aren’t affected.
- If upstream pulls are still running after 10 seconds, the prune is skipped until the next run.