Configuring zot¶
The registry administrator configures zot primarily through settings in the configuration file.
Using the information in this guide, you can compose a configuration file with the settings and features you require for your zot registry server.
Before launching zot with a new configuration, we recommend that you verify the syntax of your configuration as described in Verifying the configuration file.
Configuration file¶
The configuration file is a JSON or YAML file that contains all configuration settings for zot functions such as:
- network
- storage
- authentication
- authorization
- logging
- metrics
- synchronization with other registries
- clustering
The zot service is initiated with the zot serve command followed by the name of a configuration file, as in this example:
zot serve config.json
The instructions and examples in this guide use
zotas the name of the zot executable file. The examples do not include the path to the executable file.
When you first build zot or deploy an image or container from the distribution, a basic configuration file config.json is created. This initial file is similar to the following example:
{
+ Configuring zot - zotregistry.dev Configuring zot¶
The registry administrator configures zot primarily through settings in the configuration file.
Using the information in this guide, you can compose a configuration file with the settings and features you require for your zot registry server.
Before launching zot with a new configuration, we recommend that you verify the syntax of your configuration as described in Verifying the configuration file.
Configuration file¶
The configuration file is a JSON or YAML file that contains all configuration settings for zot functions such as:
- network
- storage
- authentication
- authorization
- logging
- metrics
- synchronization with other registries
- clustering
The zot service is initiated with the zot serve command followed by the name of a configuration file, as in this example:
zot serve config.json
The instructions and examples in this guide use zot as the name of the zot executable file. The examples do not include the path to the executable file.
When you first build zot or deploy an image or container from the distribution, a basic configuration file config.json is created. This initial file is similar to the following example:
{
"distSpecVersion": "1.0.1",
"storage": {
"rootDirectory": "/tmp/zot"
diff --git a/v2.1.0/admin-guide/admin-getting-started/index.html b/v2.1.0/admin-guide/admin-getting-started/index.html
index b80a233..e6699b4 100644
--- a/v2.1.0/admin-guide/admin-getting-started/index.html
+++ b/v2.1.0/admin-guide/admin-getting-started/index.html
@@ -1,4 +1,4 @@
- Getting Started - zotregistry.dev Getting Started with zot Administration¶
This document helps you to deploy an appropriate zot image or to build zot if desired.
After deploying zot, proceed to Configuring zot to choose and configure the features you need.
Installing zot¶
How to get zot¶
The zot project is hosted on GitHub at project-zot. From GitHub, you can download zot executable binary images or full source code.
Supported platforms¶
zot is officially supported on Linux and Apple MacOS platforms, using Intel or ARM processors. However, development should be possible on any platform that supports the golang toolchain.
OS ARCH Platform linux amd64 Intel-based Linux servers linux arm64 ARM-based servers and Raspberry Pi4 darwin amd64 Intel-based MacOS darwin arm64 ARM-based MacOS freebsd amd64 Intel-based FreeBSD* freebsd arm64 ARM-based FreeBSD*
* NOTE: While binary images are available for FreeBSD, building container images is not supported at this time.
About binary images¶
Executable binary zot images are available for multiple platforms and architectures and with full or minimal implementations.
Refer to Released Images for zot for information about available zot images along with information about image variations, image locations, and image naming formats.
Deployment methods¶
Several options exist for deploying zot:
-
You can launch a zot binary as a container service using a container management tool such as Podman, Docker, or Helm.
-
You can launch zot as a host-level service by downloading a binary image and running it as a systemd service.
-
You can copy or clone the full zot source code and build an image with custom build flags.
Deploying a zot binary image¶
Executable binary images for supported server platforms and architectures are available from the zot package repository in GitHub.
You can download the appropriate binary image and run it directly on your server, or you can use a container management tool such as Podman, runc, Helm, or Docker to fetch and deploy the image in a container on your server.
For convenience, you can rename the binary image file to simply zot.
Example: Deploying with a container manager¶
Using a container manager such as Podman, runc, Helm, or Docker, you can install a zot binary image, as in the following examples.
Using podman
podman run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64:latest
+ Getting Started - zotregistry.dev Getting Started with zot Administration¶
This document helps you to deploy an appropriate zot image or to build zot if desired.
After deploying zot, proceed to Configuring zot to choose and configure the features you need.
Installing zot¶
How to get zot¶
The zot project is hosted on GitHub at project-zot. From GitHub, you can download zot executable binary images or full source code.
Supported platforms¶
zot is officially supported on Linux and Apple MacOS platforms, using Intel or ARM processors. However, development should be possible on any platform that supports the golang toolchain.
OS ARCH Platform linux amd64 Intel-based Linux servers linux arm64 ARM-based servers and Raspberry Pi4 darwin amd64 Intel-based MacOS darwin arm64 ARM-based MacOS freebsd amd64 Intel-based FreeBSD* freebsd arm64 ARM-based FreeBSD*
* NOTE: While binary images are available for FreeBSD, building container images is not supported at this time.
About binary images¶
Executable binary zot images are available for multiple platforms and architectures and with full or minimal implementations.
Refer to Released Images for zot for information about available zot images along with information about image variations, image locations, and image naming formats.
Deployment methods¶
Several options exist for deploying zot:
-
You can launch a zot binary as a container service using a container management tool such as Podman, Docker, or Helm.
-
You can launch zot as a host-level service by downloading a binary image and running it as a systemd service.
-
You can copy or clone the full zot source code and build an image with custom build flags.
Deploying a zot binary image¶
Executable binary images for supported server platforms and architectures are available from the zot package repository in GitHub.
You can download the appropriate binary image and run it directly on your server, or you can use a container management tool such as Podman, runc, Helm, or Docker to fetch and deploy the image in a container on your server.
For convenience, you can rename the binary image file to simply zot.
Example: Deploying with a container manager¶
Using a container manager such as Podman, runc, Helm, or Docker, you can install a zot binary image, as in the following examples.
Using podman
podman run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64:latest
podman run -p 5000:5000 ghcr.io/project-zot/zot-minimal-linux-amd64:latest
Click here to view an example of deploying using podman.
Using docker
docker run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64:latest
diff --git a/v2.1.0/articles/authn-authz/index.html b/v2.1.0/articles/authn-authz/index.html
index da4216f..d1eefeb 100644
--- a/v2.1.0/articles/authn-authz/index.html
+++ b/v2.1.0/articles/authn-authz/index.html
@@ -1,4 +1,4 @@
- Authentication and Authorization - zotregistry.dev User Authentication and Authorization with zot¶
A robust set of authentication/authorization options are supported:
-
Authentication
- TLS, including mTLS
- Username/password or token-based user authentication
- LDAP
- htpasswd
- OAuth2 with bearer token
-
Authorization
- Powerful identity-based access controls for repositories or specific repository paths
- OpenID/OAuth2 social login with Google, GitHub, GitLab, and dex
The zot configuration model supports both authentication and authorization. Authentication credentials allow access to zot HTTP APIs. Authorization policies provide fine-grained control of the actions each authenticated user can perform in the registry.
Authentication¶
TLS authentication¶
Because authentication credentials are passed over HTTP, it is imperative that TLS be enabled. You can enable and configure TLS authentication in the zot configuration file, as shown in the following example.
"http": {
+ Authentication and Authorization - zotregistry.dev User Authentication and Authorization with zot¶
A robust set of authentication/authorization options are supported:
-
Authentication
- TLS, including mTLS
- Username/password or token-based user authentication
- LDAP
- htpasswd
- OAuth2 with bearer token
-
Authorization
- Powerful identity-based access controls for repositories or specific repository paths
- OpenID/OAuth2 social login with Google, GitHub, GitLab, and dex
The zot configuration model supports both authentication and authorization. Authentication credentials allow access to zot HTTP APIs. Authorization policies provide fine-grained control of the actions each authenticated user can perform in the registry.
Authentication¶
TLS authentication¶
Because authentication credentials are passed over HTTP, it is imperative that TLS be enabled. You can enable and configure TLS authentication in the zot configuration file, as shown in the following example.
"http": {
...
"tls": {
"cert": "/etc/zot/certs/server.cert",
diff --git a/v2.1.0/articles/benchmarking-with-zb/index.html b/v2.1.0/articles/benchmarking-with-zb/index.html
index 4ad8b31..53b3cc5 100644
--- a/v2.1.0/articles/benchmarking-with-zb/index.html
+++ b/v2.1.0/articles/benchmarking-with-zb/index.html
@@ -1,4 +1,4 @@
- Benchmarking with zb - zotregistry.dev Benchmarking zot with zb¶
The zb tool is useful for benchmarking OCI registry workloads in scenarios such as the following:
- comparing configuration changes
- comparing software versions
- comparing hardware/deployment environments
- comparing with other registries
With the zb tool, you can benchmark a zot registry or any other container image registry that conforms to the OCI Distribution Specification published by the Open Container Initiative (OCI).
We recommend installing and benchmarking with zb when you install zot.
How to get zb¶
The zb project is hosted with zot on GitHub at project-zot. From GitHub, you can download the zb binary or you can build zb from the source. You can also directly run the released docker image.
Supported platforms and architectures¶
zb is supported for the following operating systems and platform architectures:
OS ARCH Platform linux amd64 Intel-based Linux servers linux arm64 ARM-based servers and Raspberry Pi4 darwin amd64 Intel-based MacOS darwin arm64 ARM-based MacOS
Downloading zb binaries¶
Download the executable binary for your server platform and architecture under "Assets" on the GitHub zot releases page.
The binary image is named using the target platform and architecture from the Supported platforms and architectures table. For example, the binary for an Intel-based MacOS server is zb-darwin-amd64.
Building zb from source¶
To build the zb binary, copy or clone the zot project from GitHub and execute the make bench command in the zot directory. Use the same command options that you used to build zot, as shown:
make OS=os ARCH=architecture bench
For example, the following command builds zb for an Intel-based MacOS server:
make OS=darwin ARCH=amd64 bench
In this example, the resulting executable file is zb-darwin-amd64 in the zot/bin directory.
A sample Dockerfile for zb is available at Dockerfile-zb.
Running zb¶
The original filename of the executable file will reflect the build options, such as zb-linux-amd64. For convenience, you can rename the executable to simply zb.
The instructions and examples in this guide use zb as the name of the executable file.
Usage¶
To view the usage and options of zb, run the command with the --help option:
bin/zb --help
Command output:
Usage:
+ Benchmarking with zb - zotregistry.dev Benchmarking zot with zb¶
The zb tool is useful for benchmarking OCI registry workloads in scenarios such as the following:
- comparing configuration changes
- comparing software versions
- comparing hardware/deployment environments
- comparing with other registries
With the zb tool, you can benchmark a zot registry or any other container image registry that conforms to the OCI Distribution Specification published by the Open Container Initiative (OCI).
We recommend installing and benchmarking with zb when you install zot.
How to get zb¶
The zb project is hosted with zot on GitHub at project-zot. From GitHub, you can download the zb binary or you can build zb from the source. You can also directly run the released docker image.
Supported platforms and architectures¶
zb is supported for the following operating systems and platform architectures:
OS ARCH Platform linux amd64 Intel-based Linux servers linux arm64 ARM-based servers and Raspberry Pi4 darwin amd64 Intel-based MacOS darwin arm64 ARM-based MacOS
Downloading zb binaries¶
Download the executable binary for your server platform and architecture under "Assets" on the GitHub zot releases page.
The binary image is named using the target platform and architecture from the Supported platforms and architectures table. For example, the binary for an Intel-based MacOS server is zb-darwin-amd64.
Building zb from source¶
To build the zb binary, copy or clone the zot project from GitHub and execute the make bench command in the zot directory. Use the same command options that you used to build zot, as shown:
make OS=os ARCH=architecture bench
For example, the following command builds zb for an Intel-based MacOS server:
make OS=darwin ARCH=amd64 bench
In this example, the resulting executable file is zb-darwin-amd64 in the zot/bin directory.
A sample Dockerfile for zb is available at Dockerfile-zb.
Running zb¶
The original filename of the executable file will reflect the build options, such as zb-linux-amd64. For convenience, you can rename the executable to simply zb.
The instructions and examples in this guide use zb as the name of the executable file.
Usage¶
To view the usage and options of zb, run the command with the --help option:
bin/zb --help
Command output:
Usage:
zb <url> [flags]
Flags:
diff --git a/v2.1.0/articles/building-ci-cd-pipeline/index.html b/v2.1.0/articles/building-ci-cd-pipeline/index.html
index d1bf9df..386ee24 100644
--- a/v2.1.0/articles/building-ci-cd-pipeline/index.html
+++ b/v2.1.0/articles/building-ci-cd-pipeline/index.html
@@ -1,4 +1,4 @@
- CI/CD Pipeline - zotregistry.dev Building an OCI-native Container Image CI/CD Pipeline¶
An OCI-native secure container image build/delivery pipeline using the following tools:
The Open Container Initiative (OCI) is an open governance structure for the express purpose of creating open industry standards around container formats and runtimes.
This document describes a step-by-step procedure towards achieving an OCI-native secure software supply chain using zot in collaboration with other open source tools. The following diagram shows a portion of the CI/CD pipeline.
Build images¶
stacker is a standalone tool for building OCI images via a declarative yaml format. The output of the build process is a container image in an OCI layout.
example: stacker build command
stacker build -f <stackerfile.yaml>
+ CI/CD Pipeline - zotregistry.dev Building an OCI-native Container Image CI/CD Pipeline¶
An OCI-native secure container image build/delivery pipeline using the following tools:
The Open Container Initiative (OCI) is an open governance structure for the express purpose of creating open industry standards around container formats and runtimes.
This document describes a step-by-step procedure towards achieving an OCI-native secure software supply chain using zot in collaboration with other open source tools. The following diagram shows a portion of the CI/CD pipeline.
Build images¶
stacker is a standalone tool for building OCI images via a declarative yaml format. The output of the build process is a container image in an OCI layout.
example: stacker build command
stacker build -f <stackerfile.yaml>
Image registry¶
zot is a production-ready vendor-neutral OCI image registry server purely based on the OCI Distribution Specification. If stacker is used to build the OCI image, it can also be used to publish the built image to an OCI registry.
example: stacker publish command
stacker publish --url <url> --username <user> --password <password>
Alternatively, you can use skopeo, a command line utility that performs various operations on container images and image repositories.
example: skopeo copies an image to a registry
skopeo copy --format=oci oci:<oci-dir>/image:tag \
docker://<zot-server>/image:tag
diff --git a/v2.1.0/articles/clustering/index.html b/v2.1.0/articles/clustering/index.html
index 93f199f..656b0d0 100644
--- a/v2.1.0/articles/clustering/index.html
+++ b/v2.1.0/articles/clustering/index.html
@@ -1,4 +1,4 @@
- Clustering - zotregistry.dev zot Clustering¶
High availability of the zot registry is supported by the following features:
- Stateless zot instances to simplify scale out
- Shared remote storage
- Bare-metal and Kubernetes deployments
To ensure high availability of the registry, zot supports a clustering scheme with stateless zot instances/replicas fronted by a load balancer and a shared remote backend storage. This scheme allows the registry service to remain available even if a few replicas fail or become unavailable. Load balancing across many zot replicas can also increase aggregate network throughput.
Beginning with zot release v2.1.0, you can design a highly scalable cluster that does not require configuring the load balancer to direct repository queries to specific zot instances within the cluster. See Scale-out clustering. Scale-out clustering is the preferred method if you are running v2.1.0 or later.
Clustering is supported in both bare-metal and Kubernetes environments.
The remote backend storage must be S3 API-compatible.
Bare-metal deployment¶
Prerequisites¶
-
A highly-available load balancer such as HAProxy configured to direct traffic to zot replicas
-
Multiple zot replicas as systemd services hosted on multiple hosts or VMs
-
AWS S3 API-compatible remote backend storage
Kubernetes deployment¶
Prerequisites¶
-
A zot Kubernetes Deployment with required number of replicas
-
AWS S3 API-compatible remote backend storage.
-
A zot Kubernetes Service
-
A zot Kubernetes Ingress Gateway if the service needs to be exposed outside
Implementing stateless zot¶
zot maintains two types of durable state:
-
the actual image data itself
-
the image metadata in the registry’s cache
In a stateless clustering scheme, the image data is stored in the remote storage backend and the registry cache is disabled by turning off deduplication.
Ecosystem tools¶
The OCI Distribution Specification imposes certain rules about the HTTP URI paths to which various ecosystem tools must conform. Consider these rules when setting the HTTP prefixes during load balancing and ingress gateway configuration.
Examples¶
Clustering is supported by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load balancing traffic to the replicas. Each replica is responsible for one or more repositories.
HAProxy configuration¶
Click here to view a sample HAProxy configuration.
global
+ Clustering - zotregistry.dev zot Clustering¶
High availability of the zot registry is supported by the following features:
- Stateless zot instances to simplify scale out
- Shared remote storage
- Bare-metal and Kubernetes deployments
To ensure high availability of the registry, zot supports a clustering scheme with stateless zot instances/replicas fronted by a load balancer and a shared remote backend storage. This scheme allows the registry service to remain available even if a few replicas fail or become unavailable. Load balancing across many zot replicas can also increase aggregate network throughput.
Beginning with zot release v2.1.0, you can design a highly scalable cluster that does not require configuring the load balancer to direct repository queries to specific zot instances within the cluster. See Scale-out clustering. Scale-out clustering is the preferred method if you are running v2.1.0 or later.
Clustering is supported in both bare-metal and Kubernetes environments.
The remote backend storage must be S3 API-compatible.
Bare-metal deployment¶
Prerequisites¶
-
A highly-available load balancer such as HAProxy configured to direct traffic to zot replicas
-
Multiple zot replicas as systemd services hosted on multiple hosts or VMs
-
AWS S3 API-compatible remote backend storage
Kubernetes deployment¶
Prerequisites¶
-
A zot Kubernetes Deployment with required number of replicas
-
AWS S3 API-compatible remote backend storage.
-
A zot Kubernetes Service
-
A zot Kubernetes Ingress Gateway if the service needs to be exposed outside
Implementing stateless zot¶
zot maintains two types of durable state:
-
the actual image data itself
-
the image metadata in the registry’s cache
In a stateless clustering scheme, the image data is stored in the remote storage backend and the registry cache is disabled by turning off deduplication.
Ecosystem tools¶
The OCI Distribution Specification imposes certain rules about the HTTP URI paths to which various ecosystem tools must conform. Consider these rules when setting the HTTP prefixes during load balancing and ingress gateway configuration.
Examples¶
Clustering is supported by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load balancing traffic to the replicas. Each replica is responsible for one or more repositories.
HAProxy configuration¶
Click here to view a sample HAProxy configuration.
global
log /dev/log local0
log /dev/log local1 notice
chroot /var/lib/haproxy
diff --git a/v2.1.0/articles/graphql/index.html b/v2.1.0/articles/graphql/index.html
index bc3d479..e3acb62 100644
--- a/v2.1.0/articles/graphql/index.html
+++ b/v2.1.0/articles/graphql/index.html
@@ -1,4 +1,4 @@
- Using GraphQL for Enhanced Searches - zotregistry.dev Using GraphQL for Enhanced Searches¶
A GraphQL backend server within zot's registry search engine provides efficient and enhanced search capabilities. You can submit a GraphQL structured query as an API call or you can use a browser to access the GraphQL Playground, an interactive graphical environment for GraphQL queries.
How to use GraphQL for search queries¶
GraphQL is a query language for APIs. A GraphQL server, as implemented in zot's registry search engine, executes GraphQL queries that match schema recognized by the server. In response, the server returns a structure containing the requested information. The schema currently recognized by zot are those that correspond to the queries listed in What GraphQL queries are supported.
To learn more about GraphQL, see these resources:
To perform a search, compose a GraphQL structured query for a specific search and deliver it to zot using one of the methods described in the following sections.
For examples of GraphQL queries supported in zot, see Examples of zot searches using GraphQL.
Using the search API directly¶
You can submit a GraphQL structured query as the HTML data payload in a direct API call using a shell tool such as cURL or Postman. GraphQL queries are sent to the zot search extension API:
/v2/_zot/ext/search
+ Using GraphQL for Enhanced Searches - zotregistry.dev Using GraphQL for Enhanced Searches¶
A GraphQL backend server within zot's registry search engine provides efficient and enhanced search capabilities. You can submit a GraphQL structured query as an API call or you can use a browser to access the GraphQL Playground, an interactive graphical environment for GraphQL queries.
How to use GraphQL for search queries¶
GraphQL is a query language for APIs. A GraphQL server, as implemented in zot's registry search engine, executes GraphQL queries that match schema recognized by the server. In response, the server returns a structure containing the requested information. The schema currently recognized by zot are those that correspond to the queries listed in What GraphQL queries are supported.
To learn more about GraphQL, see these resources:
To perform a search, compose a GraphQL structured query for a specific search and deliver it to zot using one of the methods described in the following sections.
For examples of GraphQL queries supported in zot, see Examples of zot searches using GraphQL.
Using the search API directly¶
You can submit a GraphQL structured query as the HTML data payload in a direct API call using a shell tool such as cURL or Postman. GraphQL queries are sent to the zot search extension API:
/v2/_zot/ext/search
The following example submits a zot GraphQL query using cURL:
curl -X POST -H "Content-Type: application/json" --data '{ "query": "{ ImageListForCVE (id:\"CVE-2002-1119\") { Results { Name Tags } } }" }' http://localhost:8080/v2/_zot/ext/search
The reply to your query is returned as a JSON payload in the HTML response.
Using the GraphQL Playground¶
The GraphQL Playground feature is available only in a binary-debug zot build or when the zot registry was built with the debug extension label.
The GraphQL Playground is an interactive graphical web interface for GraphQL hosted by the zot registry server.
The GraphQL Playground is reachable by a browser at the following zot API:
/v2/_zot/debug/graphql-playground#
For example, if your zot server is located at http://localhost:8080, the GraphQL Playground can be accessed by your browser at this URL:
http://localhost:8080/v2/_zot/debug/graphql-playground#
diff --git a/v2.1.0/articles/high-availability/index.html b/v2.1.0/articles/high-availability/index.html
new file mode 100644
index 0000000..189f7f8
--- /dev/null
+++ b/v2.1.0/articles/high-availability/index.html
@@ -0,0 +1 @@
+ Deploying a Highly Available Registry - zotregistry.dev Deploying a Highly Available zot Registry¶
A highly available zot registry can be easily implemented using zot's registry synchronization feature.
In the zot configuration, the sync extension allows a zot instance to mirror another zot instance with various container image download policies, including on-demand and periodic downloads. You can use the zot sync function combined with a load balancer such as HAProxy to implement a highly available registry.
Two failover configurations are possible:
-
Active/standby
Registry requests are sent by the load balancer to the active zot instance, while a standby instance mirrors the active. If the load balancer detects a failure of the active instance, it then sends requests to the standby instance.
-
Active/active
Registry requests are load-balanced between two zot instances, each of which mirrors the other.
The highly available zot registry described in this article differs from zot clustering. Although zot clustering provides a level of high availability, the instances share common storage, whose failure would affect all instances. In the method described in this article, each instance has its own storage, providing an additional level of safety.
For details of configuring the sync extension, see OCI Registry Mirroring With zot.
Configuring an active/standby registry¶
An active/standby zot registry can be implemented between two zot instances by configuring the sync extension in the standby instance to mirror the other instance. In this scheme:
- a load balancer such as HAProxy is deployed for active/passive load balancing of the zot instances
- each zot instance is configured as a standalone registry with its own storage
- the standby zot instance has its
sync extension enabled to periodically synchronize with (mirror) the active instance
With periodic synchronization, a window of failure exists between synchronization actions. For example, if an image is posted to the active instance soon after the standby has synchronized with the active, and then the active fails, the standby will not have the new image. To minimize this exposure, we recommend keeping the synchronization period as small as practical.
Configuring an active/active registry¶
An active/active zot registry can be implemented between two zot instances by configuring the sync extension in each instance to point to the other instance. In this scheme:
- a load balancer such as HAProxy or a DNS-based routing scheme is deployed for load balancing between zot instances
- path-based routing must be implemented
- each zot instance is configured as a standalone registry with its own storage
- each zot instance has its
sync extension enabled to periodically synchronize with the other instance
With periodic synchronization, a window of failure exists between synchronization actions. For example, if an image is posted to instance A soon after instance B has synchronized with instance A, and then instance A fails, instance B will not have the new image. To minimize this exposure, we recommend keeping the synchronization period as small as practical.
Last update: June 24, 2024 Back to top
\ No newline at end of file
diff --git a/v2.1.0/articles/immutable-tags/index.html b/v2.1.0/articles/immutable-tags/index.html
index 05f16f9..83df18b 100644
--- a/v2.1.0/articles/immutable-tags/index.html
+++ b/v2.1.0/articles/immutable-tags/index.html
@@ -1,4 +1,4 @@
- Immutable Tags - zotregistry.dev Immutable Image Tags¶
Immutable image tag support is achieved by leveraging authorization policies.
It is considered best practice to avoid changing the content once a software version has been released. While zot does not have an explicit configuration flag to make image tags immutable, the same effect can be achieved with authorization as follows.
Immutable For All Users¶
By setting the defaultPolicy to "read" and "create" for a particular repository, images can be pushed (once) and pulled but further updates are rejected.
{
+ Immutable Tags - zotregistry.dev Immutable Image Tags¶
Immutable image tag support is achieved by leveraging authorization policies.
It is considered best practice to avoid changing the content once a software version has been released. While zot does not have an explicit configuration flag to make image tags immutable, the same effect can be achieved with authorization as follows.
Immutable For All Users¶
By setting the defaultPolicy to "read" and "create" for a particular repository, images can be pushed (once) and pulled but further updates are rejected.
{
...
"repositories": {
"**": {
diff --git a/v2.1.0/articles/kind-deploy/index.html b/v2.1.0/articles/kind-deploy/index.html
index 2db5c1d..d6e4461 100644
--- a/v2.1.0/articles/kind-deploy/index.html
+++ b/v2.1.0/articles/kind-deploy/index.html
@@ -1,4 +1,4 @@
- Using kind for Deployment Testing - zotregistry.dev Using kind for Deployment Testing¶
Use kind to try out zot deployment with Kubernetes.
This article describes how to create a kind cluster that includes a local zot registry.
Deploying the cluster and registry¶
The procedure described installs a kind cluster with a zot registry at localhost:5001 and then loads and runs a "hello" app to test the installation. Although the procedure is given as a series of steps, you can find a complete shell script to perform these steps at the end of this article.
This article is based on Create A Cluster And Registry, which you can find on the kind website.
Step 1: Prepare the environment¶
The following packages must be installed:
dockerkuberneteskindcontainerdskopeo
Execute the following shell commands to set environment variables.
set -o errexit
+ Using kind for Deployment Testing - zotregistry.dev Using kind for Deployment Testing¶
Use kind to try out zot deployment with Kubernetes.
This article describes how to create a kind cluster that includes a local zot registry.
Deploying the cluster and registry¶
The procedure described installs a kind cluster with a zot registry at localhost:5001 and then loads and runs a "hello" app to test the installation. Although the procedure is given as a series of steps, you can find a complete shell script to perform these steps at the end of this article.
This article is based on Create A Cluster And Registry, which you can find on the kind website.
Step 1: Prepare the environment¶
The following packages must be installed:
dockerkuberneteskindcontainerdskopeo
Execute the following shell commands to set environment variables.
set -o errexit
# set no_proxy if applicable
if [ ! -z "${no_proxy}" ]; then
diff --git a/v2.1.0/articles/mirroring/index.html b/v2.1.0/articles/mirroring/index.html
index 39c6de1..83de121 100644
--- a/v2.1.0/articles/mirroring/index.html
+++ b/v2.1.0/articles/mirroring/index.html
@@ -1,4 +1,4 @@
- Mirroring - zotregistry.dev OCI Registry Mirroring With zot¶
A zot registry can mirror one or more upstream OCI registries, including popular cloud registries such as Docker Hub and Google Container Registry (gcr.io).
A key use case for zot is to act as a mirror for upstream registries. If an upstream registry is OCI distribution-spec conformant for pulling images, you can use zot's sync feature to implement a downstream mirror, synchronizing OCI images and corresponding artifacts. Because synchronized images are stored in zot's local storage, registry mirroring allows for a fully distributed disconnected container image build pipeline. Container image operations terminate in local zot storage, which may reduce network latency and costs.
Because zot is a OCI-only registry, any upstream image stored in the Docker image format is converted to OCI format when downloading to zot. In the conversion, some non-OCI attributes may be lost. Signatures, for example, are removed due to the incompatibility between formats.
Mirroring modes¶
For mirroring an upstream registry, two common use cases are a fully mirrored or a pull through (on-demand) cache registry.
As with git, wherein every clone is a full repository, you can configure your local zot instance to be a fully mirrored OCI registry. For this mode, configure zot for synchronization by periodic polling, not on-demand. Zot copies and caches a full copy of every image on the upstream registry, updating the cache whenever polling discovers a change in content or image version at the upstream registry.
For a pull through cache mirrored registry, configure zot for on-demand synchronization. When an image is first requested from the local zot registry, the image is downloaded from the upstream registry and cached in local storage. Subsequent requests for the same image are served from zot's cache. Images that have not been requested are not downloaded. If a polling interval is also configured, zot periodically polls the upstream registry for changes, updating any cached images if changes are detected.
Because Docker Hub rate-limits pulls and does not support catalog listing, do not use polled mirroring with Docker Hub. Use only on-demand mirroring with Docker Hub.
Migrating or updating a registry using mirroring¶
Mirroring zot using the sync feature allows you to easily migrate a registry. In situations such as the following, zot mirroring provides an easy solution.
-
Migrating an existing zot or non-zot registry to a new location.
Provided that the source registry is OCI-compliant for image pulls, you can mirror the registry to a new zot registry, delete the old registry, and reroute network traffic to the new registry.
-
Updating (or downgrading) a zot registry.
To minimize downtime during an update, or to avoid any incompatibilities between zot releases that would preclude an in-place update, you can bring up a new zot registry with the desired release and then migrate from the existing registry.
To ensure a complete migration of the registry contents, set a polling interval in the configuration of the new zot registry and set prefix to **, as shown in this example:
{
+ Mirroring - zotregistry.dev OCI Registry Mirroring With zot¶
A zot registry can mirror one or more upstream OCI registries, including popular cloud registries such as Docker Hub and Google Container Registry (gcr.io).
A key use case for zot is to act as a mirror for upstream registries. If an upstream registry is OCI distribution-spec conformant for pulling images, you can use zot's sync feature to implement a downstream mirror, synchronizing OCI images and corresponding artifacts. Because synchronized images are stored in zot's local storage, registry mirroring allows for a fully distributed disconnected container image build pipeline. Container image operations terminate in local zot storage, which may reduce network latency and costs.
Because zot is a OCI-only registry, any upstream image stored in the Docker image format is converted to OCI format when downloading to zot. In the conversion, some non-OCI attributes may be lost. Signatures, for example, are removed due to the incompatibility between formats.
Mirroring modes¶
For mirroring an upstream registry, two common use cases are a fully mirrored or a pull through (on-demand) cache registry.
As with git, wherein every clone is a full repository, you can configure your local zot instance to be a fully mirrored OCI registry. For this mode, configure zot for synchronization by periodic polling, not on-demand. Zot copies and caches a full copy of every image on the upstream registry, updating the cache whenever polling discovers a change in content or image version at the upstream registry.
For a pull through cache mirrored registry, configure zot for on-demand synchronization. When an image is first requested from the local zot registry, the image is downloaded from the upstream registry and cached in local storage. Subsequent requests for the same image are served from zot's cache. Images that have not been requested are not downloaded. If a polling interval is also configured, zot periodically polls the upstream registry for changes, updating any cached images if changes are detected.
Because Docker Hub rate-limits pulls and does not support catalog listing, do not use polled mirroring with Docker Hub. Use only on-demand mirroring with Docker Hub.
Migrating or updating a registry using mirroring¶
Mirroring zot using the sync feature allows you to easily migrate a registry. In situations such as the following, zot mirroring provides an easy solution.
-
Migrating an existing zot or non-zot registry to a new location.
Provided that the source registry is OCI-compliant for image pulls, you can mirror the registry to a new zot registry, delete the old registry, and reroute network traffic to the new registry.
-
Updating (or downgrading) a zot registry.
To minimize downtime during an update, or to avoid any incompatibilities between zot releases that would preclude an in-place update, you can bring up a new zot registry with the desired release and then migrate from the existing registry.
To ensure a complete migration of the registry contents, set a polling interval in the configuration of the new zot registry and set prefix to **, as shown in this example:
{
"urls": [
"https://registry1:5000"
],
diff --git a/v2.1.0/articles/monitoring/index.html b/v2.1.0/articles/monitoring/index.html
index a0acc0b..ac60698 100644
--- a/v2.1.0/articles/monitoring/index.html
+++ b/v2.1.0/articles/monitoring/index.html
@@ -1,4 +1,4 @@
- Monitoring - zotregistry.dev Monitoring the registry¶
zot supports a range of monitoring tools including logging, metrics, and benchmarking.
The following sections describe how to configure logging and monitoring with zot. You can use zot's benchmarking tool to test your configuration and deployment, as described in Benchmarking zot with zb.
Logging¶
Logging for zot operations is configured with the log attribute in the configuration file, as shown in the following example.
"log":{
+ Monitoring - zotregistry.dev Monitoring the registry¶
zot supports a range of monitoring tools including logging, metrics, and benchmarking.
The following sections describe how to configure logging and monitoring with zot. You can use zot's benchmarking tool to test your configuration and deployment, as described in Benchmarking zot with zb.
Logging¶
Logging for zot operations is configured with the log attribute in the configuration file, as shown in the following example.
"log":{
"level":"debug",
"output":"/tmp/zot.log",
"audit": "/tmp/zot-audit.log"
diff --git a/v2.1.0/articles/pprofiling/index.html b/v2.1.0/articles/pprofiling/index.html
index a3994da..9f557c6 100644
--- a/v2.1.0/articles/pprofiling/index.html
+++ b/v2.1.0/articles/pprofiling/index.html
@@ -1,4 +1,4 @@
- Performance Profiling - zotregistry.dev Performance Profiling in zot¶
Use zot's built-in profiling tools to collect and analyze runtime performance.
The profiling capabilities within zot allow a zot administrator to collect and export a range of diagnostic performance data such as CPU intensive function calls, memory allocations, and execution traces. The collected data can then be analyzed using Go tools and a variety of available visualization tools.
If authentication is enabled, only a zot admin user can access the APIs for profiling.
All examples in this article assume that the zot registry is running at localhost:8080.
What data is available?¶
The zot source code incorporates golang's pprof package of runtime analysis tools to collect data for the following performance-related profiles:
Profile Description allocs A sampling of all past memory allocations. block Stack traces that led to blocking on synchronization primitives. cmdline The command line invocation of the current program. goroutine Stack traces of all current goroutines. Use debug=2 as a URL query parameter to export in the same format as an unrecovered panic. heap A sampling of memory allocations of live objects. You can specify the gc GET parameter to run GC before taking the heap sample. mutex Stack traces of holders of contended mutexes. profile CPU usage profile. You can specify the duration in the seconds URL query parameter. After receiving the profile file, use the go tool pprof command to investigate the profile. threadcreate Stack traces that led to the creation of new OS threads. trace A trace of execution of the current program. You can specify the duration in the seconds URL query parameter. After you get the trace file, use the go tool trace command to investigate the trace.
To return a current HTML-format profile list along with a count of currently available records for each profile, use the following API command:
/v2/_zot/pprof/
+ Performance Profiling - zotregistry.dev Performance Profiling in zot¶
Use zot's built-in profiling tools to collect and analyze runtime performance.
The profiling capabilities within zot allow a zot administrator to collect and export a range of diagnostic performance data such as CPU intensive function calls, memory allocations, and execution traces. The collected data can then be analyzed using Go tools and a variety of available visualization tools.
If authentication is enabled, only a zot admin user can access the APIs for profiling.
All examples in this article assume that the zot registry is running at localhost:8080.
What data is available?¶
The zot source code incorporates golang's pprof package of runtime analysis tools to collect data for the following performance-related profiles:
Profile Description allocs A sampling of all past memory allocations. block Stack traces that led to blocking on synchronization primitives. cmdline The command line invocation of the current program. goroutine Stack traces of all current goroutines. Use debug=2 as a URL query parameter to export in the same format as an unrecovered panic. heap A sampling of memory allocations of live objects. You can specify the gc GET parameter to run GC before taking the heap sample. mutex Stack traces of holders of contended mutexes. profile CPU usage profile. You can specify the duration in the seconds URL query parameter. After receiving the profile file, use the go tool pprof command to investigate the profile. threadcreate Stack traces that led to the creation of new OS threads. trace A trace of execution of the current program. You can specify the duration in the seconds URL query parameter. After you get the trace file, use the go tool trace command to investigate the trace.
To return a current HTML-format profile list along with a count of currently available records for each profile, use the following API command:
/v2/_zot/pprof/
If authentication is enabled, only an admin user can access this API.
How do I export profile data?¶
To collect and export any available profile, use the following API command format:
/v2/_zot/pprof/<profile-type>[?<query-parameters>]
The following example shows an API request for the CPU usage profile named profile using a collection window of 30 seconds:
$ curl -s http://localhost:8080/v2/_zot/pprof/profile?seconds=30 > cpu.prof
This command example creates an output data file named "cpu.prof".
- The query parameter
?seconds=<number> specifies the number of seconds to gather the profile data. If this parameter is not specified, the default is 30 seconds. - In this example, the raw output data is redirected to a file named "cpu.prof". Alternatively, you can use
curl -O to create a file with the default profile name (in this case, "profile"). If no output file is specified by either a cURL flag or an output redirection, the cURL command fails with "Failure writing output to destination". - The command output file is in a machine-readable format that can be interpreted by performance analyzers.
Analyzing the CPU usage profile using go tool pprof¶
Go's pprof package provides a variety of presentation formats for analyzing runtime performance.
For detailed information, see the pprof documentation.
Generating a pprof web presentation¶
When an HTTP port is specified as a command flag, the go tool pprof command installs and opens a local web server that provides a web interface for viewing and analyzing the profile data. This example opens a localhost page at port 9090 for viewing the CPU usage data captured in the profile file named "cpu.prof".
$ go tool pprof -http=:9090 cpu.prof
diff --git a/v2.1.0/articles/retention/index.html b/v2.1.0/articles/retention/index.html
index f3d68ae..2537b7d 100644
--- a/v2.1.0/articles/retention/index.html
+++ b/v2.1.0/articles/retention/index.html
@@ -1,4 +1,4 @@
- Retention Policies - zotregistry.dev Configuring zot Tag Retention Policies¶
To optimize image storage, you can configure tag retention policies to remove images that are no longer needed.
Tag retention policies in zot can specify how many tags of a given repository to retain or how long to retain certain tags.
You can define tag retention policies that apply one or more of the following rules:
- Top <n> tags most recently pushed
- Top <n> tags most recently pulled
- Tags pushed in the past <n> hours
- Tags pulled in the past <n> hours
- Tags matching a regular expression (regex) pattern
Configuring retention policies¶
Retention policies are configured in the storage section of the zot configuration file under the retention attribute. One or more policies can be grouped under the policies attribute.
By default, if no retention policies are defined, all tags are retained.
If at least one keepTags policy is defined for a repository, all tags not matching those policies are removed. To avoid unintended removals, we recommend defining a default policy, as described in Configuration notes.
Configuration example¶
The following example is a simple retention configuration with two policies:
- The first includes all available configuration attributes.
- The second acts as a default policy.
simple policy example
"storage": {
+ Retention Policies - zotregistry.dev Configuring zot Tag Retention Policies¶
To optimize image storage, you can configure tag retention policies to remove images that are no longer needed.
Tag retention policies in zot can specify how many tags of a given repository to retain or how long to retain certain tags.
You can define tag retention policies that apply one or more of the following rules:
- Top <n> tags most recently pushed
- Top <n> tags most recently pulled
- Tags pushed in the past <n> hours
- Tags pulled in the past <n> hours
- Tags matching a regular expression (regex) pattern
Configuring retention policies¶
Retention policies are configured in the storage section of the zot configuration file under the retention attribute. One or more policies can be grouped under the policies attribute.
By default, if no retention policies are defined, all tags are retained.
If at least one keepTags policy is defined for a repository, all tags not matching those policies are removed. To avoid unintended removals, we recommend defining a default policy, as described in Configuration notes.
Configuration example¶
The following example is a simple retention configuration with two policies:
- The first includes all available configuration attributes.
- The second acts as a default policy.
simple policy example
"storage": {
"retention": {
"dryRun": false,
"delay": "24h",
diff --git a/v2.1.0/articles/scaleout/index.html b/v2.1.0/articles/scaleout/index.html
index c51deb3..d4391e7 100644
--- a/v2.1.0/articles/scaleout/index.html
+++ b/v2.1.0/articles/scaleout/index.html
@@ -1,4 +1,4 @@
- Scale-out clustering - zotregistry.dev Scale-out clustering¶
A cluster of zot instances can be easily scaled with no repo-specific intelligence in the load balancing scheme, using:
- Stateless zot instances to simplify scale out
- Shared remote storage
- zot release v2.1.0 or later
Beginning with zot release v2.1.0, a new "scale-out" architecture greatly reduces the configuration required when deploying large numbers of zot instances. As before, multiple identical zot instances run simultaneously using the same shared reliable storage, but with improved scale and performance in large deployments. A highly scalable cluster can be architected by automatically sharding based on repository name so that each zot instance is responsible for a subset of repositories.
In a cloud deployment, the shared backend storage (such as AWS S3) and metadata storage (such as DynamoDB) can also be easily scaled along with the zot instances.
For high availability clustering with earlier zot releases, see zot Clustering.
Prerequisites¶
For easy scaling of instances (replicas), the following conditions must be met:
- All zot replicas must be running zot release v2.1.0 (or later) with identical configurations.
- All zot replicas in the cluster use remote storage at a single shared S3 backend. There is no local caching in the zot replicas.
- Each zot replica in the cluster has its own IP address, but all replicas use the same port number.
How it works¶
Each repo is served by one zot replica, and that replica is solely responsible for serving all images of that repo. A repo in storage can be written to only by the zot replica responsible for that repo.
When a zot replica in the cluster receives an image push or pull request for a repo, the receiving replica hashes the repo path and consults a hash table to determine which replica is responsible for the repo.
- If the hash indicates that another replica is responsible, the receiving replica forwards the request to the responsible replica and then acts as a proxy, returning the response to the requestor.
- If the hash indicates that the current (receiving) replica is responsible, the request is handled locally.
For better resistance to collisions and preimage attacks, zot uses SipHash as the hashing algorithm.
Either of the following two schemes can be used to reach the cluster.
Using a single entry point load balancer¶
When a single entry point load balancer such as HAProxy is deployed, the number of zot replicas can easily be expanded by simply adding the IP addresses of the new replicas in the load balancer configuration.
When the load balancer receives an image push or pull request for a repo, it forwards the request to any replica in the cluster. No repo-specific programming of the load balancer is needed because the load balancer does not need to know which replica owns which repo. The replicas themselves can determine this.
Using DNS-based load balancing¶
Because the scale-out architecture greatly simplifies the role of the load balancer, it may be possible to eliminate the load balancer entirely. A scheme such as DNS-based routing can be implemented, exposing the zot replicas directly to the clients.
Configuration examples¶
In these examples, clustering is supported by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load balancer forwarding traffic to the replicas.
Cluster member configuration¶
In the replica configuration, each replica must have a list of its peers configured in the "members" section of the JSON structure. This is a list of reachable addresses or hostnames. Each replica owns one of these addresses.
The replica must also have a hash key for hashing the repo path of the image request and a TLS certificate for authenticating with its peers.
Click here to view a sample cluster configuration for each replica. See the "cluster" section in the JSON structure.
{
+ Scale-out clustering - zotregistry.dev Scale-out clustering¶
A cluster of zot instances can be easily scaled with no repo-specific intelligence in the load balancing scheme, using:
- Stateless zot instances to simplify scale out
- Shared remote storage
- zot release v2.1.0 or later
Beginning with zot release v2.1.0, a new "scale-out" architecture greatly reduces the configuration required when deploying large numbers of zot instances. As before, multiple identical zot instances run simultaneously using the same shared reliable storage, but with improved scale and performance in large deployments. A highly scalable cluster can be architected by automatically sharding based on repository name so that each zot instance is responsible for a subset of repositories.
In a cloud deployment, the shared backend storage (such as AWS S3) and metadata storage (such as DynamoDB) can also be easily scaled along with the zot instances.
For high availability clustering with earlier zot releases, see zot Clustering.
Prerequisites¶
For easy scaling of instances (replicas), the following conditions must be met:
- All zot replicas must be running zot release v2.1.0 (or later) with identical configurations.
- All zot replicas in the cluster use remote storage at a single shared S3 backend. There is no local caching in the zot replicas.
- Each zot replica in the cluster has its own IP address, but all replicas use the same port number.
How it works¶
Each repo is served by one zot replica, and that replica is solely responsible for serving all images of that repo. A repo in storage can be written to only by the zot replica responsible for that repo.
When a zot replica in the cluster receives an image push or pull request for a repo, the receiving replica hashes the repo path and consults a hash table to determine which replica is responsible for the repo.
- If the hash indicates that another replica is responsible, the receiving replica forwards the request to the responsible replica and then acts as a proxy, returning the response to the requestor.
- If the hash indicates that the current (receiving) replica is responsible, the request is handled locally.
For better resistance to collisions and preimage attacks, zot uses SipHash as the hashing algorithm.
Either of the following two schemes can be used to reach the cluster.
Using a single entry point load balancer¶
When a single entry point load balancer such as HAProxy is deployed, the number of zot replicas can easily be expanded by simply adding the IP addresses of the new replicas in the load balancer configuration.
When the load balancer receives an image push or pull request for a repo, it forwards the request to any replica in the cluster. No repo-specific programming of the load balancer is needed because the load balancer does not need to know which replica owns which repo. The replicas themselves can determine this.
Using DNS-based load balancing¶
Because the scale-out architecture greatly simplifies the role of the load balancer, it may be possible to eliminate the load balancer entirely. A scheme such as DNS-based routing can be implemented, exposing the zot replicas directly to the clients.
Configuration examples¶
In these examples, clustering is supported by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load balancer forwarding traffic to the replicas.
Cluster member configuration¶
In the replica configuration, each replica must have a list of its peers configured in the "members" section of the JSON structure. This is a list of reachable addresses or hostnames. Each replica owns one of these addresses.
The replica must also have a hash key for hashing the repo path of the image request and a TLS certificate for authenticating with its peers.
Click here to view a sample cluster configuration for each replica. See the "cluster" section in the JSON structure.
{
"distSpecVersion": "1.1.0",
"storage": {
"rootDirectory": "/tmp/zot",
diff --git a/v2.1.0/articles/security-posture/index.html b/v2.1.0/articles/security-posture/index.html
index 6b6fbe4..815429a 100644
--- a/v2.1.0/articles/security-posture/index.html
+++ b/v2.1.0/articles/security-posture/index.html
@@ -1 +1 @@
- Security Posture - zotregistry.dev zot Security Posture¶
An overview of zot build-time and runtime security hardening features, including:
- Build-time hardening such as PIE-mode builds
- Minimal-build option for smaller attack surface
- Open Source Security Foundation best practices for CI/CD
- Non-root deployment
- Robust authentication/authorization options
The zot project takes a defense-in-depth approach to security, applying industry-standard best practices at various stages. Recognizing that security hardening and product features are sometimes in conflict with each other, we also provide flexibility both at build and deployment time.
Build-time hardening¶
The following are the steps taken during build-time.
PIE build-mode¶
The zot binary is built with PIE build-mode enabled to take advantage of ASLR support in modern operating systems such as Linux ASLR. While zot is intended to be a long-running service (without frequent restarts), it prevents attackers from developing a generic attack that depends on predictable memory addresses across multiple zot deployments.
Conditional builds¶
Functionality in zot is broadly organized as a core Distribution Specification implementation and additional features as extensions. The rationale behind this approach is to minimize or control library dependencies that get included in the binary and consequently the attack surface.
We currently build and release two image flavors:
-
minimal, which is a minimal Distribution Specification conformant registry, and
-
full, which incorporates the minimal build and all extensions
The minimal flavor is for the security-minded and minimizes the number of dependencies and libraries. The full flavor is for the functionality-minded with the caveat that the attack surface of the binary is potentially broader. However by no means are these the only options. Our build (via the Makefile) provides the flexibility to pick and choose extensions in order to build a binary between minimal and full. For example,
make EXTENSIONS=search binary
produces a zot binary with only the search feature enabled.
CI/CD pipeline¶
zot CI/CD process attempts to align with the Open Source Security Foundation (OSSF) best practices guidelines to achieve high code quality.
Code reviews¶
zot is an open source project and all code submissions are open and transparent. Every pull request (PR) submitted to the project repository must be reviewed by the code owners. We have additional CI/CD workflows monitoring for unreviewed commits.
CI/CD checks¶
All PRs must pass the full CI/CD pipeline checks including unit, functional, and integration tests, code quality and style checks, and performance regressions. In addition, all binaries produced are subjected to further security scans to detect any known vulnerabilities.
Runtime hardening¶
The following steps can be taken to harden a zot deployment.
Unprivileged runtime process¶
Running zot doesn’t require root privileges. In fact, the recommended approach is to create a separate user/group ID for the zot process.
Authentication¶
All interactions with zot are over HTTP APIs, and htpasswd-based local authentication, LDAP, mutual TLS, and token-based authentication mechanisms are supported. We strongly recommend enabling a suitable mechanism for your deployment use case in order to prevent unauthorized access. See the provided authentication examples.
Access control¶
Following authentication, it is further possible to allow or deny actions by a user on a particular repository stored on the zot registry. See the provided access control examples.
Vulnerability scans¶
Apart from hardening the deployment itself, zot also supports security scanning of stored container images.
Reporting security issues¶
We understand that no software is perfect and in spite of our best efforts, security bugs may be found. Refer to our security policy for taking a responsible course of action when reporting security bugs.
Last update: December 21, 2022 Back to top
\ No newline at end of file
+ Security Posture - zotregistry.dev zot Security Posture¶
An overview of zot build-time and runtime security hardening features, including:
- Build-time hardening such as PIE-mode builds
- Minimal-build option for smaller attack surface
- Open Source Security Foundation best practices for CI/CD
- Non-root deployment
- Robust authentication/authorization options
The zot project takes a defense-in-depth approach to security, applying industry-standard best practices at various stages. Recognizing that security hardening and product features are sometimes in conflict with each other, we also provide flexibility both at build and deployment time.
Build-time hardening¶
The following are the steps taken during build-time.
PIE build-mode¶
The zot binary is built with PIE build-mode enabled to take advantage of ASLR support in modern operating systems such as Linux ASLR. While zot is intended to be a long-running service (without frequent restarts), it prevents attackers from developing a generic attack that depends on predictable memory addresses across multiple zot deployments.
Conditional builds¶
Functionality in zot is broadly organized as a core Distribution Specification implementation and additional features as extensions. The rationale behind this approach is to minimize or control library dependencies that get included in the binary and consequently the attack surface.
We currently build and release two image flavors:
-
minimal, which is a minimal Distribution Specification conformant registry, and
-
full, which incorporates the minimal build and all extensions
The minimal flavor is for the security-minded and minimizes the number of dependencies and libraries. The full flavor is for the functionality-minded with the caveat that the attack surface of the binary is potentially broader. However by no means are these the only options. Our build (via the Makefile) provides the flexibility to pick and choose extensions in order to build a binary between minimal and full. For example,
make EXTENSIONS=search binary
produces a zot binary with only the search feature enabled.
CI/CD pipeline¶
zot CI/CD process attempts to align with the Open Source Security Foundation (OSSF) best practices guidelines to achieve high code quality.
Code reviews¶
zot is an open source project and all code submissions are open and transparent. Every pull request (PR) submitted to the project repository must be reviewed by the code owners. We have additional CI/CD workflows monitoring for unreviewed commits.
CI/CD checks¶
All PRs must pass the full CI/CD pipeline checks including unit, functional, and integration tests, code quality and style checks, and performance regressions. In addition, all binaries produced are subjected to further security scans to detect any known vulnerabilities.
Runtime hardening¶
The following steps can be taken to harden a zot deployment.
Unprivileged runtime process¶
Running zot doesn’t require root privileges. In fact, the recommended approach is to create a separate user/group ID for the zot process.
Authentication¶
All interactions with zot are over HTTP APIs, and htpasswd-based local authentication, LDAP, mutual TLS, and token-based authentication mechanisms are supported. We strongly recommend enabling a suitable mechanism for your deployment use case in order to prevent unauthorized access. See the provided authentication examples.
Access control¶
Following authentication, it is further possible to allow or deny actions by a user on a particular repository stored on the zot registry. See the provided access control examples.
Vulnerability scans¶
Apart from hardening the deployment itself, zot also supports security scanning of stored container images.
Reporting security issues¶
We understand that no software is perfect and in spite of our best efforts, security bugs may be found. Refer to our security policy for taking a responsible course of action when reporting security bugs.
Last update: December 21, 2022 Back to top
\ No newline at end of file
diff --git a/v2.1.0/articles/storage/index.html b/v2.1.0/articles/storage/index.html
index 9a2f28c..af1cd01 100644
--- a/v2.1.0/articles/storage/index.html
+++ b/v2.1.0/articles/storage/index.html
@@ -1,4 +1,4 @@
- Storage Planning - zotregistry.dev Storage Planning with zot¶
zot supports the following features to provide OCI standards-based, vendor-agnostic image storage:
- Local and remote file storage
- Inline deduplication and garbage collection
- Data scrubbing in background
Storage model¶
Data handling in zot revolves around two main principles: that data and APIs on the wire conform to the OCI Distribution Specification and that data on the disk conforms to the OCI Image Layout Specification. As a result, any client that is compliant with the Distribution Specification can read from or write to a zot registry. Furthermore, the actual storage is simply an OCI Image Layout. With only these two specification documents in hand, the entire data flow inside can be easily understood.
zot does not implement, support, or require any vendor-specific protocols, including that of Docker.
Hosting an OCI image layout¶
Because zot supports the OCI image layout, it can readily host and serve any directories holding a valid OCI image layout even when those directories have been created elsewhere. This property of zot is suitable for use cases in which container images are independently built, stored, and transferred, but later need to be served over the network.
Storage features¶
Exposing flexibility in storage capabilities is a key tenet for catering to the requirements of varied environments ranging from cloud to on-premises to IoT.
Commit¶
Most modern filesystems buffer and flush RAM data to disk after a delay. The purpose of this function is to improve performance at the cost of higher disk memory usage. In embedded devices such as Raspberry Pi, for example, where RAM may be very limited and at a premium, it is desirable to flush data to disk more frequently. The zot storage configuration exposes an option called commit which, when enabled, causes data writes to be committed to disk immediately. This option is disabled by default.
Deduplication¶
Deduplication is a storage space saving feature wherein only a single copy of specific content is maintained on disk while many different image manifests may hold references to that same content. The deduplication option (dedupe) is also available for supported cloud storage backends.
Upon startup, zot enforces the dedupe status on the existing storage. If the dedupe status upon startup is true, zot deduplicates all blobs found in storage, both local and remote. If the status upon startup is false, zot restores cloud storage blobs to their original state. There is no need for zot to restore local filesystem storage if hard links are used.
Garbage collection¶
After an image is deleted by deleting an image manifest, the corresponding blobs can be purged to free up space. However, since Distribution Specification APIs are not transactional between blob and manifest lifecycle, care must be taken so as not to put the storage in an inconsistent state. Garbage collection in zot is an inline feature meaning that it is not necessary to take the registry offline. See Configuring garbage collection for details.
Scrub¶
The scrub function, available as an extension, makes it possible to ascertain data validity by computing hashes on blobs periodically and continuously so that any bit rot is caught and reported early.
Storage backends¶
The following types of storage backends are supported.
Local filesystem¶
zot can store and serve files from one or more local directories. A minimum of one root directory is required for local hosting, but additional hosted directories can be added. When accessed by HTTP APIs, all directories can appear as a single data store.
Remote filesystems that are mounted and accessible locally such as NFS or fuse are treated as local filesystems.
Remote filesystem¶
zot can also store data remotely in the cloud, using the storage APIs of the cloud service. Currently, zot supports only the AWS s3 storage service.
Example: configuration for remote (s3) storage¶