From b800c5f20a3b00acedfd7fc95ab336b493756758 Mon Sep 17 00:00:00 2001 From: Ramkumar Chinchani Date: Sat, 29 Jan 2022 02:21:58 +0000 Subject: [PATCH] README: update README.md Signed-off-by: Ramkumar Chinchani --- README.md | 125 ++++++++++++++++++++++++++++------- examples/config-minimal.json | 3 +- 2 files changed, 102 insertions(+), 26 deletions(-) diff --git a/README.md b/README.md index 45432705..78308b68 100644 --- a/README.md +++ b/README.md @@ -1,32 +1,45 @@ # zot [![build-test](https://github.com/project-zot/zot/actions/workflows/ci-cd.yml/badge.svg?branch=main)](https://github.com/project-zot/zot/actions/workflows/ci-cd.yml) [![codecov.io](http://codecov.io/github/project-zot/zot/coverage.svg?branch=main)](http://codecov.io/github/project-zot/zot?branch=main) [![Conformance Results](https://github.com/project-zot/zot/workflows/conformance/badge.svg)](https://github.com/project-zot/zot/actions?query=workflow%3Aconformance) [![CodeQL](https://github.com/project-zot/zot/workflows/CodeQL/badge.svg)](https://github.com/project-zot/zot/actions?query=workflow%3ACodeQL) -**zot** is a vendor-neutral OCI image registry server purely based on -[OCI Distribution Specification](https://github.com/opencontainers/distribution-spec). +**zot**: a production-ready vendor-neutral OCI image registry - images stored in [OCI image format](https://github.com/opencontainers/image-spec), [distribution specification](https://github.com/opencontainers/distribution-spec) on-the-wire, that's it! https://zotregistry.io -[```docker pull ghcr.io/project-zot/zot:latest```](https://github.com/project-zot/zot/pkgs/container/zot) +[```docker pull ghcr.io/project-zot/zot-linux-amd64:latest```](https://github.com/project-zot/zot/pkgs/container/zot) -[```docker run -p 5000:5000 ghcr.io/project-zot/zot:latest```](https://github.com/project-zot/zot/pkgs/container/zot) +[```docker run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64:latest```](https://github.com/project-zot/zot/pkgs/container/zot) -[**Why zot?**](COMPARISON.md) +**Check the [package repository](https://github.com/orgs/project-zot/packages?repo_name=zot) for your os/arch** + +## [**Why zot?**](COMPARISON.md) + +## What's new? +* Supports container image signatures - [cosign](https://github.com/sigstore/cosign) and [notation](https://github.com/notaryproject/notation) +* Multi-arch support # Features * Conforms to [OCI distribution spec](https://github.com/opencontainers/distribution-spec) APIs * Clear separation between core dist-spec and zot-specific extensions * ```make binary-minimal``` builds a dist-spec-only zot * ```make binary``` builds a zot with all extensions enabled + + **Check [released binaries](https://github.com/project-zot/zot/releases) for your os/arch** + * 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 container image signatures - [cosign](https://github.com/sigstore/cosign) and [notation](https://github.com/notaryproject/notation) * Supports [helm charts](https://helm.sh/docs/topics/registries/) * Behavior controlled via [configuration](./examples/README.md) -* Supports `amd64` (Intel, AMD, etc) and `arm64` (ARM servers, Raspberry PI 4, etc) architectures +* Supports multi-arch + | OS | Arch | Use Case | + | --- | --- | --- | + | linux | amd64 | Intel-based Linux platforms | + | linux | arm64 | ARM servers and Raspberry PI4 | + | darwin | amd64 | Intel-based Macs | + | darwin | arm64 | ARM-based Macs | * 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) * [Vulnerability scanning of images](#Scanning-images-for-known-vulnerabilities) -* [Command-line client support](#cli) * TLS support * Authentication via: * TLS mutual authentication @@ -41,10 +54,12 @@ https://zotregistry.io * Serve [multiple storage paths (and backends)](./examples/config-multiple.json) using a single zot server * Pull and synchronize from other dist-spec conformant registries [sync](#sync) * Supports ratelimiting including per HTTP method +* [Metrics](#metrics) with Prometheus * Swagger based documentation * Single binary for _all_ the above features +* [zli](https://github.com/project-zot/zot/tree/main/cmd/zli): [command-line client support](#cli) +* Also, [zb](https://github.com/project-zot/zot/tree/main/cmd/zb): [a benchmarking tool](#benchmarking) for dist-spec conformant registries * Released under Apache 2.0 License -* [Metrics](#metrics) with Prometheus * Using a node exporter in case of dist-spec-only zot * ```go get -u github.com/project-zot/zot/cmd/zot``` @@ -126,19 +141,27 @@ podman run --rm -p 8080:8080 \ # CLI -The same zot binary can be used for interacting with any zot server instances. +## Building `zli` + +You can interact with the zot registry server using the `zli` binary. + +```console +$ make cli +``` + +will produce `bin/zli` binary. ## Adding a zot server URL To add a zot server URL with an alias "remote-zot": ```console -$ zot config add remote-zot https://server-example:8080 +$ zli config add remote-zot https://server-example:8080 ``` List all configured URLs with their aliases: ```console -$ zot config -l +$ zli config -l remote-zot https://server-example:8080 local http://localhost:8080 ``` @@ -147,7 +170,7 @@ local http://localhost:8080 You can list all images from a server by using its alias specified [in this step](#adding-a-zot-server-url): ```console -$ zot images remote-zot +$ zli images remote-zot IMAGE NAME TAG DIGEST SIZE postgres 9.6.18-alpine ef27f3e1 14.4MB postgres 9.5-alpine 264450a7 14.4MB @@ -157,7 +180,7 @@ busybox latest 414aeb86 707.8KB Or filter the list by an image name: ```console -$ zot images remote-zot -n busybox +$ zli images remote-zot -n busybox IMAGE NAME TAG DIGEST SIZE busybox latest 414aeb86 707.8KB ``` @@ -168,7 +191,7 @@ You can fetch CVE (Common Vulnerabilities and Exposures) info for images hosted - Get all images affected by a CVE ```console -$ zot cve remote-zot -i CVE-2017-9935 +$ zli cve remote-zot -i CVE-2017-9935 IMAGE NAME TAG DIGEST SIZE c3/openjdk-dev commit-5be4d92 ac3762e2 335MB ``` @@ -176,7 +199,7 @@ c3/openjdk-dev commit-5be4d92 ac3762e2 335MB - Get all CVEs for an image ```console -$ zot cve remote-zot -I c3/openjdk-dev:0.3.19 +$ zli cve remote-zot -I c3/openjdk-dev:0.3.19 ID SEVERITY TITLE CVE-2015-8540 LOW libpng: underflow read in png_check_keyword() CVE-2017-16826 LOW binutils: Invalid memory access in the coff_s... @@ -185,7 +208,7 @@ CVE-2017-16826 LOW binutils: Invalid memory access in the coff_s... - Get detailed json output ```console -$ zot cve remote-zot -I c3/openjdk-dev:0.3.19 -o json +$ zli cve remote-zot -I c3/openjdk-dev:0.3.19 -o json { "Tag": "0.3.19", "CVEList": [ @@ -217,7 +240,7 @@ $ zot cve remote-zot -I c3/openjdk-dev:0.3.19 -o json - Get all images in a specific repo affected by a CVE ```console -$ zot cve remote-zot -I c3/openjdk-dev -i CVE-2017-9935 +$ zli cve remote-zot -I c3/openjdk-dev -i CVE-2017-9935 IMAGE NAME TAG DIGEST SIZE c3/openjdk-dev commit-2674e8a 71046748 338MB c3/openjdk-dev commit-bd5cc94 0ab7fc76 @@ -226,13 +249,13 @@ c3/openjdk-dev commit-bd5cc94 0ab7fc76 - Get all images of a specific repo where a CVE is fixed ```console -$ zot cve remote-zot -I c3/openjdk-dev -i CVE-2017-9935 --fixed +$ zli cve remote-zot -I c3/openjdk-dev -i CVE-2017-9935 --fixed IMAGE NAME TAG DIGEST SIZE c3/openjdk-dev commit-2674e8a-squashfs b545b8ba 321MB c3/openjdk-dev commit-d5024ec-squashfs cd45f8cf 321MB ``` -# Sync +# Sync (pull-based mirroring) Periodically pull and synchronize images between zot registries. The synchronization is achieved by copying all the images found at source to destination. To use it see [sync-config](examples/config-sync.json) @@ -242,6 +265,65 @@ Supports: - Tags regex filtering - Tags semver compliance filtering (the 'v' prefix is optional) - BASIC auth + - Image signatures + +# Benchmarking + +You can benchmark a zot registry or any other dist-spec conformant registry with `zb`. + +## Building `zb`` + +```console +$ make bench +``` + +will produce `bin/zb` binary. + +## Running `zb` + +```console +$ zb -c 10 -n 1000 http://localhost:8080 + +Registry URL: http://localhost:8080 + +Concurrency Level: 2 +Total requests: 100 +Working dir: + +============ +Test name: Get Catalog +Time taken for tests: 45.397205ms +Complete requests: 100 +Failed requests: 0 +Requests per second: 2202.7788 + +2xx responses: 100 + +min: 402.259µs +max: 3.295887ms +p50: 855.045µs +p75: 971.709µs +p90: 1.127389ms +p99: 3.295887ms + +============ +Test name: Push Monolith 1MB +Time taken for tests: 952.336383ms +Complete requests: 100 +Failed requests: 0 +Requests per second: 105.00491 + +2xx responses: 100 + +min: 11.125673ms +max: 26.375356ms +p50: 18.917253ms +p75: 21.753441ms +p90: 24.02137ms +p99: 26.375356ms + +... +``` # Ecosystem @@ -286,11 +368,6 @@ bin/zxp config _config-file_ ## Enable Metrics In the zot with all extensions case see [configuration example](./examples/config-metrics.json) for enabling metrics -# Caveats - -* go 1.15+ -* The OCI distribution spec is still WIP, and we try to keep up - # Contributing We encourage and support an active, healthy community of contributors. diff --git a/examples/config-minimal.json b/examples/config-minimal.json index 795e1698..5b6bc60d 100644 --- a/examples/config-minimal.json +++ b/examples/config-minimal.json @@ -9,7 +9,6 @@ "ReadOnly": false }, "log": { - "level": "debug", - "output": "/tmp/zot.log" + "level": "debug" } }