0
Fork 0
mirror of https://github.com/project-zot/zot.git synced 2024-12-30 22:34:13 -05:00

doc: add initial documentation for configuration options

We have built a long list of features and the documentation for users is
only available under examples/

Add a examples/README.md to further explain various configuration
options.

Signed-off-by: Ramkumar Chinchani <rchincha@cisco.com>
This commit is contained in:
Ramkumar Chinchani 2021-08-31 06:30:41 +00:00 committed by Ramkumar Chinchani
parent 609d85d875
commit c8779d9e87
2 changed files with 248 additions and 14 deletions

View file

@ -17,6 +17,7 @@ https://anuvu.github.io/zot/
* Uses [OCI image layout](https://github.com/opencontainers/image-spec/blob/master/image-layout.md) for image storage
* Can serve any OCI image layout as a registry
* Supports [helm charts](https://helm.sh/docs/topics/registries/)
* Behavior controlled via [configuration](./examples/README.md)
* Supports image deletion by tag
* Currently suitable for on-prem deployments (e.g. colocated with Kubernetes)
* Compatible with ecosystem tools such as [skopeo](#skopeo) and [cri-o](#cri-o)
@ -27,7 +28,7 @@ https://anuvu.github.io/zot/
* TLS mutual authentication
* HTTP *Basic* (local _htpasswd_ and LDAP)
* HTTP *Bearer* token
* [Authorization](#Authorization) Supports Identity-Based Access Control: [Configuration](./examples/config-policy.json)
* Supports Identity-Based Access Control
* Supports live modifications on the config file while zot is running (Authorization config only)
* Doesn't require _root_ privileges
* Storage optimizations:
@ -224,15 +225,6 @@ c3/openjdk-dev commit-2674e8a-squashfs b545b8ba 321MB
c3/openjdk-dev commit-d5024ec-squashfs cd45f8cf 321MB
```
## Authorization
zot follows the next logic for deciding who has rights on what resource:
1) First it checks the requested resource in "repositories" as specified in configuration
2) Searches in all policies for the user who requested the resource
3) If found, applies the policy, otherwise it falls back to the default policy for that repository
4) If not found, it falls back to the adminPolicy
# Ecosystem

View file

@ -1,5 +1,247 @@
You can check a configuration file validity by running the verify command:
```console
$ zot verify /path/to/config
```
The behavior of _zot_ registry is controlled via its configuration file, which
can either be a JSON (used in details below) or YAML file.
```
zot serve <config-file>
```
A candidate configuration file can be verified via:
```
zot verify <config-file>
```
Examples of working configurations for various use cases are available [here](../examples/)
# Configuration Parameters
* [Network](#network)
* [Storage](#storage)
* [Authentication](#authentication)
* [Identity-based Authorization](#identity-based-authorization)
* [Logging](#logging)
## Network
Configure network params with:
```
"http": {
```
Configure address and port to listen on with:
```
"address": "127.0.0.1",
"port": "5000",
```
Additionally, TLS configuration can be specified with:
```
"tls": {
"cert":"test/data/server.cert",
"key":"test/data/server.key"
},
```
The registry can be deployed as a read-only service with:
```
"ReadOnly": false
},
```
## Storage
Configure storage with:
```
"storage": {
```
Configure storage root directory with:
```
"rootDirectory": "/tmp/zot",
```
Often, container images have shared layers and blobs and for filesystems that
support hard links, inline deduplication can be enabled with:
```
"dedupe": true,
```
When an image is deleted (either by tag or reference), orphaned blobs can lead
to wasted storage, and background garbage collection can be enabled with:
```
"gc": true,
```
It is also possible to store and serve images from multiple filesystems with
their own repository paths, dedupe and garbage collection settings with:
```
"subPaths": {
"/a": {
"rootDirectory": "/tmp/zot1",
"dedupe": true,
"gc": true
},
"/b": {
"rootDirectory": "/tmp/zot2",
"dedupe": true
},
"/c": {
"rootDirectory": "/tmp/zot3",
"dedupe": false
}
}
},
```
## Authentication
TLS mutual authentication and passphrase-based authentication are supported.
### TLS Mutual Authentication
Apart from the server cert and key specified under
[network configuration](#network), specifying the _cacert_ field enables TLS mutual
authentication:
```
"http": {
"tls": {
"cert":"test/data/server.cert",
"key":"test/data/server.key",
"cacert":"test/data/cacert.cert"
},
```
### Passphrase Authentication
**Local authentication** is supported via htpasswd file with:
```
"http": {
"auth": {
"htpasswd": {
"path": "test/data/htpasswd"
},
```
**LDAP authentication** can be configured with:
```
"http": {
"auth": {
"ldap": {
"address":"ldap.example.org",
"port":389,
"startTLS":false,
"baseDN":"ou=Users,dc=example,dc=org",
"userAttribute":"uid",
"bindDN":"cn=ldap-searcher,ou=Users,dc=example,dc=org",
"bindPassword":"ldap-searcher-password",
"skipVerify":false,
"subtreeSearch":true
},
```
NOTE: When both htpasswd and LDAP configuration are specified, LDAP authentication is given preference.
**OAuth2 authentication** (client credentials grant type) support via _Bearer Token_ configured with:
```
"http": {
"auth": {
"bearer": {
"realm": "https://auth.myreg.io/auth/token",
"service": "myauth",
"cert": "/etc/zot/auth.crt"
}
```
#### Authentication Failures
Should authentication fail, to prevent automated attacks, a delayed response can be configured with:
```
"http": {
"auth": {
"failDelay": 5
```
## Identity-based Authorization
Allowing actions on one or more repository paths can be tied to user
identities. An additional per-repository default policy can be specified for
identities not in the whitelist. Furthermore, a global admin policy can also be
specified which can override per-repository policies.
```
"accessControl": {
"repos1/repo": {
"policies": [
{
"users": ["alice", "bob"],
"actions": ["create", "read", "update", "delete"]
},
{
"users": ["mallory"],
"actions": ["create", "read"]
}
],
"defaultPolicy": ["read"]
},
"repos2/repo": {
"policies": [
{
"users": ["bob"],
"actions": ["read", "create"]
},
{
"users": ["mallory"],
"actions": ["create", "read"]
}
],
"defaultPolicy": ["read"]
},
"adminPolicy": {
"users": ["admin"],
"actions": ["read", "create", "update", "delete"]
}
}
```
## Logging
Enable and configure logging with:
```
"log":{
```
Set log level with:
```
"level":"debug",
```
Set output file (default is _stdout_) with:
```
"output":"/tmp/zot.log",
```
Enable audit logs and set output file with:
```
"audit": "/tmp/zot-audit.log"
}
```