diff --git a/v2.0.1/404.html b/v2.0.1/404.html index c3c135f..7bd6ad3 100644 --- a/v2.0.1/404.html +++ b/v2.0.1/404.html @@ -1 +1 @@ - zotregistry.dev

404 - Not found

\ No newline at end of file + zotregistry.dev

404 - Not found

\ No newline at end of file diff --git a/v2.0.1/admin-guide/admin-configuration/index.html b/v2.0.1/admin-guide/admin-configuration/index.html index 2f3b2af..a70550b 100644 --- a/v2.0.1/admin-guide/admin-configuration/index.html +++ b/v2.0.1/admin-guide/admin-configuration/index.html @@ -118,4 +118,4 @@

Toggle repository bookmark

This action sets the repository bookmark property to true if it is false, and to false if it is true.

Action Parameter Parameter Description
toggleBookmark repo The name of the repository whose bookmark is to be changed

This example toggles a bookmark on a repository named repoName:

PUT
 http://localhost:5000/v2/_zot/ext/userprefs?
 action=toggleBookmark&repo=repoName
-

Verifying the configuration file

Before launching zot, verify the syntax of your configuration file using the following command:

zot verify <configfile>

✏ Verifying the configuration file protects against operator errors and any conflicts arising from zot release version changes.

After verifying your configuration file, you can launch zot with the following command:

zot serve <configfile>

Last update: October 12, 2023
\ No newline at end of file +

Verifying the configuration file

Before launching zot, verify the syntax of your configuration file using the following command:

zot verify <configfile>

✏ Verifying the configuration file protects against operator errors and any conflicts arising from zot release version changes.

After verifying your configuration file, you can launch zot with the following command:

zot serve <configfile>

Last update: October 12, 2023
\ No newline at end of file diff --git a/v2.0.1/admin-guide/admin-getting-started/index.html b/v2.0.1/admin-guide/admin-getting-started/index.html index 244446e..7b0cca4 100644 --- a/v2.0.1/admin-guide/admin-getting-started/index.html +++ b/v2.0.1/admin-guide/admin-getting-started/index.html @@ -16,4 +16,4 @@ -v $(pwd)/custom-config.yml:/etc/zot/config.yml \ -v $(pwd)/registry:/tmp/zot \ zot:latest -

This command causes the registry to listen on port 8080 and to use /tmp/zot for content storage.

We recommend that, when deploying zot, you also install the command line (zli) and benchmarking (zb) packages.

Launching zot

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.yml

💡 For convenience, you can rename the binary image file to simply zot.The instructions and examples in this guide use zot as the name of the zot executable file and do not include the path to the executable file.

Next Steps

Configuring zot

You configure zot primarily through adding and modifying settings in the zot configuration file. The configuration file is a JSON or YAML file that contains all configuration settings for zot functions.

When you first build zot or deploy an image or container from the distribution, a basic configuration file config.json is created. You can modify the initial file or you can create a new file.

Follow the instructions in Configuring zot, to compose a configuration file with the settings and features you require for your zot registry server.

Last update: September 13, 2023
\ No newline at end of file +

This command causes the registry to listen on port 8080 and to use /tmp/zot for content storage.

We recommend that, when deploying zot, you also install the command line (zli) and benchmarking (zb) packages.

Launching zot

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.yml

💡 For convenience, you can rename the binary image file to simply zot.The instructions and examples in this guide use zot as the name of the zot executable file and do not include the path to the executable file.

Next Steps

Configuring zot

You configure zot primarily through adding and modifying settings in the zot configuration file. The configuration file is a JSON or YAML file that contains all configuration settings for zot functions.

When you first build zot or deploy an image or container from the distribution, a basic configuration file config.json is created. You can modify the initial file or you can create a new file.

Follow the instructions in Configuring zot, to compose a configuration file with the settings and features you require for your zot registry server.

Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/authn-authz/index.html b/v2.0.1/articles/authn-authz/index.html index b155202..1319fb0 100644 --- a/v2.0.1/articles/authn-authz/index.html +++ b/v2.0.1/articles/authn-authz/index.html @@ -145,12 +145,12 @@ }

Using Google, GitHub, or GitLab

A client logging into zot by social login must specify a supported OpenID/OAuth2 provider as a URL query parameter. A client logging in using Google, GitHub, or GitLab must additionally specify a callback URL for redirection to a zot page after a successful authentication.

The login URL using Google, GitHub, or GitLab uses the following format:

http://<zot-server>/auth/login?provider=<provider>&callback_ui=<zot-server>/<page>

For example, a user logging in to the zot home page using GitHub as the authentication provider sends this URL:

http://zot.example.com:8080/auth/login?provider=github&callback_ui=http://zot.example.com:8080/home
-

Based on the specified provider, zot redirects the login to a provider service with the following URL:

http://<zot-server>/auth/callback/<provider>
-

For the GitHub authentication example:

http://zot.example.com:8080/auth/callback/github
+

Based on the specified provider, zot redirects the login to a provider service with the following URL:

http://<zot-server>/zot/auth/callback/<provider>
+

For the GitHub authentication example:

http://zot.example.com:8080/zot/auth/callback/github

✏ If your network policy doesn't allow inbound connections, the callback will not work and this authentication method will fail.

Using dex

dex is an identity service that uses OpenID Connect (OIDC) to drive authentication for client apps, such as zot. While this section shows how to use dex with zot, zot supports other OIDC services as well.

Like zot, dex uses a configuration file for setup. To specify zot as a client in dex, configure a staticClients entry in the dex configuration file with a zot callback, such as the following example in the dex configuration file:

staticClients:
   - id: zot-client
     redirectURIs:
-      - 'http://zot.example.com:8080/auth/callback/oidc'
+      - 'http://zot.example.com:8080/zot/auth/callback/oidc'
     name: 'zot'
     secret: ZXhhbXBsZS1hcHAtc2VjcmV0

In the zot configuration file, configure dex as an OpenID auth provider as in the following example:

  "http": {
@@ -185,4 +185,4 @@
       }
     }
   }
-
Last update: November 21, 2023
\ No newline at end of file +
Last update: February 5, 2024
\ No newline at end of file diff --git a/v2.0.1/articles/benchmarking-with-zb/index.html b/v2.0.1/articles/benchmarking-with-zb/index.html index a36324c..74c69b0 100644 --- a/v2.0.1/articles/benchmarking-with-zb/index.html +++ b/v2.0.1/articles/benchmarking-with-zb/index.html @@ -51,4 +51,4 @@ p99: 26.375356ms ... -
Last update: December 21, 2022
\ No newline at end of file +
Last update: December 21, 2022
\ No newline at end of file diff --git a/v2.0.1/articles/building-ci-cd-pipeline/index.html b/v2.0.1/articles/building-ci-cd-pipeline/index.html index 4fa6538..444b9d2 100644 --- a/v2.0.1/articles/building-ci-cd-pipeline/index.html +++ b/v2.0.1/articles/building-ci-cd-pipeline/index.html @@ -24,4 +24,4 @@ helm install cosigned -n cosign-system sigstore/cosigned \ --devel --set cosign.secretKeyRef.name=mysecret -
Last update: May 18, 2023
\ No newline at end of file +
Last update: May 18, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/clustering/index.html b/v2.0.1/articles/clustering/index.html index a802ac5..11b9726 100644 --- a/v2.0.1/articles/clustering/index.html +++ b/v2.0.1/articles/clustering/index.html @@ -73,4 +73,4 @@ "level": "debug" } } -
Last update: May 18, 2023
\ No newline at end of file +
Last update: May 18, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/graphql/index.html b/v2.0.1/articles/graphql/index.html index 8e8b6d4..7f91f72 100644 --- a/v2.0.1/articles/graphql/index.html +++ b/v2.0.1/articles/graphql/index.html @@ -595,4 +595,4 @@ ] } } -
Last update: November 15, 2023
\ No newline at end of file +
Last update: November 15, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/kind-deploy/index.html b/v2.0.1/articles/kind-deploy/index.html index 93481f8..8675566 100644 --- a/v2.0.1/articles/kind-deploy/index.html +++ b/v2.0.1/articles/kind-deploy/index.html @@ -121,4 +121,4 @@ kind delete cluster docker stop kind-registry docker rm kind-registry -
Last update: September 13, 2023
\ No newline at end of file +
Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/mirroring/index.html b/v2.0.1/articles/mirroring/index.html index 1fd35a6..b71e0df 100644 --- a/v2.0.1/articles/mirroring/index.html +++ b/v2.0.1/articles/mirroring/index.html @@ -245,4 +245,4 @@ "kube-proxy/kube-proxy" ] } -

In zot storage, the requested content is located here:
    /tmp/zot/kube-proxy/kube-proxy/kube-proxy/
This subpath is created from the following path components:

Last update: September 13, 2023
\ No newline at end of file +

In zot storage, the requested content is located here:
    /tmp/zot/kube-proxy/kube-proxy/kube-proxy/
This subpath is created from the following path components:

Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/monitoring/index.html b/v2.0.1/articles/monitoring/index.html index 0b9f436..8a447f7 100644 --- a/v2.0.1/articles/monitoring/index.html +++ b/v2.0.1/articles/monitoring/index.html @@ -24,4 +24,4 @@ } } } -

💡 The zxp module does not have Prometheus integration.

The zxp module is not needed with a full zot image.

Last update: September 13, 2023
\ No newline at end of file +

💡 The zxp module does not have Prometheus integration.

The zxp module is not needed with a full zot image.

Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/pprofiling/index.html b/v2.0.1/articles/pprofiling/index.html index b8aeabf..20f1d03 100644 --- a/v2.0.1/articles/pprofiling/index.html +++ b/v2.0.1/articles/pprofiling/index.html @@ -29,4 +29,4 @@ 2023/09/21 16:58:58 Opening browser. Trace viewer is listening on http://127.0.0.1:62606

The go tool trace command installs and opens a local web server that provides a web interface for viewing and analyzing the trace data.

As an alternative, you can generate a pprof-like profile from the trace file using the following command:

$ go tool trace -pprof=[net|sync|syscall|sched] <filename>

For example:

$ go tool trace -pprof=net trace.prof
-
Last update: October 12, 2023
\ No newline at end of file +
Last update: October 12, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/retention/index.html b/v2.0.1/articles/retention/index.html index fbb1124..bb00bfe 100644 --- a/v2.0.1/articles/retention/index.html +++ b/v2.0.1/articles/retention/index.html @@ -96,4 +96,4 @@ "level": "debug" } } -
Last update: November 1, 2023
\ No newline at end of file +
Last update: November 1, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/security-posture/index.html b/v2.0.1/articles/security-posture/index.html index 8b1e410..090fe86 100644 --- a/v2.0.1/articles/security-posture/index.html +++ b/v2.0.1/articles/security-posture/index.html @@ -1 +1 @@ - Security Posture - zotregistry.dev
Skip to content

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
\ No newline at end of file + Security Posture - zotregistry.dev
Skip to content

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
\ No newline at end of file diff --git a/v2.0.1/articles/storage/index.html b/v2.0.1/articles/storage/index.html index 4d37b46..1529285 100644 --- a/v2.0.1/articles/storage/index.html +++ b/v2.0.1/articles/storage/index.html @@ -162,4 +162,4 @@ . } } -

The subPaths feature ties together several separate storage filesystems and backends behind the same HTTP API interface. In the example above, both repository paths "/a" and "/b" are exposed to clients. Content on these two paths can be hosted completely separately by different storage services, locations, or filesystems, with no difference to the user interface and no perceptible difference to the user experience. This is useful if one wants to serve existing OCI images from different backends or if storage can be expanded only by using different backing stores.

💡 zot also supports different storage drivers for each subpath.

Last update: September 13, 2023
\ No newline at end of file +

The subPaths feature ties together several separate storage filesystems and backends behind the same HTTP API interface. In the example above, both repository paths "/a" and "/b" are exposed to clients. Content on these two paths can be hosted completely separately by different storage services, locations, or filesystems, with no difference to the user interface and no perceptible difference to the user experience. This is useful if one wants to serve existing OCI images from different backends or if storage can be expanded only by using different backing stores.

💡 zot also supports different storage drivers for each subpath.

Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/verifying-signatures/index.html b/v2.0.1/articles/verifying-signatures/index.html index fb178f8..dbea199 100644 --- a/v2.0.1/articles/verifying-signatures/index.html +++ b/v2.0.1/articles/verifying-signatures/index.html @@ -83,4 +83,4 @@ } } } -
Last update: September 13, 2023
\ No newline at end of file +
Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/articles/workflow/index.html b/v2.0.1/articles/workflow/index.html index c646794..2c772a3 100644 --- a/v2.0.1/articles/workflow/index.html +++ b/v2.0.1/articles/workflow/index.html @@ -204,4 +204,4 @@ # stop zot zot_teardown -
Last update: October 6, 2023
\ No newline at end of file +
Last update: October 6, 2023
\ No newline at end of file diff --git a/v2.0.1/developer-guide/api-reference/index.html b/v2.0.1/developer-guide/api-reference/index.html index 0306611..c0726ea 100644 --- a/v2.0.1/developer-guide/api-reference/index.html +++ b/v2.0.1/developer-guide/api-reference/index.html @@ -309,4 +309,4 @@ "string" ] } -

Responses

Status Meaning Description Schema
200 OK OK common.ImageTags
400 Bad Request bad request". string
404 Not Found not found string

This operation does not require authentication

Last update: November 17, 2023
\ No newline at end of file +

Responses

Status Meaning Description Schema
200 OK OK common.ImageTags
400 Bad Request bad request". string
404 Not Found not found string

This operation does not require authentication

Last update: November 17, 2023
\ No newline at end of file diff --git a/v2.0.1/developer-guide/api-user-guide/index.html b/v2.0.1/developer-guide/api-user-guide/index.html index 9432143..e946785 100644 --- a/v2.0.1/developer-guide/api-user-guide/index.html +++ b/v2.0.1/developer-guide/api-user-guide/index.html @@ -74,4 +74,4 @@

Uploading a certificate for Notation

To upload a certificate for notation, use the following endpoint:

POST /v2/_zot/ext/notation

cURL command example:

curl --data-binary @certificate.crt -X POST "http://localhost:8080/v2/_zot/ext/notation?truststoreType=ca"

Viewing the complete zot API reference

You can find comprehensive details of all zot API commands in either of the following locations:

There are many ways to view a swagger file as an interactive document. If you have the npm package installed, for example, you can execute the following command:

  $ npx open-swagger-ui swagger.json
-

This command creates a local web server at localhost:3355 where you can interact with the API reference using a browser.

Last update: November 29, 2023
\ No newline at end of file +

This command creates a local web server at localhost:3355 where you can interact with the API reference using a browser.

Last update: November 29, 2023
\ No newline at end of file diff --git a/v2.0.1/developer-guide/contributing/index.html b/v2.0.1/developer-guide/contributing/index.html index c57bd8e..e3d8c30 100644 --- a/v2.0.1/developer-guide/contributing/index.html +++ b/v2.0.1/developer-guide/contributing/index.html @@ -1 +1 @@ - Contributing - zotregistry.dev
Skip to content

Contributing to zot Development

👉 The zot project is built for developers by developers. The zot project welcomes the participation of the open source community in extending and improving zot.

Submission Requirements

Summary: All contributions must meet these requirements:

  • Adhere to the Apache license
  • Be submitted by a pull request (PR) from your fork
  • Commits must have a

License

zot is released under the Apache License 2.0. All contributions must adhere to this license and must explicitly state adherence.

Submitting a Pull Request (PR)

First, fork the zot project on GitHub and submit a commit to your fork. Then open a new pull request (PR) to the zot project. All pull requests must meet these requirements:

  • License statement

Either the commit message or the PR description must contain the following statement:

"By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license."

  • Developer Certificate of Origin (DCO) and sign-off

All commits require a Developer Certificate of Origin via the "Signed-off-by:" commit message and commit signatures using GPG keys. Include the -s flag in your git commit command.

  • Commit message format

The commit message must follow the Convention Commits format. The message must begin with a keyword that categorizes the commit, followed by a colon. Validation of a commit message is determined by this expression:

"^((build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(.+\))?(!)?(: (.*\s*)*))"

An example of a valid commit message is "docs: Fixes a typo in module.md."

In addition, any new PR requires a brief form to be completed by the submitter with details about the PR. Appropriate code owners are automatically identified and will be notified of the new PR.

CI/CD Checks

We take code quality very seriously. All PRs must pass various CI/CD checks that enforce code quality such as code coverage, security scanning, performance regressions, distribution spec conformance, ecosystem client tool compatibility, etc.

Reporting Issues

Issues are broadly classified as functional bugs and security issues. The latter is treated a little differently due to the sensitive nature.

Filing a Functional Issue

No software is perfect, and we expect users to find issues with the zot code base. First, check whether your issue has already been filed by someone else by performing an issue search. If the issue is not found, file a new issue by clicking the New issue button on the zot/issues page and answering the questions. The more information that you can provide, the easier it becomes to triage the issue.

Filing a Security Issue

Security issues are best filed by sending an email to security@zotregistry.dev. After 45 days, we will make the issue public and give credit to the original filer of the issue.

Code of Conduct

The zot project follows the CNCF Code of Conduct.

Reporting Conduct Incidents

To report a conduct-related incident occurring on the zot project, contact the zot project conduct committee by sending an email to conduct@zotregistry.dev. You can expect a response within three business days.

Last update: January 16, 2024
\ No newline at end of file + Contributing - zotregistry.dev
Skip to content

Contributing to zot Development

👉 The zot project is built for developers by developers. The zot project welcomes the participation of the open source community in extending and improving zot.

Submission Requirements

Summary: All contributions must meet these requirements:

  • Adhere to the Apache license
  • Be submitted by a pull request (PR) from your fork
  • Commits must have a

License

zot is released under the Apache License 2.0. All contributions must adhere to this license and must explicitly state adherence.

Submitting a Pull Request (PR)

First, fork the zot project on GitHub and submit a commit to your fork. Then open a new pull request (PR) to the zot project. All pull requests must meet these requirements:

  • License statement

Either the commit message or the PR description must contain the following statement:

"By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license."

  • Developer Certificate of Origin (DCO) and sign-off

All commits require a Developer Certificate of Origin via the "Signed-off-by:" commit message and commit signatures using GPG keys. Include the -s flag in your git commit command.

  • Commit message format

The commit message must follow the Convention Commits format. The message must begin with a keyword that categorizes the commit, followed by a colon. Validation of a commit message is determined by this expression:

"^((build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\(.+\))?(!)?(: (.*\s*)*))"

An example of a valid commit message is "docs: Fixes a typo in module.md."

In addition, any new PR requires a brief form to be completed by the submitter with details about the PR. Appropriate code owners are automatically identified and will be notified of the new PR.

CI/CD Checks

We take code quality very seriously. All PRs must pass various CI/CD checks that enforce code quality such as code coverage, security scanning, performance regressions, distribution spec conformance, ecosystem client tool compatibility, etc.

Reporting Issues

Issues are broadly classified as functional bugs and security issues. The latter is treated a little differently due to the sensitive nature.

Filing a Functional Issue

No software is perfect, and we expect users to find issues with the zot code base. First, check whether your issue has already been filed by someone else by performing an issue search. If the issue is not found, file a new issue by clicking the New issue button on the zot/issues page and answering the questions. The more information that you can provide, the easier it becomes to triage the issue.

Filing a Security Issue

Security issues are best filed by sending an email to security@zotregistry.dev. After 45 days, we will make the issue public and give credit to the original filer of the issue.

Code of Conduct

The zot project follows the CNCF Code of Conduct.

Reporting Conduct Incidents

To report a conduct-related incident occurring on the zot project, contact the zot project conduct committee by sending an email to conduct@zotregistry.dev. You can expect a response within three business days.

Last update: January 16, 2024
\ No newline at end of file diff --git a/v2.0.1/developer-guide/extensions-dev/index.html b/v2.0.1/developer-guide/extensions-dev/index.html index 7b3df20..8216c7a 100644 --- a/v2.0.1/developer-guide/extensions-dev/index.html +++ b/v2.0.1/developer-guide/extensions-dev/index.html @@ -15,4 +15,4 @@ ... See extension lint-disabled.go in the zot project for an example of a "no-op" file.

Building zot with extensions

When you build the full zot image (for example, make binary), all extensions listed in the EXTENSIONS variable in Makefile are included in the build. When you've created a new extension, you must modify the EXTENSIONS variable in Makefile by adding the new extension.

To build an image with only selected extensions, you can specify the desired extensions by declaring them in the build command:

make binary EXTENSIONS=extension1,extension2,extension3...

For example, to build with only sync and scrub, the command would be:

make binary EXTENSIONS=sync,scrub
-
Last update: September 13, 2023
\ No newline at end of file +
Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/developer-guide/onboarding/index.html b/v2.0.1/developer-guide/onboarding/index.html index 81438c1..96c29d6 100644 --- a/v2.0.1/developer-guide/onboarding/index.html +++ b/v2.0.1/developer-guide/onboarding/index.html @@ -26,4 +26,4 @@ - examples/ # Configuration examples - swagger/ # Swagger integration - docs/ # Documentation -

Additional state in zot

In addition to the storage of repository images, zot stores data for various processes in local and remote storage and databases. The following table shows the storage locations for different processes and types of data.

Data or Process Storage Location Description
images local and
AWS S3		 Image blobs
repository synchronization local
/<repo_name>/.sync		 The sync operation temporarily copies the upstream blobs to:
/<repo_name>/.sync/${UUID}/<repo_name>, then copies to /<repo_name> and deletes the temporary directory ${UUID}
deduplication local
/cache.db		 Cache for deduplication of files stored locally
AWS DynamoDB Cache for deduplication of files stored in AWS
CVE local
/_trivy		 Database of Common Vulnerabilities and Exposures (CVE) information and scan results
user sessions local
/_sessions		 zot user session authentication (for zui)
PKI authentication documents local
/_cosign		 Private keys for signature verification using cosign
local
/_notation		 Certificates for signature verification using notation
metadata local
/repo.db		 Local storage of manifests, configurations, download counters, signature verification results
AWS DynamoDB Cloud storage of manifests, configurations, download counters, signature verification results
Last update: October 12, 2023
\ No newline at end of file +

Additional state in zot

In addition to the storage of repository images, zot stores data for various processes in local and remote storage and databases. The following table shows the storage locations for different processes and types of data.

Data or Process Storage Location Description
images local and
AWS S3		 Image blobs
repository synchronization local
/<repo_name>/.sync		 The sync operation temporarily copies the upstream blobs to:
/<repo_name>/.sync/${UUID}/<repo_name>, then copies to /<repo_name> and deletes the temporary directory ${UUID}
deduplication local
/cache.db		 Cache for deduplication of files stored locally
AWS DynamoDB Cache for deduplication of files stored in AWS
CVE local
/_trivy		 Database of Common Vulnerabilities and Exposures (CVE) information and scan results
user sessions local
/_sessions		 zot user session authentication (for zui)
PKI authentication documents local
/_cosign		 Private keys for signature verification using cosign
local
/_notation		 Certificates for signature verification using notation
metadata local
/repo.db		 Local storage of manifests, configurations, download counters, signature verification results
AWS DynamoDB Cloud storage of manifests, configurations, download counters, signature verification results
Last update: October 12, 2023
\ No newline at end of file diff --git a/v2.0.1/general/architecture/index.html b/v2.0.1/general/architecture/index.html index 21fd0a7..c99e2f7 100644 --- a/v2.0.1/general/architecture/index.html +++ b/v2.0.1/general/architecture/index.html @@ -1 +1 @@ - Architecture - zotregistry.dev
Skip to content

Architecture

👉 zot is an OCI-native container image registry. This document discusses the design goals, the overall architecture, and the design choices made in the implementation of the design goals.

Design Goals

OCI-first

  • HTTP APIs strictly conforms to the OCI Distribution Specification

    zot intends to be a production reference implementation for the OCI Distribution Specification. In fact, zot does not support any other vendor protocol or specification.

  • Storage layout follows the OCI Image Specification

    The default and only supported storage layout is the OCI Image Layout. The implications of this choice are that any OCI image layout can be served by zot and conversely, zot converts data on-the-wire into an OCI image layout.

Single binary model

zot is a single binary image with all features included so that deployment is extremely simple in various environments, including bare-metal, cloud, and embedded devices. Behavior is controlled by a single configuration file.

Enable Only What You Need

A clear separation exists between (1) the core OCI-compliant HTTP APIs and storage functionality, and (2) other add-on features modeled as extensions. The extension features can be selectively enabled both at build-time and run-time.

For more information, see "Conditional Builds" in zot's security posture document.

Overall Architecture

As shown in the following figure, the architecture of zot is organized as:

👉 zot-full = zot-minimal + extensions

504567.jpg

The minimal build is the core OCI-compliant registry functionality as described by the OCI Distribution Specification.

The full build adds features that are not a part of the Distribution Specification, but are allowed to be added as Extensions.

External Interaction

External interaction with zot consists of the following two types:

  • Client-initiated data or meta-data queries

  • Admin-initiated configuration

All client-side interaction occurs over HTTP APIs. The core data path queries are governed by the OCI Distribution Specification. All additional meta-data queries are handled based on the setting of the search extension:

  • If the search extension is enabled, enhanced registry searching and filtering is supported, using graphQL. A database is maintained by zot to efficiently answer complex queries on data stored in the database.

  • If the search extension is not enabled, basic queries are supported using the core APIs. These queries are less efficient and search actual storage, which is limited in content.

Configuration

A single configuration file governs zot instance behavior. An exception can be made for security concerns, wherein configuration items containing sensitive credentials can be stored in separate files referenced by the main configuration file. Using separate files allows stricter permissions to be enforced on those files if stored locally. Also, modeling as external files allows for storing Kubernetes Secrets.

The configuration file is divided into sections for http, storage, log, and extension, governing the behavior of the respective components.

Authentication and Authorization

A robust set of authentication and authorization options are supported natively in zot. These controls are enforced before access is allowed into the storage layer.

For more information, see User Authentication and Authorization with zot.

Storage Driver Support

zot supports any modern local filesystem. Remote filesystems, such as AWS S3 or any AWS S3-compatible storage system, are supported. Additional driver support is planned in the roadmap.

✏ Deduplication is supported for both local and remote filesystems, but deduplication requires a filesystem with hard-link support.

For more information, see Storage Planning with zot.

Security Scanning

zot integrates with the trivy security scanner to scan container images for vulnerabilities. The database is kept current by periodically downloading any vulnerability database updates at a configurable interval. The user remains agnostic of the actual scanner implementation, which may change over time.

Extensions

Additional registry features that are not a part of the Distribution Specification are added as Extensions.

✏ Extension features of zot are available only with a full zot image. They are not supported in a minimal zot image.

For more information about zot's extensions, see Extensions.

Background Tasks

Several periodic tasks occur in the registry, such as garbage collection, sync mirroring, and scrubbing. A task scheduler handles these tasks in the background, taking care not to degrade or interrupt foreground tasks running in the context of HTTP APIs.

Last update: September 13, 2023
\ No newline at end of file + Architecture - zotregistry.dev
Skip to content

Architecture

👉 zot is an OCI-native container image registry. This document discusses the design goals, the overall architecture, and the design choices made in the implementation of the design goals.

Design Goals

OCI-first

  • HTTP APIs strictly conforms to the OCI Distribution Specification

    zot intends to be a production reference implementation for the OCI Distribution Specification. In fact, zot does not support any other vendor protocol or specification.

  • Storage layout follows the OCI Image Specification

    The default and only supported storage layout is the OCI Image Layout. The implications of this choice are that any OCI image layout can be served by zot and conversely, zot converts data on-the-wire into an OCI image layout.

Single binary model

zot is a single binary image with all features included so that deployment is extremely simple in various environments, including bare-metal, cloud, and embedded devices. Behavior is controlled by a single configuration file.

Enable Only What You Need

A clear separation exists between (1) the core OCI-compliant HTTP APIs and storage functionality, and (2) other add-on features modeled as extensions. The extension features can be selectively enabled both at build-time and run-time.

For more information, see "Conditional Builds" in zot's security posture document.

Overall Architecture

As shown in the following figure, the architecture of zot is organized as:

👉 zot-full = zot-minimal + extensions

504567.jpg

The minimal build is the core OCI-compliant registry functionality as described by the OCI Distribution Specification.

The full build adds features that are not a part of the Distribution Specification, but are allowed to be added as Extensions.

External Interaction

External interaction with zot consists of the following two types:

  • Client-initiated data or meta-data queries

  • Admin-initiated configuration

All client-side interaction occurs over HTTP APIs. The core data path queries are governed by the OCI Distribution Specification. All additional meta-data queries are handled based on the setting of the search extension:

  • If the search extension is enabled, enhanced registry searching and filtering is supported, using graphQL. A database is maintained by zot to efficiently answer complex queries on data stored in the database.

  • If the search extension is not enabled, basic queries are supported using the core APIs. These queries are less efficient and search actual storage, which is limited in content.

Configuration

A single configuration file governs zot instance behavior. An exception can be made for security concerns, wherein configuration items containing sensitive credentials can be stored in separate files referenced by the main configuration file. Using separate files allows stricter permissions to be enforced on those files if stored locally. Also, modeling as external files allows for storing Kubernetes Secrets.

The configuration file is divided into sections for http, storage, log, and extension, governing the behavior of the respective components.

Authentication and Authorization

A robust set of authentication and authorization options are supported natively in zot. These controls are enforced before access is allowed into the storage layer.

For more information, see User Authentication and Authorization with zot.

Storage Driver Support

zot supports any modern local filesystem. Remote filesystems, such as AWS S3 or any AWS S3-compatible storage system, are supported. Additional driver support is planned in the roadmap.

✏ Deduplication is supported for both local and remote filesystems, but deduplication requires a filesystem with hard-link support.

For more information, see Storage Planning with zot.

Security Scanning

zot integrates with the trivy security scanner to scan container images for vulnerabilities. The database is kept current by periodically downloading any vulnerability database updates at a configurable interval. The user remains agnostic of the actual scanner implementation, which may change over time.

Extensions

Additional registry features that are not a part of the Distribution Specification are added as Extensions.

✏ Extension features of zot are available only with a full zot image. They are not supported in a minimal zot image.

For more information about zot's extensions, see Extensions.

Background Tasks

Several periodic tasks occur in the registry, such as garbage collection, sync mirroring, and scrubbing. A task scheduler handles these tasks in the background, taking care not to degrade or interrupt foreground tasks running in the context of HTTP APIs.

Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/general/concepts/index.html b/v2.0.1/general/concepts/index.html index 9326974..1021648 100644 --- a/v2.0.1/general/concepts/index.html +++ b/v2.0.1/general/concepts/index.html @@ -1 +1 @@ - Concepts - zotregistry.dev
Skip to content

Concepts

What is zot?

👉 zot is a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

Two broad trends are changing how we build, distribute, and consume software. The first trend is the increasing adoption of container technologies. The second trend is that software solutions are being composed by combining elements from various sources rather than being built entirely from scratch. The latter trend raises the importance of software provenance and supply chain security. In both trends, zot intends to play an important role by providing a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

What is an OCI image registry?

An OCI image registry is a server-based application that allows you to store, manage, and share container images. A developer uploads (pushes) an image to the registry for distribution. Users can then download (pull) the image to run on their systems. The OCI Distribution Specification, published by the Open Container Initiative (OCI), defines a standard API protocol for these and other image registry operations.

An image registry can be a part of your continuous integration and continuous deployment (CI/CD) pipeline when you host zot on your public or private server. In its minimal form, you can also embed a zot registry in a product. In either case, zot provides a secure software supply chain for container images.

Why zot?

👉 zot = OCI Distribution Specification + OCI Image Format

At its heart, zot is a production-ready, vendor-neutral OCI image registry with images stored in the OCI image format and with the OCI distribution specification on-the-wire. zot is built for developers by developers, offering features such as minimal deployment using a single binary image, built-in authentication and authorization, and inline garbage collection and storage deduplication.

504566

Some of the principal advantages of zot are:

  • Open source

  • OCI standards-only both on-the-wire and on-disk

  • Clear separation between core distribution spec and zot-specific extensions

  • Software supply chain security, including support for cosign and notation

  • Security hardening

  • Single binary with many features built-in

  • Suitable for deployments in cloud, bare-metal, and embedded devices

zot fully conforms to the OCI Distribution Specification.

The following table lists additional advantages of zot:
Distribution Spec conformance yes
CNCF project accepted as a Sandbox Project
License Apache 2.0
On-premises deployment yes
OCI conformance* yes
Single binary image* yes
Minimal build* yes
Storage Layout OCI v1 Image Layout
Authentication built-in
Authorization built-in
Garbage collection inline
Storage deduplication inline
Cloud storage support yes
Delete by tag yes
Vulnerability scanning built-in
Command line interface (cli) yes
UI yes
External contributions beta available
Image signatures built-in

✏ * The minimal build feature is the ability to build a minimal Distribution Spec compliant registry in order to reduce library dependencies and the possible attack surface.

Last update: May 18, 2023
\ No newline at end of file + Concepts - zotregistry.dev
Skip to content

Concepts

What is zot?

👉 zot is a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

Two broad trends are changing how we build, distribute, and consume software. The first trend is the increasing adoption of container technologies. The second trend is that software solutions are being composed by combining elements from various sources rather than being built entirely from scratch. The latter trend raises the importance of software provenance and supply chain security. In both trends, zot intends to play an important role by providing a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

What is an OCI image registry?

An OCI image registry is a server-based application that allows you to store, manage, and share container images. A developer uploads (pushes) an image to the registry for distribution. Users can then download (pull) the image to run on their systems. The OCI Distribution Specification, published by the Open Container Initiative (OCI), defines a standard API protocol for these and other image registry operations.

An image registry can be a part of your continuous integration and continuous deployment (CI/CD) pipeline when you host zot on your public or private server. In its minimal form, you can also embed a zot registry in a product. In either case, zot provides a secure software supply chain for container images.

Why zot?

👉 zot = OCI Distribution Specification + OCI Image Format

At its heart, zot is a production-ready, vendor-neutral OCI image registry with images stored in the OCI image format and with the OCI distribution specification on-the-wire. zot is built for developers by developers, offering features such as minimal deployment using a single binary image, built-in authentication and authorization, and inline garbage collection and storage deduplication.

504566

Some of the principal advantages of zot are:

  • Open source

  • OCI standards-only both on-the-wire and on-disk

  • Clear separation between core distribution spec and zot-specific extensions

  • Software supply chain security, including support for cosign and notation

  • Security hardening

  • Single binary with many features built-in

  • Suitable for deployments in cloud, bare-metal, and embedded devices

zot fully conforms to the OCI Distribution Specification.

The following table lists additional advantages of zot:
Distribution Spec conformance yes
CNCF project accepted as a Sandbox Project
License Apache 2.0
On-premises deployment yes
OCI conformance* yes
Single binary image* yes
Minimal build* yes
Storage Layout OCI v1 Image Layout
Authentication built-in
Authorization built-in
Garbage collection inline
Storage deduplication inline
Cloud storage support yes
Delete by tag yes
Vulnerability scanning built-in
Command line interface (cli) yes
UI yes
External contributions beta available
Image signatures built-in

✏ * The minimal build feature is the ability to build a minimal Distribution Spec compliant registry in order to reduce library dependencies and the possible attack surface.

Last update: May 18, 2023
\ No newline at end of file diff --git a/v2.0.1/general/extensions/index.html b/v2.0.1/general/extensions/index.html index 218bd66..6d9645f 100644 --- a/v2.0.1/general/extensions/index.html +++ b/v2.0.1/general/extensions/index.html @@ -1 +1 @@ - Extensions - zotregistry.dev
Skip to content

Extensions

👉 Extensions provide additional registry features that are not a part of the Distribution Specification.

The following extensions are currently available with zot:

  • Search (enhanced)
  • Sync
  • Lint
  • Scrub
  • Trust
  • Metrics
  • Graphical user interface
  • User preferences

💡 For detailed information about configuring zot extensions, see Configuring zot.

About extensions

The OCI Distribution Specification supports extending the functionality of an OCI-compliant registry implementation by adding extensions. Extensions are new APIs developed outside of the core OCI specs. Developers may propose their extensions to the OCI for possible future addition to the Distribution Specification.

Wherever applicable, extensions can be dynamically discovered using the extensions support of the OCI Distribution Specification.

⚠ Extension features of zot are available only with a full zot image. They are excluded from the minimal zot image.

Extensions implemented in zot

The extensions implemented in zot include administrator-configured functionality and end-user features.

✏ Currently, search, trust, and userprefs are the only zot extensions operable by end users. Only these extensions are accessible through HTTP APIs and are discoverable using the OCI extensions mechanism.

The following extensions are currently supported by zot:

One of the key functions of a container image registry (which is essentially a graph of blobs) is the ability to perform interesting image and graph traversal queries. The user interacts with the search extension via a graphQL endpoint. The schema is published with every release.

Examples of queries are:

  • "Does an image exist?"
  • "What is its size?"
  • "Does an image depend on this image via its layers?"
  • "What vulnerabilities exist in an image or its dependent images?"

Sync

You can deploy a local mirror pointing to an upstream zot instance with various container image download policies, including on-demand and periodic downloads. The sync function is useful to avoid overwhelming the upstream instance, or if the upstream instance has rate-limited access.

💡 docker.io is supported as an upstream mirror.

Lint

The lint extension helps to avoid image compliance issues by enforcing certain policies about the image or the image metadata. Currently, lint can check an uploaded image to enforce the presence of required annotations such as the author or the license.

Scrub

Although container images are content-addressable with their SHA256 checksums, and validations are performed during storage and retrieval, it is possible that bit-rot sets in when not in use. The scrub extension actively scans container images in the background to proactively detect errors.

Trust

Images stored in zot can be signed with a digital signature to verify the source and integrity of the image. The digital signature can be verified by zot using public keys or certificates uploaded by the user through the zot API. The trust extension enables and configures this function.

Metrics

The metrics extension adds a node exporter, which is not present in the minimal build.

Graphical user interface

Using the zot graphical user interface (GUI), you can browse a zot registry for container images and artifacts. From the web interface, you can copy the shell commands for downloading an image using popular third-party tools such as docker, podman, and skopeo.

User preferences

The userprefs extension provides an API endpoint for adding configurable user preferences for a repository. This custom extension, not a part of the OCI distribution, is accessible only by authenticated users of the registry. Unauthenticated users are denied access.

The functions currently implemented by this extension include:

  • Toggling the star (favorites) icon for a repository.
  • Toggling the bookmark icon for a repository.

💡 For information about configuring zot extensions, see Configuring zot.

Last update: September 13, 2023
\ No newline at end of file + Extensions - zotregistry.dev
Skip to content

Extensions

👉 Extensions provide additional registry features that are not a part of the Distribution Specification.

The following extensions are currently available with zot:

  • Search (enhanced)
  • Sync
  • Lint
  • Scrub
  • Trust
  • Metrics
  • Graphical user interface
  • User preferences

💡 For detailed information about configuring zot extensions, see Configuring zot.

About extensions

The OCI Distribution Specification supports extending the functionality of an OCI-compliant registry implementation by adding extensions. Extensions are new APIs developed outside of the core OCI specs. Developers may propose their extensions to the OCI for possible future addition to the Distribution Specification.

Wherever applicable, extensions can be dynamically discovered using the extensions support of the OCI Distribution Specification.

⚠ Extension features of zot are available only with a full zot image. They are excluded from the minimal zot image.

Extensions implemented in zot

The extensions implemented in zot include administrator-configured functionality and end-user features.

✏ Currently, search, trust, and userprefs are the only zot extensions operable by end users. Only these extensions are accessible through HTTP APIs and are discoverable using the OCI extensions mechanism.

The following extensions are currently supported by zot:

One of the key functions of a container image registry (which is essentially a graph of blobs) is the ability to perform interesting image and graph traversal queries. The user interacts with the search extension via a graphQL endpoint. The schema is published with every release.

Examples of queries are:

  • "Does an image exist?"
  • "What is its size?"
  • "Does an image depend on this image via its layers?"
  • "What vulnerabilities exist in an image or its dependent images?"

Sync

You can deploy a local mirror pointing to an upstream zot instance with various container image download policies, including on-demand and periodic downloads. The sync function is useful to avoid overwhelming the upstream instance, or if the upstream instance has rate-limited access.

💡 docker.io is supported as an upstream mirror.

Lint

The lint extension helps to avoid image compliance issues by enforcing certain policies about the image or the image metadata. Currently, lint can check an uploaded image to enforce the presence of required annotations such as the author or the license.

Scrub

Although container images are content-addressable with their SHA256 checksums, and validations are performed during storage and retrieval, it is possible that bit-rot sets in when not in use. The scrub extension actively scans container images in the background to proactively detect errors.

Trust

Images stored in zot can be signed with a digital signature to verify the source and integrity of the image. The digital signature can be verified by zot using public keys or certificates uploaded by the user through the zot API. The trust extension enables and configures this function.

Metrics

The metrics extension adds a node exporter, which is not present in the minimal build.

Graphical user interface

Using the zot graphical user interface (GUI), you can browse a zot registry for container images and artifacts. From the web interface, you can copy the shell commands for downloading an image using popular third-party tools such as docker, podman, and skopeo.

User preferences

The userprefs extension provides an API endpoint for adding configurable user preferences for a repository. This custom extension, not a part of the OCI distribution, is accessible only by authenticated users of the registry. Unauthenticated users are denied access.

The functions currently implemented by this extension include:

  • Toggling the star (favorites) icon for a repository.
  • Toggling the bookmark icon for a repository.

💡 For information about configuring zot extensions, see Configuring zot.

Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/general/features/index.html b/v2.0.1/general/features/index.html index 38f614a..cb15da0 100644 --- a/v2.0.1/general/features/index.html +++ b/v2.0.1/general/features/index.html @@ -1 +1 @@ - Key Features - zotregistry.dev
Skip to content

Summary of Key Features

  • Conforms to OCI distribution spec APIs
  • Uses OCI image layout for image storage
    • Can serve any OCI image layout as a registry
  • Single binary for all the features
  • Doesn't require root privileges
  • Clear separation between core dist-spec and zot-specific extensions
  • Supports container image signatures - cosign and notation
  • Supports helm charts
  • Behavior controlled via configuration
  • Binaries released for multiple operating systems and architectures
  • Supports advanced image queries using search extension
  • Supports image deletion by tag
  • Currently suitable for on-premises deployments (e.g. colocated with Kubernetes)
  • Compatible with ecosystem tools such as skopeo and cri-o
  • Vulnerability scanning of images
  • TLS support Authentication via:
    • TLS mutual authentication
    • HTTP Basic (local htpasswd and LDAP)
    • HTTP Bearer token
  • Supports Identity-Based Access Control
  • Supports live modifications on the configuration file while zot is running (Authorization configuration only)
  • Inline storage optimizations:
    • Automatic garbage collection of orphaned blobs
    • Layer deduplication using hard links when content is identical
    • Data scrubbing
  • Serve multiple storage paths (and backends) using a single zot server
  • Pull and synchronize from other dist-spec conformant registries
  • Supports rate limiting including per HTTP method
  • Metrics with Prometheus
    • Using a node exporter in case of minimal zot
  • Swagger based documentation
  • zli: command-line client support
  • zb: a benchmarking tool for dist-spec conformant registries
  • Released under Apache 2.0 License
Last update: September 13, 2023
\ No newline at end of file + Key Features - zotregistry.dev
Skip to content

Summary of Key Features

  • Conforms to OCI distribution spec APIs
  • Uses OCI image layout for image storage
    • Can serve any OCI image layout as a registry
  • Single binary for all the features
  • Doesn't require root privileges
  • Clear separation between core dist-spec and zot-specific extensions
  • Supports container image signatures - cosign and notation
  • Supports helm charts
  • Behavior controlled via configuration
  • Binaries released for multiple operating systems and architectures
  • Supports advanced image queries using search extension
  • Supports image deletion by tag
  • Currently suitable for on-premises deployments (e.g. colocated with Kubernetes)
  • Compatible with ecosystem tools such as skopeo and cri-o
  • Vulnerability scanning of images
  • TLS support Authentication via:
    • TLS mutual authentication
    • HTTP Basic (local htpasswd and LDAP)
    • HTTP Bearer token
  • Supports Identity-Based Access Control
  • Supports live modifications on the configuration file while zot is running (Authorization configuration only)
  • Inline storage optimizations:
    • Automatic garbage collection of orphaned blobs
    • Layer deduplication using hard links when content is identical
    • Data scrubbing
  • Serve multiple storage paths (and backends) using a single zot server
  • Pull and synchronize from other dist-spec conformant registries
  • Supports rate limiting including per HTTP method
  • Metrics with Prometheus
    • Using a node exporter in case of minimal zot
  • Swagger based documentation
  • zli: command-line client support
  • zb: a benchmarking tool for dist-spec conformant registries
  • Released under Apache 2.0 License
Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/general/glossary/index.html b/v2.0.1/general/glossary/index.html index a644e43..2fd4aa7 100644 --- a/v2.0.1/general/glossary/index.html +++ b/v2.0.1/general/glossary/index.html @@ -1 +1 @@ - Glossary - zotregistry.dev
Skip to content

Glossary

Documentation Icons

Icon Description
✏ Note — A point of emphasis or caution.
💡 Tip — A helpful suggestion or a reference to additional material not covered in this document.
⚠ Warning — A suggestion or advisory intended to avoid a loss of service or data.

Definitions

Term Description
artifact A file of any kind produced during a container build process or associated with the operation of a container. For example, a Helm chart is an artifact that might be stored along with a container.
CNCF As part of the Linux Foundation, the Cloud Native Computing Foundation provides support, oversight, and direction for open-source, cloud native projects.
cosign cosign is a tool that performs container signing, verification, and storage in an OCI registry.
cosigned cosigned is an image admission controller that validates container images before deploying them.
cri-o cri-o is an implementation of the Kubernetes Container Runtime Interface (CRI) to enable using OCI compatible runtimes. It is a lightweight alternative to using Docker as the runtime for Kubernetes.
deduplication 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.
digest A hashed checksum, such as SHA-256, for verifying the integrity of the downloaded image.
Distribution Specification The OCI Distribution Specification project defines an API protocol to facilitate and standardize the distribution of content.
extensions Additional registry features (APIs) that are not a part of the Distribution Specification can be added as Extensions.
helm chart A helm chart is a package of files that orchestrate the deployment of Kubernetes resources into a Kubernetes cluster.
manifest An image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system.
node exporter A software component that collects hardware and operating system level metrics exposed by the kernel.
OCI The Open Container Initiative (OCI) is an open governance structure for the express purpose of creating open industry standards around container formats and runtimes.
ORAS OCI Registry as Storage (ORAS) is a tool for distributing OCI artifacts across OCI registries.
prometheus Prometheus is a node exporter that exposes a wide variety of hardware- and kernel-related metrics.
referrer An image containing a non-nil subject field with a descriptor to the referred image.
registry A service that stores and distributes container images and artifacts.
repository A collection of images with the same name, differentiated by tags.
skopeo skopeo is a command line utility that performs various operations on container images and image repositories.
stacker 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.
tag A label applied to an image that distinguishes the image from other images in the same repository. A common example is a version tag.
zb A benchmarking tool, available as a zot companion binary, for benchmarking a zot registry or any other container image registry that conforms to the OCI Distribution Specification.
zli A zot companion binary that implements a set of command line commands for interacting with the zot registry server.
zui A zot companion binary that implements a graphical user interface (GUI) for interacting with the zot registry server.
zxp A node exporter, available as a zot companion binary, that can be deployed with a minimal zot image in order to scrape metrics from the zot server.
Last update: August 4, 2023
\ No newline at end of file + Glossary - zotregistry.dev
Skip to content

Glossary

Documentation Icons

Icon Description
✏ Note — A point of emphasis or caution.
💡 Tip — A helpful suggestion or a reference to additional material not covered in this document.
⚠ Warning — A suggestion or advisory intended to avoid a loss of service or data.

Definitions

Term Description
artifact A file of any kind produced during a container build process or associated with the operation of a container. For example, a Helm chart is an artifact that might be stored along with a container.
CNCF As part of the Linux Foundation, the Cloud Native Computing Foundation provides support, oversight, and direction for open-source, cloud native projects.
cosign cosign is a tool that performs container signing, verification, and storage in an OCI registry.
cosigned cosigned is an image admission controller that validates container images before deploying them.
cri-o cri-o is an implementation of the Kubernetes Container Runtime Interface (CRI) to enable using OCI compatible runtimes. It is a lightweight alternative to using Docker as the runtime for Kubernetes.
deduplication 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.
digest A hashed checksum, such as SHA-256, for verifying the integrity of the downloaded image.
Distribution Specification The OCI Distribution Specification project defines an API protocol to facilitate and standardize the distribution of content.
extensions Additional registry features (APIs) that are not a part of the Distribution Specification can be added as Extensions.
helm chart A helm chart is a package of files that orchestrate the deployment of Kubernetes resources into a Kubernetes cluster.
manifest An image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system.
node exporter A software component that collects hardware and operating system level metrics exposed by the kernel.
OCI The Open Container Initiative (OCI) is an open governance structure for the express purpose of creating open industry standards around container formats and runtimes.
ORAS OCI Registry as Storage (ORAS) is a tool for distributing OCI artifacts across OCI registries.
prometheus Prometheus is a node exporter that exposes a wide variety of hardware- and kernel-related metrics.
referrer An image containing a non-nil subject field with a descriptor to the referred image.
registry A service that stores and distributes container images and artifacts.
repository A collection of images with the same name, differentiated by tags.
skopeo skopeo is a command line utility that performs various operations on container images and image repositories.
stacker 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.
tag A label applied to an image that distinguishes the image from other images in the same repository. A common example is a version tag.
zb A benchmarking tool, available as a zot companion binary, for benchmarking a zot registry or any other container image registry that conforms to the OCI Distribution Specification.
zli A zot companion binary that implements a set of command line commands for interacting with the zot registry server.
zui A zot companion binary that implements a graphical user interface (GUI) for interacting with the zot registry server.
zxp A node exporter, available as a zot companion binary, that can be deployed with a minimal zot image in order to scrape metrics from the zot server.
Last update: August 4, 2023
\ No newline at end of file diff --git a/v2.0.1/general/project/index.html b/v2.0.1/general/project/index.html index 78ed1ac..b439ce1 100644 --- a/v2.0.1/general/project/index.html +++ b/v2.0.1/general/project/index.html @@ -1 +1 @@ - About - zotregistry.dev
Skip to content
\ No newline at end of file + About - zotregistry.dev
Skip to content
\ No newline at end of file diff --git a/v2.0.1/general/releases/index.html b/v2.0.1/general/releases/index.html index 61a4830..f633d8c 100644 --- a/v2.0.1/general/releases/index.html +++ b/v2.0.1/general/releases/index.html @@ -1,3 +1,3 @@ Released Images - zotregistry.dev
Skip to content

Released Images for zot

👉 This document describes the available zot images for the various supported hardware and software platforms, along with information about image variations, image locations, and image naming formats.

Supported platforms

zot is supported on Linux and Apple MacOS platforms with Intel or ARM processors.

Table: Supported platforms and 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 (Apple M1)
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.

Full and minimal binary images

In addition to variations for specific platforms and architectures, binary images are also available in full and minimal flavors:

  • A full zot binary image is compiled with all extensions. Extensions include functions such as metrics, registry synchronization, search, and scrub.

  • A minimal distribution-spec conformant zot binary image is compiled with only a minimal set of code and libraries, reducing the attack surface. This option might be optimal for a registry embedded in a shipping product.

Binary image file naming

An executable binary image for zot is named using the target platform and architecture from the Supported platforms and architectures table. The general format of a binary image file name is one of these two:

zot-<os>-<architecture>

  • A full zot binary image with all extensions has a filename of the form zot-<os>-<architecture>. For example, the full binary image for an Intel-based linux server is zot-linux-amd64.

zot-<os>-<architecture>-minimal

  • A minimal distribution-spec conformant zot binary image has a filename of the form zot-<os>-<architecture>-minimal. For example, the minimal binary image for an Intel-based linux server is zot-linux-amd64-minimal.

💡 For convenience, you can rename the binary image file to simply zot after downloading.

Where to get zot

You can download native executable binary images or container (Docker) images.

Getting binary images

The zot project is hosted on GitHub at project-zot.

To download a binary image, go to the zot releases and select a release. Go to the Assets section of the release page and download the binary for your platform and architecture.

✏ You may need to use the chmod command to make the image executable.

✏ When downloading a binary image for MacOS, download the darwin image.

Getting container images

You can download a container image from ghcr.io by forming a URL with the desired image name, such as:

https://ghcr.io/project-zot/zot-<os>-<architecture>[-<build>]

If <build> is not specified, the default is full. For example, to download the minimal binary image for an Intel-based linux server. The URL is:

https://ghcr.io/project-zot/zot-linux-amd64-minimal
-

✏ When downloading a container image for MacOS, download the linux image, not the darwin image.

Licensing

zot is released under the Apache License 2.0.

Last update: July 31, 2023
\ No newline at end of file +

✏ When downloading a container image for MacOS, download the linux image, not the darwin image.

Licensing

zot is released under the Apache License 2.0.

Last update: July 31, 2023
\ No newline at end of file diff --git a/v2.0.1/general/whats-new/index.html b/v2.0.1/general/whats-new/index.html index 4494ab9..a6e4e69 100644 --- a/v2.0.1/general/whats-new/index.html +++ b/v2.0.1/general/whats-new/index.html @@ -1 +1 @@ - What's New - zotregistry.dev
Skip to content

What's New

v2.0.1

Support for hot reloading of LDAP credentials file

Since v2.0.0, LDAP credentials have been specified in a separate file. Starting with this version, the file is watched and changes applied without restarting zot.

Bugfixes and performance improvements

Under some configurations, zot consumes significant CPU and memory resources. This has been fixed in this release.

v2.0.0

Updated OCI support

Built-in UI support

  • Using the new zot GUI, you can browse a zot registry for container images and artifacts. The web interface provides the shell commands for downloading an image using popular third-party tools such as docker, podman, and skopeo.

Support for social logins

Group policies for authorization

  • When creating authorization policies, you can assign multiple users to a named group. A group-specific authorization policy can then be defined, specifying allowed access and actions for the group.

    ✏  Configuration syntax change: In the previous release, authorization policies were defined directly under the accessControl key in the zot configuration file. With the new ability to create authorization groups, it becomes necessary to add a new repositories key below accessControl. Beginning with zot v2.0.0, the set of authorization policies are now defined under the repositories key.

Signature verification

  • The validity of an image's signature can be verified by zot. Users can upload public keys or certificates to zot.

LDAP credentials stored separately from configuration

  • The LDAP credentials are removed from zot's LDAP configuration and stored in a separate file. See zot's LDAP documentation.

    ⚠ This LDAP configuration change is incompatible with previous zot releases. When upgrading, you must reconfigure your LDAP credentials if you use LDAP.

Storage deduplication on startup

  • Deduplication, a storage space saving feature, now runs or reverts at startup depending on whether the feature is enabled or disabled. You can trigger deduplication by enabling it and then restarting zot.

Retention policies

  • To optimize image storage, you can configure tag retention policies to remove images that are no longer needed.

CVE scanning support for image indexes

  • The trivy backend now supports vulnerability scanning of image indexes. Previously, only images were scanned.

Bookmarks

  • In the zot GUI, you can bookmark an image so that it can be easily found later. Bookmarked images appear in search queries when the bookmarked option is enabled.

Ability to delete tags from the UI

  • The zli search command allows smart searching for a repository by its name or for an image by its repo:tag.

Search by digest

  • You can perform a global search for a digest (SHA hash) using either the UI or the CLI. This function is useful when an issue is found in a layer that is used by multiple images. In the UI Search box, for example, begin typing sha256: followed by a partial or complete digest value to see a dropdown list of images that contain the layer with the digest value.
  • A GraphQL backend server within zot's registry search engine provides efficient and enhanced search capabilities. In addition to supporting direct GraphQL queries through the API, zot hosts the GraphQL Playground, which provides an interactive graphical environment for GraphQL queries.

Scheduling of background tasks

  • You can adjust the background scheduler based on your deployment requirements for tasks that are handled in the background, such as garbage collection. See Configuring zot.

Performance profiling for troubleshooting

Binaries for FreeBSD

  • zot binary images are available for the FreeBSD operating system. Supported architectures are amd64 and arm64.

    ✏  zot container images for FreeBSD will be available in a future release.

v1.4.3

Remote-only Storage Support

  • The two types of state (images and image metadata) can both now be on remote storage so that zot process lifecycle and its storage can be managed and scaled independently.

Digest Collision Detection During Image Deletion

  • When two or more image tags point to the same image digest and the image is deleted by digest causes data loss and dangling references. A new behavior-based policy called detectManifestCollision was added to prevent this.
Last update: January 25, 2024
\ No newline at end of file + What's New - zotregistry.dev
Skip to content

What's New

v2.0.1

Support for hot reloading of LDAP credentials file

Since v2.0.0, LDAP credentials have been specified in a separate file. Starting with this version, the file is watched and changes applied without restarting zot.

Bugfixes and performance improvements

Under some configurations, zot consumes significant CPU and memory resources. This has been fixed in this release.

v2.0.0

Updated OCI support

Built-in UI support

  • Using the new zot GUI, you can browse a zot registry for container images and artifacts. The web interface provides the shell commands for downloading an image using popular third-party tools such as docker, podman, and skopeo.

Support for social logins

Group policies for authorization

  • When creating authorization policies, you can assign multiple users to a named group. A group-specific authorization policy can then be defined, specifying allowed access and actions for the group.

    ✏  Configuration syntax change: In the previous release, authorization policies were defined directly under the accessControl key in the zot configuration file. With the new ability to create authorization groups, it becomes necessary to add a new repositories key below accessControl. Beginning with zot v2.0.0, the set of authorization policies are now defined under the repositories key.

Signature verification

  • The validity of an image's signature can be verified by zot. Users can upload public keys or certificates to zot.

LDAP credentials stored separately from configuration

  • The LDAP credentials are removed from zot's LDAP configuration and stored in a separate file. See zot's LDAP documentation.

    ⚠ This LDAP configuration change is incompatible with previous zot releases. When upgrading, you must reconfigure your LDAP credentials if you use LDAP.

Storage deduplication on startup

  • Deduplication, a storage space saving feature, now runs or reverts at startup depending on whether the feature is enabled or disabled. You can trigger deduplication by enabling it and then restarting zot.

Retention policies

  • To optimize image storage, you can configure tag retention policies to remove images that are no longer needed.

CVE scanning support for image indexes

  • The trivy backend now supports vulnerability scanning of image indexes. Previously, only images were scanned.

Bookmarks

  • In the zot GUI, you can bookmark an image so that it can be easily found later. Bookmarked images appear in search queries when the bookmarked option is enabled.

Ability to delete tags from the UI

  • The zli search command allows smart searching for a repository by its name or for an image by its repo:tag.

Search by digest

  • You can perform a global search for a digest (SHA hash) using either the UI or the CLI. This function is useful when an issue is found in a layer that is used by multiple images. In the UI Search box, for example, begin typing sha256: followed by a partial or complete digest value to see a dropdown list of images that contain the layer with the digest value.
  • A GraphQL backend server within zot's registry search engine provides efficient and enhanced search capabilities. In addition to supporting direct GraphQL queries through the API, zot hosts the GraphQL Playground, which provides an interactive graphical environment for GraphQL queries.

Scheduling of background tasks

  • You can adjust the background scheduler based on your deployment requirements for tasks that are handled in the background, such as garbage collection. See Configuring zot.

Performance profiling for troubleshooting

Binaries for FreeBSD

  • zot binary images are available for the FreeBSD operating system. Supported architectures are amd64 and arm64.

    ✏  zot container images for FreeBSD will be available in a future release.

v1.4.3

Remote-only Storage Support

  • The two types of state (images and image metadata) can both now be on remote storage so that zot process lifecycle and its storage can be managed and scaled independently.

Digest Collision Detection During Image Deletion

  • When two or more image tags point to the same image digest and the image is deleted by digest causes data loss and dangling references. A new behavior-based policy called detectManifestCollision was added to prevent this.
Last update: January 25, 2024
\ No newline at end of file diff --git a/v2.0.1/index.html b/v2.0.1/index.html index ea222e4..96b3f71 100644 --- a/v2.0.1/index.html +++ b/v2.0.1/index.html @@ -1 +1 @@ - Zot Registry - zotregistry.dev

Zot Registry

OCI-native container image registry, simplified

  accepted as a CNCF Sandbox Project

@zothub #zot Community

Get Started User Guide

Try out our beta deployment at zothub.io

Pair zot with stacker, an OCI-native Image Builder and other ecosystem tools

OCI-native Image Registry

  • OCI Standards

    Strongly conforms to OCI Standards (Distribution and Image Specifications)

  • Single Binary

    One statically built binary for simplified download and install with no additional dependencies or services.

  • Unprivileged

    Doesn't require elevated privileges on host.

  • Features vs Security

    Separate Full (all features included) or Minimal (stripped for security) builds.

  • Support For Multiple Platforms

    Linux, MacOS, Intel, Arm, Raspberry PI, Cloud, Bare-metal ...

  • Batteries Included

    All features such as security scanning, authentication, authorization, garbage collection, deduplication and so on, included in the same binary.

  • Open Source

    Released as an open source project under Apache2 License.

  • Sponsors

  • Adopters

+ Zot Registry - zotregistry.dev

Zot Registry

OCI-native container image registry, simplified

  accepted as a CNCF Sandbox Project

@zothub #zot Community

Get Started User Guide

Try out our beta deployment at zothub.io

Pair zot with stacker, an OCI-native Image Builder and other ecosystem tools

OCI-native Image Registry

  • OCI Standards

    Strongly conforms to OCI Standards (Distribution and Image Specifications)

  • Single Binary

    One statically built binary for simplified download and install with no additional dependencies or services.

  • Unprivileged

    Doesn't require elevated privileges on host.

  • Features vs Security

    Separate Full (all features included) or Minimal (stripped for security) builds.

  • Support For Multiple Platforms

    Linux, MacOS, Intel, Arm, Raspberry PI, Cloud, Bare-metal ...

  • Batteries Included

    All features such as security scanning, authentication, authorization, garbage collection, deduplication and so on, included in the same binary.

  • Open Source

    Released as an open source project under Apache2 License.

  • Sponsors

  • Adopters

\ No newline at end of file diff --git a/v2.0.1/install-guides/install-guide-k8s/index.html b/v2.0.1/install-guides/install-guide-k8s/index.html index e6b26da..6fa35f3 100644 --- a/v2.0.1/install-guides/install-guide-k8s/index.html +++ b/v2.0.1/install-guides/install-guide-k8s/index.html @@ -41,7 +41,7 @@ service: type: NodePort port: 5000 -

The configurable settings in the chart are listed in the following table:

parameter description

replicaCount

Desired number of replicas of the application

image.repository

Repository and image name for the application

image.pullPolicy

Whether to pull the image from the repository. If not specified, the policy depends on image.tag:

  • If tag is :latest or no tag: Always

  • If tag is other than :latest: IfNotPresent

image.tag

Identifies different versions the image. default is the chart appVersion.

Examples: :latest (the default) or :v2.0.1

serviceAccount.create

Specifies whether a service account should be created

serviceAccount.annotations

Annotations to add to the service account

serviceAccount.name

Name of the service account to use. If name is not set and create is true, a name is generated using the fullname template.

service.type

ClusterIP (default), NodePort, LoadBalancer, ExternalName, or Headless

service.port

Port number for calling the service

Customizing the Helm chart using 'set'

To override the default values in the chart, you can pass your custom values by adding the --set flag in the helm install command.

For example, if your servers use an ARM processor instead of Intel, you must change the image.repository name from zot-linux-amd64 to zot-linux-arm64:

--set image.repository=ghcr.io/project-zot/zot-linux-arm64

You can change multiple settings with one --set statement. For example, you might want your installation to have more replicas or a different port number:

--set replicaCount=2,service.port=5050

Customizing the Helm chart using a file

You can also create a YAML file with your overrides and then add the new file by adding the -f flag to the helm install command. For example, to override the replica count and port number, the contents of your YAML file (for example, "myfile.yaml") would be:

replicaCount: 2
+

The configurable settings in the chart are listed in the following table:

parameter description

replicaCount

Desired number of replicas of the application

image.repository

Repository and image name for the application

image.pullPolicy

Whether to pull the image from the repository. If not specified, the policy depends on image.tag:

  • If tag is :latest or no tag: Always

  • If tag is other than :latest: IfNotPresent

image.tag

Identifies different versions the image. default is the chart appVersion.

Examples: :latest (the default) or :v2.0.1

serviceAccount.create

Specifies whether a service account should be created

serviceAccount.annotations

Annotations to add to the service account

serviceAccount.name

Name of the service account to use. If name is not set and create is true, a name is generated using the fullname template.

service.type

ClusterIP (default), NodePort, LoadBalancer, ExternalName, or Headless

service.port

Port number for calling the service

strategy.type

Kubernetes deployment strategy type. [More Info](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy)

Customizing the Helm chart using 'set'

To override the default values in the chart, you can pass your custom values by adding the --set flag in the helm install command.

For example, if your servers use an ARM processor instead of Intel, you must change the image.repository name from zot-linux-amd64 to zot-linux-arm64:

--set image.repository=ghcr.io/project-zot/zot-linux-arm64

You can change multiple settings with one --set statement. For example, you might want your installation to have more replicas or a different port number:

--set replicaCount=2,service.port=5050

Customizing the Helm chart using a file

You can also create a YAML file with your overrides and then add the new file by adding the -f flag to the helm install command. For example, to override the replica count and port number, the contents of your YAML file (for example, "myfile.yaml") would be:

replicaCount: 2
 service:
   port: 5050

and the following flag would be added to the helm install command:

-f myfile.yaml

Additional information

See the Helm documentation for further information about modifying the Helm chart.

Step 3: Install zot

Install zot using the helm install command. The first example shows how to perform a default installation. The additional examples show different ways to modify the helm install command to override default settings in the Helm chart:

Example 1: use default chart parameters

helm install zot project-zot/zot

NAME: zot
@@ -76,4 +76,4 @@
         "level": "debug"
     }
 }
-

The zot configuration file is located at /etc/zot/config.json.

Refer to Configuring zot for complete information on configuring the zot server with the zot configuration file.

Uninstalling zot

Should you need to uninstall zot, use the helm uninstall command, as in this example:

helm uninstall zot

Last update: January 16, 2024
\ No newline at end of file +

The zot configuration file is located at /etc/zot/config.json.

Refer to Configuring zot for complete information on configuring the zot server with the zot configuration file.

Uninstalling zot

Should you need to uninstall zot, use the helm uninstall command, as in this example:

helm uninstall zot

Last update: February 22, 2024
\ No newline at end of file diff --git a/v2.0.1/install-guides/install-guide-linux/index.html b/v2.0.1/install-guides/install-guide-linux/index.html index 24c5e8d..fa2a251 100644 --- a/v2.0.1/install-guides/install-guide-linux/index.html +++ b/v2.0.1/install-guides/install-guide-linux/index.html @@ -1,4 +1,6 @@ - Installing zot on Bare Metal Linux - zotregistry.dev
Skip to content

Installing zot on Bare Metal Linux

👉 Using an available executable zot image, you can easily deploy zot on a Linux server.

Before you begin

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.

Installation

Step 1: Get zot

Using wget, download the appropriate zot binary image for your platform from the zot GitHub project. Download the image to the`/usr/bin/` directory and rename it to zot, as in this example:

wget -O /usr/bin/zot  https://github.com/project-zot/zot/releases/download/v2.0.1/zot-linux-amd64
+ Installing zot on Bare Metal Linux - zotregistry.dev      
 
  
  
 
 
 
 
 
 
  
 
 
 
 
 
  
 
 
 
 
 
Installing zot on Bare Metal Linux
 
 
👉 Using an available executable zot image, you can easily deploy zot on a Linux server.
 
 
Before you begin
 
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.
 
Installation
 
Step 1: Get zot
 
Using wget, download the appropriate zot binary image for your platform from the zot GitHub project. Download the image to the`/usr/bin/` directory and rename it to zot, as in this example:
 
sudo wget -O /usr/bin/zot https://github.com/project-zot/zot/releases/download/v2.0.1/zot-linux-amd64
+
 
Then fix permissions to it:
 
sudo chmod +x /usr/bin/zot
+sudo chown root:root /usr/bin/zot
 
 
Step 2: Create a zot configuration file
 
Create a zot configuration file as /etc/zot/config.json.
 
See Configuration file options for an example file with options and recommendations. You can find other configuration file examples in the zot GitHub project and in Configuring zot.
 
Step 3: Configure a local authentication account
 
If you want to use local authentication with zot, create a /etc/zot/htpasswd file with an initial account entry using the htpasswd command as in this example:
 
htpasswd -bnB myUserName myPassword > /etc/zot/htpasswd
 
 
To add additional local users, use the >> redirect as in this example:
 
htpasswd -bnB myUserName2 myPassword2 >> /etc/zot/htpasswd
 
 
Step 4: Define the zot service
 
Create a /etc/systemd/system/zot.service file to define the zot service in systemd. The following is an example service file for zot:
 
[Unit]
@@ -26,10 +28,11 @@
 sudo mkdir -p /var/log/zot
 sudo chown -R zot:zot /var/log/zot
 
-sudo chown root:root /usr/bin/zot
-sudo chown root:root config.json
-
 
With the adduser options shown, the 'zot' user ID has no local directory. There is no ability to log into the zot user account, and the account has no finger information.
 
Step 6: Start zot
 
Enable and start the zot service with these commands:
 
sudo systemctl enable zot
+sudo chown -R root:root /etc/zot/
+
 
With the adduser options shown, the 'zot' user ID has no local directory. There is no ability to log into the zot user account, and the account has no finger information.
 
Step 6: Start zot
 
Reload systemd config:
 
sudo systemctl daemon-reload
+
 
Enable and start the zot service with these commands:
 
sudo systemctl enable zot
 sudo systemctl start zot
+
 
Check if zot config is valid:
 
sudo -u zot zot verify /etc/zot/config.json
 
 
When the zot service has started, you can check its status with this command:
 
sudo systemctl status zot
 
 
After the installation
 
If your zot registry server is public facing, we recommend that you test your TLS configuration using a service such as the Qualys SSL Server Test.
 
Refer to Configuring zot for further information about maintaining your zot registry server.
 
 
Configuration file options and recommendations
 
The following zot configuration file (config.json) can be used as a template for your own installation. You can modify this file to suit your own environment.
 
 Click here to view the sample configuration file. 
{
   "distSpecVersion":"1.0.1",
@@ -109,4 +112,4 @@
     }
   ]
 }
-
 
 
  Last update: January 16, 2024  
 
 
 
  
 
 
 
 
 
 Copyright © 2019 - 2024 The zot project authors, All Rights Reserved. | The Linux Foundation® (TLF) has registered trademarks and uses trademarks. For a list of TLF trademarks, see Trademark Usage 
 
 
          
 
 
 
 
 
 
 
    
\ No newline at end of file
+
Last update: February 22, 2024
\ No newline at end of file diff --git a/v2.0.1/pdf/document.pdf b/v2.0.1/pdf/document.pdf index 938ca9d..ba1e4ed 100644 Binary files a/v2.0.1/pdf/document.pdf and b/v2.0.1/pdf/document.pdf differ diff --git a/v2.0.1/search/search_index.json b/v2.0.1/search/search_index.json index 9f720cd..fb4fa54 100644 --- a/v2.0.1/search/search_index.json +++ b/v2.0.1/search/search_index.json @@ -1 +1 @@ -{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"admin-guide/admin-configuration/","title":"Configuring zot","text":"

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.

"},{"location":"admin-guide/admin-configuration/#configuration-file","title":"Configuration file","text":"

The configuration file is a JSON or YAML file that contains all configuration settings for zot functions such as:

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:

{\n    \"distSpecVersion\": \"1.0.1\",\n    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\"\n    },\n    \"http\": {\n        \"address\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"log\": {\n        \"level\": \"debug\"\n    }\n}\n

The configuration file contains the Distribution Specification version (distSpecVersion). The structure and content of other attributes are described in the later sections of this guide.

"},{"location":"admin-guide/admin-configuration/#extensions","title":"Extensions","text":"

Additional registry features that are not a part of the Distribution Specification are allowed to be added as Extensions.

With a full (not minimal) zot image, the following extension features can be enabled and configured under an extensions attribute in the configuration file as shown in the following example.

{\n  ...\n  \"extensions\": {\n    \"metrics\": {},\n    \"sync\": {},\n    \"search\": {},\n    \"scrub\": {},\n    \"lint\": {},\n    \"trust\": {},\n    \"ui\": {}\n  }\n}\n

The extension features are available only with a full zot image. With a minimal zot image, the extensions section is ignored if present.

The following features are configured under the extensions attribute.

An extension feature is usually enabled by the presence of the feature\u2019s attribute under extensions. An extension feature can then be disabled by either omitting the feature attribute or by including an enable attribute with a value of false.

Two API-only extensions, User Preferences and Mgmt, are not enabled or configured under the extensions section of the configuration file. These API-only extensions are enabled as follows:

"},{"location":"admin-guide/admin-configuration/#enabling-and-disabling-extensions","title":"Enabling and disabling extensions","text":"

Following is an example of enabling or disabling a feature in the extensions section. The scrub feature is enabled in these two configurations:

\"extensions\": {\n  \"scrub\": {}\n}\n
\"extensions\": {\n  \"scrub\": {\n    \"enable\": true\n  }\n}\n

The scrub feature is disabled in these two configurations:

\"extensions\": {\n}\n
\"extensions\": {\n  \"scrub\": {\n    \"enable\": false\n  }\n}\n
"},{"location":"admin-guide/admin-configuration/#developing-custom-extensions","title":"Developing custom extensions","text":"

New functionality can be added to the zot registry by developing custom extensions for integration into zot. For information about developing extensions, see Developing New Extensions.

"},{"location":"admin-guide/admin-configuration/#network-configuration","title":"Network configuration","text":"

Use the http attribute in the configuration file to configure the zot network settings, as shown in the following example.

\"http\": {\n  \"address\":\"127.0.0.1\",\n  \"port\":\"8080\",\n  \"realm\":\"zot\",\n  \"tls\": {\n    \"cert\":\"test/data/server.cert\",\n    \"key\":\"test/data/server.key\"\n  }\n}\n

The following table lists the configurable attributes.

Attribute Description address The IP address of the zot server. port The port number of the zot server. realm The security policy domain defined for the server. tls The included attributes in this section specify the Transport Layer Security (TLS) settings for the server. cert The path and filename of the server\u2019s SSL/TLS certificate. key The path and filename of the server\u2019s registry key."},{"location":"admin-guide/admin-configuration/#storage","title":"Storage","text":"

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.

Filesystem storage is configured with the storage attribute in the zot configuration file, as shown in the following simple example.

\"storage\":{\n  \"rootDirectory\":\"/tmp/zot\",\n  \"commit\": true,\n  \"dedupe\": true,\n  \"gc\": true,\n  \"gcDelay\": \"1h\",\n  \"gcInterval\": \"24h\"\n}\n

With zot, you have the option to store your registry image files either in local filesystem storage or in cloud storage, such as an Amazon Simple Storage Service (S3) bucket.

"},{"location":"admin-guide/admin-configuration/#local-storage","title":"Local storage","text":"

zot can store and serve files from one or more local directories (folders). 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.

"},{"location":"admin-guide/admin-configuration/#remote-storage","title":"Remote storage","text":"

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.

For detailed information about configuring S3 storage, see the AWS S3 documentation and Storage Planning with zot.

"},{"location":"admin-guide/admin-configuration/#storage-features","title":"Storage features","text":""},{"location":"admin-guide/admin-configuration/#commit","title":"Commit","text":"

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.

"},{"location":"admin-guide/admin-configuration/#deduplication","title":"Deduplication","text":"

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.

"},{"location":"admin-guide/admin-configuration/#garbage-collection","title":"Garbage collection","text":"

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. The zot configuration model allows for enabling and disabling garbage collection (gc). The model also allows the configuration of a tunable delay (gcDelay), which can be set depending on client network speeds and the size of blobs.

"},{"location":"admin-guide/admin-configuration/#scrub","title":"Scrub","text":"

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.

"},{"location":"admin-guide/admin-configuration/#configuring-storage","title":"Configuring storage","text":"

For detailed information about configuring local or remote storage and storage features for your zot registry, see Storage Planning with zot.

"},{"location":"admin-guide/admin-configuration/#security-and-hardening","title":"Security and hardening","text":""},{"location":"admin-guide/admin-configuration/#authentication","title":"Authentication","text":"

zot supports authentication by the following methods:

For detailed information about configuring authentication for your zot registry, see User Authentication and Authorization with zot.

"},{"location":"admin-guide/admin-configuration/#identity-based-authorization","title":"Identity-based authorization","text":"

User identity can be used as an authorization criterion for allowing actions on one or more repository paths. For specific users, you can choose to allow any combination of read, create, update, or delete actions on specific repository paths.

For detailed information about configuring access control policies for your zot registry, see User Authentication and Authorization with zot.

"},{"location":"admin-guide/admin-configuration/#preventing-automated-attacks-with-failure-delay","title":"Preventing automated attacks with failure delay","text":"

Use the auth and failDelay attributes under http in the configuration file to delay the response to an authentication failure. A delayed response helps to prevent automated attacks. The configuration is shown in the following example.

\"http\": {\n  \"auth\": {\n    \"failDelay\": 5\n  }\n}\n

The failDelay attribute specifies a waiting time, in seconds, before zot sends a failure notification to an authenticating user who has been denied access.

"},{"location":"admin-guide/admin-configuration/#rate-limiting","title":"Rate limiting","text":"

You can limit the rate of API calls from users by configuring the Ratelimit attribute in the configuration file, as shown in the following example:

\"http\": {\n    \"address\": \"127.0.0.1\",\n    \"port\": \"8080\",\n    \"Ratelimit\": {\n        \"Rate\": 10,\n        \"Methods\": [\n            {\n                \"Method\": \"GET\",\n                \"Rate\": 5\n            }\n        ]\n    }\n}\n

In this example, the Rate attribute directly under Ratelimit sets a global rate limit of ten API calls per second. You can optionally override the global limit for specific API Methods. In this example, API GET calls are limited to five per second.

"},{"location":"admin-guide/admin-configuration/#additional-security-features","title":"Additional security features","text":"

For detailed information about configuring additional security features for your zot registry, see Security Posture.

"},{"location":"admin-guide/admin-configuration/#monitoring","title":"Monitoring","text":"

zot supports a range of monitoring tools including the following:

When zot is deployed in a Kubernetes setup, a site reliability engineering (SRE) operator can monitor service level indicators (SLI) such as metrics and logs. Metrics will appear in Prometheus using the zot metrics extension, while logs will appear in the Elasticsearch stack (ELK stack) using Filebeat.

For detailed information about the monitoring tools, see Monitoring the registry.

For detailed information about benchmarking, see Benchmarking zot with zb.

For detailed information about performance profiling, see Performance Profiling in zot.

"},{"location":"admin-guide/admin-configuration/#clustering-zot","title":"Clustering zot","text":"

To ensure high-availability of the registry, zot supports a clustering scheme with stateless zot instances/replicas fronted by a loadbalancer and a shared remote backend storage. This scheme allows the registry service to remain available even if a few replicas fail or become unavailable. Loadbalancing across many zot replicas can also increase aggregate network throughput.

For detailed information about clustering with zot, see zot Clustering.

"},{"location":"admin-guide/admin-configuration/#syncing-and-mirroring-registries","title":"Syncing and mirroring registries","text":"

A zot registry can mirror one or more upstream OCI registries, including popular cloud registries such as Docker Hub and Google Container Registry. If an upstream registry is OCI distribution-spec conformant for pulling images, you can use zot's sync extension feature to implement a downstream mirror, synchronizing OCI images and corresponding artifacts. Synchronization between registries can be implemented by periodic polling of the upstream registry or synchronization can occur on demand, when a user pulls an image from the downstream registry.

As with git, wherein every clone is a full repository, you can configure a local zot instance to be a full OCI mirror registry. This allows for a fully distributed disconnected container image build pipeline.

For detailed information about syncing and mirroring, see OCI Registry Mirroring With zot.

"},{"location":"admin-guide/admin-configuration/#linting-uploaded-images","title":"Linting uploaded images","text":"

The lint extension can check an uploaded image to enforce the presence of required annotations such as the author or the license.

To configure linting, add the lint attribute under extensions in the configuration file, as shown in the following example:

\"extensions\": {\n    \"lint\": {\n      \"enable\": true,\n      \"mandatoryAnnotations\": [\"annot1\", \"annot2\", \"annot3\"]\n      }\n  }\n

The following table lists the configurable attributes of the lint extension.

Attribute Description enable If this attribute is missing, incoming image linting is disabled by default. Linting can be enabled by including this attribute and setting it to true. mandatoryAnnotations A list of annotations that are required to be present in the image being pushed to the repository.

If the mandatory annotations option is configured when you push an image, linter will verify that the mandatory annotations list present in the configuration is also found in the manifest's annotations list. If any annotations are missing, the push is denied.

"},{"location":"admin-guide/admin-configuration/#verifying-the-signatures-of-uploaded-images","title":"Verifying the signatures of uploaded images","text":"

The trust extension provides a mechanism to verify image signatures using certificates and public keys.

To enable image signature verification, you must add the trust attribute under extensions in the zot configuration file and enable one or more verification tools, as shown in the following example:

\"extensions\": {\n  \"trust\": {\n    \"enable\": true,\n    \"cosign\": true,\n    \"notation\": true\n  }\n}\n

You must also upload public keys (for cosign) or certificates (for notation) that can be used to verify the image signatures.

For detailed information about configuring image signature verification, see Verifying image signatures.

"},{"location":"admin-guide/admin-configuration/#enabling-the-registrys-graphical-user-interface","title":"Enabling the registry's graphical user interface","text":"

Using the zot graphical user interface (GUI), a user can browse a zot registry for container images and artifacts.

To configure zot's GUI, add the ui attribute under extensions in the configuration file, as shown in the following example:

\"extensions\": {\n  \"ui\": {\n    \"enable\": true\n  }\n}\n

The following table lists the configurable attributes of the ui extension.

Attribute Description enable If this attribute is missing, the zot GUI is disabled by default. The GUI can be enabled by including this attribute and setting it to true."},{"location":"admin-guide/admin-configuration/#scrubbing-the-image-registry","title":"Scrubbing the image registry","text":"

To check the integrity of the filesystem and the data in the registry, you can schedule a periodic scrub operation. The scrub process traverses the filesystem, verifying that all data blocks are readable. While running, the process may slightly reduce the registry performance.

To enable scrubbing, add the scrub attribute under extensions in the configuration file, as shown in the following example:

\"extensions\": {\n  \"scrub\": {\n    \"enable\": true,\n    \"interval\": \"24h\"\n  }\n}\n

The following table lists the configurable attributes for scrubbing the registry.

Attribute Description enable If this attribute is missing, registry scrubbing is enabled by default. Scrubbing can be disabled by setting this attribute to false. interval The time interval between periodic scrub operations. This value must be at least two hours (2h)."},{"location":"admin-guide/admin-configuration/#scheduling-background-tasks","title":"Scheduling background tasks","text":"

Some zot functions, such as garbage collection and registry synchronization, run as background tasks. These tasks are queued and executed by the scheduler.

The scheduler is by default allowed to simultaneously run a maximum number of tasks equal to four times the number of CPUs available to the zot process. For most users, there should be no need to modify this maximum number. If such a need arises, you can configure a new maximum number of simultaneous tasks in the numWorkers property of the scheduler attribute in the configuration file, as shown in the following example.

{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"scheduler\": {\n    \"numWorkers\": 3\n  },\n...\n}\n
"},{"location":"admin-guide/admin-configuration/#enhanced-searching-and-querying-images","title":"Enhanced searching and querying images","text":"

While basic searching is always enabled for images in the zot registry, you can enable enhanced registry searching and filtering using graphQL.

Add the search attribute under extensions in the configuration file to enable and configure the enhanced search extension, as shown in the following example.

\"extensions\": {\n  \"search\": {\n    \"enable\": true,\n    \"cve\": {\n      \"updateInterval\": \"2h\"\n    }\n  }\n}\n

The following table lists the configurable attributes for enhanced search.

Attribute Description enable If this attribute is missing, enhanced search is enabled by default. Enhanced search can be disabled by setting this attribute to false. cve Extends enhanced search to allow searching of Common Vulnerabilities and Exposures (CVE). updateInterval Sets the interval at which the searchable database of CVE items is refreshed."},{"location":"admin-guide/admin-configuration/#setting-user-preferences","title":"Setting user preferences","text":"

The user preferences extension provides an API endpoint for adding configurable user preferences for a repository. This custom extension, not a part of the OCI distribution, is accessible only by authenticated users of the registry. Unauthenticated users are denied access.

The user preferences extension is enabled by default when the search and ui extensions are enabled. There are no other configuration file fields for this extension.

A userprefs API endpoint accepts as a query parameter an action to perform along with any other required parameters for the specified action. The actions currently implemented do not require an HTTP payload, nor do they return any related data other than an HTTP response code.

"},{"location":"admin-guide/admin-configuration/#current-functionality","title":"Current functionality","text":"

The current functions implemented by this extension include:

"},{"location":"admin-guide/admin-configuration/#toggle-repository-star","title":"Toggle repository star","text":"

This action sets the repository star property to true if it is false, and to false if it is true.

Action Parameter Parameter Description toggleStar repo The name of the repository whose star is to be changed

This example toggles a star on a repository named repoName:

PUT\nhttp://localhost:5000/v2/_zot/ext/userprefs?\naction=toggleStar&repo=repoName\n
"},{"location":"admin-guide/admin-configuration/#toggle-repository-bookmark","title":"Toggle repository bookmark","text":"

This action sets the repository bookmark property to true if it is false, and to false if it is true.

Action Parameter Parameter Description toggleBookmark repo The name of the repository whose bookmark is to be changed

This example toggles a bookmark on a repository named repoName:

PUT\nhttp://localhost:5000/v2/_zot/ext/userprefs?\naction=toggleBookmark&repo=repoName\n
"},{"location":"admin-guide/admin-configuration/#verifying-the-configuration-file","title":"Verifying the configuration file","text":"

Before launching zot, verify the syntax of your configuration file using the following command:

zot verify <configfile>

Verifying the configuration file protects against operator errors and any conflicts arising from zot release version changes.

After verifying your configuration file, you can launch zot with the following command:

zot serve <configfile>

"},{"location":"admin-guide/admin-getting-started/","title":"Getting Started with zot Administration","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#installing-zot","title":"Installing zot","text":""},{"location":"admin-guide/admin-getting-started/#how-to-get-zot","title":"How to get zot","text":"

The zot project is hosted on GitHub at project-zot. From GitHub, you can download zot executable binary images or full source code.

"},{"location":"admin-guide/admin-getting-started/#supported-platforms","title":"Supported platforms","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#about-binary-images","title":"About binary images","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#deployment-methods","title":"Deployment methods","text":"

Several options exist for deploying zot:

"},{"location":"admin-guide/admin-getting-started/#deploying-a-zot-binary-image","title":"Deploying a zot binary image","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#example-deploying-with-a-container-manager","title":"Example: Deploying with a container manager","text":"

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\n\npodman run -p 5000:5000 ghcr.io/project-zot/zot-minimal-linux-amd64:latest\n
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\n

Each of these example commands pulls a zot binary image from the GitHub Container Registry (ghcr.io) and launches a zot image registry at http://localhost:5000.

Click here to view an example of deploying using docker.

"},{"location":"admin-guide/admin-getting-started/#building-zot-from-source","title":"Building zot from source","text":""},{"location":"admin-guide/admin-getting-started/#prerequisites","title":"Prerequisites","text":""},{"location":"admin-guide/admin-getting-started/#install-golang","title":"Install golang","text":"

Follow the golang instructions to install the golang toolchain. After installation, make sure that the path environment variable or your IDE can find the toolchain.

You must use a golang version of at least the minimum specified in go.mod or the build will fail.

"},{"location":"admin-guide/admin-getting-started/#building-an-executable-binary-from-source","title":"Building an executable binary from source","text":"

Download or clone the full zot project from GitHub at project-zot. To clone the zot project from GitHub, use this command:

git clone https://github.com/project-zot/zot.git\n

To build zot, execute the make command in the zot directory using the following general syntax:

make OS=os ARCH=architecture {binary | binary-minimal}

For example, to build a zot image with extensions for an Intel-based linux server, use the following command:

make OS=linux ARCH=amd64 binary\n

The make command builds an executable image in the zot/bin directory. The original filename of the zot executable image will indicate the build options. For example, the filename of an Intel-based linux minimal image is zot-linux-amd64-minimal.

For convenience, you can rename the binary image file to simply zot.

"},{"location":"admin-guide/admin-getting-started/#building-a-zot-container-image-from-source","title":"Building a zot container image from source","text":"

with Stacker

Using the settings in stacker.yaml, you can build a container image that runs the latest zot by running the following command:

make binary-stacker\n

with Docker

A sample Dockerfile is provided on the zot project page in GitHub. You can edit the sample file with your specific values, such as the desired operating system, hardware architecture, and full or minimal build, as in this example:

ARG OS=linux\nARG ARCH=amd64\n\nRUN make COMMIT=$COMMIT OS=$OS ARCH=$ARCH clean binary-minimal\n

Using your edited Dockerfile, you can build a container image that runs the latest zot by running the following command:

make image\n
"},{"location":"admin-guide/admin-getting-started/#deploying-the-container-image","title":"Deploying the container image","text":"

Deploy the image using your container manager, such as Podman, runc, Helm, or Docker, as in these examples:

with Podman

podman run --rm -it -p 5000:5000 -v $(pwd)/registry:/var/lib/registry zot:latest\n

with Docker

docker run --rm -it -p 5000:5000 -v $(pwd)/registry:/var/lib/registry zot:latest\n

A container image built with the sample Dockerfile and deployed with the example command results in a running registry at http://localhost:5000. Registry content is stored at .registry, which is bind mounted to /var/lib/registry in the container. By default, auth is disabled. As part of the build, a YAML configuration file is created at /etc/zot/config.yml in the container.

You can override the configuration file with custom configuration settings in the deployment command and in a local configuration file as shown in this example:

podman run --rm -p 8080:8080 \\\n  -v $(pwd)/custom-config.yml:/etc/zot/config.yml \\\n  -v $(pwd)/registry:/tmp/zot \\\n  zot:latest\n

This command causes the registry to listen on port 8080 and to use /tmp/zot for content storage.

"},{"location":"admin-guide/admin-getting-started/#additional-recommended-steps","title":"Additional recommended steps","text":"

We recommend that, when deploying zot, you also install the command line (zli) and benchmarking (zb) packages.

"},{"location":"admin-guide/admin-getting-started/#launching-zot","title":"Launching zot","text":"

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.yml

For convenience, you can rename the binary image file to simply zot.The instructions and examples in this guide use zot as the name of the zot executable file and do not include the path to the executable file.

"},{"location":"admin-guide/admin-getting-started/#next-steps","title":"Next Steps","text":""},{"location":"admin-guide/admin-getting-started/#configuring-zot","title":"Configuring zot","text":"

You configure zot primarily through adding and modifying settings in the zot configuration file. The configuration file is a JSON or YAML file that contains all configuration settings for zot functions.

When you first build zot or deploy an image or container from the distribution, a basic configuration file config.json is created. You can modify the initial file or you can create a new file.

Follow the instructions in Configuring zot, to compose a configuration file with the settings and features you require for your zot registry server.

"},{"location":"articles/authn-authz/","title":"User Authentication and Authorization with zot","text":"

A robust set of authentication/authorization options are supported:

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.

"},{"location":"articles/authn-authz/#authentication","title":"Authentication","text":""},{"location":"articles/authn-authz/#tls-authentication","title":"TLS authentication","text":"

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\": {\n...\n  \"tls\": {\n    \"cert\": \"/etc/zot/certs/server.cert\",\n    \"key\": \"/etc/zot/certs/server.key\"\n  }\n

See Mutual TLS authentication for additional information about TLS.

"},{"location":"articles/authn-authz/#http-basic-authentication","title":"HTTP basic authentication","text":"

When basic HTTP authentication is used, the username and password credentials are joined by a colon (:), base64 encoded, and passed in the HTTP Authorization header.

"},{"location":"articles/authn-authz/#http-bearer-authentication","title":"HTTP bearer authentication","text":"

To avoid passing the username and password credentials for every HTTP request, a zot client can use bearer token-based authentication. In this method, the client first authenticates with a token server and receives a short-lived token. The client then passes this token in the HTTP Authorization header, specifying Bearer as the authentication scheme.

Configure bearer authentication in the zot configuration file as shown in this example.

\"http\": {\n...\n  \"auth\": {\n    \"bearer\": {\n      \"realm\": \"https://auth.myreg.io/auth/token\",\n        \"service\": \"myauth\",\n        \"cert\": \"/etc/zot/auth.crt\"\n    }\n  }\n

The following table lists the configurable attributes.

Attribute Description realm A string typically related to the authentication scheme (BASIC and BEARER). service The name of the authentication service. cert The path and filename of the server\u2019s SSL/TLS certificate."},{"location":"articles/authn-authz/#mutual-tls-authentication","title":"Mutual TLS authentication","text":"

zot supports basic TLS and password-less mutual TLS authentication (mTLS). Specifying a cacert file in the TLS section of the zot configuration file enables mTLS. The cacert parameter is used to validate the client-side TLS certificates.

\"http\": {\n...\n  \"tls\": {\n    \"cert\": \"/etc/zot/certs/server.cert\",\n    \"key\": \"/etc/zot/certs/server.key\",\n    \"cacert\": \"/etc/zot/certs/ca.cert\"\n  }\n

The following table lists the configurable attributes.

Attribute Description cert The path and filename of the server\u2019s SSL/TLS certificate. key The path and filename of the server\u2019s registry key. cacert The path and filename of the server\u2019s cacerts file, which contains trusted certificate authority (CA) certificates."},{"location":"articles/authn-authz/#preventing-automated-attacks-with-failure-delay","title":"Preventing automated attacks with failure delay","text":"

To help prevent automated attacks, you can add a delayed response to an authentication failure. Configure the failDelay attribute in the configuration file as shown in the following example.

\"http\": {\n  \"auth\": {\n    \"failDelay\": 5\n  }\n}\n

The failDelay attribute specifies a waiting time, in seconds, before zot sends a failure notification to an authenticating user who has been denied access.

"},{"location":"articles/authn-authz/#server-side-authentication","title":"Server-side authentication","text":"

You can implement server-side authentication for zot using htpasswd or LDAP or both.

When both htpasswd and LDAP configuration are specified, LDAP authentication is given preference. Because htpasswd authentication is strictly local and requires no remote service, htpasswd serves as a fail-safe authentication mechanism should LDAP become unavailable.

"},{"location":"articles/authn-authz/#ldap","title":"LDAP","text":"

zot supports integration with an LDAP-based authentication service such as Microsoft Windows Active Directory (AD). Enable and configure LDAP authentication in the zot configuration file, as shown in the following example.

\"http\": {\n...\n  \"auth\": {\n    \"ldap\": {\n      \"credentialsFile\": \"examples/config-ldap-credentials.json\",\n      \"address\": \"ldap.example.org\",\n      \"port\": 389,\n      \"startTLS\": false,\n      \"baseDN\": \"ou=Users,dc=example,dc=org\",\n      \"userAttribute\": \"uid\",\n      \"userGroupAttribute\": \"memberOf\",\n      \"bindDN\": \"cn=ldap-searcher,ou=Users,dc=example,dc=org\",\n      \"bindPassword\": \"ldap-searcher-password\",\n      \"skipVerify\": false,\n      \"subtreeSearch\": true\n    }\n  }\n}\n

The following table lists the configurable attributes for LDAP authentication.

Attribute Description credentialsFile The path to a file containing the bind credentials for LDAP. address The IP address or hostname of the LDAP server. port The port number used by the LDAP service. startTLS Set to true to enable TLS communication with the LDAP server. baseDN Starting location within the LDAP directory for performing user searches. userAttribute Attribute name used to obtain the username. userGroupAttribute Attribute name used to obtain groups to which a user belongs. skipVerify Skip TLS verification. subtreeSearch Set to true to expand the scope for search to include subtrees of the base DN.

To allow for separation of configuration and credentials, the credentials for the LDAP server are specified in a separate file, as shown in the following example. 

{\n  \"bindDN\":\"cn=ldap-searcher,ou=Users,dc=example,dc=org\",\n  \"bindPassword\":\"ldap-searcher-password\"\n}\n

The following table lists the configurable attributes of the LDAP credentials file.

Attribute Description bindDN Base Distinguished Name for the LDAP search. bindPassword Password of the bind LDAP user."},{"location":"articles/authn-authz/#htpasswd","title":"htpasswd","text":"

Enable and configure htpasswd authentication in the zot configuration file, as shown in the following example.

  1. Create and store an htpasswd file on the server.

    $ htpasswd -bBn <username> <password> >> /etc/zot/htpasswd\n

    For strong security, make sure to use the -B option, specifying the bcrypt hashing algorithm. This is the only algorithm supported by zot for htpasswd.

  2. Enable htpasswd authentication and configure the path to the htpasswd authentication in the zot configuration file.

    \"http\": {\n...\n  \"auth\": {\n      \"htpasswd\": {\n        \"path\": \"/etc/zot/htpasswd\"\n      },\n

    The path attribute specifies the path and filename of the htpasswd file, which contains user names and hashed passwords.

"},{"location":"articles/authn-authz/#authorization","title":"Authorization","text":"

With an access scheme that relies solely on authentication, any authenticated user would be given complete access to the registry. To better control access, zot supports identity-based repository-level access control (authorization) policies. The access control policy is a function of repository, user, and the action being performed on that repository.

"},{"location":"articles/authn-authz/#access-control-policies","title":"Access control policies","text":"

Five identity-based types of access control policies are supported:

Policy type Attribute Access allowed Default defaultPolicy The default policy specifies what actions are allowed if a user is authenticated but does match any user-specific policy. User-specific users, actions A user-specific policy specifies access and actions for explicitly named users. Group-specific groups, actions A group-specific policy specifies access and actions for explicitly named groups. Anonymous anonymousPolicy An anonymous policy specifies what an unauthenticated user is allowed to do. This is an appropriate policy when you want to grant open read-only access to one or more repositories. Admin adminPolicy The admin policy is a global access control policy that grants privileges to perform actions on any repository.

Access control is organized by repositories, users, and their actions. Most users of a particular repository will have similar access control requirements and can be served by a repository-specific defaultPolicy. Should a user require an exception to the default policy, a user-specific or group-specific override policy can be configured.

With an anonymousPolicy, a repository can allow anonymous actions which do not require user authentication. Finally, one or more users can be designated as administrators, to whom the global adminPolicy applies.

A user's access to a particular repository is evaluated first by whether a user-specific policy exists, then by group-specific policies, and then (in order) by default and admin policies.

A group-specific policy can be applied within any type of access policy, including default or admin policies. The group policy name can also be used with LDAP.

"},{"location":"articles/authn-authz/#configuring-access-control","title":"Configuring access control","text":"

User identity or group identity can be used as an authorization criterion for allowing actions on one or more repository paths. For specific users, you can choose to allow any combination of read, create, update, or delete actions on specific paths.

When you define policies for specific repository paths, the paths can be specified explicitly or by using glob patterns with simple or recursive wildcards. When a repository path matches more than one path description, authorization is granted based on the policy of the longest (most specific) path matched. For example, if policies are defined for path descriptions ** and repos2/repo, the repos2/repo path will match both ** and repos2/repo descriptions. In this case, the repos2/repo policy will be applied because it is longer.

Note that ** effectively defines the default policy, as it matches any path not matched by any other per-repository policy. To override all other policies, you can specify a global admin policy.

Always include the read action in any policy that you define. The create, update, and delete actions cannot be used without the read action.

"},{"location":"articles/authn-authz/#example-access-control-configuration","title":"Example: Access control configuration","text":"

Use the accessControl attribute in the configuration file to define a set of identity-based authorization policies, as shown in the following example.

\"http\": {\n...\n  \"accessControl\": {\n    \"groups\": {\n      \"group1\": {\n        \"users\": [\"bob\", \"mary\"]\n      },\n      \"group2\": {\n        \"users\": [\"alice\", \"mallory\", \"jim\"]\n      }\n    },\n    \"repositories\": {\n      \"**\": {\n        \"policies\": [{\n          \"users\": [\"charlie\"],\n          \"groups\": [\"group2\"],\n          \"actions\": [\"read\", \"create\", \"update\"]\n        }],\n        \"defaultPolicy\": [\"read\", \"create\"]\n      },\n      \"tmp/**\": {\n        \"anonymousPolicy\": [\"read\"],\n        \"defaultPolicy\": [\"read\", \"create\", \"update\"]\n      },\n      \"infra/*\": {\n        \"policies\": [{\n            \"users\": [\"alice\", \"bob\"],\n            \"actions\": [\"create\", \"read\", \"update\", \"delete\"]\n          },\n          {\n            \"users\": [\"mallory\"],\n            \"groups\": [\"group1\"],\n            \"actions\": [\"create\", \"read\"]\n          }\n        ],\n        \"defaultPolicy\": [\"read\"]\n      },\n      \"repos2/repo\": {\n        \"policies\": [{\n            \"users\": [\"bob\"],\n            \"actions\": [\"read\", \"create\"]\n          },\n          {\n            \"users\": [\"mallory\"],\n            \"actions\": [\"create\", \"read\"]\n          }\n        ],\n        \"defaultPolicy\": [\"read\"]\n      }\n    },\n    \"adminPolicy\": {\n      \"users\": [\"admin\"],\n      \"actions\": [\"read\", \"create\", \"update\", \"delete\"]\n    }\n  }\n

In this example, five policies are defined:

In releases prior to zot v2.0.0, authorization policies were defined directly under the accessControl key in the zot configuration file. Beginning with v2.0.0, the set of authorization policies are now defined under a new repositories key.

"},{"location":"articles/authn-authz/#social-login-using-openidoauth2","title":"Social login using OpenID/OAuth2","text":"

Social login is an authentication/authorization method in which your existing credentials for another site or service can be used to log in to a service such as zot. For example, you can log in to zot using your GitHub account credentials, and zot will contact GitHub to verify your identity using OAuth 2.0 and OpenID Connect (OIDC) protocols.

Several social login providers are supported by zot:

The following example shows the zot configuration for these providers:

{\n  \"http\": {\n    \"auth\": {\n      \"openid\": {\n        \"providers\": {\n          \"github\": {\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"read:org\", \"user\", \"repo\"]\n          },\n          \"google\": {\n            \"issuer\": \"https://accounts.google.com\",\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"openid\", \"email\"]\n          },\n          \"gitlab\": {\n            \"issuer\": \"https://gitlab.com\",\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"openid\", \"read_api\", \"read_user\", \"profile\", \"email\"]\n          },\n          \"oidc\": {\n            \"issuer\": \"http://<zot-server>:5556/dex\",\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"keypath\": \"\",\n            \"scopes\": [\"openid\", \"profile\", \"email\", \"groups\"]\n          }\n        }\n      }\n    }\n  }\n}\n
"},{"location":"articles/authn-authz/#using-google-github-or-gitlab","title":"Using Google, GitHub, or GitLab","text":"

A client logging into zot by social login must specify a supported OpenID/OAuth2 provider as a URL query parameter. A client logging in using Google, GitHub, or GitLab must additionally specify a callback URL for redirection to a zot page after a successful authentication.

The login URL using Google, GitHub, or GitLab uses the following format:

http://<zot-server>/auth/login?provider=<provider>&callback_ui=<zot-server>/<page>\n

For example, a user logging in to the zot home page using GitHub as the authentication provider sends this URL:

http://zot.example.com:8080/auth/login?provider=github&callback_ui=http://zot.example.com:8080/home\n

Based on the specified provider, zot redirects the login to a provider service with the following URL:

http://<zot-server>/auth/callback/<provider>\n

For the GitHub authentication example:

http://zot.example.com:8080/auth/callback/github\n

If your network policy doesn't allow inbound connections, the callback will not work and this authentication method will fail.

"},{"location":"articles/authn-authz/#using-dex","title":"Using dex","text":"

dex is an identity service that uses OpenID Connect (OIDC) to drive authentication for client apps, such as zot. While this section shows how to use dex with zot, zot supports other OIDC services as well.

Like zot, dex uses a configuration file for setup. To specify zot as a client in dex, configure a staticClients entry in the dex configuration file with a zot callback, such as the following example in the dex configuration file:

staticClients:\n  - id: zot-client\n    redirectURIs:\n      - 'http://zot.example.com:8080/auth/callback/oidc'\n    name: 'zot'\n    secret: ZXhhbXBsZS1hcHAtc2VjcmV0\n

In the zot configuration file, configure dex as an OpenID auth provider as in the following example:

  \"http\": {\n    \"auth\": {\n      \"openid\": {\n        \"providers\": {\n          \"oidc\": {\n            \"name\": \"Corporate SSO\",\n            \"issuer\": \"http://<zot-server>:5556/dex\",\n            \"clientid\": \"zot-client\",\n            \"clientsecret\": \"ZXhhbXBsZS1hcHAtc2VjcmV0\",\n            \"keypath\": \"\",\n            \"scopes\": [\"openid\", \"profile\", \"email\", \"groups\"]\n          }\n        }\n      }\n    }\n  }\n

A user logging in to zot using dex OpenID authentication sends a URL with dex as a URL query parameter, such as the following example:

http://zot.example.com:8080/auth/login?provider=oidc

For detailed information about configuring dex service, see the dex Getting Started documentation.

"},{"location":"articles/authn-authz/#using-openidoauth2-when-zot-is-behind-a-proxy-or-load-balancer","title":"Using OpenID/OAuth2 when zot is behind a proxy or load balancer","text":"

When the zot registry is running behind a proxy or load balancer, you must provide an external URL for OpenID/OAuth2 clients to redirect back to zot. This externalUrl attribute is the URL of the registry, as shown in this example:

  \"http\": {\n    \"address\": \"0.0.0.0\",\n    \"port\": \"8080\",\n    \"externalUrl\": \"https://zot.example.com\",\n    \"auth\": {\n      \"openid\": {\n        \"providers\": {\n          \"github\": {\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"read:org\", \"user\", \"repo\"]\n          }\n        }\n      }\n    }\n  }\n
"},{"location":"articles/benchmarking-with-zb/","title":"Benchmarking zot with zb","text":"

The zb tool is useful for benchmarking OCI registry workloads in scenarios such as the following:

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.

"},{"location":"articles/benchmarking-with-zb/#how-to-get-zb","title":"How to get zb","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#supported-platforms-and-architectures","title":"Supported platforms and architectures","text":"

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"},{"location":"articles/benchmarking-with-zb/#downloading-zb-binaries","title":"Downloading zb binaries","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#building-zb-from-source","title":"Building zb from source","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#running-zb","title":"Running zb","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#usage","title":"Usage","text":"

To view the usage and options of zb, run the command with the --help option:

bin/zb --help

Command output:

    Usage:\n      zb <url> [flags]\n\n    Flags:\n      -A, --auth-creds string \u00a0 \u00a0 \u00a0Use colon-separated BASIC auth creds\n      -c, --concurrency int \u00a0 \u00a0 \u00a0 \u00a0Number of multiple requests to make at a time (default 1)\n \u00a0    -h, --help \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 help for zb\n \u00a0    -o, --output-format string \u00a0 Output format of test results: stdout (default), json, ci-cd\n \u00a0    -r, --repo string \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0Use specified repo on remote registry for test data\n \u00a0    -n, --requests int \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 Number of requests to perform (default 1)\n \u00a0    -s, --src-cidr string \u00a0 \u00a0 \u00a0 \u00a0Use specified cidr to obtain ips to make requests from, src-ips and src-cidr are mutually exclusive\n \u00a0    -i, --src-ips string \u00a0 \u00a0 \u00a0 \u00a0 Use colon-separated ips to make requests from, src-ips and src-cidr are mutually exclusive\n \u00a0    -v, --version \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0Show the version and exit\n \u00a0    -d, --working-dir string \u00a0 \u00a0 Use specified directory to store test data\n
"},{"location":"articles/benchmarking-with-zb/#example","title":"Example","text":"

The following example executes a benchmark operation using zb.

bin/zb -c 10 -s 127.0.10.0/24 -n 1000 http://localhost:8080

You can also run the released docker image.

docker run --net=host -it ghcr.io/project-zot/zb-linux-amd64:latest -c 10 -n 1000 -s 127.0.10.0/24 http://localhost:8080

Command output:

    Registry URL: http://localhost:8080\n\n    Concurrency Level: 2\n    Total requests:    100\n    Working dir:\n\n    ========\n    Test name:            Get Catalog\n    Time taken for tests: 45.397205ms\n    Complete requests:    100\n    Failed requests:      0\n    Requests per second:  2202.7788\n\n    2xx responses: 100\n\n    min: 402.259\u00b5s\n    max: 3.295887ms\n    p50: 855.045\u00b5s\n    p75: 971.709\u00b5s\n    p90: 1.127389ms\n    p99: 3.295887ms\n\n    ========\n    Test name:            Push Monolith 1MB\n    Time taken for tests: 952.336383ms\n    Complete requests:    100\n    Failed requests:      0\n    Requests per second:  105.00491\n\n    2xx responses: 100\n\n    min: 11.125673ms\n    max: 26.375356ms\n    p50: 18.917253ms\n    p75: 21.753441ms\n    p90: 24.02137ms\n    p99: 26.375356ms\n\n    ...\n
"},{"location":"articles/building-ci-cd-pipeline/","title":"Building an OCI-native Container Image CI/CD Pipeline","text":"

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.

"},{"location":"articles/building-ci-cd-pipeline/#build-images","title":"Build images","text":"

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>\n
"},{"location":"articles/building-ci-cd-pipeline/#image-registry","title":"Image registry","text":"

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>\n

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 \\\n  docker://<zot-server>/image:tag\n
Click here to view an example of pushing and pulling an image using skopeo.

"},{"location":"articles/building-ci-cd-pipeline/#signing-images","title":"Signing images","text":"

cosign is a tool that performs container signing, verification, and storage in an OCI registry.

example: cosign generates keys and signs an image in the registry

cosign generate-key-pair\n\ncosign sign --key cosign.key <zot-server>/image:tag\n
Click here to view an example of cosign operations.

"},{"location":"articles/building-ci-cd-pipeline/#deploying-container-images","title":"Deploying container images","text":"

cri-o is an implementation of the Kubernetes Container Runtime Interface (CRI) to enable using OCI compatible runtimes. It is a lightweight alternative to using Docker as the runtime for Kubernetes.

zot is compatible with kubernetes/cri-o using docker:// transport, which is the default.

example: kubelet configuration file

apiVersion: v1\nkind: Pod\nmetadata:\n  name: example-pod\nspec:\n  containers:\n  - name: example-container\n    image: <zot-server>/image:tag\n
"},{"location":"articles/building-ci-cd-pipeline/#container-image-verification","title":"Container image verification","text":"

cosigned is an image admission controller that validates container images before deploying them.

example: install cosigned using Helm

kubectl create namespace cosign-system\n\nkubectl create secret generic mysecret -n \\\n  cosign-system --from-file=cosign.pub=./cosign.pub\n\nhelm repo add sigstore https://sigstore.github.io/helm-charts\n\nhelm repo update\n\nhelm install cosigned -n cosign-system sigstore/cosigned \\\n  --devel --set cosign.secretKeyRef.name=mysecret\n
"},{"location":"articles/clustering/","title":"zot Clustering","text":"

High availability of the zot registry is supported by the following features:

To ensure high-availability of the registry, zot supports a clustering scheme with stateless zot instances/replicas fronted by a loadbalancer and a shared remote backend storage. This scheme allows the registry service to remain available even if a few replicas fail or become unavailable. Loadbalancing across many zot replicas can also increase aggregate network throughput.

Clustering is supported in both bare-metal and Kubernetes environments.

The remote backend storage must be S3 API-compatible.

"},{"location":"articles/clustering/#bare-metal-deployment","title":"Bare-metal deployment","text":""},{"location":"articles/clustering/#prerequisites","title":"Prerequisites","text":""},{"location":"articles/clustering/#kubernetes-deployment","title":"Kubernetes deployment","text":""},{"location":"articles/clustering/#prerequisites_1","title":"Prerequisites","text":""},{"location":"articles/clustering/#implementing-stateless-zot","title":"Implementing stateless zot","text":"

zot maintains two types of durable state:

In a stateless clustering scheme, the image data is stored in the remote storage backend and the registry cache is disabled by turning off both deduplication and garbage collection.

"},{"location":"articles/clustering/#ecosystem-tools","title":"Ecosystem tools","text":"

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 loadbalancing and ingress gateway configuration.

"},{"location":"articles/clustering/#examples","title":"Examples","text":"

zot supports clustering by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load-balancing traffic to the replicas.

"},{"location":"articles/clustering/#yaml-configuration","title":"YAML configuration","text":"Click here to view a sample haproxy configuration. 
global\n        log /dev/log    local0\n        log /dev/log    local1 notice\n        chroot /var/lib/haproxy\n        maxconn 2000\n        stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners\n        stats timeout 30s\n        user haproxy\n        group haproxy\n        daemon\n\n        # Default SSL material locations\n        ca-base /etc/ssl/certs\n        crt-base /etc/ssl/private\n\n        # See: https://ssl-config.mozilla.org/#server=haproxy&server-version=2.0.3&config=intermediate\n        ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384\n        ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\n        ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets\n\ndefaults\n        log     global\n        mode    http\n        option  httplog\n        option  dontlognull\n        timeout connect 5000\n        timeout client  50000\n        timeout server  50000\n        errorfile 400 /etc/haproxy/errors/400.http\n        errorfile 403 /etc/haproxy/errors/403.http\n        errorfile 408 /etc/haproxy/errors/408.http\n        errorfile 500 /etc/haproxy/errors/500.http\n        errorfile 502 /etc/haproxy/errors/502.http\n        errorfile 503 /etc/haproxy/errors/503.http\n        errorfile 504 /etc/haproxy/errors/504.http\n\nfrontend zot\n    bind *:8080\n    mode http\n    default_backend zot-cluster\n\nbackend zot-cluster\n    mode http\n    balance roundrobin\n    server zot1 127.0.0.1:8081 check\n    server zot2 127.0.0.1:8082 check\n    server zot3 127.0.0.1:8083 check\n
"},{"location":"articles/clustering/#zot-s3-configuration","title":"zot S3 configuration","text":"Click here to view a sample zot configuration for S3. 
{\n    \"distSpecVersion\": \"1.0.1-dev\",\n    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true,\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"rootdirectory\": \"/zot\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false\n        },\n        \"cacheDriver\": {\n            \"name\": \"dynamodb\",\n            \"endpoint\": \"http://localhost:4566\",\n            \"region\": \"us-east-2\",\n            \"tableName\": \"MainTable\"\n        }\n    },\n    \"http\": {\n        \"address\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"log\": {\n        \"level\": \"debug\"\n    }\n}\n
"},{"location":"articles/graphql/","title":"Using GraphQL for Enhanced Searches","text":"

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.

"},{"location":"articles/graphql/#how-to-use-graphql-for-search-queries","title":"How to use GraphQL for search queries","text":"

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.

"},{"location":"articles/graphql/#using-the-search-api-directly","title":"Using the search API directly","text":"

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\n

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\n

The reply to your query is returned as a JSON payload in the HTML response.

"},{"location":"articles/graphql/#using-the-graphql-playground","title":"Using the GraphQL Playground","text":"

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#\n

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#\n

In the GraphQL Playground, you can construct and submit a query structure and you can view the query response in a graphical environment in the browser. You can also inspect the schema.

"},{"location":"articles/graphql/#what-graphql-queries-are-supported","title":"What GraphQL queries are supported","text":"Supported queries graphQL query Input Output Description Search images by digest ImageListForDigest digest image list Searches all repositories in the registry and returns list of images that matches given digest (manifest, config or layers) Search images affected by a given CVE id CVEListForImage CVE id image list Searches the entire registry and returns list of images affected by given CVE List CVEs for a given image CVEListForImage image CVE list Scans given image and returns list of CVEs affecting the image List images not affected by a given CVE id ImagesListWithCVEFixed repository, CVE id image list Scans all images in a given repository and returns list of latest (by date) images not affected by the given CVE Latest image from all repos RepoListWithNewestImage none repo summary list Returns the latest image from all the repos in the registry List all images with expanded information for a given repository ExpandedRepoInfo repository repo info List expanded repo information for all images in repo, alongside a repo summary All images in repo ImageList repository image list Returns all images in the specified repo Global search GlobalSearch query image summary / repo summary / layer summary Will return what's requested in the query argument Derived image list DerivedImageList image image list Returns a list of images that depend on the image specified in the argument Base image list BaseImageList image image list Returns a list of images that the specified image depends on Get details of a specific image Image image image summary Returns details about a specific image Get referrers of a specific image Referrers repo, digest, type artifact manifests Returns a list of artifacts of given type referring to a specific repo and digests"},{"location":"articles/graphql/#examples-of-zot-searches-using-graphql","title":"Examples of zot searches using GraphQL","text":"

These examples show only the GraphQL query without details on how to send them to a server. See How to use GraphQL for search queries.

The query structures shown in these examples request all fields allowed by the schema for the particular query type. The schema allows you to request a subset of the data, if desired, omitting any fields that you don't need.

"},{"location":"articles/graphql/#list-cves-of-given-image","title":"List CVEs of given image","text":"

Sample request

{\n  CVEListForImage(\n    image: \"alpine:3.17\"\n    requestedPage: {limit: 1, offset:1, sortBy: SEVERITY}\n  ) {\n    Tag\n    Page {\n      TotalCount\n      ItemCount\n    }\n    CVEList {\n      Id\n      Title\n      Description\n      Severity\n      PackageList {\n        Name\n        InstalledVersion\n        FixedVersion\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"CVEListForImage\": {\n      \"Tag\": \"3.17\",\n      \"Page\": {\n        \"TotalCount\": 9,\n        \"ItemCount\": 1\n      },\n      \"CVEList\": [\n        {\n          \"Id\": \"CVE-2023-5363\",\n          \"Title\": \"openssl: Incorrect cipher key and IV length processing\",\n          \"Description\": \"Issue summary: A bug has been identified in the processing of key and\\ninitialisation vector (IV) lengths.  This can lead to potential truncation\\nor overruns during the initialisation of some symmetric ciphers.\\n\\nImpact summary: A truncation in the IV can result in non-uniqueness,\\nwhich could result in loss of confidentiality for some cipher modes.\\n\\nWhen calling EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2() or\\nEVP_CipherInit_ex2() the provided OSSL_PARAM array is processed after\\nthe key and IV have been established.  Any alterations to the key length,\\nvia the \\\"keylen\\\" parameter or the IV length, via the \\\"ivlen\\\" parameter,\\nwithin the OSSL_PARAM array will not take effect as intended, potentially\\ncausing truncation or overreading of these values.  The following ciphers\\nand cipher modes are impacted: RC2, RC4, RC5, CCM, GCM and OCB.\\n\\nFor the CCM, GCM and OCB cipher modes, truncation of the IV can result in\\nloss of confidentiality.  For example, when following NIST's SP 800-38D\\nsection 8.2.1 guidance for constructing a deterministic IV for AES in\\nGCM mode, truncation of the counter portion could lead to IV reuse.\\n\\nBoth truncations and overruns of the key and overruns of the IV will\\nproduce incorrect results and could, in some cases, trigger a memory\\nexception.  However, these issues are not currently assessed as security\\ncritical.\\n\\nChanging the key and/or IV lengths is not considered to be a common operation\\nand the vulnerable API was recently introduced. Furthermore it is likely that\\napplication developers will have spotted this problem during testing since\\ndecryption would fail unless both peers in the communication were similarly\\nvulnerable. For these reasons we expect the probability of an application being\\nvulnerable to this to be quite low. However if an application is vulnerable then\\nthis issue is considered very serious. For these reasons we have assessed this\\nissue as Moderate severity overall.\\n\\nThe OpenSSL SSL/TLS implementation is not affected by this issue.\\n\\nThe OpenSSL 3.0 and 3.1 FIPS providers are not affected by this because\\nthe issue lies outside of the FIPS provider boundary.\\n\\nOpenSSL 3.1 and 3.0 are vulnerable to this issue.\",\n          \"Severity\": \"HIGH\",\n          \"PackageList\": [\n            {\n              \"Name\": \"libcrypto3\",\n              \"InstalledVersion\": \"3.0.8-r0\",\n              \"FixedVersion\": \"3.0.12-r0\"\n            },\n            {\n              \"Name\": \"libssl3\",\n              \"InstalledVersion\": \"3.0.8-r0\",\n              \"FixedVersion\": \"3.0.12-r0\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-images-affected-by-a-given-cve-id","title":"Search images affected by a given CVE id","text":"

Sample request

{\n  ImageListForCVE(id: \"CVE-2023-0464\") {\n    Results{\n      RepoName\n      Tag\n      Digest\n      LastUpdated\n      IsSigned\n      Size\n      Vendor\n      DownloadCount\n      Licenses\n      Title\n      Manifests {\n        Digest\n        ConfigDigest\n        Platform {\n          Os\n          Arch\n        }\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageListForCVE\": {\n      \"Results\": [\n        {\n          \"RepoName\": \"alpine\",\n          \"Tag\": \"3.17\",\n          \"Digest\": \"sha256:75bfe77c8d5a76b4421cfcebbd62a28ae70d10147578d0cda45820e99b0ef1d8\",\n          \"LastUpdated\": \"2023-02-11T04:46:42.558343068Z\",\n          \"IsSigned\": true,\n          \"Size\": \"3375436\",\n          \"Vendor\": \"\",\n          \"DownloadCount\": 0,\n          \"Licenses\": \"\",\n          \"Title\": \"\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:75bfe77c8d5a76b4421cfcebbd62a28ae70d10147578d0cda45820e99b0ef1d8\",\n              \"ConfigDigest\": \"sha256:6a2bcc1c7b4c9207f791a4512d7f2fa8fc2daeae58dbc51cb2797b05415f082a\",\n              \"Platform\": {\n                \"Os\": \"linux\",\n                \"Arch\": \"amd64\"\n              }\n            }\n          ]\n        },\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#list-images-not-affected-by-a-given-cve-id","title":"List images not affected by a given CVE id","text":"

Sample request

{\n  ImageListWithCVEFixed(id: \"CVE-2023-0464\", image: \"ubuntu\") {\n    Results {\n      RepoName\n      Tag\n      Digest\n      LastUpdated\n      Manifests {\n        Digest\n        ConfigDigest\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageListWithCVEFixed\": {\n      \"Results\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"kinetic\",\n          \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\",\n          \"LastUpdated\": \"2022-10-14T15:28:55.0263968Z\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\",\n              \"ConfigDigest\": \"sha256:824c0269745923afceb9765ae24f5b331bb6fcf2a82f7eba98b3cfd543afb41e\"\n            }\n          ]\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"kinetic-20220922\",\n          \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\",\n          \"LastUpdated\": \"2022-10-14T15:27:41.2144454Z\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\",\n              \"ConfigDigest\": \"sha256:15c8dcf63970bb14ea36e41aa001b87d8d31e25a082bf6f659d12489d3e53d90\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-images-by-digest","title":"Search images by digest","text":"

Sample request

{\n  ImageListForDigest(\n    id: \"79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\"\n  ) {\n    Results{\n      RepoName\n      Tag\n      Title\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageListForDigest\": {\n      \"Results\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"kinetic-20220922\",\n          \"Title\": \"ubuntu\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#list-the-latest-image-across-every-repository","title":"List the latest image across every repository","text":"

Sample request

{\n  RepoListWithNewestImage(requestedPage: {limit: 2, offset:0, sortBy: ALPHABETIC_ASC}) {\n    Page {\n      TotalCount\n      ItemCount\n    }\n    Results {\n      Name\n      LastUpdated\n      Size\n      Platforms {\n        Os\n        Arch\n      }\n      NewestImage {\n        Digest\n        Tag\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"RepoListWithNewestImage\": {\n      \"Page\": {\n        \"TotalCount\": 30,\n        \"ItemCount\": 2\n      },\n      \"Results\": [\n        {\n          \"Name\": \"mariadb\",\n          \"LastUpdated\": \"2022-10-18T14:56:33.1993083+03:00\",\n          \"Size\": \"124116964\",\n          \"Platforms\": [\n            {\n              \"Os\": \"linux\",\n              \"Arch\": \"amd64\"\n            }\n          ],\n          \"NewestImage\": {\n            \"Digest\": \"sha256:49a299f5c4b1af5bc2aa6cf8e50ab5bad85db4d0095745369acfc1934ece99d0\",\n            \"Tag\": \"latest\"\n          }\n        },\n        {\n          \"Name\": \"tomcat\",\n          \"LastUpdated\": \"2022-10-18T14:55:13.8303866+03:00\",\n          \"Size\": \"311658063\",\n          \"Platforms\": [\n            {\n              \"Os\": \"linux\",\n              \"Arch\": \"amd64\"\n            }\n          ],\n          \"NewestImage\": {\n            \"Digest\": \"sha256:bbc5a3912b568fbfb5912beaf25054f1f407c32a53acae29f19ad97485731a78\",\n            \"Tag\": \"jre17\"\n          }\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#all-images-in-repo","title":"All images in repo","text":"

Sample request

{\n  ImageList (repo: \"ubuntu\") {\n    Results {\n      Tag\n      Digest\n      LastUpdated\n      Size\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageList\": {\n      \"Results\": [\n        {\n          \"Tag\": \"jammy\",\n          \"Digest\": \"sha256:f96fcb040c7ee00c037c758cf0ab40638e6ee89b03a9d639178fcbd0e7f96d27\",\n          \"LastUpdated\": \"2022-10-14T15:29:18.0325322Z\",\n          \"Size\": \"30472739\"\n        },\n        {\n          \"Tag\": \"jammy-20221003\",\n          \"Digest\": \"sha256:86681debca1719dff33f426a0f5c41792ebc52496c5d78a93b655b8b48fb71b2\",\n          \"LastUpdated\": \"2022-10-14T15:29:07.0004587Z\",\n          \"Size\": \"30472748\"\n        },\n        {\n          \"Tag\": \"kinetic\",\n          \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\",\n          \"LastUpdated\": \"2022-10-14T15:28:55.0263968Z\",\n          \"Size\": \"27498890\"\n        },\n        {\n          \"Tag\": \"kinetic-20220922\",\n          \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\",\n          \"LastUpdated\": \"2022-10-14T15:27:41.2144454Z\",\n          \"Size\": \"27498899\"\n        },\n        {\n          \"Tag\": \"latest\",\n          \"Digest\": \"sha256:9bc6d811431613bf2fd8bf3565b319af9998fc5c46304022b647c63e1165657c\",\n          \"LastUpdated\": \"2022-10-14T15:26:59.6707939Z\",\n          \"Size\": \"30472740\"\n        },\n        {\n          \"Tag\": \"rolling\",\n          \"Digest\": \"sha256:72e75626c5068b9d9a462c4fc80a29787d0cf61c8abc81bfd5ea69f6248d56fc\",\n          \"LastUpdated\": \"2022-10-14T15:27:21.2441356Z\",\n          \"Size\": \"30472741\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#list-all-images-with-expanded-information-for-a-given-repository","title":"List all images with expanded information for a given repository","text":"

Sample request

{\n  ExpandedRepoInfo(repo: \"ubuntu\") {\n    Images {\n      Tag\n      Digest\n    }\n    Summary {\n      LastUpdated\n      Size\n      NewestImage {\n        Tag\n        LastUpdated\n        Digest\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ExpandedRepoInfo\": {\n      \"Images\": [\n        {\n          \"Tag\": \"jammy\",\n          \"Digest\": \"sha256:f96fcb040c7ee00c037c758cf0ab40638e6ee89b03a9d639178fcbd0e7f96d27\"\n        },\n        {\n          \"Tag\": \"jammy-20221003\",\n          \"Digest\": \"sha256:86681debca1719dff33f426a0f5c41792ebc52496c5d78a93b655b8b48fb71b2\"\n        },\n        {\n          \"Tag\": \"kinetic\",\n          \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\"\n        },\n        {\n          \"Tag\": \"kinetic-20220922\",\n          \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\"\n        },\n        {\n          \"Tag\": \"rolling\",\n          \"Digest\": \"sha256:72e75626c5068b9d9a462c4fc80a29787d0cf61c8abc81bfd5ea69f6248d56fc\"\n        },\n        {\n          \"Tag\": \"latest\",\n          \"Digest\": \"sha256:9bc6d811431613bf2fd8bf3565b319af9998fc5c46304022b647c63e1165657c\"\n        }\n      ],\n      \"Summary\": {\n        \"LastUpdated\": \"2022-10-14T15:29:18.0325322Z\",\n        \"Size\": \"58146896\",\n        \"NewestImage\": {\n          \"Tag\": \"jammy\",\n          \"LastUpdated\": \"2022-10-14T15:29:18.0325322Z\",\n          \"Digest\": \"sha256:f96fcb040c7ee00c037c758cf0ab40638e6ee89b03a9d639178fcbd0e7f96d27\"\n        }\n      }\n    }\n  }\n}\n
"},{"location":"articles/graphql/#global-search","title":"Global search","text":"

Sample request

{\n  GlobalSearch(query: \"ubuntu:latest\") {\n    Page {\n      ItemCount\n      TotalCount\n    }\n    Images {\n      RepoName\n      Tag\n      LastUpdated\n      Manifests {\n        Digest\n        Layers {\n          Size\n          Digest\n        }\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"GlobalSearch\": {\n      \"Page\": {\n        \"ItemCount\": 1,\n        \"TotalCount\": 1\n      },\n      \"Images\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-14T15:26:59.6707939Z\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:9bc6d811431613bf2fd8bf3565b319af9998fc5c46304022b647c63e1165657c\",\n              \"Layers\": [\n                {\n                  \"Size\": \"30428928\",\n                  \"Digest\": \"sha256:cf92e523b49ea3d1fae59f5f082437a5f96c244fda6697995920142ff31d59cf\"\n                }\n              ]\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n

Sample request

{\n  GlobalSearch(query: \"\") {\n    Repos {\n      Name\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"GlobalSearch\": {\n      \"Repos\": [\n        {\n          \"Name\": \"centos\"\n        },\n        {\n          \"Name\": \"ubuntu\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-derived-images","title":"Search derived images","text":"

Sample query

{\n  DerivedImageList(image: \"ubuntu:latest\", requestedPage: {offset: 0, limit: 10}) {\n    Page {\n      TotalCount\n      ItemCount\n    }\n    Results {\n      RepoName\n      Tag\n      LastUpdated\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"DerivedImageList\": {\n      \"Page\": {\n        \"TotalCount\": 9,\n        \"ItemCount\": 9\n      },\n      \"Results\": [\n        {\n          \"RepoName\": \"mariadb\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-18T14:56:33.1993083+03:00\"\n        },\n        {\n          \"RepoName\": \"maven\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-14T18:30:12.0929807+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-18T14:50:09.7229959+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"jre17\",\n          \"LastUpdated\": \"2022-10-18T14:55:13.8303866+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"jre17-temurin\",\n          \"LastUpdated\": \"2022-10-18T14:54:46.4133521+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"jre17-temurin-jammy\",\n          \"LastUpdated\": \"2022-10-18T14:51:12.235475+03:00\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-base-images","title":"Search base images","text":"

Sample query

{\n  BaseImageList(image: \"mariadb:latest\", requestedPage: {offset: 0, limit: 10}) {\n    Page {\n      TotalCount\n      ItemCount\n    }\n    Results {\n      RepoName\n      Tag\n      LastUpdated\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"BaseImageList\": {\n      \"Page\": {\n        \"TotalCount\": 4,\n        \"ItemCount\": 4\n      },\n      \"Results\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"jammy\",\n          \"LastUpdated\": \"2022-10-14T18:29:18.0325322+03:00\"\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"jammy-20221003\",\n          \"LastUpdated\": \"2022-10-14T18:29:07.0004587+03:00\"\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-14T18:26:59.6707939+03:00\"\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"rolling\",\n          \"LastUpdated\": \"2022-10-14T18:27:21.2441356+03:00\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#get-details-of-a-specific-image","title":"Get details of a specific image","text":"

Sample query

{\n  Image(image: \"mariadb:latest\") {\n    RepoName\n    Tag\n    LastUpdated\n    Digest\n    Description\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"Image\": {\n      \"RepoName\": \"mariadb\",\n      \"Tag\": \"latest\",\n      \"LastUpdated\": \"2022-10-18T14:56:33.1993083+03:00\",\n      \"Digest\": \"sha256:49a299f5c4b1af5bc2aa6cf8e50ab5bad85db4d0095745369acfc1934ece99d0\",\n      \"Description\": \"MariaDB Server is a high performing open source relational database, forked from MySQL.\"\n    }\n  }\n}\n
"},{"location":"articles/graphql/#get-referrers-of-a-specific-image","title":"Get referrers of a specific image","text":"

Sample query

{\n  Referrers(\n    repo: \"golang\"\n    digest: \"sha256:fed08b0eaea00aab17f82ecbb78675919d216c72eea985581758191f694aeaf7\"\n    type: \"application/vnd.example.icecream.v1\"\n  ) {\n    MediaType\n    ArtifactType\n    Digest\n    Annotations {\n      Key\n      Value\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"Referrers\": [\n      {\n        \"MediaType\": \"application/vnd.oci.artifact.manifest.v1+json\",\n        \"ArtifactType\": \"application/vnd.example.icecream.v1\",\n        \"Digest\": \"sha256:be7a3d01c35a2cf53c502e9dc50cdf36b15d9361c81c63bf319f1d5cbe44ab7c\",\n        \"Annotations\": [\n          {\n            \"Key\": \"format\",\n            \"Value\": \"oci\"\n          },\n          {\n            \"Key\": \"demo\",\n            \"Value\": \"true\"\n          }\n        ]\n      },\n      {\n        \"MediaType\": \"application/vnd.oci.artifact.manifest.v1+json\",\n        \"ArtifactType\": \"application/vnd.example.icecream.v1\",\n        \"Digest\": \"sha256:d9ad22f41d9cb9797c134401416eee2a70446cee1a8eb76fc6b191f4320dade2\",\n        \"Annotations\": [\n          {\n            \"Key\": \"demo\",\n            \"Value\": \"true\"\n          },\n          {\n            \"Key\": \"format\",\n            \"Value\": \"oci\"\n          }\n        ]\n      }\n    ]\n  }\n}\n
"},{"location":"articles/kind-deploy/","title":"Using kind for Deployment Testing","text":"

Use kind to try out zot deployment with Kubernetes.

This article describes how to create a kind cluster that includes a local zot registry.

"},{"location":"articles/kind-deploy/#deploying-the-cluster-and-registry","title":"Deploying the cluster and registry","text":"

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.

"},{"location":"articles/kind-deploy/#step-1-prepare-the-environment","title":"Step 1: Prepare the environment","text":"

The following packages must be installed:

Execute the following shell commands to set environment variables.

set -o errexit\n\n# set no_proxy if applicable\nif [ ! -z \"${no_proxy}\" ]; then \n  echo \"Updating no_proxy environment variables\";\n  export no_proxy=${no_proxy},kind-registry;\n  export NO_PROXY=${no_proxy};\nfi\n
"},{"location":"articles/kind-deploy/#step-2-create-a-registry-container","title":"Step 2: Create a registry container","text":"

Create a kind-registry container, pulling a zot binary from the GitHub Container Registry (ghcr.io).

This example pulls zot-minimal-linux-amd64:latest, a minimal (no extensions) zot image for an AMD-based linux server.

Other available images are described at the zot releases page in GitHub. You can also specify a release by replacing latest with an available release number.

# create registry container unless it already exists\nreg_name='kind-registry'\nreg_port='5001'\nif [ \"$(docker inspect -f '{{.State.Running}}' \"${reg_name}\" 2>/dev/null || true)\" != 'true' ]; then\n  docker run \\\n    -d --restart=always -p \"127.0.0.1:${reg_port}:5000\" --name \"${reg_name}\" \\\n    ghcr.io/project-zot/zot-minimal-linux-amd64:latest\nfi\n
"},{"location":"articles/kind-deploy/#step-3-create-the-kind-cluster","title":"Step 3: Create the kind cluster","text":"

Create a cluster with the local registry enabled.

# enable the local registry in containerd\ncat <<EOF | kind create cluster --config=-\nkind: Cluster\napiVersion: kind.x-k8s.io/v1alpha4\ncontainerdConfigPatches:\n- |-\n  [plugins.\"io.containerd.grpc.v1.cri\".registry.mirrors.\"localhost:${reg_port}\"]\n    endpoint = [\"http://${reg_name}:5000\"]\nEOF\n
"},{"location":"articles/kind-deploy/#step-4-connect-the-registry-to-the-cluster-network","title":"Step 4: Connect the registry to the cluster network","text":"

Connect the registry to the \"kind\" network so that it can communicate with other resources in the same network.

# check whether already connected to the network\nif [ \"$(docker inspect -f='{{json .NetworkSettings.Networks.kind}}' \\\n\"${reg_name}\")\" = 'null' ]; then\n  docker network connect \"kind\" \"${reg_name}\"\nfi\n
"},{"location":"articles/kind-deploy/#step-5-document-the-local-registry","title":"Step 5: Document the local registry","text":"

Create a ConfigMap that specifies how to interact with the local registry. This ConfigMap follows the KEP-1755 Standard for communicating a local registry.

cat <<EOF | kubectl apply -f -\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: local-registry-hosting\n  namespace: kube-public\ndata:\n  localRegistryHosting.v1: |\n    host: \"localhost:${reg_port}\"\n    help: \"https://kind.sigs.k8s.io/docs/user/local-registry/\"\nEOF\n
"},{"location":"articles/kind-deploy/#step-6-deploy-and-test","title":"Step 6: Deploy and test","text":"

Use skopeo to copy (pull) a \"hello\" app from the Google Container Registry (gcr.io) into the new zot registry. Using kubectl, deploy the app from the new local zot registry as \"hello-server\" and monitor the deployment for initial availability.

# copy an image\nskopeo copy --format=oci --dest-tls-verify=false \\\ndocker://gcr.io/google-samples/hello-app:1.0 \\\ndocker://localhost:5001/hello-app:1.0\n\n# deploy the image\nkubectl create deployment hello-server --image=localhost:5001/hello-app:1.0\n\n# check for availability\necho \"Waiting for deployment/hello-server to be ready ...\"\nkubectl wait deployment -n default hello-server \\\n  --for condition=Available=True --timeout=90s\n
"},{"location":"articles/kind-deploy/#clean-up","title":"Clean up","text":"

To clean up after testing, run the following commands to delete the kind cluster and registry.

kind delete cluster\ndocker stop kind-registry\ndocker rm kind-registry\n
"},{"location":"articles/kind-deploy/#reference-a-complete-script","title":"Reference: A complete script","text":"

The following script executes all of the preceding steps.

Click here to view the entire script 
#!/bin/sh\nset -o errexit\n\n# Reference: https://kind.sigs.k8s.io/docs/user/local-registry/\n\n# set no_proxy if applicable\nif [ ! -z \"${no_proxy}\" ]; then \n  echo \"Updating no_proxy env var\";\n  export no_proxy=${no_proxy},kind-registry;\n  export NO_PROXY=${no_proxy};\nfi\n\n# create registry container unless it already exists\nreg_name='kind-registry'\nreg_port='5001'\nif [ \"$(docker inspect -f '{{.State.Running}}' \"${reg_name}\" 2>/dev/null || true)\" != 'true' ]; then\n  docker run \\\n    -d --restart=always -p \"127.0.0.1:${reg_port}:5000\" --name \"${reg_name}\" \\\n    ghcr.io/project-zot/zot-minimal-linux-amd64:latest\nfi\n\n# create a cluster with the local registry enabled in containerd\ncat <<EOF | kind create cluster --config=-\nkind: Cluster\napiVersion: kind.x-k8s.io/v1alpha4\ncontainerdConfigPatches:\n- |-\n  [plugins.\"io.containerd.grpc.v1.cri\".registry.mirrors.\"localhost:${reg_port}\"]\n    endpoint = [\"http://${reg_name}:5000\"]\nEOF\n\n# connect the registry to the cluster network if not already connected\nif [ \"$(docker inspect -f='{{json .NetworkSettings.Networks.kind}}' \"${reg_name}\")\" = 'null' ]; then\n  docker network connect \"kind\" \"${reg_name}\"\nfi\n\n# https://github.com/kubernetes/enhancements/tree/master/keps/sig-cluster-lifecycle/generic/1755-communicating-a-local-registry\n#\n# document the local registry\ncat <<EOF | kubectl apply -f -\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: local-registry-hosting\n  namespace: kube-public\ndata:\n  localRegistryHosting.v1: |\n    host: \"localhost:${reg_port}\"\n    help: \"https://kind.sigs.k8s.io/docs/user/local-registry/\"\nEOF\n\n# copy an image\nskopeo copy --format=oci --dest-tls-verify=false docker://gcr.io/google-samples/hello-app:1.0 docker://localhost:5001/hello-app:1.0\n\n# deploy the image\nkubectl create deployment hello-server --image=localhost:5001/hello-app:1.0\n\n# check for availability\necho \"Waiting for deployment/hello-server to be ready ...\"\nkubectl wait deployment -n default hello-server --for condition=Available=True --timeout=90s\n\n# cleanup\necho \"Press a key to begin cleanup ...\"\nread KEYPRESS\nkind delete cluster\ndocker stop kind-registry\ndocker rm kind-registry\n
"},{"location":"articles/mirroring/","title":"OCI Registry Mirroring With zot","text":"

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.

"},{"location":"articles/mirroring/#mirroring-modes","title":"Mirroring modes","text":"

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.

"},{"location":"articles/mirroring/#migrating-or-updating-a-registry-using-mirroring","title":"Migrating or updating a registry using mirroring","text":"

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.

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: 

  {\n    \"urls\": [\n        \"https://registry1:5000\"\n    ],\n    \"pollInterval\": \"12h\",\n    \"onDemand\": true,\n    \"content\": [\n        {\n            \"prefix\": \"**\"\n        }\n    ]\n  }\n
"},{"location":"articles/mirroring/#basic-configuration-for-mirroring-with-sync","title":"Basic configuration for mirroring with sync","text":"

The sync feature of zot is an extension of the OCI-compliant registry implementation. You can configure the sync feature under the extensions section of the zot configuration file, as shown in this example:

  \"extensions\": {\n    \"sync\": {\n      \"credentialsFile\": \"./examples/sync-auth-filepath.json\",\n      \"registries\": [\n        {\n          \"urls\": [\n            \"https://registry1:5000\"\n          ],\n          \"onDemand\": false,\n          \"pollInterval\": \"6h\",\n          \"tlsVerify\": true,\n          \"certDir\": \"/home/user/certs\",\n          \"maxRetries\": 3,\n          \"retryDelay\": \"5m\", \n          \"onlySigned\": true,\n          \"content\": [\n            {\n              \"prefix\": \"/repo2/repo\",\n              \"tags\": {\n                \"regex\": \"4.*\",\n                \"semver\": true\n              }\n              \"destination\": \"/repo2\",\n              \"stripPrefix\": true\n            }\n          ]\n        }\n      ]\n    }\n  }\n

The following table lists the configurable attributes for the sync feature:

Attribute Description

credentialsFile

The location of a local file containing credentials for other registries, as in the following example: 

{\u2003\u2003\"127.0.0.1:8080\": {\u2003\u2003\u2003\u2003\"username\": \"user\",\u2003\u2003\u2003\u2003\"password\": \"pass\"\u2003\u2003},\u2003\u2003\u2003\u2003\"registry2:5000\": {\u2003\u2003\u2003\u2003\"username\": \"user2\",\u2003\u2003\u2003\u2003\"password\": \"pass2\"\u2003\u2003}}

urls

A list of one or more URLs to an upstream image registry. If the main URL fails, the sync process will try the next URLs in the listed order.

onDemand

pollInterval

The period in seconds between polling of a remote registry. If no value is specified, no periodic polling will occur. If a value is set and the content attributes are configured, periodic synchronization is enabled and will run at the specified value.Note: Because Docker Hub rate-limits pulls and does not support catalog listing, do not use polled mirroring with Docker Hub. Use only onDemand mirroring with Docker Hub.

tlsVerify

certDir

If a path is specified, use certificates (*.crt, *.cert, *.key files) at this path when connecting to the destination registry or daemon. If no path is specified, use the default certificates directory.

maxRetries

The maximum number of retries if an error occurs during either an on-demand or periodic synchronization. If no value is specified, no retries will occur.

retryDelay

The interval in seconds between retries. This attribute is mandatory when maxRetries is configured.

onlySigned

content

The included attributes in this section specify which content will be pulled. If this section is not populated, periodic polling will not occur. The included attributes can also filter which on-demand images are pulled.

prefix

On the remote registry, the path from which images will be pulled. This path can be a string that exactly matches the remote path, or it can be a glob pattern. For example, the path can include a wildcard (*) or a recursive wildcard (**).

tags

The included attributes in this optional section specify how remote images will be selected for synchronization based on image tags.

tags.regex

Specifies a regular expression for matching image tags. Images whose tags do not match the expression are not pulled.

tags.semver

Specifies whether image tags are to be filtered by semantic versioning (semver) compliance.

destination

Specifies the local path in which pulled images are to be stored.

stripPrefix

Specifies whether the prefix path from the remote registry will be retained or replaced when the image is stored in the zot registry.

"},{"location":"articles/mirroring/#configuration-examples-for-mirroring","title":"Configuration examples for mirroring","text":""},{"location":"articles/mirroring/#example-multiple-repositories-with-polled-mirroring","title":"Example: Multiple repositories with polled mirroring","text":"

The following is an example of sync configuration for mirroring multiple repositories with polled mirroring.

\"sync\": {\n  \"enable\": true,\n  \"credentialsFile\": \"./examples/sync-auth-filepath.json\",\n  \"registries\": [\n    {\n      \"urls\": [\"https://registry1:5000\"],\n      \"onDemand\": false,\n      \"pollInterval\": \"6h\",\n      \"tlsVerify\": true,\n      \"certDir\": \"/home/user/certs\",\n      \"maxRetries\": 3,\n      \"retryDelay\": \"5m\",\n      \"onlySigned\": true,\n      \"content\": [\n        {\n          \"prefix\": \"/repo1/repo\",\n          \"tags\": {\n            \"regex\": \"4.*\",\n            \"semver\": true\n          }\n        },\n        {\n          \"prefix\": \"/repo2/repo\",\n          \"destination\": \"/repo2\",\n          \"stripPrefix\": true\n        },\n        {\n          \"prefix\": \"/repo3/repo\"\n        }\n      ]\n    }\n  }\n

The configuration in this example will result in the following behavior:

"},{"location":"articles/mirroring/#example-multiple-registries-with-on-demand-mirroring","title":"Example: Multiple registries with on-demand mirroring","text":"

The following is an example of sync configuration for mirroring multiple registries with on-demand mirroring.

{\n  \"distSpecVersion\": \"1.0.1\",\n  \"storage\": {\n    \"rootDirectory\": \"/tmp/zot\",\n    \"gc\": true\n  },\n  \"http\": {\n    \"address\": \"0.0.0.0\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  },\n  \"extensions\": {\n    \"sync\": {\n      \"enable\": true,\n      \"registries\": [\n        {\n          \"urls\": [\"https://k8s.gcr.io\"],\n          \"content\": [\n            {\n              \"prefix\": \"**\", \n              \"destination\": \"/k8s-images\"\n            }\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true\n        },\n        {\n          \"urls\": [\"https://docker.io/library\"],\n          \"content\": [\n            {\n              \"prefix\": \"**\", \n              \"destination\": \"/docker-images\"\n            }\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true\n        }\n      ]\n    }\n  }\n}\n

With this zot configuration, the sync behavior is as follows:

  1. This initial user request for content from the zot registry: skopeo copy --src-tls-verify=false docker://localhost:8080/docker-images/alpine <dest>causes zot to synchronize the content with the docker.io registry: docker.io/library/alpine:latestto the zot registry: localhost:8080/docker-images/alpine:latestbefore delivering the content to the requestor at <dest>.

  2. This initial user request for content from the zot registry: skopeo copy --src-tls-verify=false docker://localhost:8080/k8s-images/kube-proxy:v1.19.2 <dest>causes zot to synchronize the content with the gcr.io registry: k8s.gcr.io/kube-proxy:v1.19.2 to the zot registry: localhost:8080/k8s-images/kube-proxy:v1.19.2before delivering the content to the requestor at <dest>.

You can use this command: curl http://localhost:8080/v2/_catalogto display the local repositories:

  {\n    \"repositories\":[\n      \"docker-images/alpine\",\n      \"k8s-images/kube-proxy\"\n    ]\n  }\n
"},{"location":"articles/mirroring/#example-multiple-registries-with-mixed-mirroring-modes","title":"Example: Multiple registries with mixed mirroring modes","text":"

The following is an example of a zot configuration file for mirroring multiple upstream registries.

{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n    \"rootDirectory\": \"/tmp/zot\"\n  },\n  \"http\": {\n    \"address\": \"127.0.0.1\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  },\n  \"extensions\": {\n    \"sync\": {\n      \"enable\": true,\n      \"credentialsFile\": \"./examples/sync-auth-filepath.json\",\n      \"registries\": [\n        {\n          \"urls\": [\n            \"https://registry1:5000\"\n          ],\n          \"onDemand\": false,\n          \"pollInterval\": \"6h\",\n          \"tlsVerify\": true,\n          \"certDir\": \"/home/user/certs\",\n          \"maxRetries\": 3,\n          \"retryDelay\": \"5m\",\n          \"onlySigned\": true,\n          \"content\": [\n            {\n              \"prefix\": \"/repo1/repo\",\n              \"tags\": {\n                \"regex\": \"4.*\",\n                \"semver\": true\n              }\n            },\n            {\n              \"prefix\": \"/repo1/repo\",\n              \"destination\": \"/repo\",\n              \"stripPrefix\": true\n            },\n            {\n              \"prefix\": \"/repo2/repo\"\n            }\n          ]\n        },\n        {\n          \"urls\": [\n            \"https://registry2:5000\",\n            \"https://registry3:5000\"\n          ],\n          \"pollInterval\": \"12h\",\n          \"tlsVerify\": false,\n          \"onDemand\": false,\n          \"content\": [\n            {\n              \"prefix\": \"/repo2\",\n              \"tags\": {\n                \"semver\": true\n              }\n            }\n          ]\n        },\n        {\n          \"urls\": [\n            \"https://docker.io/library\"\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true,\n          \"maxRetries\": 6,\n          \"retryDelay\": \"5m\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/mirroring/#example-support-for-subpaths-in-local-storage","title":"Example: Support for subpaths in local storage","text":"

{\n  \"distSpecVersion\": \"1.0.1\",\n  \"storage\": {\n    \"subPaths\":{\n      \"/kube-proxy\":{\n        \"rootDirectory\": \"/tmp/kube-proxy\",\n        \"dedupe\": true,\n        \"gc\": true\n       }\n     },\n    \"rootDirectory\": \"/tmp/zot\",\n    \"gc\": true\n  },\n  \"http\": {\n    \"address\": \"0.0.0.0\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  },\n  \"extensions\": {\n    \"sync\": {\n      \"enable\": true,\n      \"registries\": [\n        {\n          \"urls\": [\"https://k8s.gcr.io\"],\n          \"content\": [\n            {\n              \"destination\": \"/kube-proxy\", \n              \"prefix\": \"**\"\n            }\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true,\n          \"maxRetries\": 2,\n          \"retryDelay\": \"5m\"\n        }\n      ]\n    }\n  }\n}\n
With this zot configuration, the sync behavior is as follows:

You can use this command: curl http://localhost:8080/v2/_catalogto display the local repositories:

  {\n    \"repositories\":[\n      \"docker-images/alpine\",\n      \"k8s-images/kube-proxy\",\n      \"kube-proxy/kube-proxy\"\n    ]\n  }\n

In zot storage, the requested content is located here: /tmp/zot/kube-proxy/kube-proxy/kube-proxy/This subpath is created from the following path components:

"},{"location":"articles/monitoring/","title":"Monitoring the registry","text":"

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.

"},{"location":"articles/monitoring/#logging","title":"Logging","text":"

Logging for zot operations is configured with the log attribute in the configuration file, as shown in the following example.

\"log\":{\n  \"level\":\"debug\",\n  \"output\":\"/tmp/zot.log\",\n  \"audit\": \"/tmp/zot-audit.log\"\n}\n

The following table lists the configurable attributes.

Attribute Description

level

The minimum level for logged events. The levels are: panic, fatal, error, warn, info, debug, and trace.

output

The filesystem path for the log output file. The default is stdout.

audit

(Optional) If a filesystem path is specified for audit logging, an audit log is enabled and will be stored at the specified path.

"},{"location":"articles/monitoring/#metrics","title":"Metrics","text":"

The available methods for collecting metrics varies depending on whether your zot installation is a minimal (distribution-spec-only) image or a full image including extensions.

"},{"location":"articles/monitoring/#enabling-metrics-for-a-full-zot-image-with-extensions","title":"Enabling metrics for a full zot image with extensions","text":"

Add the metrics attribute under extensions in the configuration file to enable and configure metrics, as shown in the following example.

\"extensions\": {\n    \"metrics\": {\n        \"enable\": true,\n        \"prometheus\": {\n            \"path\": \"/metrics\"\n        }\n    }\n}\n

The following table lists the configurable attributes for metrics collection.

Attribute Description enable If this attribute is missing, metrics collection is enabled by default. Metrics collection can be disabled by setting this attribute to false. prometheus Attributes under prometheus contain configuration settings for the Prometheus node exporter. path The server path on which metrics will be exposed."},{"location":"articles/monitoring/#collecting-metrics-from-a-minimal-zot-image-using-a-node-exporter","title":"Collecting metrics from a minimal zot image using a node exporter","text":"

Although a minimal zot image does not contain a node exporter, it exposes internal metrics in a Prometheus format for collection by a separate node exporter tool such as zxp. The zot companion binary zxp is a node exporter that can be deployed with a minimal zot image in order to scrape metrics from the zot server.

Metrics are automatically enabled in the zot server upon first scrape from the node exporter and the metrics are automatically disabled when the node exporter has not performed any scraping for some period. No extra zot configuration is needed for this behavior.

You can download the zxp 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. For example, the binary for an Intel-based MacOS server is zxp-darwin-amd64. To configure the zxp example image, run this command:

zxp-darwin-amd64 config zxp-config-file

For convenience, you can rename the binary image file to simply zxp.

A sample Dockerfile for zxp is available at Dockerfile-zxp.

The configuration file of zxp contains connection details for the zot server from which it will scrape metrics. The following JSON structure is an example of the zxp-config-file contents:

{\n    \"Server\": {\n        \"protocol\": \"http\",\n        \"host\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"Exporter\": {\n        \"port\": \"8081\",\n        \"log\": {\n            \"level\": \"debug\"\n        }\n    }\n}\n

The zxp module does not have Prometheus integration.

The zxp module is not needed with a full zot image.

"},{"location":"articles/pprofiling/","title":"Performance Profiling in zot","text":"

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.

"},{"location":"articles/pprofiling/#what-data-is-available","title":"What data is available?","text":"

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/\n

If authentication is enabled, only an admin user can access this API.

"},{"location":"articles/pprofiling/#how-do-i-export-profile-data","title":"How do I export profile data?","text":"

To collect and export any available profile, use the following API command format:

/v2/_zot/pprof/<profile-type>[?<query-parameters>]\n

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\n

This command example creates an output data file named \"cpu.prof\".

"},{"location":"articles/pprofiling/#analyzing-the-cpu-usage-profile-using-go-tool-pprof","title":"Analyzing the CPU usage profile using go tool pprof","text":"

Go's pprof package provides a variety of presentation formats for analyzing runtime performance.

For detailed information, see the pprof documentation.

"},{"location":"articles/pprofiling/#generating-a-pprof-web-presentation","title":"Generating a pprof web presentation","text":"

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\nServing web UI on http://localhost:9090\n

The pprof web view offers several options for viewing and interpreting the collected performance data. Select VIEW to see the available options:

A Flame Graph can be very useful for analyzing CPU usage:

"},{"location":"articles/pprofiling/#generating-a-graphic-image","title":"Generating a graphic image","text":"

The pprof package can generate graphic representations of profile data in many formats. This example generates a PNG file representing the CPU usage in the \"cpu.prof\" file.

$ go tool pprof -png cpu.prof\nGenerating report in profile001.png\n
"},{"location":"articles/pprofiling/#opening-a-pprof-interactive-session","title":"Opening a pprof interactive session","text":"

This example opens an interactive session with pprof and executes the pprof top command, which displays the top ten modules by CPU usage during the profiling capture window.

$ go tool pprof cpu.prof\nType: cpu\nTime: Sep 26, 2023 at 10:01am (PDT)\nDuration: 30s, Total samples = 10ms (  0.1%)\nEntering interactive mode (type \"help\" for commands, \"o\" for options)\n(pprof) top\nShowing nodes accounting for 10ms, 100% of 10ms total\n    flat  flat%   sum%        cum   cum%\n    10ms   100%   100%       10ms   100%  runtime.pthread_cond_signal\n        0     0%   100%       10ms   100%  runtime.findRunnable\n        0     0%   100%       10ms   100%  runtime.mcall\n        0     0%   100%       10ms   100%  runtime.notewakeup\n        0     0%   100%       10ms   100%  runtime.park_m\n        0     0%   100%       10ms   100%  runtime.runSafePointFn\n        0     0%   100%       10ms   100%  runtime.schedule\n        0     0%   100%       10ms   100%  runtime.semawakeup\n(pprof)\n
"},{"location":"articles/pprofiling/#analyzing-the-trace-profile-using-go-tool-trace","title":"Analyzing the trace profile using go tool trace","text":"

You can collect trace data with the trace profile, as in this example:

  $ curl -s -v http://localhost:8080/v2/_zot/pprof/trace?seconds=30 > trace.prof\n

Using the go tool trace package, you can analyze the trace data captured in the \"trace.prof\" example file:

$ go tool trace trace.prof\n2023/09/21 16:58:58 Parsing trace...\n2023/09/21 16:58:58 Splitting trace...\n2023/09/21 16:58:58 Opening browser. Trace viewer is listening on http://127.0.0.1:62606\n

The go tool trace command installs and opens a local web server that provides a web interface for viewing and analyzing the trace data.

As an alternative, you can generate a pprof-like profile from the trace file using the following command:

$ go tool trace -pprof=[net|sync|syscall|sched] <filename>\n

For example:

$ go tool trace -pprof=net trace.prof\n
"},{"location":"articles/retention/","title":"Configuring zot Tag Retention Policies","text":"

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:

"},{"location":"articles/retention/#configuring-retention-policies","title":"Configuring retention policies","text":"

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.

"},{"location":"articles/retention/#configuration-example","title":"Configuration example","text":"

The following example is a simple retention configuration with two policies:

simple policy example

  \"storage\": {\n    \"retention\": {\n      \"dryRun\": false,\n      \"delay\": \"24h\",\n      \"policies\": [\n        {\n          \"repoNames\": [\"infra/*\", \"tmp/**\"],\n          \"deleteReferrers\": false,\n          \"deleteUntagged\": true,\n          \"KeepTags\": [{\n            \"patterns\": [\"v2.*\", \".*-prod\"],\n            \"mostRecentlyPushedCount\": 10,\n            \"mostRecentlyPulledCount\": 10,\n            \"pulledWithin\": \"720h\",\n            \"pushedWithin\": \"720h\"\n          }]  \n        },\n        {\n          \"keepTags\": [{\n            \"patterns\": [\".*\"]\n          }]\n        }\n      ]\n    }\n  }\n
"},{"location":"articles/retention/#configurable-attributes","title":"Configurable attributes","text":"

The following table lists the attributes available in the retention policy configuration.

Attribute Value Description dryRun boolean If true, will log a removal action without actually removing the image. Default is false. delay time Remove untagged and referrers only if they are older than the specified <time> hours, such as 24h. policies list A list of policies. repositories list A list of glob patterns to match repositories. deleteReferrers boolean If true, delete manifests with a missing Subject. Default is false. deleteUntagged boolean If true, delete untagged manifests. Default is true. keepTags list Criteria for tags to retain always. mostRecentlyPushedCount count Retains the top <count> most recently pushed tags. mostRecentlyPulledCount count Retains the top <count> most recently pulled tags. pushedWithin time Retains the tags pushed during the last <time> hours, such as 24h. pulledWithin time Retains the tags pulled during the last <time> hours, such as 24h. patterns regex See Notes."},{"location":"articles/retention/#configuration-notes","title":"Configuration notes","text":"

We recommend defining a default keepTags policy, such as the following example, as the last policy in the policy list. All tags that don't match the preceding policies will be retained by this default policy:

default policy example

  {\n    \"keepTags\": [{                               \n        \"patterns\": [\".*\"]\n      }]\n  }\n
"},{"location":"articles/retention/#complete-configuration-file-example","title":"Complete configuration file example","text":"

The following example shows the configuration of multiple retention policies in the context of a complete configuration file.

{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n    \"rootDirectory\": \"/tmp/zot\",\n    \"gc\": true,\n    \"gcDelay\": \"2h\",\n    \"gcInterval\": \"1h\",\n    \"retention\": {\n      \"dryRun\": false,\n      \"delay\": \"24h\",\n      \"policies\": [\n        {\n          \"repositories\": [\"infra/*\", \"prod/*\"],\n          \"deleteReferrers\": false,\n          \"keepTags\": [{\n            \"patterns\": [\"v2.*\", \".*-prod\"]\n          },\n          {\n            \"patterns\": [\"v3.*\", \".*-prod\"],\n            \"pulledWithin\": \"168h\"\n          }]\n        },\n        {\n          \"repositories\": [\"tmp/**\"],\n          \"deleteReferrers\": true,\n          \"deleteUntagged\": true,\n          \"keepTags\": [{\n            \"patterns\": [\"v1.*\"],\n            \"pulledWithin\": \"168h\",\n            \"pushedWithin\": \"168h\"\n          }]\n        },\n        {\n          \"repositories\": [\"**\"],\n          \"deleteReferrers\": true,\n          \"deleteUntagged\": true,\n          \"keepTags\": [{\n            \"mostRecentlyPushedCount\": 10,\n            \"mostRecentlyPulledCount\": 10,\n            \"pulledWithin\": \"720h\",\n            \"pushedWithin\": \"720h\"\n          }]\n        }\n      ]\n    },\n    \"subPaths\": {\n      \"/a\": {\n        \"rootDirectory\": \"/tmp/zot1\",\n        \"dedupe\": true,\n        \"retention\": {\n          \"policies\": [\n            {\n              \"repositories\": [\"infra/*\", \"prod/*\"],\n              \"deleteReferrers\": false\n            }\n          ]\n        }\n      }\n    }\n  },\n  \"http\": {\n    \"address\": \"127.0.0.1\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  }\n}\n
"},{"location":"articles/security-posture/","title":"zot Security Posture","text":"

An overview of zot build-time and runtime security hardening features, including:

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.

"},{"location":"articles/security-posture/#build-time-hardening","title":"Build-time hardening","text":"

The following are the steps taken during build-time.

"},{"location":"articles/security-posture/#pie-build-mode","title":"PIE build-mode","text":"

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.

"},{"location":"articles/security-posture/#conditional-builds","title":"Conditional builds","text":"

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:

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.

"},{"location":"articles/security-posture/#cicd-pipeline","title":"CI/CD pipeline","text":"

zot CI/CD process attempts to align with the Open Source Security Foundation (OSSF) best practices guidelines to achieve high code quality.

"},{"location":"articles/security-posture/#code-reviews","title":"Code reviews","text":"

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.

"},{"location":"articles/security-posture/#cicd-checks","title":"CI/CD checks","text":"

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.

"},{"location":"articles/security-posture/#runtime-hardening","title":"Runtime hardening","text":"

The following steps can be taken to harden a zot deployment.

"},{"location":"articles/security-posture/#unprivileged-runtime-process","title":"Unprivileged runtime process","text":"

Running zot doesn\u2019t require root privileges. In fact, the recommended approach is to create a separate user/group ID for the zot process.

"},{"location":"articles/security-posture/#authentication","title":"Authentication","text":"

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.

"},{"location":"articles/security-posture/#access-control","title":"Access control","text":"

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.

"},{"location":"articles/security-posture/#vulnerability-scans","title":"Vulnerability scans","text":"

Apart from hardening the deployment itself, zot also supports security scanning of stored container images.

"},{"location":"articles/security-posture/#reporting-security-issues","title":"Reporting security issues","text":"

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.

"},{"location":"articles/storage/","title":"Storage Planning with zot","text":"

zot supports the following features to provide OCI standards-based, vendor-agnostic image storage:

"},{"location":"articles/storage/#storage-model","title":"Storage model","text":"

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.

"},{"location":"articles/storage/#hosting-an-oci-image-layout","title":"Hosting an OCI image layout","text":"

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.

"},{"location":"articles/storage/#storage-features","title":"Storage features","text":"

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.

"},{"location":"articles/storage/#commit","title":"Commit","text":"

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.

"},{"location":"articles/storage/#deduplication","title":"Deduplication","text":"

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.

"},{"location":"articles/storage/#garbage-collection","title":"Garbage collection","text":"

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.

"},{"location":"articles/storage/#scrub","title":"Scrub","text":"

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.

"},{"location":"articles/storage/#storage-backends","title":"Storage backends","text":"

The following types of storage backends are supported.

"},{"location":"articles/storage/#local-filesystem","title":"Local filesystem","text":"

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.

"},{"location":"articles/storage/#remote-filesystem","title":"Remote filesystem","text":"

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.

"},{"location":"articles/storage/#example-configuration-for-remote-s3-storage","title":"Example: configuration for remote (s3) storage","text":"Click here to view a sample zot configuration for remote storage. 
{\n    \"distSpecVersion\": \"1.0.1-dev\",\n    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true,\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"rootdirectory\": \"/zot\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false\n        },\n        \"cacheDriver\": {\n            \"name\": \"dynamodb\",\n            \"endpoint\": \"http://localhost:4566\",\n            \"region\": \"us-east-2\",\n            \"tableName\": \"MainTable\"\n        },\n    },\n    \"http\": {\n        \"address\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"log\": {\n        \"level\": \"debug\"\n    }\n}\n
"},{"location":"articles/storage/#configuring-zot-storage","title":"Configuring zot storage","text":"

Filesystem storage is configured with the storage attribute in the zot configuration file, as shown in the following example.

    \"storage\":{\n        \"rootDirectory\":\"/tmp/zot\",\n        \"commit\": true,\n        \"dedupe\": true,\n        \"gc\": true,\n        \"gcDelay\": \"1h\",\n        \"gcInterval\": \"24h\"\n    }\n
"},{"location":"articles/storage/#configurable-attributes","title":"Configurable attributes","text":"

The following table lists the attributes of the storage configuration.

Attribute Description

rootDirectory

Location of the images stored in the server file system.

commit

For faster performance, data written by zot is retained in memory before being periodically committed to disk by the operating system. To eliminate this retention time and cause data to be written to disk immediately, set to true. This prevents data loss but reduces performance.

dedupe

If the server filesystem supports hard links, you can optimize storage space by enabling inline deduplication of layers and blobs that are shared among multiple container images. Deduplication is enabled by default. Set to false to disable deduplication.

gc

When an image is deleted, either by tag or by reference, orphaned blobs can lead to wasted storage. Garbage collection (gc) is enabled by default to reclaim this space. Set to false to disable garbage collection.

gcDelay

(Optional) If garbage collection is enabled, causes it to run once after the specified delay time. The default is 1 hour. Requires the gc attribute to be true.

gcInterval

(Optional) If garbage collection is enabled, causes periodic collection at the specified interval. Must be set based on use cases and user workloads. If no value is specified, there is no periodic collection. Requires the gc attribute to be true.

subpaths

You can store and serve images from multiple filesystems, each with their own repository paths and settings. The following example shows three subpaths.

\"storage\":{\n  \"subPaths\": {\n    \"/a\": {\n      \"rootDirectory\": \"/tmp/zot1\",\n      \"dedupe\": true,\n      \"gc\": true\n    },\n    \"/b\": {\n      \"rootDirectory\": \"/tmp/zot2\",\n      \"dedupe\": true\n    },\n    \"/c\": {\n      \"rootDirectory\": \"/tmp/zot3\",\n      \"dedupe\": false\n    }\n  }\n}

storageDriver

(Remote storage only) Contains settings for a remote storage service. See Configuring remote storage with s3 for details.

cacheDriver

Specifies which database is used to store duplicate blobs when deduplication is enabled. See Cache drivers for details.

"},{"location":"articles/storage/#configuring-garbage-collection","title":"Configuring garbage collection","text":"

The zot configuration model allows for enabling and disabling garbage collection (gc) and specifying a periodic interval (gcInterval) for collection.

gc gcInterval Result false n/a GC disabled omitted n/a GC enabled with 1 hour interval (default) true omitted GC enabled with 1 hour interval true 0 GC runs only once true >0 GC enabled with specified interval

The configuration model also allows the configuration of a tunable delay (gcDelay), which can be set depending on client network speeds and the size of blobs. The gcDelay attribute causes collection to run once after the specified delay time. This attribute has a default value of one hour (1h).

"},{"location":"articles/storage/#configuring-remote-storage-with-s3","title":"Configuring remote storage with s3","text":"

To configure an Amazon Simple Storage Service (s3) bucket for zot, use the storageDriver attribute in the zot configuration file, as shown in the following example:

    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false,\n            \"accesskey\": \"<YOUR_ACCESS_KEY_ID>\",\n            \"secretkey\": \"<YOUR_SECRET_ACCESS_KEY>\"\n        }\n    }\n

For descriptions of the configurable attributes for storageDriver, see the s3 storage driver project in GitHub.

"},{"location":"articles/storage/#s3-credentials","title":"s3 Credentials","text":"

In the s3 configuration file example, the s3 credentials were configured with the attributes accesskey and secretkey. As an alternative, you can omit these attributes from the configuration file and you can configure them using environment variables or a credential file.

For more details about specifying s3 credentials, see the AWS documentation.

"},{"location":"articles/storage/#s3-permissions-scopes","title":"S3 permissions scopes","text":"

The following AWS policy is required by zot for push and pull.

Replace S3_BUCKET_NAME with the name of your s3 bucket.

[AWS CONFIGURATION]\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"s3:ListBucket\",\n        \"s3:GetBucketLocation\",\n        \"s3:ListBucketMultipartUploads\"\n      ],\n      \"Resource\": \"arn:aws:s3:::<S3_BUCKET_NAME>\"\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"s3:PutObject\",\n        \"s3:GetObject\",\n        \"s3:DeleteObject\",\n        \"s3:ListMultipartUploadParts\",\n        \"s3:AbortMultipartUpload\"\n      ],\n      \"Resource\": \"arn:aws:s3:::<S3_BUCKET_NAME>/*\"\n    }\n  ]\n}\n

For more details about configuring AWS policies, see the AWS documentation.

"},{"location":"articles/storage/#cache-drivers","title":"Cache drivers","text":"

A cache driver is used to store duplicate blobs when dedupe is enabled. zot supports database caching using BoltDB as the cache driver for local filesystems and DynamoDB for remote filesystems.

"},{"location":"articles/storage/#boltdb","title":"BoltDB","text":"

If you don't specify a cache driver, zot defaults to BoltDB. BoltDB is stored either in zot's root directory or in the subpath root directory.

    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true\n    }\n

In this example, BoltDB can be found at /tmp/zot/cache.db.

"},{"location":"articles/storage/#dynamodb","title":"DynamoDB","text":"

To use DynamoDB as the cache driver, the following storage configuration must be present:

    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true,\n        \"remoteCache\": true,\n        \"cacheDriver\": {\n            \"name\": \"dynamodb\",                  // driver name\n            \"endpoint\": \"http://localhost:4566\", // aws endpoint\n            \"region\": \"us-east-2\"                // aws region\n            \"cacheTablename\": \"ZotBlobTable\"     // table to store deduped blobs\n        }\n    },\n

The AWS GO SDK loads additional configuration and credentials values from your environment variables, shared credentials, and shared configuration files.

If the search extension is enabled, additional parameters are required:

        \"cacheDriver\": {\n            \"name\": \"dynamodb\",\n            \"endpoint\": \"http://localhost:4566\",\n            \"region\": \"us-east-2\",\n            \"cacheTablename\": \"ZotBlobTable\",\n            // used by search extensions\n            \"repoMetaTablename\": \"ZotRepoMetadataTable\",\n            \"manifestDataTablename\": \"ZotManifestDataTable\",\n            \"versionTablename\": \"ZotVersion\"\n        }\n
"},{"location":"articles/storage/#dynamodb-permission-scopes","title":"DynamoDB permission scopes","text":"

The following AWS policy is required by zot for caching blobs.

Replace DYNAMODB_TABLE with the name of your table, which should be the value of cacheTablename in the zot configuration.

In this case, the AWS Resource value would be arn:aws:dynamodb:*:*:table/ZotBlobTable

[AWS CONFIGURATION]\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"dynamodb:CreateTable\",\n        \"dynamodb:GetItem\",\n        \"dynamodb:UpdateItem\",\n        \"dynamodb:DeleteItem\"\n      ],\n      \"Resource\": \"arn:aws:dynamodb:*:*:table/<DYNAMODB_TABLE>\"\n    }\n  ]\n}\n

For more details about configuring AWS DynamoDB, see the AWS documentation.

"},{"location":"articles/storage/#remote-storage-subpaths","title":"Remote storage subpaths","text":"

As in the case with local filesystem storage, you can use multiple remote storage locations using the subpath attribute, as in the following example.

\"subPaths\": {\n    \"/a\": {\n        \"rootDirectory\": \"/zot-a\",\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false\n        }\n    },\n    \"/b\": {\n       .\n       .\n       .\n    }\n}\n

The subPaths feature ties together several separate storage filesystems and backends behind the same HTTP API interface. In the example above, both repository paths \"/a\" and \"/b\" are exposed to clients. Content on these two paths can be hosted completely separately by different storage services, locations, or filesystems, with no difference to the user interface and no perceptible difference to the user experience. This is useful if one wants to serve existing OCI images from different backends or if storage can be expanded only by using different backing stores.

zot also supports different storage drivers for each subpath.

"},{"location":"articles/verifying-signatures/","title":"Verifying image signatures","text":"

Images stored in zot can be signed with a digital signature to verify the source and integrity of the image. The digital signature can be verified by zot using public keys or certificates uploaded by the user.

To verify image signatures, zot supports the following tools:

"},{"location":"articles/verifying-signatures/#enabling-image-signature-verification","title":"Enabling image signature verification","text":"

To enable image signature verification, add the trust attribute under extensions in the zot configuration file and enable one or more verification tools, as shown in the following example:

\"extensions\": {\n  \"trust\": {\n    \"enable\": true,\n    \"cosign\": true,\n    \"notation\": true\n  }\n}\n

The following table lists the configurable attributes of the trust extension.

Attribute Description enable If this attribute is missing, signature verification is disabled by default. Signature verification is enabled by including this attribute and setting it to true. You must also enable at least one of the verification tools. cosign Set to true to enable signature verification using the cosign tool. notation Set to true to enable signature verification using the notation tool."},{"location":"articles/verifying-signatures/#what-is-needed-for-verifying-signatures","title":"What is needed for verifying signatures","text":"

To verify the validity of a signature for an image, zot makes use of two types of files:

Upload these files using an extension of the zot API, as shown in the following examples:

"},{"location":"articles/verifying-signatures/#where-needed-files-are-stored","title":"Where needed files are stored","text":"

Uploaded public keys and certificates are stored in the local filesystem, in specific directories named _cosign and _notation under $rootDir, or in the Secrets Manager.

"},{"location":"articles/verifying-signatures/#how-signature-verification-works","title":"How signature verification works","text":"

Based on the uploaded files and the information about images stored in zot's database, signature verification is performed for all signed images. The verification result for each signed image is stored in the database and is visible from GraphQL. The stored information about a signature includes:

"},{"location":"articles/verifying-signatures/#example-of-graphql-output","title":"Example of GraphQL output","text":"

Sample request

{\n  Image(image: \"busybox:latest\") {\n    Digest\n    IsSigned\n    Tag\n    SignatureInfo {\n        Tool\n        IsTrusted\n        Author\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"Image\": {\n      \"Digest\":\"sha256:6c19fba547b87bde9a45df2f8563e0c61826d098dd30192a2c8b86da1e1a6360\",\n      \"IsSigned\": true,\n      \"Tag\": \"latest\",\n      \"SignatureInfo\":[\n        {\n          \"Tool\":\"cosign\",\n          \"IsTrusted\":false,\n          \"Author\":\"\"\n        },\n        {\n          \"Tool\":\"cosign\",\n          \"IsTrusted\":false,\n          \"Author\":\"\"\n        },\n        {\n          \"Tool\":\"cosign\",\n          \"IsTrusted\": true,\n          \"Author\":\"-----BEGIN PUBLIC KEY-----\\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9pN+/hGcFlh4YYaNvZxNvuh8Qyhl\\npURz77qScOHe3DqdmiWiuqIseyhEdjEDwpL6fHRwu3a2Nd9wbKqm0la76w==\\n-----END PUBLIC KEY-----\\n\"\n        },\n        {\n          \"Tool\":\"notation\",\n          \"IsTrusted\": false,\n          \"Author\":\"CN=v4-test,O=Notary,L=Seattle,ST=WA,C=US\"\n        },\n        {\n          \"Tool\":\"notation\",\n          \"IsTrusted\": true,\n          \"Author\":\"CN=multipleSig,O=Notary,L=Seattle,ST=WA,C=US\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/workflow/","title":"Software Provenance Workflow Using OCI Artifacts","text":"

This article demonstrates an end-to-end workflow for installing a zot registry, then pushing and signing an image and a related artifact, such as an SBOM.

"},{"location":"articles/workflow/#workflow","title":"Workflow","text":"

The following sections describe the step-by-step workflow. To view the steps combined into a single script, see Reference: Full workflow script.

For the workflow examples, the zot registry is assumed to be installed and running at localhost:8080.

"},{"location":"articles/workflow/#step-1-download-the-client-tools","title":"Step 1: Download the client tools","text":"

This workflow uses the regctl registry client and the cosign image signing tool. As a first step, we download binaries for these tools in a tools directory. 

TEST_TMPDIR=$(mktemp -d \"${PWD}/artifact-test-${1:+-$1}.XXXXXX\")\n\nTOOLSDIR=$(pwd)/hack/tools\nmkdir -p ${TOOLSDIR}/bin\n\nREGCLIENT=${TOOLSDIR}/bin/regctl\nREGCLIENT_VERSION=v0.5.1\ncurl -Lo ${REGCLIENT} https://github.com/regclient/regclient/releases/download/${REGCLIENT_VERSION}/regctl-linux-amd64\nchmod +x ${REGCLIENT}\n\nCOSIGN=${TOOLSDIR}/bin/cosign\nCOSIGN_VERSION=2.1.1\ncurl -Lo ${COSIGN} https://github.com/sigstore/cosign/releases/download/v${COSIGN_VERSION}/cosign-linux-amd64 \nchmod +x ${COSIGN}\n
"},{"location":"articles/workflow/#step-2-deploy-an-oci-registry-with-referrers-support-zot","title":"Step 2: Deploy an OCI registry with referrers support (zot)","text":"

Next, we execute the following tasks to deploy an OCI registry:

ZOT=${TOOLSDIR}/bin/zot\nZOT_VERSION=2.0.0-rc6\ncurl -Lo ${ZOT} https://github.com/project-zot/zot/releases/download/v${ZOT_VERSION}/zot-linux-amd64-minimal\nchmod +x ${ZOT}\n\nZOT_HOST=localhost\nZOT_PORT=8080\n\n# function to start zot and test for readiness\nfunction zot_setup() {\ncat > $TEST_TMPDIR/zot-config.json << EOF\n{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n      \"rootDirectory\": \"$TEST_TMPDIR/zot\"\n  },\n  \"http\": {\n      \"address\": \"$ZOT_HOST\",\n      \"port\": \"$ZOT_PORT\"\n  },\n  \"log\": {\n      \"level\": \"error\"\n  }\n}\nEOF\n  # start zot as a background task\n  ${ZOT} serve $TEST_TMPDIR/zot-config.json &\n  pid=$!\n        # wait until service is up\n  count=5\n  up=0\n  while [[ $count -gt 0 ]]; do\n    if [ ! -d /proc/$pid ]; then\n      echo \"zot failed to start or died\"\n      exit 1\n    fi\n    up=1\n    curl -f http://$ZOT_HOST:$ZOT_PORT/v2/ || up=0\n    if [ $up -eq 1 ]; then break; fi\n    sleep 1\n    count=$((count - 1))\n  done\n  if [ $up -eq 0 ]; then\n    echo \"Timed out waiting for zot\"\n    exit 1\n  fi\n  # setup an OCI client\n  ${REGCLIENT} registry set --tls=disabled $ZOT_HOST:$ZOT_PORT\n}\n\n# call the function to start zot\nzot_setup\n
"},{"location":"articles/workflow/#step-3-copy-an-image-to-the-oci-registry","title":"Step 3: Copy an image to the OCI registry","text":"

This step copies a busybox container image into the registry.

skopeo copy --format=oci --dest-tls-verify=false docker://busybox:latest docker://${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n
"},{"location":"articles/workflow/#step-4-copy-a-related-artifact-to-the-oci-registry","title":"Step 4: Copy a related artifact to the OCI registry","text":"

This step creates a simple artifact file and associates it with the busybox image in the registry.

cat > ${TEST_TMPDIR}/artifact.yaml << EOF\nkey:\n  val: artifact\nEOF\n${REGCLIENT} artifact put --artifact-type application/yaml -f ${TEST_TMPDIR}/artifact.yaml --subject ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n

The --subject command flag associates the artifact file with the specified subject (in this case, the busybox image). If no subject is specified by the command, the artifact is considered independent and not associated with any existing image.

"},{"location":"articles/workflow/#step-5-display-the-artifact-tree","title":"Step 5: Display the artifact tree","text":"

This step prints the artifact tree of the busybox image. The tree includes the artifact yaml file, showing the association of the artifact to the busybox image.

These script commands define REF0 as the artifact that was uploaded referring to the first container image. 

REF0=$(${REGCLIENT} artifact tree --format '{{jsonPretty .}}' localhost:8080/busybox:latest | jq .referrer[0].reference.Digest)\nREF0=\"${REF0:1:-1}\"\n

The following example shows the command and its output:

$ regctl artifact tree localhost:8080/busybox:latest\n\nRef: localhost:8080/busybox:latest  \nDigest: sha256:9172c5f692f2c65e4f773448503b21dba2de6454bd159905c4bf6d83176e4ea3\nReferrers:  \n   - sha256:9c0655368b10ca4b2ffe39e4dd261fb89df25a46ae92d6eb4e6e1792a451883e: application/yaml\n

The displayed artifact tree shows that the original image (localhost:8080/busybox:latest) has one direct referrer (sha256:9c06...883e: application/yaml), the artifact yaml file.

"},{"location":"articles/workflow/#step-6-sign-the-image-and-artifact","title":"Step 6: Sign the image and artifact","text":"

This step creates a key pair for cosign in a separate directory, then uses cosign to sign both the image and the artifact file. Both signatures, like the artifact file itself, are associated with the busybox image. 

# create a key pair in a different directory\npushd ${TEST_TMPDIR}\nCOSIGN_PASSWORD= ${COSIGN} generate-key-pair\npopd\n# sign the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n# sign the artifact referring to the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox@${REF0}\n
"},{"location":"articles/workflow/#step-7-display-the-artifact-tree","title":"Step 7: Display the artifact tree","text":"

This step again prints the artifact tree, which should now show the artifact and the two signatures, all associated to the busybox image.

${REGCLIENT} artifact tree localhost:8080/busybox:latest\n

The following example shows the command and its output:

$ regctl artifact tree localhost:8080/busybox:latest\n\nRef: localhost:8080/busybox:latest\nDigest: sha256:9172c5f692f2c65e4f773448503b21dba2de6454bd159905c4bf6d83176e4ea3\nReferrers:\n  - sha256:9c0655368b10ca4b2ffe39e4dd261fb89df25a46ae92d6eb4e6e1792a451883e: application/yaml\n    Referrers:\n      - sha256:06792b209137486442a2b804b2225c0014e3e238d363cdbea088bbd73207fb34: application/vnd.dev.cosign.artifact.sig.v1+json\n  - sha256:995b6a78bf04a7a9676dac76b4598ccb645c17e30b02f294de9fdfa2f28eb7b2: application/vnd.dev.cosign.artifact.sig.v1+json\n

The displayed artifact tree shows that the original image now has two direct referrers \u2014 the artifact and the cosign signature of the original image. In addition, there is a second-level referrer \u2014 the cosign signature of the artifact, which is a referrer of the artifact file.

"},{"location":"articles/workflow/#step-8-end-of-demonstration","title":"Step 8: End of demonstration","text":"

This step halts the zot registry server, ending the workflow demonstration.

# function for stopping zot after demonstration\nfunction zot_teardown() {\n  killall zot\n}\n\n# stop zot\nzot_teardown\n
"},{"location":"articles/workflow/#reference-full-workflow-script","title":"Reference: Full workflow script","text":"

Expand the text box below to view the entire workflow as a single executable shell script.

To copy the script to the clipboard, click the copy icon that appears in the upper right corner of the expanded text box.

Click here to view the all-in-one script 
#!/bin/bash -xe\n\nTEST_TMPDIR=$(mktemp -d \"${PWD}/artifact-test-${1:+-$1}.XXXXXX\")\n\nTOOLSDIR=$(pwd)/hack/tools\nmkdir -p ${TOOLSDIR}/bin\n\nREGCLIENT=${TOOLSDIR}/bin/regctl\nREGCLIENT_VERSION=v0.5.1\ncurl -Lo ${REGCLIENT} https://github.com/regclient/regclient/releases/download/${REGCLIENT_VERSION}/regctl-linux-amd64\nchmod +x ${REGCLIENT}\n\nCOSIGN=${TOOLSDIR}/bin/cosign\nCOSIGN_VERSION=2.1.1\ncurl -Lo ${COSIGN} https://github.com/sigstore/cosign/releases/download/v${COSIGN_VERSION}/cosign-linux-amd64 \nchmod +x ${COSIGN}\n\n# OCI registry\nZOT=${TOOLSDIR}/bin/zot\nZOT_VERSION=2.0.0-rc6\ncurl -Lo ${ZOT} https://github.com/project-zot/zot/releases/download/v${ZOT_VERSION}/zot-linux-amd64-minimal\nchmod +x ${ZOT}\n\nZOT_HOST=localhost\nZOT_PORT=8080\n\nfunction zot_setup() {\ncat > $TEST_TMPDIR/zot-config.json << EOF\n{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n      \"rootDirectory\": \"$TEST_TMPDIR/zot\"\n  },\n  \"http\": {\n      \"address\": \"$ZOT_HOST\",\n      \"port\": \"$ZOT_PORT\"\n  },\n  \"log\": {\n      \"level\": \"error\"\n  }\n}\nEOF\n# start as a background task\n${ZOT} serve $TEST_TMPDIR/zot-config.json &\npid=$!\n        # wait until service is up\ncount=5\nup=0\nwhile [[ $count -gt 0 ]]; do\n    if [ ! -d /proc/$pid ]; then\n    echo \"zot failed to start or died\"\n    exit 1\n    fi\n    up=1\n    curl -f http://$ZOT_HOST:$ZOT_PORT/v2/ || up=0\n    if [ $up -eq 1 ]; then break; fi\n    sleep 1\n    count=$((count - 1))\ndone\nif [ $up -eq 0 ]; then\n    echo \"Timed out waiting for zot\"\n    exit 1\nfi\n# setup a OCI client\n${REGCLIENT} registry set --tls=disabled $ZOT_HOST:$ZOT_PORT\n}\n\n# function for stopping zot after demonstration\nfunction zot_teardown() {\nkillall zot\n}\n\n# call the function to start zot\nzot_setup\n\n# copy an image\nskopeo copy --format=oci --dest-tls-verify=false docker://busybox:latest docker://${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n\n# copy an artifact referring to the above image\ncat > ${TEST_TMPDIR}/artifact.yaml << EOF\nkey:\nval: artifact\nEOF\n${REGCLIENT} artifact put --artifact-type application/yaml -f ${TEST_TMPDIR}/artifact.yaml --subject ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\nREF0=$(${REGCLIENT} artifact tree --format '{{jsonPretty .}}' localhost:8080/busybox:latest | jq .referrer[0].reference.Digest)\nREF0=\"${REF0:1:-1}\"\n\n# create a key pair in a different directory\npushd ${TEST_TMPDIR}\nCOSIGN_PASSWORD= ${COSIGN} generate-key-pair\npopd\n# sign the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n# sign the artifact referring to the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox@${REF0}\n\n# list the reference tree\n${REGCLIENT} artifact tree localhost:8080/busybox:latest\n\n# stop zot\nzot_teardown\n
"},{"location":"developer-guide/api-reference/","title":"zot API Command Reference","text":"

This article describes the zot REST API commands, parameters, and responses.

The information presented here is adapted from the interactive OpenAPI (formerly swagger) JSON file in the zot Github project.

For instructions and examples of how to use the zot API, see Using the zot API.

"},{"location":"developer-guide/api-reference/#zotauthapikey","title":"/zot/auth/apikey","text":""},{"location":"developer-guide/api-reference/#delete-zotauthapikey","title":"DELETE /zot/auth/apikey","text":"

Revokes one current user API key based on given key ID

Parameters

Name In Type Required Description id query string true api token id (UUID)

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request string 401 Unauthorized unauthorized string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-zotauthapikey","title":"GET /zot/auth/apikey","text":"

Get list of all API keys for a logged in user

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 401 Unauthorized unauthorized string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#post-zotauthapikey","title":"POST /zot/auth/apikey","text":"

Can create an api key for a logged in user, based on the provided label and scopes.

Body parameter

{\n  \"expirationDate\": \"string\",\n  \"label\": \"string\",\n  \"scopes\": [\n    \"string\"\n  ]\n}\n

Parameters

Name In Type Required Description body body api.APIKeyPayload true api token id (UUID)

Example responses

201 Response

\"string\"\n

Responses

Status Meaning Description Schema 201 Created created string 400 Bad Request bad request string 401 Unauthorized unauthorized string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#zotauthlogout","title":"/zot/auth/logout","text":""},{"location":"developer-guide/api-reference/#post-zotauthlogout","title":"POST /zot/auth/logout","text":"

Logout by removing current session

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok\". string 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#orasartifactsv1namemanifestsdigestreferrers","title":"/oras/artifacts/v1/{name}/manifests/{digest}/referrers","text":""},{"location":"developer-guide/api-reference/#get-orasartifactsv1namemanifestsdigestreferrers","title":"GET /oras/artifacts/v1/{name}/manifests/{digest}/referrers","text":"

Get references for an image given a digest and artifact type

Parameters

Name In Type Required Description name path string true repository name digest path string true image digest artifactType query string true artifact type

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2","title":"/v2/","text":""},{"location":"developer-guide/api-reference/#get-v2","title":"GET /v2/","text":"

Check if this API version is supported

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_catalog","title":"/v2/_catalog","text":""},{"location":"developer-guide/api-reference/#get-v2_catalog","title":"GET /v2/_catalog","text":"

List all image repositories

Example responses

200 Response

{\n  \"repositories\": [\n    \"string\"\n  ]\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.RepositoryList 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_ociextdiscover","title":"/v2/_oci/ext/discover","text":""},{"location":"developer-guide/api-reference/#get-v2_ociextdiscover","title":"GET /v2/_oci/ext/discover","text":"

List all extensions present on registry

Example responses

200 Response

{\n  \"extensions\": [\n    {\n      \"description\": \"string\",\n      \"endpoints\": [\n        \"string\"\n      ],\n      \"name\": \"string\",\n      \"url\": \"string\"\n    }\n  ]\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ExtensionList

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextcosign","title":"/v2/_zot/ext/cosign","text":""},{"location":"developer-guide/api-reference/#post-v2_zotextcosign","title":"POST /v2/_zot/ext/cosign","text":"

Upload cosign public keys for verifying signatures

Body parameter

string\n

Parameters

Name In Type Required Description body body string true Public key content

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request\". string 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextmgmt","title":"/v2/_zot/ext/mgmt","text":""},{"location":"developer-guide/api-reference/#get-v2_zotextmgmt","title":"GET /v2/_zot/ext/mgmt","text":"

Get current server configuration

Parameters

Name In Type Required Description resource query string false specify resource

Enumerated Values

Parameter Value resource config

Example responses

200 Response

{\n  \"binaryType\": \"string\",\n  \"distSpecVersion\": \"string\",\n  \"http\": {\n    \"auth\": {\n      \"bearer\": {\n        \"realm\": \"string\",\n        \"service\": \"string\"\n      },\n      \"htpasswd\": {\n        \"path\": \"string\"\n      },\n      \"ldap\": {\n        \"address\": \"string\"\n      },\n      \"openid\": {\n        \"providers\": {\n          \"property1\": {\n            \"name\": \"string\"\n          },\n          \"property2\": {\n            \"name\": \"string\"\n          }\n        }\n      }\n    }\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK extensions.StrippedConfig 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextnotation","title":"/v2/_zot/ext/notation","text":""},{"location":"developer-guide/api-reference/#post-v2_zotextnotation","title":"POST /v2/_zot/ext/notation","text":"

Upload notation certificates for verifying signatures

Body parameter

string\n

Parameters

Name In Type Required Description truststoreType query string false truststore type body body string true Certificate content

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request\". string 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextuserprefs","title":"/v2/_zot/ext/userprefs","text":""},{"location":"developer-guide/api-reference/#put-v2_zotextuserprefs","title":"PUT /v2/_zot/ext/userprefs","text":"

Add bookmarks/stars info

Parameters

Name In Type Required Description action query string true specify action repo query string true repository name

Enumerated Values

Parameter Value action toggleBookmark action toggleStar

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request\". string 403 Forbidden forbidden string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nameblobsdigest","title":"/v2/{name}/blobs/{digest}","text":""},{"location":"developer-guide/api-reference/#delete-v2nameblobsdigest","title":"DELETE /v2/{name}/blobs/{digest}","text":"

Delete an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true blob/layer digest

Example responses

202 Response

\"string\"\n

Responses

Status Meaning Description Schema 202 Accepted accepted string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-v2nameblobsdigest","title":"GET /v2/{name}/blobs/{digest}","text":"

Get an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true blob/layer digest

Example responses

200 Response

Responses

Status Meaning Description Schema 200 OK OK api.ImageManifest

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#head-v2nameblobsdigest","title":"HEAD /v2/{name}/blobs/{digest}","text":"

Check an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true blob/layer digest

Example responses

200 Response

{\n  \"annotations\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"artifactType\": \"string\",\n  \"config\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  },\n  \"layers\": [\n    {\n      \"annotations\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"artifactType\": \"string\",\n      \"data\": [\n        0\n      ],\n      \"digest\": \"string\",\n      \"mediaType\": \"string\",\n      \"platform\": {\n        \"architecture\": \"string\",\n        \"os\": \"string\",\n        \"os.features\": [\n          \"string\"\n        ],\n        \"os.version\": \"string\",\n        \"variant\": \"string\"\n      },\n      \"size\": 0,\n      \"urls\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"mediaType\": \"string\",\n  \"schemaVersion\": 0,\n  \"subject\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ImageManifest

Response Headers

Status Header Type Format Description 200 constants.DistContentDigestKey object none

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nameblobsuploads","title":"/v2/{name}/blobs/uploads","text":""},{"location":"developer-guide/api-reference/#post-v2nameblobsuploads","title":"POST /v2/{name}/blobs/uploads","text":"

Create a new image blob/layer upload

Parameters

Name In Type Required Description name path string true repository name

Example responses

202 Response

\"string\"\n

Responses

Status Meaning Description Schema 202 Accepted accepted string 401 Unauthorized unauthorized string 404 Not Found not found string 500 Internal Server Error internal server error string

Response Headers

Status Header Type Format Description 202 Location string /v2/{name}/blobs/uploads/{session_id} 202 Range string 0-0

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nameblobsuploadssession_id","title":"/v2/{name}/blobs/uploads/{session_id}","text":""},{"location":"developer-guide/api-reference/#delete-v2nameblobsuploadssession_id","title":"DELETE /v2/{name}/blobs/uploads/{session_id}","text":"

Delete an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-v2nameblobsuploadssession_id","title":"GET /v2/{name}/blobs/uploads/{session_id}","text":"

*Get an image's blob/layer upload given a session_id

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id

Example responses

204 Response

\"string\"\n

Responses

Status Meaning Description Schema 204 No Content no content string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#patch-v2nameblobsuploadssession_id","title":"PATCH /v2/{name}/blobs/uploads/{session_id}","text":"

Resume an image's blob/layer upload given an session_id

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id

Example responses

202 Response

\"string\"\n

Responses

Status Meaning Description Schema 202 Accepted accepted string 400 Bad Request bad request string 404 Not Found not found string 416 Range Not Satisfiable range not satisfiable string 500 Internal Server Error internal server error string

Response Headers

Status Header Type Format Description 202 Location string /v2/{name}/blobs/uploads/{session_id} 202 Range string 0-128

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#put-v2nameblobsuploadssession_id","title":"PUT /v2/{name}/blobs/uploads/{session_id}","text":"

Update and finish an image's blob/layer upload given a digest

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id digest query string true blob/layer digest

Example responses

201 Response

\"string\"\n

Responses

Status Meaning Description Schema 201 Created created string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2namemanifestsreference","title":"/v2/{name}/manifests/{reference}","text":""},{"location":"developer-guide/api-reference/#delete-v2namemanifestsreference","title":"DELETE /v2/{name}/manifests/{reference}","text":"

Delete an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-v2namemanifestsreference","title":"GET /v2/{name}/manifests/{reference}","text":"

Get an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

200 Response

{\n  \"annotations\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"artifactType\": \"string\",\n  \"config\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  },\n  \"layers\": [\n    {\n      \"annotations\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"artifactType\": \"string\",\n      \"data\": [\n        0\n      ],\n      \"digest\": \"string\",\n      \"mediaType\": \"string\",\n      \"platform\": {\n        \"architecture\": \"string\",\n        \"os\": \"string\",\n        \"os.features\": [\n          \"string\"\n        ],\n        \"os.version\": \"string\",\n        \"variant\": \"string\"\n      },\n      \"size\": 0,\n      \"urls\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"mediaType\": \"string\",\n  \"schemaVersion\": 0,\n  \"subject\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size20\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ImageManifest 404 Not Found not found string 500 Internal Server Error internal server error string

Response Headers

Status Header Type Format Description 200 constants.DistContentDigestKey object none

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#head-v2namemanifestsreference","title":"HEAD /v2/{name}/manifests/{reference}","text":"

Check an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 404 Not Found not found string 500 Internal Server Error internal server error\". string

Response Headers

Status Header Type Format Description 200 constants.DistContentDigestKey object none

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#put-v2namemanifestsreference","title":"PUT /v2/{name}/manifests/{reference}","text":"

Update an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

201 Response

\"string\"\n

Responses

Status Meaning Description Schema 201 Created created string 400 Bad Request bad request string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2namereferrersdigest","title":"/v2/{name}/referrers/{digest}","text":""},{"location":"developer-guide/api-reference/#get-v2namereferrersdigest","title":"GET /v2/{name}/referrers/{digest}","text":"

Get referrers given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true digest artifactType query string false artifact type

Example responses

200 Response

{\n  \"annotations\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"artifactType\": \"string\",\n  \"manifests\": [\n    {\n      \"annotations\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"artifactType\": \"string\",\n      \"data\": [\n        0\n      ],\n      \"digest\": \"string\",\n      \"mediaType\": \"string\",\n      \"platform\": {\n        \"architecture\": \"string\",\n        \"os\": \"string\",\n        \"os.features\": [\n          \"string\"\n        ],\n        \"os.version\": \"string\",\n        \"variant\": \"string\"\n      },\n      \"size\": 0,\n      \"urls\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"mediaType\": \"string\",\n  \"schemaVersion\": 0,\n  \"subject\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ImageIndex 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nametagslist","title":"/v2/{name}/tags/list","text":""},{"location":"developer-guide/api-reference/#get-v2nametagslist","title":"GET /v2/{name}/tags/list","text":"

List all image tags in a repository

Parameters

Name In Type Required Description name path string true repository name n query integer true limit entries for pagination last query string true last tag value for pagination

Example responses

200 Response

{\n  \"name\": \"string\",\n  \"tags\": [\n    \"string\"\n  ]\n}\n

Responses

Status Meaning Description Schema 200 OK OK common.ImageTags 400 Bad Request bad request\". string 404 Not Found not found string

This operation does not require authentication

"},{"location":"developer-guide/api-user-guide/","title":"Using the zot API","text":"

This document describes how to use the zot REST API and provides a number of examples.

For comprehensive details of all zot API commands, see Viewing the complete zot API reference.

The zot API implements the OCI Distribution endpoints along with additional endpoints for supported extensions. You can access the REST API at the same URL and port number used by the GUI and by datapath tools.

The examples in this article assume that the zot registry is located at localhost:8080.

"},{"location":"developer-guide/api-user-guide/#supported-api-endpoints","title":"Supported API endpoints","text":"

The following is a list of zot API endpoints along with the conditions under which each endpoint is available.

Some API endpoints are available only when a specific extension is enabled in the zot configuration file, or when an extension build label is specified in the make command (for example, make binary EXTENSIONS=ui), or both.

For comprehensive details of the API endpoints, see Viewing the complete zot API reference.

"},{"location":"developer-guide/api-user-guide/#oci-endpoints","title":"OCI endpoints","text":"Endpoint Actions Description /v2/ GET OCI specification endpoints /v2/_catalog GET Lists repositories in a registry. /v2/_oci/ext/discover GET Discover extensions per the OCI specification /v2/{repo}/blobs/{digest} DELETE, GET, HEAD Lists or deletes an image's blob/layer given a digest /v2/{repo}/blobs/uploads POST Creates an image blob/layer upload /v2/{repo}/blobs/uploads/{session_id} DELETE, GET, PATCH, PUT Creates, lists, or deletes an image's blob/layer upload given a session_id /v2/{repo}/manifests/{reference} DELETE, GET, HEAD, PUT Creates, lists, or deletes references for an image /v2/{repo}/referrers/{digest} GET Lists referrers given a digest /v2/{repo}/tags/list GET List all image tags in a repository"},{"location":"developer-guide/api-user-guide/#zot-oci-extension-endpoints","title":"zot OCI extension endpoints","text":"Endpoint Actions Description Availability /v2/_zot/ext/mgmt GET Mgmt extension endpoints Enabled by using the mgmt build label and enabling the search extension in the configuration file. /v2/_zot/ext/notation POST With query parameters, uploads certificates for signature verification Enabled by using the imagetrust build label and enabling the trust extension with the notation option enabled. /v2/_zot/ext/search Enhanced search Enabled by using the search build label and enabling the search extension in the configuration file. /v2/_zot/ext/cosign POST Uploads keys for signature verification Enabled by using the imagetrust build label and enabling the trust extension with the cosign option enabled. /v2/_zot/ext/userprefs PUT User preferences endpoints Enabled by using the userprefs build label and enabling both the search and the ui extensions in the configuration file."},{"location":"developer-guide/api-user-guide/#zot-auth-endpoints","title":"zot auth endpoints","text":"Endpoint Actions Description Availability /zot/auth/apikey DELETE, GET, POST Creates, lists, or deletes API keys Available when API key authentication is enabled in the configuration file (\"apikey\": true). /zot/auth/login POST Opens an API session Available when authentication is available. This includes not only OpenID, but all session-based authentication. /zot/auth/logout POST Ends an API session Available when authentication is available. This includes not only OpenID, but all session-based authentication. /zot/auth/callback/\\<provider> POST Specifies a social authentication service provider for redirecting logins, such as Google or dex. Enabled when an OpenID authentication service provider is specified in the configuration file."},{"location":"developer-guide/api-user-guide/#other-zot-endpoints","title":"other zot endpoints","text":"Endpoint Actions Description Availability /v2/_zot/pprof/ GET Returns a current HTML-format profile list along with a count of currently available records for each profile. See Performance Profiling in zot for usage details. Always enabled. /v2/_zot/debug/graphql-playground# See Using GraphQL for details. Enabled only in a binary-debug zot build or when the zot registry has been built with the debug extension label."},{"location":"developer-guide/api-user-guide/#oras-endpoints","title":"ORAS endpoints","text":"Endpoint Actions Description Availability /oras/artifacts/v1/{repo}/ manifests/{digest}/referrers GET OCI Registry As Storage (ORAS) endpoints Always enabled."},{"location":"developer-guide/api-user-guide/#prometheus-endpoint","title":"prometheus endpoint","text":"Endpoint Actions Description Availability /metrics GET Returns extended metrics for monitoring by prometheus Enabled when the metrics extension is enabled in the configuration file."},{"location":"developer-guide/api-user-guide/#openapi-swagger-endpoints","title":"OpenAPI (swagger) endpoints","text":"

This endpoint is accessed with a browser.

Endpoint Action Description Availability /swagger/v2/ (browser) Displays an interactive OpenAPI (swagger) API reference. Enabled only in a binary-debug zot build or when the zot registry has been built with the debug extension label."},{"location":"developer-guide/api-user-guide/#api-authentication","title":"API authentication","text":"

If zot authentication is not configured, any user can access the zot API.

When pushing and pulling images using API calls, your identity can be authenticated by either a password or an API key.

With a valid password, you can specify your credentials in a cURL request as shown in this example:

curl -u <user>:<password> -X GET http://<server>/<endpoint>\n

An API key has advantages in situations where the primary zot authentication does not use the command line, such as a GUI login or social login. Also, you can reduce your security exposure by using an API key instead of your broader credentials, such as an LDAP username and password.

"},{"location":"developer-guide/api-user-guide/#using-api-keys","title":"Using API keys","text":""},{"location":"developer-guide/api-user-guide/#enabling-api-keys","title":"Enabling API keys","text":"

To enable the use of API keys, you must set the apikey attribute to true in the zot configuration file, as shown in the following example:

  \"http\": {\n    \"auth\": {\n      \"apikey\": true\n    }\n  }\n
"},{"location":"developer-guide/api-user-guide/#creating-your-api-key","title":"Creating your API key","text":"

Before you can create or revoke an API key, you must first log in using a different authentication mechanism, such as logging in through the zot GUI. When you are logged in, you can create an API key for your identity using the following API command:

POST /zot/auth/apikey\n

cURL command example:

curl -u user:password -X POST http://localhost:8080/zot/auth/apikey -d '{\"label\": \"myAPIKEY\", \"scopes\": [\"repo1\", \"repo2\"], \"expirationDate\": \"2023-08-28T17:10:05+03:00\"}'\n

The scopes and expiration date in this example are optional. By default, an API key has the same permissions as the user who created it.

Command output:

{\n  \"createdAt\":\"2023-08-28T17:09:59.2603515+03:00\",\n  \"expirationDate\":\"2023-08-28T17:10:05+03:00\",\n  \"isExpired\":false,\n  \"creatorUa\":\"curl/7.68.0\",\n  \"generatedBy\":\"manual\",\n  \"lastUsed\":\"0001-01-01T00:00:00Z\",\n  \"label\":\"myAPIKEY\",\n  \"scopes\": [\n    \"repo1\",\n    \"repo2\"\n  ],\n  \"uuid\":\"c931e635-a80d-4b52-b035-6b57be5f6e74\",\n  \"apiKey\":\"zak_ac55a8693d6b4370a2003fa9e10b3682\"\n}\n

The API key (apiKey) is shown to the user only in the command output when the key is created. It cannot be later retrieved from zot with any other command.

"},{"location":"developer-guide/api-user-guide/#using-your-api-key-in-an-api-command","title":"Using your API key in an API command","text":"

The API key replaces a password in the API command, as shown in the following cURL example:

curl -u user:zak_e77bcb9e9f634f1581756abbf9ecd269 http://localhost:8080/v2/_catalog\n
"},{"location":"developer-guide/api-user-guide/#removing-your-api-key","title":"Removing your API key","text":"

When logged in, you can revoke your own API key with the following API command:

DELETE /zot/auth/apikey?id=$uuid\n

cURL command example:

curl -u user:password -X DELETE http://localhost:8080/v2/zot/auth/apikey?id=46a45ce7-5d92-498a-a9cb-9654b1da3da1\n
"},{"location":"developer-guide/api-user-guide/#listing-your-current-api-keys","title":"Listing your current API keys","text":"

When logged in, you can display a list of your API keys with the following API command:

GET /zot/auth/apikey\n

cURL command example:

curl -u user:password -X GET http://localhost:8080/zot/auth/apikey\n

Command output:

{\n  \"apiKeys\": [\n    {\n      \"createdAt\": \"2023-05-05T15:39:28.420926+03:00\",\n      \"expirationDate\": \"0001-01-01T00:00:00Z\",\n      \"isExpired\": true,\n      \"creatorUa\": \"curl/7.68.0\",\n      \"generatedBy\": \"manual\",\n      \"lastUsed\": \"0001-01-01T00:00:00Z\",\n      \"label\": \"git\",\n      \"scopes\": [\n        \"repo1\",\n        \"repo2\"\n      ],\n      \"uuid\": \"46a45ce7-5d92-498a-a9cb-9654b1da3da1\"\n    },\n    {\n      \"createdAt\": \"2023-08-11T14:43:00.6459729+03:00\",\n      \"expirationDate\": \"2023-08-17T18:24:05+03:00\",\n      \"isExpired\": false,\n      \"creatorUa\": \"curl/7.68.0\",\n      \"generatedBy\": \"manual\",\n      \"lastUsed\": \"2023-08-11T14:43:47.5559998+03:00\",\n      \"label\": \"myAPIKEY\",\n      \"scopes\": null,\n      \"uuid\": \"294abf69-b62f-4e58-b214-dad2aec0bc52\"\n    }\n  ]\n}\n

This command output example shows an expired key and a current key for this user.

The actual API key (apiKey) is not shown. The key is shown to the user only when it is created.

"},{"location":"developer-guide/api-user-guide/#api-examples","title":"API examples","text":"

The following examples assume that the zot registry is located at localhost:8080.

"},{"location":"developer-guide/api-user-guide/#listing-repositories","title":"Listing repositories","text":"

To get a list of all image repositories in the registry, use the following API endpoint:

GET /v2/_catalog\n

cURL command example:

curl -X GET http://localhost:8080/v2/_catalog\n

Command output:

{\n    \"repositories\": [\"alpine\", \"busybox\"]\n}\n
"},{"location":"developer-guide/api-user-guide/#discovering-extension-endpoints","title":"Discovering extension endpoints","text":"

To list the installed and enabled zot extensions that can be accessed through the API, use the following OCI API endpoint:

GET /v2/_oci/ext/discover\n

cURL command example:

curl -X GET http://localhost:8080/v2/_oci/ext/discover\n

Command output:

{\n  \"extensions\": [\n  {\n    \"name\": \"_zot\",\n    \"url\": \"https://github.com/project-zot/zot/blob//pkg/extensions/_zot.md\",\n    \"description\": \"zot registry extensions\",\n    \"endpoints\": [\"/v2/_zot/ext/search\", \"/v2/_zot/ext/userprefs\", \"/v2/_zot/ext/mgmt\"]\n  }]\n}\n
"},{"location":"developer-guide/api-user-guide/#uploading-a-certificate-for-notation","title":"Uploading a certificate for Notation","text":"

To upload a certificate for notation, use the following endpoint:

POST /v2/_zot/ext/notation\n

cURL command example:

curl --data-binary @certificate.crt -X POST \"http://localhost:8080/v2/_zot/ext/notation?truststoreType=ca\"\n
"},{"location":"developer-guide/api-user-guide/#viewing-the-complete-zot-api-reference","title":"Viewing the complete zot API reference","text":"

You can find comprehensive details of all zot API commands in either of the following locations:

There are many ways to view a swagger file as an interactive document. If you have the npm package installed, for example, you can execute the following command:

  $ npx open-swagger-ui swagger.json\n

This command creates a local web server at localhost:3355 where you can interact with the API reference using a browser.

"},{"location":"developer-guide/contributing/","title":"Contributing to zot Development","text":"

The zot project is built for developers by developers. The zot project welcomes the participation of the open source community in extending and improving zot.

"},{"location":"developer-guide/contributing/#submission-requirements","title":"Submission Requirements","text":"

Summary: All contributions must meet these requirements:

"},{"location":"developer-guide/contributing/#license","title":"License","text":"

zot is released under the Apache License 2.0. All contributions must adhere to this license and must explicitly state adherence.

"},{"location":"developer-guide/contributing/#submitting-a-pull-request-pr","title":"Submitting a Pull Request (PR)","text":"

First, fork the zot project on GitHub and submit a commit to your fork. Then open a new pull request (PR) to the zot project. All pull requests must meet these requirements:

Either the commit message or the PR description must contain the following statement:

\"By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.\"

All commits require a Developer Certificate of Origin via the \"Signed-off-by:\" commit message and commit signatures using GPG keys. Include the -s flag in your git commit command.

The commit message must follow the Convention Commits format. The message must begin with a keyword that categorizes the commit, followed by a colon. Validation of a commit message is determined by this expression:

\"^((build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\(.+\\))?(!)?(: (.*\\s*)*))\"

An example of a valid commit message is \"docs: Fixes a typo in module.md.\"

In addition, any new PR requires a brief form to be completed by the submitter with details about the PR. Appropriate code owners are automatically identified and will be notified of the new PR.

"},{"location":"developer-guide/contributing/#cicd-checks","title":"CI/CD Checks","text":"

We take code quality very seriously. All PRs must pass various CI/CD checks that enforce code quality such as code coverage, security scanning, performance regressions, distribution spec conformance, ecosystem client tool compatibility, etc.

"},{"location":"developer-guide/contributing/#reporting-issues","title":"Reporting Issues","text":"

Issues are broadly classified as functional bugs and security issues. The latter is treated a little differently due to the sensitive nature.

"},{"location":"developer-guide/contributing/#filing-a-functional-issue","title":"Filing a Functional Issue","text":"

No software is perfect, and we expect users to find issues with the zot code base. First, check whether your issue has already been filed by someone else by performing an issue search. If the issue is not found, file a new issue by clicking the New issue button on the zot/issues page and answering the questions. The more information that you can provide, the easier it becomes to triage the issue.

"},{"location":"developer-guide/contributing/#filing-a-security-issue","title":"Filing a Security Issue","text":"

Security issues are best filed by sending an email to security@zotregistry.dev. After 45 days, we will make the issue public and give credit to the original filer of the issue.

"},{"location":"developer-guide/contributing/#code-of-conduct","title":"Code of Conduct","text":"

The zot project follows the CNCF Code of Conduct.

"},{"location":"developer-guide/contributing/#reporting-conduct-incidents","title":"Reporting Conduct Incidents","text":"

To report a conduct-related incident occurring on the zot project, contact the zot project conduct committee by sending an email to conduct@zotregistry.dev. You can expect a response within three business days.

"},{"location":"developer-guide/extensions-dev/","title":"Developing New Extensions","text":"

You can add new functionality to the zot registry by developing extensions for integration into zot.

The OCI Distribution Specification supports extending the functionality of an OCI-compliant registry implementation by adding extensions. Extensions are new APIs developed outside of the core OCI specs. Developers may propose their extensions to the OCI for possible future addition to the Distribution Specification.

When planning the development of a new extension, be sure to familiarize yourself with the OCI documentation and guidelines for extensions.

"},{"location":"developer-guide/extensions-dev/#current-extensions","title":"Current extensions","text":"

The following extensions are currently available in the zot project:

You can examine the implementation of these extensions in the zot project extensions section. The operation and configuration of the current extensions is described in Configuring zot.

"},{"location":"developer-guide/extensions-dev/#guidelines-for-developing-new-extensions","title":"Guidelines for developing new extensions","text":" 
  //go:build foo\n  // +build foo\n\n  package foo\n\n  ...\n
- The first line (`//go:build foo`) is added automatically by the linter if not already present.\n\n- The second line and the third (blank) line are mandatory.\n

    //go:build !foo\n    // +build !foo\n\n    package foo\n\n    ...\n
See extension lint-disabled.go in the zot project for an example of a \"no-op\" file.

"},{"location":"developer-guide/extensions-dev/#building-zot-with-extensions","title":"Building zot with extensions","text":"

When you build the full zot image (for example, make binary), all extensions listed in the EXTENSIONS variable in Makefile are included in the build. When you've created a new extension, you must modify the EXTENSIONS variable in Makefile by adding the new extension.

To build an image with only selected extensions, you can specify the desired extensions by declaring them in the build command:

make binary EXTENSIONS=extension1,extension2,extension3...\n

For example, to build with only sync and scrub, the command would be:

make binary EXTENSIONS=sync,scrub\n
"},{"location":"developer-guide/onboarding/","title":"Onboarding zot for Development","text":"

zot is a production-ready, open-source, extensible OCI-native image registry, built for developers by developers.

"},{"location":"developer-guide/onboarding/#getting-started","title":"Getting Started","text":""},{"location":"developer-guide/onboarding/#supported-developer-platforms","title":"Supported Developer Platforms","text":"

Development is officially supported on Linux and Apple MacOS platforms. 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 (Apple M1)

Supported platforms and architectures

"},{"location":"developer-guide/onboarding/#prerequisites","title":"Prerequisites","text":""},{"location":"developer-guide/onboarding/#install-golang","title":"Install golang","text":"

Follow the golang instructions to install the golang toolchain. After installation, make sure that the path environment variable or your IDE can find the toolchain.

You must use a golang version of at least the minimum specified in go.mod or the build will fail.

"},{"location":"developer-guide/onboarding/#cloning-zot","title":"Cloning zot","text":"

The zot registry code base is hosted on GitHub at https://github.com/project-zot/zot.

To clone the zot project, use this command:

$ git clone https://github.com/project-zot/zot.git\n
"},{"location":"developer-guide/onboarding/#building-zot","title":"Building zot","text":"

To build zot, execute the make command in the zot directory using the following general syntax:

$ make OS=os ARCH=architecture {binary | binary-minimal}

For example, to build a zot image with extensions for an Intel-based linux server, use the following command:

make OS=linux ARCH=amd64 binary\n

The make command builds an executable image in the zot/bin directory. The original filename of the zot executable image will indicate the build options. For example, the filename of an Intel-based linux minimal image is zot-minimal-linux-amd64.

Click here to view an example of the getting started process.

"},{"location":"developer-guide/onboarding/#running-zot","title":"Running zot","text":"

The behavior of zot is controlled via configuration only. To launch the zot server, execute the following command:

$  bin/zot-linux-amd64 serve examples/config-minimal.json\n
"},{"location":"developer-guide/onboarding/#debugging-zot","title":"Debugging zot","text":"

To produce a zot binary that includes extensive debugging information, build zot with the binary-debug option, as shown in this example:

make OS=linux ARCH=amd64 binary-debug\n

You can then attach and run a debugging tool such as Delve to the running zot process.

Delve is a powerful open-source debugger for the Go programming language. Downloads and documentation for Delve are available on GitHub at https://github.com/go-delve/delve.

"},{"location":"developer-guide/onboarding/#performance-profiling","title":"Performance profiling","text":"

Performance 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.

For detailed information about performance profiling, see Performance Profiling in zot.

"},{"location":"developer-guide/onboarding/#code-organization","title":"Code Organization","text":"

The zot project codebase is organized as follows:

/\n- pkg/              # Source code for all libraries\n  - api/            # Source code for HTTP APIs\n    - config/       # Global configuration model\n  - storage/        # Source code for storage backends\n  - cli/            # Source code for command line interface (cli)\n  - common/         # Source code for common utility routines\n  - compliance/     # Source code for dist-spec conformance tests\n  - log/            # Source code for logging framework\n  - test/           # Internal test scripts/data\n  - extensions/     # Source code for all extensions\n    - config/\n    - sync/\n    - monitoring/\n    - sync/\n  - exporter/       # Source code for metrics exporter\n- cmd/              # Source code for binary main()s\n  - zot/            # Source code for zot binary\n  - zli/            # Source code for zot cli\n  - zb/             # Source code for zb, the dist-spec benchmarking tool\n- errors/           # Source code for error codes\n- examples/         # Configuration examples\n- swagger/          # Swagger integration\n- docs/             # Documentation\n
"},{"location":"developer-guide/onboarding/#additional-state-in-zot","title":"Additional state in zot","text":"

In addition to the storage of repository images, zot stores data for various processes in local and remote storage and databases. The following table shows the storage locations for different processes and types of data.

Data or Process Storage Location Description images local andAWS S3 Image blobs repository synchronization local/<repo_name>/.sync The sync operation temporarily copies the upstream blobs to: /<repo_name>/.sync/${UUID}/<repo_name>, then copies to /<repo_name> and deletes the temporary directory ${UUID} deduplication local/cache.db Cache for deduplication of files stored locally AWS DynamoDB Cache for deduplication of files stored in AWS CVE local/_trivy Database of Common Vulnerabilities and Exposures (CVE) information and scan results user sessions local/_sessions zot user session authentication (for zui) PKI authentication documents local/_cosign Private keys for signature verification using cosign local/_notation Certificates for signature verification using notation metadata local/repo.db Local storage of manifests, configurations, download counters, signature verification results AWS DynamoDB Cloud storage of manifests, configurations, download counters, signature verification results"},{"location":"general/architecture/","title":"Architecture","text":"

zot is an OCI-native container image registry. This document discusses the design goals, the overall architecture, and the design choices made in the implementation of the design goals.

"},{"location":"general/architecture/#design-goals","title":"Design Goals","text":""},{"location":"general/architecture/#oci-first","title":"OCI-first","text":""},{"location":"general/architecture/#single-binary-model","title":"Single binary model","text":"

zot is a single binary image with all features included so that deployment is extremely simple in various environments, including bare-metal, cloud, and embedded devices. Behavior is controlled by a single configuration file.

"},{"location":"general/architecture/#enable-only-what-you-need","title":"Enable Only What You Need","text":"

A clear separation exists between (1) the core OCI-compliant HTTP APIs and storage functionality, and (2) other add-on features modeled as extensions. The extension features can be selectively enabled both at build-time and run-time.

For more information, see \"Conditional Builds\" in zot's security posture document.

"},{"location":"general/architecture/#overall-architecture","title":"Overall Architecture","text":"

As shown in the following figure, the architecture of zot is organized as:

zot-full = zot-minimal + extensions

The minimal build is the core OCI-compliant registry functionality as described by the OCI Distribution Specification.

The full build adds features that are not a part of the Distribution Specification, but are allowed to be added as Extensions.

"},{"location":"general/architecture/#external-interaction","title":"External Interaction","text":"

External interaction with zot consists of the following two types:

All client-side interaction occurs over HTTP APIs. The core data path queries are governed by the OCI Distribution Specification. All additional meta-data queries are handled based on the setting of the search extension:

"},{"location":"general/architecture/#configuration","title":"Configuration","text":"

A single configuration file governs zot instance behavior. An exception can be made for security concerns, wherein configuration items containing sensitive credentials can be stored in separate files referenced by the main configuration file. Using separate files allows stricter permissions to be enforced on those files if stored locally. Also, modeling as external files allows for storing Kubernetes Secrets.

The configuration file is divided into sections for http, storage, log, and extension, governing the behavior of the respective components.

"},{"location":"general/architecture/#authentication-and-authorization","title":"Authentication and Authorization","text":"

A robust set of authentication and authorization options are supported natively in zot. These controls are enforced before access is allowed into the storage layer.

For more information, see User Authentication and Authorization with zot.

"},{"location":"general/architecture/#storage-driver-support","title":"Storage Driver Support","text":"

zot supports any modern local filesystem. Remote filesystems, such as AWS S3 or any AWS S3-compatible storage system, are supported. Additional driver support is planned in the roadmap.

Deduplication is supported for both local and remote filesystems, but deduplication requires a filesystem with hard-link support.

For more information, see Storage Planning with zot.

"},{"location":"general/architecture/#security-scanning","title":"Security Scanning","text":"

zot integrates with the trivy security scanner to scan container images for vulnerabilities. The database is kept current by periodically downloading any vulnerability database updates at a configurable interval. The user remains agnostic of the actual scanner implementation, which may change over time.

"},{"location":"general/architecture/#extensions","title":"Extensions","text":"

Additional registry features that are not a part of the Distribution Specification are added as Extensions.

Extension features of zot are available only with a full zot image. They are not supported in a minimal zot image.

For more information about zot's extensions, see Extensions.

"},{"location":"general/architecture/#background-tasks","title":"Background Tasks","text":"

Several periodic tasks occur in the registry, such as garbage collection, sync mirroring, and scrubbing. A task scheduler handles these tasks in the background, taking care not to degrade or interrupt foreground tasks running in the context of HTTP APIs.

"},{"location":"general/concepts/","title":"Concepts","text":""},{"location":"general/concepts/#what-is-zot","title":"What is zot?","text":"

zot is a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

Two broad trends are changing how we build, distribute, and consume software. The first trend is the increasing adoption of container technologies. The second trend is that software solutions are being composed by combining elements from various sources rather than being built entirely from scratch. The latter trend raises the importance of software provenance and supply chain security. In both trends, zot intends to play an important role by providing a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

"},{"location":"general/concepts/#what-is-an-oci-image-registry","title":"What is an OCI image registry?","text":"

An OCI image registry is a server-based application that allows you to store, manage, and share container images. A developer uploads (pushes) an image to the registry for distribution. Users can then download (pull) the image to run on their systems. The OCI Distribution Specification, published by the Open Container Initiative (OCI), defines a standard API protocol for these and other image registry operations.

An image registry can be a part of your continuous integration and continuous deployment (CI/CD) pipeline when you host zot on your public or private server. In its minimal form, you can also embed a zot registry in a product. In either case, zot provides a secure software supply chain for container images.

"},{"location":"general/concepts/#why-zot","title":"Why zot?","text":"

zot = OCI Distribution Specification + OCI Image Format

At its heart, zot is a production-ready, vendor-neutral OCI image registry with images stored in the OCI image format and with the OCI distribution specification on-the-wire. zot is built for developers by developers, offering features such as minimal deployment using a single binary image, built-in authentication and authorization, and inline garbage collection and storage deduplication.

Some of the principal advantages of zot are:

zot fully conforms to the OCI Distribution Specification.

The following table lists additional advantages of zot:

Distribution Spec conformance yes CNCF project accepted as a Sandbox Project License Apache 2.0 On-premises deployment yes OCI conformance* yes Single binary image* yes Minimal build* yes Storage Layout OCI v1 Image Layout Authentication built-in Authorization built-in Garbage collection inline Storage deduplication inline Cloud storage support yes Delete by tag yes Vulnerability scanning built-in Command line interface (cli) yes UI yes External contributions beta available Image signatures built-in

* The minimal build feature is the ability to build a minimal Distribution Spec compliant registry in order to reduce library dependencies and the possible attack surface.

"},{"location":"general/extensions/","title":"Extensions","text":"

Extensions provide additional registry features that are not a part of the Distribution Specification.

The following extensions are currently available with zot:

For detailed information about configuring zot extensions, see Configuring zot.

"},{"location":"general/extensions/#about-extensions","title":"About extensions","text":"

The OCI Distribution Specification supports extending the functionality of an OCI-compliant registry implementation by adding extensions. Extensions are new APIs developed outside of the core OCI specs. Developers may propose their extensions to the OCI for possible future addition to the Distribution Specification.

Wherever applicable, extensions can be dynamically discovered using the extensions support of the OCI Distribution Specification.

Extension features of zot are available only with a full zot image. They are excluded from the minimal zot image.

"},{"location":"general/extensions/#extensions-implemented-in-zot","title":"Extensions implemented in zot","text":"

The extensions implemented in zot include administrator-configured functionality and end-user features.

Currently, search, trust, and userprefs are the only zot extensions operable by end users. Only these extensions are accessible through HTTP APIs and are discoverable using the OCI extensions mechanism.

The following extensions are currently supported by zot:

"},{"location":"general/extensions/#search","title":"Search","text":"

One of the key functions of a container image registry (which is essentially a graph of blobs) is the ability to perform interesting image and graph traversal queries. The user interacts with the search extension via a graphQL endpoint. The schema is published with every release.

Examples of queries are:

"},{"location":"general/extensions/#sync","title":"Sync","text":"

You can deploy a local mirror pointing to an upstream zot instance with various container image download policies, including on-demand and periodic downloads. The sync function is useful to avoid overwhelming the upstream instance, or if the upstream instance has rate-limited access.

docker.io is supported as an upstream mirror.

"},{"location":"general/extensions/#lint","title":"Lint","text":"

The lint extension helps to avoid image compliance issues by enforcing certain policies about the image or the image metadata. Currently, lint can check an uploaded image to enforce the presence of required annotations such as the author or the license.

"},{"location":"general/extensions/#scrub","title":"Scrub","text":"

Although container images are content-addressable with their SHA256 checksums, and validations are performed during storage and retrieval, it is possible that bit-rot sets in when not in use. The scrub extension actively scans container images in the background to proactively detect errors.

"},{"location":"general/extensions/#trust","title":"Trust","text":"

Images stored in zot can be signed with a digital signature to verify the source and integrity of the image. The digital signature can be verified by zot using public keys or certificates uploaded by the user through the zot API. The trust extension enables and configures this function.

"},{"location":"general/extensions/#metrics","title":"Metrics","text":"

The metrics extension adds a node exporter, which is not present in the minimal build.

"},{"location":"general/extensions/#graphical-user-interface","title":"Graphical user interface","text":"

Using the zot graphical user interface (GUI), you can browse a zot registry for container images and artifacts. From the web interface, you can copy the shell commands for downloading an image using popular third-party tools such as docker, podman, and skopeo.

"},{"location":"general/extensions/#user-preferences","title":"User preferences","text":"

The userprefs extension provides an API endpoint for adding configurable user preferences for a repository. This custom extension, not a part of the OCI distribution, is accessible only by authenticated users of the registry. Unauthenticated users are denied access.

The functions currently implemented by this extension include:

For information about configuring zot extensions, see Configuring zot.

"},{"location":"general/features/","title":"Summary of Key Features","text":""},{"location":"general/glossary/","title":"Glossary","text":""},{"location":"general/glossary/#documentation-icons","title":"Documentation Icons","text":"Icon Description Note \u2014 A point of emphasis or caution. Tip \u2014 A helpful suggestion or a reference to additional material not covered in this document. Warning \u2014 A suggestion or advisory intended to avoid a loss of service or data."},{"location":"general/glossary/#definitions","title":"Definitions","text":"Term Description artifact A file of any kind produced during a container build process or associated with the operation of a container. For example, a Helm chart is an artifact that might be stored along with a container. CNCF As part of the Linux Foundation, the Cloud Native Computing Foundation provides support, oversight, and direction for open-source, cloud native projects. cosign cosign is a tool that performs container signing, verification, and storage in an OCI registry. cosigned cosigned is an image admission controller that validates container images before deploying them. cri-o cri-o is an implementation of the Kubernetes Container Runtime Interface (CRI) to enable using OCI compatible runtimes. It is a lightweight alternative to using Docker as the runtime for Kubernetes. deduplication 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. digest A hashed checksum, such as SHA-256, for verifying the integrity of the downloaded image. Distribution Specification The OCI Distribution Specification project defines an API protocol to facilitate and standardize the distribution of content. extensions Additional registry features (APIs) that are not a part of the Distribution Specification can be added as Extensions. helm chart A helm chart is a package of files that orchestrate the deployment of Kubernetes resources into a Kubernetes cluster. manifest An image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system. node exporter A software component that collects hardware and operating system level metrics exposed by the kernel. OCI The Open Container Initiative (OCI) is an open governance structure for the express purpose of creating open industry standards around container formats and runtimes. ORAS OCI Registry as Storage (ORAS) is a tool for distributing OCI artifacts across OCI registries. prometheus Prometheus is a node exporter that exposes a wide variety of hardware- and kernel-related metrics. referrer An image containing a non-nil subject field with a descriptor to the referred image. registry A service that stores and distributes container images and artifacts. repository A collection of images with the same name, differentiated by tags. skopeo skopeo is a command line utility that performs various operations on container images and image repositories. stacker 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. tag A label applied to an image that distinguishes the image from other images in the same repository. A common example is a version tag. zb A benchmarking tool, available as a zot companion binary, for benchmarking a zot registry or any other container image registry that conforms to the OCI Distribution Specification. zli A zot companion binary that implements a set of command line commands for interacting with the zot registry server. zui A zot companion binary that implements a graphical user interface (GUI) for interacting with the zot registry server. zxp A node exporter, available as a zot companion binary, that can be deployed with a minimal zot image in order to scrape metrics from the zot server."},{"location":"general/project/","title":"About the zot Project","text":""},{"location":"general/project/#project-repository","title":"Project Repository","text":"

The zot project is hosted on GitHub:

project-zot/zot

"},{"location":"general/project/#sponsors","title":"Sponsors","text":"

Cisco Systems, Inc.

"},{"location":"general/project/#adopters","title":"Adopters","text":"

Cisco Systems, Inc.

"},{"location":"general/project/#presentations","title":"Presentations","text":"

OCI Weekly Discussion - Oct 2, 2019

"},{"location":"general/releases/","title":"Released Images for zot","text":"

This document describes the available zot images for the various supported hardware and software platforms, along with information about image variations, image locations, and image naming formats.

"},{"location":"general/releases/#supported-platforms","title":"Supported platforms","text":"

zot is supported on Linux and Apple MacOS platforms with Intel or ARM processors.

Table: Supported platforms and 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 (Apple M1) 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."},{"location":"general/releases/#full-and-minimal-binary-images","title":"Full and minimal binary images","text":"

In addition to variations for specific platforms and architectures, binary images are also available in full and minimal flavors:

"},{"location":"general/releases/#binary-image-file-naming","title":"Binary image file naming","text":"

An executable binary image for zot is named using the target platform and architecture from the Supported platforms and architectures table. The general format of a binary image file name is one of these two:

zot-<os>-<architecture>

zot-<os>-<architecture>-minimal

For convenience, you can rename the binary image file to simply zot after downloading.

"},{"location":"general/releases/#where-to-get-zot","title":"Where to get zot","text":"

You can download native executable binary images or container (Docker) images.

"},{"location":"general/releases/#getting-binary-images","title":"Getting binary images","text":"

The zot project is hosted on GitHub at project-zot.

To download a binary image, go to the zot releases and select a release. Go to the Assets section of the release page and download the binary for your platform and architecture.

You may need to use the chmod command to make the image executable.

When downloading a binary image for MacOS, download the darwin image.

"},{"location":"general/releases/#getting-container-images","title":"Getting container images","text":"

You can download a container image from ghcr.io by forming a URL with the desired image name, such as:

https://ghcr.io/project-zot/zot-<os>-<architecture>[-<build>]\n

If <build> is not specified, the default is full. For example, to download the minimal binary image for an Intel-based linux server. The URL is:

https://ghcr.io/project-zot/zot-linux-amd64-minimal\n

When downloading a container image for MacOS, download the linux image, not the darwin image.

"},{"location":"general/releases/#licensing","title":"Licensing","text":"

zot is released under the Apache License 2.0.

"},{"location":"general/whats-new/","title":"What's New","text":""},{"location":"general/whats-new/#v201","title":"v2.0.1","text":""},{"location":"general/whats-new/#support-for-hot-reloading-of-ldap-credentials-file","title":"Support for hot reloading of LDAP credentials file","text":"

Since v2.0.0, LDAP credentials have been specified in a separate file. Starting with this version, the file is watched and changes applied without restarting zot.

"},{"location":"general/whats-new/#bugfixes-and-performance-improvements","title":"Bugfixes and performance improvements","text":"

Under some configurations, zot consumes significant CPU and memory resources. This has been fixed in this release.

"},{"location":"general/whats-new/#v200","title":"v2.0.0","text":""},{"location":"general/whats-new/#updated-oci-support","title":"Updated OCI support","text":""},{"location":"general/whats-new/#built-in-ui-support","title":"Built-in UI support","text":""},{"location":"general/whats-new/#support-for-social-logins","title":"Support for social logins","text":""},{"location":"general/whats-new/#group-policies-for-authorization","title":"Group policies for authorization","text":""},{"location":"general/whats-new/#signature-verification","title":"Signature verification","text":""},{"location":"general/whats-new/#ldap-credentials-stored-separately-from-configuration","title":"LDAP credentials stored separately from configuration","text":""},{"location":"general/whats-new/#storage-deduplication-on-startup","title":"Storage deduplication on startup","text":""},{"location":"general/whats-new/#retention-policies","title":"Retention policies","text":""},{"location":"general/whats-new/#cve-scanning-support-for-image-indexes","title":"CVE scanning support for image indexes","text":""},{"location":"general/whats-new/#bookmarks","title":"Bookmarks","text":""},{"location":"general/whats-new/#ability-to-delete-tags-from-the-ui","title":"Ability to delete tags from the UI","text":""},{"location":"general/whats-new/#command-line-search","title":"Command line search","text":""},{"location":"general/whats-new/#search-by-digest","title":"Search by digest","text":""},{"location":"general/whats-new/#graphql-support-for-search","title":"GraphQL support for search","text":""},{"location":"general/whats-new/#scheduling-of-background-tasks","title":"Scheduling of background tasks","text":""},{"location":"general/whats-new/#performance-profiling-for-troubleshooting","title":"Performance profiling for troubleshooting","text":""},{"location":"general/whats-new/#binaries-for-freebsd","title":"Binaries for FreeBSD","text":""},{"location":"general/whats-new/#v143","title":"v1.4.3","text":""},{"location":"general/whats-new/#remote-only-storage-support","title":"Remote-only Storage Support","text":""},{"location":"general/whats-new/#digest-collision-detection-during-image-deletion","title":"Digest Collision Detection During Image Deletion","text":""},{"location":"install-guides/install-guide-k8s/","title":"Installing zot with Kubernetes and Helm","text":"

Using Kubernetes with Helm charts for zot, you can easily deploy zot as an application in a Kubernetes cluster.

"},{"location":"install-guides/install-guide-k8s/#before-you-begin","title":"Before you begin","text":""},{"location":"install-guides/install-guide-k8s/#prerequisites","title":"Prerequisites","text":""},{"location":"install-guides/install-guide-k8s/#supported-platforms","title":"Supported platforms","text":"

You can install zot on standard Linux platforms with Intel or ARM processors and with systemd installed.

OS ARCH Platform linux amd64 Intel-based Linux servers linux arm64 ARM-based servers and Raspberry Pi4

Supported platforms and architectures

"},{"location":"install-guides/install-guide-k8s/#about-binary-images","title":"About binary images","text":"

Refer to Released Images for zot for information about available zot images along with information about image variations, image locations, and image naming formats.

"},{"location":"install-guides/install-guide-k8s/#installing-zot","title":"Installing zot","text":""},{"location":"install-guides/install-guide-k8s/#step-1-locate-the-helm-charts-in-a-remote-repository","title":"Step 1: Locate the Helm charts in a remote repository","text":"

  1. Specify a remote repository that contains the Helm charts for zot. Give the repo a local name, such as project-zot, as in this example:

    helm repo add project-zot http://zotregistry.dev/helm-charts

    \"project-zot\" has been added to your repositories\n

    The Helm charts for zot are currently hosted in these publicly-accessible repositories: - zotregistry.dev - artifacthub.io

  2. Search the repository to see the Helm charts for zot installation. Search using the keyword 'project-zot' or 'zot', as in this example:

    helm search repo project-zot

    NAME             CHART VERSION  APP VERSION  DESCRIPTION\nproject-zot/zot  <chart-version>          v2.0.1       A Helm chart for Kubernetes\n

    The APP VERSION is the version/tag of the zot image used for the deployment.

  3. Update to the latest information of available charts from the chart repository, as shown in this example:

    helm repo update project-zot

    Hang tight while we grab the latest from your chart repositories...\n...Successfully got an update from the \"project-zot\" chart repository\nUpdate Complete. \u2388Happy Helming!\u2388\n

  4. Display the default information of the Helm chart, as shown in this example:

helm show all project-zot/zot

    apiVersion: v2\n    appVersion: v2.0.1\n    description: A Helm chart for Kubernetes\n    name: zot\n    type: application\n    version: <chart-version>\n\n    # Default values for zot.\n    # This is a YAML-formatted file.\n    # Declare variables to be passed into your templates.\n    replicaCount: 1\n    image:\n      repository: ghcr.io/project-zot/zot-linux-amd64\n      pullPolicy: IfNotPresent\n      tag: \"v2.0.1\"\n    serviceAccount:\n      create: true\n      annotations: {}\n      name: \"\"\n    service:\n      type: NodePort\n      port: 5000\n
"},{"location":"install-guides/install-guide-k8s/#step-2-determine-any-needed-changes-from-the-helm-charts-defaults","title":"Step 2: Determine any needed changes from the Helm chart\u2019s defaults","text":"

Inspect the default information of the Helm chart, as shown in the previous step. In many cases, the default chart values may be acceptable. If your installation requires any non-default settings, you may be able to specify them during the installation. Not all chart values are configurable, but you can display those that are configurable using the command in the following example:

helm show values project-zot/zot

  # Default values for zot.\n  # This is a YAML-formatted file.\n  # Declare variables to be passed into your templates.\n  replicaCount: 1\n  image:\n    repository: ghcr.io/project-zot/zot-linux-amd64\n    pullPolicy: IfNotPresent\n    tag: \"v2.0.1\"\n  serviceAccount:\n    create: true\n    annotations: {}\n    name: \"\"\n  service:\n    type: NodePort\n    port: 5000\n

The configurable settings in the chart are listed in the following table:

parameter description

replicaCount

Desired number of replicas of the application

image.repository

Repository and image name for the application

image.pullPolicy

Whether to pull the image from the repository. If not specified, the policy depends on image.tag:

image.tag

Identifies different versions the image. default is the chart appVersion.

Examples: :latest (the default) or :v2.0.1

serviceAccount.create

Specifies whether a service account should be created

serviceAccount.annotations

Annotations to add to the service account

serviceAccount.name

Name of the service account to use. If name is not set and create is true, a name is generated using the fullname template.

service.type

ClusterIP (default), NodePort, LoadBalancer, ExternalName, or Headless

service.port

Port number for calling the service

"},{"location":"install-guides/install-guide-k8s/#customizing-the-helm-chart-using-set","title":"Customizing the Helm chart using 'set'","text":"

To override the default values in the chart, you can pass your custom values by adding the --set flag in the helm install command.

For example, if your servers use an ARM processor instead of Intel, you must change the image.repository name from zot-linux-amd64 to zot-linux-arm64:

--set image.repository=ghcr.io/project-zot/zot-linux-arm64

You can change multiple settings with one --set statement. For example, you might want your installation to have more replicas or a different port number:

--set replicaCount=2,service.port=5050

"},{"location":"install-guides/install-guide-k8s/#customizing-the-helm-chart-using-a-file","title":"Customizing the Helm chart using a file","text":"

You can also create a YAML file with your overrides and then add the new file by adding the -f flag to the helm install command. For example, to override the replica count and port number, the contents of your YAML file (for example, \"myfile.yaml\") would be:

replicaCount: 2\nservice:\n  port: 5050\n

and the following flag would be added to the helm install command:

-f myfile.yaml

"},{"location":"install-guides/install-guide-k8s/#additional-information","title":"Additional information","text":"

See the Helm documentation for further information about modifying the Helm chart.

"},{"location":"install-guides/install-guide-k8s/#step-3-install-zot","title":"Step 3: Install zot","text":"

Install zot using the helm install command. The first example shows how to perform a default installation. The additional examples show different ways to modify the helm install command to override default settings in the Helm chart:

Example 1: use default chart parameters

helm install zot project-zot/zot

NAME: zot\nLAST DEPLOYED: Thu Aug 11 19:13:02 2022\nNAMESPACE: default\nSTATUS: deployed\nREVISION: 1\nNOTES:\n Get the application URL by running these commands:\n export NODE_PORT=$(kubectl get --namespace default -o jsonpath=\"{.spec.ports[0].nodePort}\" services zot)\n export NODE_IP=$(kubectl get nodes --namespace default -o jsonpath=\"{.items[0].status.addresses[0].address}\")\n echo http://$NODE_IP:$NODE_PORT\n

Example 2: modify specific chart parameters with 'set'

helm install --set replicaCount=2,service.port=5050 zot project-zot/zot

Example 3: modify specific chart parameters with a file

helm install -f myfile.yaml zot project-zot/zot

Example 4: use a specific version of the Helm chart

helm install zot project-zot/zot --version 0.1.0

Example 5: link to a kubeconfig file

helm install zot project-zot/zot --kubeconfig $HOME/.kube/config

"},{"location":"install-guides/install-guide-k8s/#after-the-installation","title":"After the installation","text":""},{"location":"install-guides/install-guide-k8s/#verify-the-installation","title":"Verify the installation","text":"

  1. List all releases that are either deployed or failed.

    helm list

    NAME  NAMESPACE  REVISION  UPDATED    STATUS    CHART      APP VERSION\nzot   default    1         <datetime> deployed  <chart-version>  v2.0.1\n

    This response indicates that zot is deployed.

  2. After making sure that your pods are up and running, execute the following commands:

    $ export NODE_PORT=$(kubectl get --namespace default -o jsonpath=\"{.spec.ports[0].nodePort}\" services zot)\n$ export NODE_IP=$(kubectl get nodes --namespace default -o jsonpath=\"{.items[0].status.addresses[0].address}\")\n$ echo http://$NODE_IP:$NODE_PORT\n$ curl http://$NODE_IP:$NODE_PORT/v2/_catalog\n

    The response should display the current contents of your zot repository, which should be empty immediately after installation:

    {\"repositories\":[]}\n
"},{"location":"install-guides/install-guide-k8s/#edit-the-zot-configuration-file","title":"Edit the zot configuration file","text":"

The zot configuration file is a JSON or YAML file that contains all configuration settings for zot functions such as:

The Helm chart installs a minimal JSON configuration file as shown below:

{\n    \"storage\":\n    {\n        \"rootDirectory\": \"/var/lib/registry\"\n    },\n    \"http\":\n    {\n        \"address\": \"0.0.0.0\",\n        \"port\": \"5000\"\n    },\n    \"log\":\n    {\n        \"level\": \"debug\"\n    }\n}\n

The zot configuration file is located at /etc/zot/config.json.

Refer to Configuring zot for complete information on configuring the zot server with the zot configuration file.

"},{"location":"install-guides/install-guide-k8s/#uninstalling-zot","title":"Uninstalling zot","text":"

Should you need to uninstall zot, use the helm uninstall command, as in this example:

helm uninstall zot

"},{"location":"install-guides/install-guide-linux/","title":"Installing zot on Bare Metal Linux","text":"

Using an available executable zot image, you can easily deploy zot on a Linux server.

"},{"location":"install-guides/install-guide-linux/#before-you-begin","title":"Before you begin","text":""},{"location":"install-guides/install-guide-linux/#about-binary-images","title":"About binary images","text":"

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.

"},{"location":"install-guides/install-guide-linux/#installation","title":"Installation","text":""},{"location":"install-guides/install-guide-linux/#step-1-get-zot","title":"Step 1: Get zot","text":"

Using wget, download the appropriate zot binary image for your platform from the zot GitHub project. Download the image to the`/usr/bin/` directory and rename it to zot, as in this example:

wget -O /usr/bin/zot  https://github.com/project-zot/zot/releases/download/v2.0.1/zot-linux-amd64\n
"},{"location":"install-guides/install-guide-linux/#step-2-create-a-zot-configuration-file","title":"Step 2: Create a zot configuration file","text":"

Create a zot configuration file as /etc/zot/config.json.

See Configuration file options for an example file with options and recommendations. You can find other configuration file examples in the zot GitHub project and in Configuring zot.

"},{"location":"install-guides/install-guide-linux/#step-3-configure-a-local-authentication-account","title":"Step 3: Configure a local authentication account","text":"

If you want to use local authentication with zot, create a /etc/zot/htpasswd file with an initial account entry using the htpasswd command as in this example:

htpasswd -bnB myUserName myPassword > /etc/zot/htpasswd\n

To add additional local users, use the >> redirect as in this example:

htpasswd -bnB myUserName2 myPassword2 >> /etc/zot/htpasswd\n
"},{"location":"install-guides/install-guide-linux/#step-4-define-the-zot-service","title":"Step 4: Define the zot service","text":"

Create a /etc/systemd/system/zot.service file to define the zot service in systemd. The following is an example service file for zot:

[Unit]\nDescription=OCI Distribution Registry\nDocumentation=https://zotregistry.dev/\nAfter=network.target auditd.service local-fs.target\n\n[Service]\nType=simple\nExecStart=/usr/bin/zot serve /etc/zot/config.json\nRestart=on-failure\nUser=zot\nGroup=zot\nLimitNOFILE=500000\nMemoryHigh=30G\nMemoryMax=32G\n\n[Install]\nWantedBy=multi-user.target\n

Be sure to configure a dedicated non-root user ID as the User and Group in the zot service definition. The 'zot' user ID in this example is created in the next step.

"},{"location":"install-guides/install-guide-linux/#step-5-create-a-user-id-to-own-the-zot-service","title":"Step 5: Create a user ID to own the zot service","text":"

Create a non-root user ID to be the owner of the zot service and its resources.

In this example, the user ID 'zot' is created with the adduser command, and resource ownership is assigned.

sudo adduser --no-create-home --disabled-password --gecos --disabled-login zot\n\nsudo mkdir -p /data/zot\nsudo chown -R zot:zot /data/zot\n\nsudo mkdir -p /var/log/zot\nsudo chown -R zot:zot /var/log/zot\n\nsudo chown root:root /usr/bin/zot\nsudo chown root:root config.json\n

With the adduser options shown, the 'zot' user ID has no local directory. There is no ability to log into the zot user account, and the account has no finger information.

"},{"location":"install-guides/install-guide-linux/#step-6-start-zot","title":"Step 6: Start zot","text":"

Enable and start the zot service with these commands:

sudo systemctl enable zot\nsudo systemctl start zot\n

When the zot service has started, you can check its status with this command:

sudo systemctl status zot\n
"},{"location":"install-guides/install-guide-linux/#after-the-installation","title":"After the installation","text":"

If your zot registry server is public facing, we recommend that you test your TLS configuration using a service such as the Qualys SSL Server Test.

Refer to Configuring zot for further information about maintaining your zot registry server.

"},{"location":"install-guides/install-guide-linux/#configuration-file-options-and-recommendations","title":"Configuration file options and recommendations","text":"

The following zot configuration file (config.json) can be used as a template for your own installation. You can modify this file to suit your own environment.

Click here to view the sample configuration file. 
{\n  \"distSpecVersion\":\"1.0.1\",\n  \"storage\":{\n    \"dedupe\": true,\n    \"gc\": true,\n    \"gcDelay\": \"1h\",\n    \"gcInterval\": \"6h\",\n    \"rootDirectory\":\"/data/zot/\"\n  },\n  \"http\": {\n    \"address\":\"0.0.0.0\",\n    \"port\":\"443\",\n    \"realm\":\"zot\",\n    \"tls\": {\n      \"cert\": \"/etc/letsencrypt/live/zothub.io/fullchain.pem\",\n      \"key\": \"/etc/letsencrypt/live/zothub.io/privkey.pem\"\n    },\n    \"auth\": {\n      \"htpasswd\": {\n        \"path\": \"/etc/zot/htpasswd\"\n      },\n      \"failDelay\": 5\n    },\n    \"allowReadAccess\": true\n  },\n  \"log\":{\n    \"level\":\"debug\",\n    \"output\":\"/var/log/zot/zot.log\",\n    \"audit\":\"/var/log/zot/zot-audit.log\"\n  },\n  \"extensions\": {\n    \"search\": {\n      \"enable\": true,\n      \"cve\": {\n        \"updateInterval\": \"24h\"\n      }\n    },\n    \"sync\": {\n      \"enable\": false,\n      \"registries\": [\n        {\n          \"urls\": [\"https://mirror.gcr.io/library\"],\n          \"onDemand\": true,\n          \"maxRetries\": 3,\n          \"retryDelay\": \"5m\",\n          \"pollInterval\": \"6h\"\n        },\n        {\n          \"urls\": [\"https://docker.io/library\"],\n          \"onDemand\": true\n        }\n      ]\n    },\n    \"scrub\": {\n      \"interval\": \"24h\"\n    }\n  }\n}\n

Refer to Configuring zot for more details about configuration file options.

"},{"location":"install-guides/install-guide-linux/#tls-encryption","title":"TLS encryption","text":"

We recommend using a certificate authority such as Let\u2019s Encrypt that offers TLS encryption, as shown in this configuration example:

\"tls\": {\n  \"cert\": \"/etc/letsencrypt/live/zothub.io/fullchain.pem\",\n  \"key\": \"/etc/letsencrypt/live/zothub.io/privkey.pem\"\n}\n
"},{"location":"install-guides/install-guide-linux/#registry-synchronization","title":"Registry synchronization","text":"

The example file enables registry synchronization with two other container registries. In the example, the zot server synchronizes with the Google and Docker container registries, as shown here:

\"sync\": {\n  \"enable\": false,\n  \"registries\": [\n    {\n      \"urls\": [\"https://mirror.gcr.io/library\"],\n      \"onDemand\": true,\n      \"maxRetries\": 3,\n      \"retryDelay\": \"5m\",\n      \"pollInterval\": \"6h\"\n    },\n    {\n      \"urls\": [\"https://docker.io/library\"],\n      \"onDemand\": true\n    }\n  ]\n}\n
"},{"location":"user-guides/user-guide-datapath/","title":"Push and Pull Image Content","text":"

zot is an OCI image registry that allows you to store, manage, and share container images.

A zot registry can store and serve a variety of content, but the type of content may dictate your choice of a client tool.

For various content types, this document shows examples of using a third-party client tool that supports the content. The following table shows which content and client tools are demonstrated.

Content Type Client OCI images skopeo OCI images regclient (regctl) OCI images crane OCI artifacts oras Helm charts helm

zot is compatible with kubernetes/cri-o using docker:// transport, which is the default.

In the following examples, the zot registry is located at localhost, using port number 5000.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-skopeo-for-oci-images","title":"Common tasks using skopeo for OCI images","text":"

skopeo is a command line client that performs various operations on OCI container images and image repositories.

For detailed information about using skopeo, see the skopeo man page.

"},{"location":"user-guides/user-guide-datapath/#push-an-oci-image","title":"Push an OCI image","text":"

This example pushes the latest container image for the busybox application to a zot registry.

$ skopeo --insecure-policy copy --dest-tls-verify=false --multi-arch=all \\\n   --format=oci docker://busybox:latest \\\n   docker://localhost:5000/busybox:latest\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image","title":"Pull an OCI image","text":"

This example pulls the latest container image for the busybox application and stores the image to a local OCI-layout directory (/oci/images).

$ skopeo --insecure-policy copy --src-tls-verify=false --multi-arch=all \\\n   docker://localhost:5000/busybox:latest \\\n   oci:/oci/images:busybox:latest\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image-to-a-private-docker-registry","title":"Pull an OCI image to a private docker registry","text":"

This example pulls the latest container image for the busybox application and stores the image to a local private docker registry.

$ skopeo --insecure-policy copy --src-tls-verify=false --multi-arch=all \\\n   docker://localhost:5000/busybox:latest \\\n   docker://localhost:5000/busybox:latest\n
Click here to view an example of pushing and pulling an image using skopeo.

"},{"location":"user-guides/user-guide-datapath/#authentication","title":"Authentication","text":"

In these examples, authentication is disabled for the source and destination. You can enable authentication by changing the command line options as follows:

--src-tls-verify=true\n--dest-tls-verify=true\n

You can also add credentials for authenticating with a source or destination repository:

--src-creds username:password\n--dest-creds username:password\n
"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-regclient-for-oci-images","title":"Common tasks using regclient for OCI images","text":"

regclient is a client interface that performs various operations on OCI container images and image repositories. The command line interface for regclient is regctl.

For detailed information about regctl commands, see the regctl Documentation.

"},{"location":"user-guides/user-guide-datapath/#push-an-oci-image_1","title":"Push an OCI image","text":"

This example pushes version 1.20 of golang to a tools repository within the registry.

$ regctl registry set --tls=disabled localhost:5000\n$ regctl image copy ocidir://path/to/golang:1.20 localhost:5000/tools\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image_1","title":"Pull an OCI image","text":"

This example pulls version 1.20 of golang to a local OCI-layout directory.

$ regctl image copy localhost:5000/tools ocidir://path/to/golang:1.20\n
"},{"location":"user-guides/user-guide-datapath/#list-all-repositories-in-registry","title":"List all repositories in registry","text":"

This example list all repositories in the registry.

$ regctl repo ls localhost:5000\n
"},{"location":"user-guides/user-guide-datapath/#list-tags","title":"List tags","text":"

This example lists all tags in the tools repository within the registry.

$ regctl tag ls localhost:5000/tools\n
"},{"location":"user-guides/user-guide-datapath/#pull-and-push-manifest","title":"Pull and push manifest","text":"

This example pulls and pushes the manifest in the tools repository within the registry.

$ regctl manifest get localhost:5000/tools --format=raw-body\n$ regctl manifest put localhost:5000/tools:1.0.0 \\\n--format oci --content-type application/vnd.oci.image.manifest.v1+json \\\n--format oci\n
"},{"location":"user-guides/user-guide-datapath/#authentication_1","title":"Authentication","text":"

In the preceding examples, TLS authentication with the zot registry was disabled by the following command:

$ regctl registry set --tls=disabled localhost:5000\n

This command allows regctl to accept an HTTP response from the zot server. If TLS authentication is enabled on the zot registry server, you can omit this command from your regctl session.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-oras-for-oci-artifacts","title":"Common tasks using oras for OCI artifacts","text":"

ORAS (OCI Registry As Storage) is a command line client for storing OCI artifacts on OCI repositories.

For detailed information about the oras commands in these examples, see the ORAS CLI documentation.

"},{"location":"user-guides/user-guide-datapath/#push-an-artifact","title":"Push an artifact","text":"

This example pushes version 2 of an artifact file named hello-artifact to a zot registry.

$ oras push --plain-http localhost:5000/hello-artifact:v2 \\\n        --config config.json:application/vnd.acme.rocket.config.v1+json \\\n        artifact.txt:text/plain -d -v\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-artifact","title":"Pull an artifact","text":"

This example pulls version 2 of an artifact file named hello-artifact from a zot registry.

$ oras pull --plain-http localhost:5000/hello-artifact:v2 -d -v\n
Click here to view an example of pushing and pulling an artifact using oras.

"},{"location":"user-guides/user-guide-datapath/#attach-a-reference","title":"Attach a reference","text":"
$ echo '{\"artifact\": \"localhost:5000/hello-artifact:v2\", \"signature\": \"pat hancock\"}' > signature.json\n\n$ oras push localhost:5000/hello-artifact \\\n  --artifact-type 'signature/example' \\\n  --subject localhost:5000/hello-artifact:v2 \\\n  ./signature.json:application/json\n\n$ oras discover -o tree localhost:5000/hello-artifact:v2\n
"},{"location":"user-guides/user-guide-datapath/#authentication_2","title":"Authentication","text":"

To authenticate with the zot server, log in at the start of your session using the following command:

$ oras login -u myUsername -p myPassword localhost:5000\n

You can also add credentials in the push or pull commands as in this example:

$ oras pull -u myUsername -p myPassword localhost:5000/hello-artifact:v2 -d -v\n

For additional authentication options, including interactive credential entry and disabling TLS, see the ORAS authentication documentation.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-helm-for-helm-charts","title":"Common tasks using helm for helm charts","text":"

Helm is a package manager for Kubernetes. Among many other capabilities, helm can store and retrieve helm charts on OCI image repositories.

For detailed information about the helm commands in these examples, see Commands for working with registries in the helm documentation.

"},{"location":"user-guides/user-guide-datapath/#push-a-helm-chart","title":"Push a helm chart","text":"

This example pushes version 1.2.3 of a zot helm chart to a zot-chart repository within the registry.

$ helm package path/to/helm-charts/charts/zot\n$ helm push zot-1.2.3.tgz oci://localhost:5000/zot-chart\n
"},{"location":"user-guides/user-guide-datapath/#pull-a-helm-chart","title":"Pull a helm chart","text":"

This example pulls version 1.2.3 of a zot helm chart from a zot-chart repository within the registry.

$ helm pull oci://localhost:5000/zot-chart/zot --version 1.2.3\n
"},{"location":"user-guides/user-guide-datapath/#authentication_3","title":"Authentication","text":"

To authenticate with the zot server, log in at the start of your session using the following command:

$ helm registry login -u myUsername localhost:5000\n

You will be prompted to manually enter a password.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-crane-for-oci-images","title":"Common tasks using crane for OCI images","text":"

crane is an open-source project that provides a command-line interface (CLI) for interacting with container registries, such as Docker Hub and Google Container Registry.

For detailed information about crane commands, see the crane Documentation.

"},{"location":"user-guides/user-guide-datapath/#push-an-oci-image_2","title":"Push an OCI image","text":"

This example pushes the latest container image for the alpine application to a registry.

$ crane --insecure push \\\n   oci/images/alpine:latest \\\n   localhost:5000/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image_2","title":"Pull an OCI image","text":"

This example pulls the latest container image for the alpine application and stores the image to a local OCI-layout directory (/oci/images).

$ crane --insecure pull \\\n   --format oci \\\n   localhost:5000/alpine:latest \\\n   oci/images/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#copy-an-oci-image-to-a-private-docker-registry","title":"Copy an OCI image to a private docker registry","text":"

This example pulls the latest container image for the alpine application and stores the image to a local private docker registry.

$ crane --insecure copy \\\n   alpine:latest \\\n   localhost:5000/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#list-tags_1","title":"List tags","text":"

This example lists all tags in the alpine image within the registry.

$ crane ls localhost:5000/alpine\n
"},{"location":"user-guides/user-guide-datapath/#find-the-digest-of-an-image","title":"Find the digest of an image","text":"

This example gets the digest of the alpine image within the registry.

$ crane digest localhost:5000/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#authentication_4","title":"Authentication","text":"

To authenticate with the registry server, log in at the start of your session using the following command:

$ crane auth login -u myUsername localhost:5000\n
"},{"location":"user-guides/user-guide-gui/","title":"Use the Web Interface to Find Images","text":"

Using a browser, you can browse a zot repository for container images and artifacts. The web interface also provides the commands for downloading an image using popular third-party tools.

If a zot registry is built with the optional zui package, the registry has a web interface.

"},{"location":"user-guides/user-guide-gui/#access-the-registry","title":"Access the registry","text":"

Depending on the security configuration of the zot registry, you might need to authenticate before being given access.

The initial page of the registry displays a sampling of the most popular images and recently updated images. To view all available images in the registry, click the View all link in the upper right of the page to go to the /explore page.

Wherever an image name appears, two icons follow the name, indicating the results of the vulnerability scan and the signature status. These icons are described in Icons and their meanings.

"},{"location":"user-guides/user-guide-gui/#find-an-image","title":"Find an image","text":"

To assist you in finding images specific to your requirements, the /explore page provides several sorting options along with faceted navigation in addition to a general search box.

When you locate the desired image, click its tile.

"},{"location":"user-guides/user-guide-gui/#inspect-the-image-properties","title":"Inspect the image properties","text":"

The OVERVIEW tab of the initial image description page contains a brief description of the image along with several details, such as the repository URL, number of downloads, last published, size, and license type.

Click the TAGS tab to view the available versions of the image.

Click the tag link of the desired version of the image. In the resulting page, you can view detailed information about the image, including its digest hash, and you can obtain a command to pull the image from the repository.

Tabs on this page provide the following information:

Tab Description LAYERS The build command and the digest hash USES A list of images used by this image USED BY A list of images that use this image VULNERABILITIES A list of known vulnerabilities

From the LAYERS tab, click Details to view an example of the image build command and the layer's digest hash.

"},{"location":"user-guides/user-guide-gui/#pull-an-image","title":"Pull an image","text":"

After opening the tag link of the desired image, click the Pull Image drop-down list to display the available pull commands. Docker, podman, and skopeo image management tools are supported.

Select a tool and click the pages icon next to the command to copy the full command to your clipboard. An example of the pull command using podman is:

podman pull zothub.io/c3/debian/base-amd64:bullseye

Paste the pull command into your terminal to pull the image.

For information about using image management tools to pull images, see Push and Pull Image Content.

"},{"location":"user-guides/user-guide-gui/#adding-bookmarks","title":"Adding Bookmarks","text":"

To mark an image so that it can be easily found later, click the bookmark icon on the image page. Bookmarked images appear in search queries when the Bookmarked option is enabled.

The bookmark icon before selection:

The bookmark icon after selection:

"},{"location":"user-guides/user-guide-gui/#icons-and-their-meanings","title":"Icons and their meanings","text":"

These icons appear next to the image name, indicating the results of the vulnerability scan and the signature status.

Icon Description A vulnerability scan of the image found no vulnerabilities A vulnerability scan of the image failed(See severity icon in VULNERABILITIES tab) Critical severity High severity Medium severity Low severity The image signature is verified The image signature is not verified The image is not bookmarked by the user The image is bookmarked by the user"},{"location":"user-guides/zli/","title":"Using the command line interface (zli)","text":"

zli: The command line tool for zot servers

"},{"location":"user-guides/zli/#what-is-zli","title":"What is zli?","text":"

zli is a binary that implements a set of command line commands for interacting with the zot registry server.

We recommend installing zli when you install zot.

"},{"location":"user-guides/zli/#how-to-get-zli","title":"How to get zli","text":"

zli is hosted with zot on GitHub at project-zot. From GitHub, you can download the zli binary or you can build zli from the source.

"},{"location":"user-guides/zli/#supported-platforms","title":"Supported platforms","text":"

zli 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"},{"location":"user-guides/zli/#downloading-zli-binaries","title":"Downloading zli binaries","text":"

You can 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 OS and architecture from the Supported platforms table. For example, the binary for an Intel-based MacOS server is zli-darwin-amd64.

"},{"location":"user-guides/zli/#building-zli-from-source","title":"Building zli from source","text":"

To build the zli binary, copy or clone the zot project from GitHub and execute the make cli command in the zot directory. Use the same command options that you used to build zot, as shown:

make OS=os ARCH=architecture cli

For example, the following command builds zli for an Intel-based MacOS server:

make OS=darwin ARCH=amd64 cli\n

In this example, the resulting executable file is zli-darwin-amd64 in the zot/bin directory.

"},{"location":"user-guides/zli/#common-tasks-using-zli","title":"Common tasks using zli","text":"

This section includes examples of common zot server tasks using the zli command line interface. For a detailed listing of zli commands, see the zli Command Reference in this guide.

The original filename of the zli executable file will reflect the build options, such as zli-linux-amd64. For convenience, you can rename the executable to simply zli. The instructions and examples in this guide use zli as the name of the executable file.

"},{"location":"user-guides/zli/#adding-a-zot-server-url","title":"Adding a zot server URL","text":"

You can modify the zot server configuration using the zli config add command. This example adds a zot server URL with an alias of remote-zot:

$ bin/zli config add remote-zot https://server-example:8080\n

Use the zli config command to list all configured URLs with their aliases:

$ bin/zli config -l\n\nremote-zot   https://server-example:8080\nlocal        http://localhost:8080\n
"},{"location":"user-guides/zli/#listing-images","title":"Listing images","text":"

You can list all images hosted on a zot server using the zli image list command with the server\u2019s alias:

$ bin/zli image list --config local\n\nREPOSITORY        TAG       OS/ARCH         DIGEST      SIGNED      SIZE        \nalpine            latest    linux/amd64     3fc10231    false       84MB        \nbusybox           latest    linux/amd64     9172c5f6    false       2.2MB\n

You can also filter the image list to view a specific image by specifying the image name:

$ bin/zli image name busybox:latest --config local\n\nREPOSITORY        TAG       OS/ARCH         DIGEST      SIGNED      SIZE              \nbusybox           latest    linux/amd64     9172c5f6    false       2.2MB\n
"},{"location":"user-guides/zli/#scanning-images-for-known-vulnerabilities","title":"Scanning images for known vulnerabilities","text":"

Using the zli cve list command, you can fetch the CVE (Common Vulnerabilities and Exposures) information for images hosted on the zot server. This example shows how to learn which images are affected by a specific CVE:

$ bin/zli cve affected CVE-2017-9935 --config remote-zot\n\nIMAGE NAME        TAG               DIGEST    SIZE\nc3/openjdk-dev    commit-5be4d92    ac3762e2  335MB\n

This example displays a list of all CVEs affecting a specific image:

$ bin/zli cve list c3/openjdk-dev:0.3.19 --config remote-zot\n\nID                SEVERITY  TITLE\nCVE-2015-8540     LOW       libpng: underflow read in png_check_keyword()\nCVE-2017-16826    LOW       binutils: Invalid memory access in the coff_s...\n

This example displays the detailed CVEs in JSON format:

$ bin/zli cve list c3/openjdk-dev:0.3.19 --config remote-zot -f json\n{\n  \"Tag\": \"0.3.19\",\n  \"CVEList\": [\n    {\n      \"Id\": \"CVE-2019-17006\",\n      \"Severity\": \"MEDIUM\",\n      \"Title\": \"nss: Check length of inputs for cryptographic primitives\",\n      \"Description\": \"A vulnerability was discovered in nss where input text length was not checked when using certain cryptographic primitives. This could lead to a heap-buffer overflow resulting in a crash and data leak. The highest threat is to confidentiality and integrity of data as well as system availability.\",\n      \"PackageList\": [\n        {\n          \"Name\": \"nss\",\n          \"InstalledVersion\": \"3.44.0-7.el7_7\",\n          \"FixedVersion\": \"Not Specified\"\n        },\n        {\n          \"Name\": \"nss-sysinit\",\n          \"InstalledVersion\": \"3.44.0-7.el7_7\",\n          \"FixedVersion\": \"Not Specified\"\n        },\n        {\n          \"Name\": \"nss-tools\",\n          \"InstalledVersion\": \"3.44.0-7.el7_7\",\n          \"FixedVersion\": \"Not Specified\"\n        }]\n    }]\n}\n

This example lists all images on a specific zot server that are affected by a specific CVE:

$ bin/zli cve affected --config remote-zot CVE-2017-9935 --repo c3/openjdk-dev\n\nIMAGE NAME        TAG               DIGEST    SIZE\nc3/openjdk-dev    commit-2674e8a    71046748  338MB\nc3/openjdk-dev    commit-bd5cc94    0ab7fc76\n

This example lists all images on a specific zot server where the CVE has been fixed:

$ bin/zli cve fixed c3/openjdk-dev CVE-2017-9935 --config remote-zot\n\nIMAGE NAME        TAG                       DIGEST    SIZE\nc3/openjdk-dev    commit-2674e8a-squashfs   b545b8ba  321MB\nc3/openjdk-dev    commit-d5024ec-squashfs   cd45f8cf  321MB\n
"},{"location":"user-guides/zli/#listing-repositories","title":"Listing repositories","text":"

You can list all repositories hosted on a zot server using the zli repo command with the server\u2019s alias:

Searching... \ud83c\udf0d\n\nREPOSITORY NAME\nalpine\nbusybox\n
"},{"location":"user-guides/zli/#searching-for-repositories-and-images","title":"Searching for repositories and images","text":"

You can locate repositories and images hosted on a zot server using the zli search command.

This example searches the zot registry named 'local' for a repository whose name contains the substring 'ng':

$ bin/zli search query ng --config local\n\nNAME            SIZE        LAST UPDATED                             DOWNLOADS   STARS\nnginx           794MB       2023-03-01 18:44:17.707690369 +0000 UTC  0           0\nmongo           232MB       2022-10-18 15:03:40.7646203 +0300 +0300  0           0\ngolang          1.1GB       2023-06-22 00:32:38.613354854 +0000 UTC  0           0\n

This example searches the zot registry named 'local' for a repository named 'nginx'. Because the repository name is followed by a colon, the search results must match the name exactly. 

$ bin/zli search query nginx: --config local\n\nREPOSITORY  TAG          OS/ARCH         DIGEST      SIGNED      SIZE\nnginx       1.23.1       linux/amd64     d2ad9089    true        57MB\nnginx       latest       *               c724afdf    true        448MB\n                         linux/amd64     009c6fda    false       57MB\n                         linux/arm/v5    1d5d4f53    false       54MB\n                         linux/arm/v7    f809744c    false       50MB\n                         linux/arm64/v8  ebb807a9    false       56MB\n                         linux/386       19cf4b3c    false       59MB\n                         linux/mips64le  45ab60e6    false       55MB\n                         linux/ppc64le   89511bee    false       63MB\n                         linux/s390x     713b9329    false       55MB\nnginx       stable-perl  *               4383a0b8    true        534MB\n                         linux/amd64     308a37a0    false       68MB\n                         linux/arm/v5    0fb8fb71    false       64MB\n                         linux/arm/v7    6868f552    false       60MB\n                         linux/arm64/v8  aed72c86    false       66MB\n                         linux/386       5c7ed456    false       69MB\n                         linux/mips64le  546d2bae    false       65MB\n                         linux/ppc64le   7db02f5a    false       74MB\n                         linux/s390x     800fd86f    false       66MB\n
"},{"location":"user-guides/zli/#sorting-the-output-of-a-zli-command","title":"Sorting the output of a zli command","text":"

For a zli command that can result in a lengthy output list, you can use the command flag --sort-by <option> to cause the output to be sorted by a specified property of the output data. The available sorting criteria vary for different commands, but examples of sorting criteria options are described in the following table:

flag option criteria alpha-asc alphabetical, ascending alpha-dsc alphabetical, descending relevance quality of match severity severity of condition update-time timestamp

For a given command that results in an output list, you can see the available sorting criteria in the usage information returned by the --help flag. For example, bin/zli image name --help returns usage information containing the following line under \"Flags\":

--sort-by string Options for sorting the output: [update-time, alpha-asc, alpha-dsc] (default \"alpha-asc\")

According to this information, the list of image names returned by the bin/zli image name command can be sorted in order of alphabetical ascending, alphabetical descending, or the timestamp of the latest update of the image. The default sorting method for this command, if no --sort-by flag is present, is alphabetical ascending.

"},{"location":"user-guides/zli/#command-reference","title":"Command reference","text":"

This section provides detailed usage information for basic first-level zli commands. Many zli commands also support subcommands, which are listed as \"Available Commands\" in each command description. For example, zli search can be extended with either the query or subject subcommand. To see the detailed usage for each subcommand, type the command with the subcommand and append --help, such as zli search query --help. The zli search description below includes the subcommand help as an example.

"},{"location":"user-guides/zli/#zli","title":"zli","text":"
$ bin/zli --help\n\nUsage:\n  zli [flags]\n  zli [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  config      Configure zot registry parameters for CLI\n  cve         Lookup CVEs in images hosted on the zot registry\n  help        Help about any command\n  image       List images hosted on the zot registry\n  repo        List all repositories\n  search      Search images and their tags\n\nFlags:\n  -h, --help      help for zli\n  -v, --version   show the version and exit\n\nUse \"zli [command] --help\" for more information about a command.\n
"},{"location":"user-guides/zli/#zli-completion","title":"zli completion","text":"

This command generates the autocompletion script for zli for the specified shell. See each subcommand\u2019s help for details on how to use the generated script.

$ bin/zli completion --help\n\nUsage:\n  zli completion [command]\n\nAvailable Commands:\n  bash        Generate the autocompletion script for bash\n  fish        Generate the autocompletion script for fish\n  powershell  Generate the autocompletion script for powershell\n  zsh         Generate the autocompletion script for zsh\n\nFlags:\n  -h, --help   help for completion\n\nUse \"zli completion [command] --help\" for more information about a command.\n
"},{"location":"user-guides/zli/#zli-config","title":"zli config","text":"

This command configures zot registry parameters for CLI.

$ bin/zli config --help\n\nUsage:\n  zli config <config-name> [variable] [value] [flags]\n  zli config [command]\n\nExamples:\n  zli config add main https://zot-foo.com:8080\n  zli config --list\n  zli config main url\n  zli config main --list\n  zli config remove main\n\nAvailable Commands:\n  add         Add configuration for a zot registry\n  remove      Remove configuration for a zot registry\n\nFlags:\n  -h, --help    help for config\n  -l, --list    List configurations\n      --reset   Reset a variable value\n\nUse \"zli config [command] --help\" for more information about a command.\n\nUseful variables:\n  url       zot server URL\n  showspinner   show spinner while loading data [true/false]\n  verify-tls    enable TLS certificate verification of the server [default: true]\n
"},{"location":"user-guides/zli/#zli-cve","title":"zli cve","text":"

This command lists CVEs (Common Vulnerabilities and Exposures) of images hosted on the zot registry

$ ./zli cve --help\n\nUsage:\n  zli cve [command]\n\nAvailable Commands:\n  affected    List images affected by a CVE\n  fixed       List tags where a CVE is fixedRetryWithContext\n  list        List CVEs by REPO:TAG or REPO@DIGEST\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n  -h, --help            help for cve\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nUse \"zli cve [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-image","title":"zli image","text":"

This command lists images hosted on the zot registry.

$ ./zli image --help\n\nUsage:\n  zli image [command]\n\nAvailable Commands:\n  base        List images that are base for the given image\n  cve         List all CVE's of the image\n  derived     List images that are derived from given image\n  digest      List images that contain a blob(manifest, config or layer) with the given digest\n  list        List all images\n  name        List image details by name\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n  -h, --help            help for image\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nUse \"zli image [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-repo","title":"zli repo","text":"

This command lists all repositories in the zot registry.

$ ./zli repo --help\n\nUsage:\n  zli repo [command]\n\nAvailable Commands:\n  list        List all repositories\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -h, --help            help for repo\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n\nUse \"zli repo [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-search","title":"zli search","text":"

The search command allows smart searching for a repository by its name or for an image by its repo:tag.

$ ./zli search --help\n\nSearch repos or images\n\nUsage:\n  zli search [command]\n\nAvailable Commands:\n  query       Fuzzy search for repos and their tags.\n  subject     List all referrers for this subject.\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n  -h, --help            help for search\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nUse \"zli search [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-search-query","title":"zli search query","text":"
$ ./zli search query --help\n\nUsage:\n  zli search query [repo]|[repo:tag] [flags]\n\nExamples:\n# For repo search specify a substring of the repo name without the tag\n  zli search query \"test/repo\"\n\n# For image search specify the full repo name followed by the tag or a prefix of the tag.\n  zli search query \"test/repo:2.1.\"\n\nFlags:\n  -h, --help             help for query\n      --sort-by string   Options for sorting the output: [relevance, update-time, alpha-asc, alpha-dsc] (default \"relevance\")\n\nGlobal Flags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-search-subject","title":"zli search subject","text":"
$ ./zli search subject --help\n\nList all referrers for this subject. The subject can be specified by tag(repo:tag) or by digest\" or (repo@digest)\n\nUsage:\n  zli search subject [repo:tag]|[repo@digest] [flags]\n\nExamples:\n# For referrers search specify the referred subject using it's full digest or tag:\n  zli search subject \"repo@sha256:f9a0981...\"\n  zli search subject \"repo:tag\"\n\nFlags:\n  -h, --help             help for subject\n      --sort-by string   Options for sorting the output: [update-time, alpha-asc, alpha-dsc] (default \"alpha-asc\")\n\nGlobal Flags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nRun 'zli config -h' for details on [config-name] argument\n
"}]} \ No newline at end of file +{"config":{"lang":["en"],"separator":"[\\s\\-]+","pipeline":["stopWordFilter"]},"docs":[{"location":"admin-guide/admin-configuration/","title":"Configuring zot","text":"

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.

"},{"location":"admin-guide/admin-configuration/#configuration-file","title":"Configuration file","text":"

The configuration file is a JSON or YAML file that contains all configuration settings for zot functions such as:

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:

{\n    \"distSpecVersion\": \"1.0.1\",\n    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\"\n    },\n    \"http\": {\n        \"address\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"log\": {\n        \"level\": \"debug\"\n    }\n}\n

The configuration file contains the Distribution Specification version (distSpecVersion). The structure and content of other attributes are described in the later sections of this guide.

"},{"location":"admin-guide/admin-configuration/#extensions","title":"Extensions","text":"

Additional registry features that are not a part of the Distribution Specification are allowed to be added as Extensions.

With a full (not minimal) zot image, the following extension features can be enabled and configured under an extensions attribute in the configuration file as shown in the following example.

{\n  ...\n  \"extensions\": {\n    \"metrics\": {},\n    \"sync\": {},\n    \"search\": {},\n    \"scrub\": {},\n    \"lint\": {},\n    \"trust\": {},\n    \"ui\": {}\n  }\n}\n

The extension features are available only with a full zot image. With a minimal zot image, the extensions section is ignored if present.

The following features are configured under the extensions attribute.

An extension feature is usually enabled by the presence of the feature\u2019s attribute under extensions. An extension feature can then be disabled by either omitting the feature attribute or by including an enable attribute with a value of false.

Two API-only extensions, User Preferences and Mgmt, are not enabled or configured under the extensions section of the configuration file. These API-only extensions are enabled as follows:

"},{"location":"admin-guide/admin-configuration/#enabling-and-disabling-extensions","title":"Enabling and disabling extensions","text":"

Following is an example of enabling or disabling a feature in the extensions section. The scrub feature is enabled in these two configurations:

\"extensions\": {\n  \"scrub\": {}\n}\n
\"extensions\": {\n  \"scrub\": {\n    \"enable\": true\n  }\n}\n

The scrub feature is disabled in these two configurations:

\"extensions\": {\n}\n
\"extensions\": {\n  \"scrub\": {\n    \"enable\": false\n  }\n}\n
"},{"location":"admin-guide/admin-configuration/#developing-custom-extensions","title":"Developing custom extensions","text":"

New functionality can be added to the zot registry by developing custom extensions for integration into zot. For information about developing extensions, see Developing New Extensions.

"},{"location":"admin-guide/admin-configuration/#network-configuration","title":"Network configuration","text":"

Use the http attribute in the configuration file to configure the zot network settings, as shown in the following example.

\"http\": {\n  \"address\":\"127.0.0.1\",\n  \"port\":\"8080\",\n  \"realm\":\"zot\",\n  \"tls\": {\n    \"cert\":\"test/data/server.cert\",\n    \"key\":\"test/data/server.key\"\n  }\n}\n

The following table lists the configurable attributes.

Attribute Description address The IP address of the zot server. port The port number of the zot server. realm The security policy domain defined for the server. tls The included attributes in this section specify the Transport Layer Security (TLS) settings for the server. cert The path and filename of the server\u2019s SSL/TLS certificate. key The path and filename of the server\u2019s registry key."},{"location":"admin-guide/admin-configuration/#storage","title":"Storage","text":"

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.

Filesystem storage is configured with the storage attribute in the zot configuration file, as shown in the following simple example.

\"storage\":{\n  \"rootDirectory\":\"/tmp/zot\",\n  \"commit\": true,\n  \"dedupe\": true,\n  \"gc\": true,\n  \"gcDelay\": \"1h\",\n  \"gcInterval\": \"24h\"\n}\n

With zot, you have the option to store your registry image files either in local filesystem storage or in cloud storage, such as an Amazon Simple Storage Service (S3) bucket.

"},{"location":"admin-guide/admin-configuration/#local-storage","title":"Local storage","text":"

zot can store and serve files from one or more local directories (folders). 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.

"},{"location":"admin-guide/admin-configuration/#remote-storage","title":"Remote storage","text":"

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.

For detailed information about configuring S3 storage, see the AWS S3 documentation and Storage Planning with zot.

"},{"location":"admin-guide/admin-configuration/#storage-features","title":"Storage features","text":""},{"location":"admin-guide/admin-configuration/#commit","title":"Commit","text":"

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.

"},{"location":"admin-guide/admin-configuration/#deduplication","title":"Deduplication","text":"

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.

"},{"location":"admin-guide/admin-configuration/#garbage-collection","title":"Garbage collection","text":"

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. The zot configuration model allows for enabling and disabling garbage collection (gc). The model also allows the configuration of a tunable delay (gcDelay), which can be set depending on client network speeds and the size of blobs.

"},{"location":"admin-guide/admin-configuration/#scrub","title":"Scrub","text":"

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.

"},{"location":"admin-guide/admin-configuration/#configuring-storage","title":"Configuring storage","text":"

For detailed information about configuring local or remote storage and storage features for your zot registry, see Storage Planning with zot.

"},{"location":"admin-guide/admin-configuration/#security-and-hardening","title":"Security and hardening","text":""},{"location":"admin-guide/admin-configuration/#authentication","title":"Authentication","text":"

zot supports authentication by the following methods:

For detailed information about configuring authentication for your zot registry, see User Authentication and Authorization with zot.

"},{"location":"admin-guide/admin-configuration/#identity-based-authorization","title":"Identity-based authorization","text":"

User identity can be used as an authorization criterion for allowing actions on one or more repository paths. For specific users, you can choose to allow any combination of read, create, update, or delete actions on specific repository paths.

For detailed information about configuring access control policies for your zot registry, see User Authentication and Authorization with zot.

"},{"location":"admin-guide/admin-configuration/#preventing-automated-attacks-with-failure-delay","title":"Preventing automated attacks with failure delay","text":"

Use the auth and failDelay attributes under http in the configuration file to delay the response to an authentication failure. A delayed response helps to prevent automated attacks. The configuration is shown in the following example.

\"http\": {\n  \"auth\": {\n    \"failDelay\": 5\n  }\n}\n

The failDelay attribute specifies a waiting time, in seconds, before zot sends a failure notification to an authenticating user who has been denied access.

"},{"location":"admin-guide/admin-configuration/#rate-limiting","title":"Rate limiting","text":"

You can limit the rate of API calls from users by configuring the Ratelimit attribute in the configuration file, as shown in the following example:

\"http\": {\n    \"address\": \"127.0.0.1\",\n    \"port\": \"8080\",\n    \"Ratelimit\": {\n        \"Rate\": 10,\n        \"Methods\": [\n            {\n                \"Method\": \"GET\",\n                \"Rate\": 5\n            }\n        ]\n    }\n}\n

In this example, the Rate attribute directly under Ratelimit sets a global rate limit of ten API calls per second. You can optionally override the global limit for specific API Methods. In this example, API GET calls are limited to five per second.

"},{"location":"admin-guide/admin-configuration/#additional-security-features","title":"Additional security features","text":"

For detailed information about configuring additional security features for your zot registry, see Security Posture.

"},{"location":"admin-guide/admin-configuration/#monitoring","title":"Monitoring","text":"

zot supports a range of monitoring tools including the following:

When zot is deployed in a Kubernetes setup, a site reliability engineering (SRE) operator can monitor service level indicators (SLI) such as metrics and logs. Metrics will appear in Prometheus using the zot metrics extension, while logs will appear in the Elasticsearch stack (ELK stack) using Filebeat.

For detailed information about the monitoring tools, see Monitoring the registry.

For detailed information about benchmarking, see Benchmarking zot with zb.

For detailed information about performance profiling, see Performance Profiling in zot.

"},{"location":"admin-guide/admin-configuration/#clustering-zot","title":"Clustering zot","text":"

To ensure high-availability of the registry, zot supports a clustering scheme with stateless zot instances/replicas fronted by a loadbalancer and a shared remote backend storage. This scheme allows the registry service to remain available even if a few replicas fail or become unavailable. Loadbalancing across many zot replicas can also increase aggregate network throughput.

For detailed information about clustering with zot, see zot Clustering.

"},{"location":"admin-guide/admin-configuration/#syncing-and-mirroring-registries","title":"Syncing and mirroring registries","text":"

A zot registry can mirror one or more upstream OCI registries, including popular cloud registries such as Docker Hub and Google Container Registry. If an upstream registry is OCI distribution-spec conformant for pulling images, you can use zot's sync extension feature to implement a downstream mirror, synchronizing OCI images and corresponding artifacts. Synchronization between registries can be implemented by periodic polling of the upstream registry or synchronization can occur on demand, when a user pulls an image from the downstream registry.

As with git, wherein every clone is a full repository, you can configure a local zot instance to be a full OCI mirror registry. This allows for a fully distributed disconnected container image build pipeline.

For detailed information about syncing and mirroring, see OCI Registry Mirroring With zot.

"},{"location":"admin-guide/admin-configuration/#linting-uploaded-images","title":"Linting uploaded images","text":"

The lint extension can check an uploaded image to enforce the presence of required annotations such as the author or the license.

To configure linting, add the lint attribute under extensions in the configuration file, as shown in the following example:

\"extensions\": {\n    \"lint\": {\n      \"enable\": true,\n      \"mandatoryAnnotations\": [\"annot1\", \"annot2\", \"annot3\"]\n      }\n  }\n

The following table lists the configurable attributes of the lint extension.

Attribute Description enable If this attribute is missing, incoming image linting is disabled by default. Linting can be enabled by including this attribute and setting it to true. mandatoryAnnotations A list of annotations that are required to be present in the image being pushed to the repository.

If the mandatory annotations option is configured when you push an image, linter will verify that the mandatory annotations list present in the configuration is also found in the manifest's annotations list. If any annotations are missing, the push is denied.

"},{"location":"admin-guide/admin-configuration/#verifying-the-signatures-of-uploaded-images","title":"Verifying the signatures of uploaded images","text":"

The trust extension provides a mechanism to verify image signatures using certificates and public keys.

To enable image signature verification, you must add the trust attribute under extensions in the zot configuration file and enable one or more verification tools, as shown in the following example:

\"extensions\": {\n  \"trust\": {\n    \"enable\": true,\n    \"cosign\": true,\n    \"notation\": true\n  }\n}\n

You must also upload public keys (for cosign) or certificates (for notation) that can be used to verify the image signatures.

For detailed information about configuring image signature verification, see Verifying image signatures.

"},{"location":"admin-guide/admin-configuration/#enabling-the-registrys-graphical-user-interface","title":"Enabling the registry's graphical user interface","text":"

Using the zot graphical user interface (GUI), a user can browse a zot registry for container images and artifacts.

To configure zot's GUI, add the ui attribute under extensions in the configuration file, as shown in the following example:

\"extensions\": {\n  \"ui\": {\n    \"enable\": true\n  }\n}\n

The following table lists the configurable attributes of the ui extension.

Attribute Description enable If this attribute is missing, the zot GUI is disabled by default. The GUI can be enabled by including this attribute and setting it to true."},{"location":"admin-guide/admin-configuration/#scrubbing-the-image-registry","title":"Scrubbing the image registry","text":"

To check the integrity of the filesystem and the data in the registry, you can schedule a periodic scrub operation. The scrub process traverses the filesystem, verifying that all data blocks are readable. While running, the process may slightly reduce the registry performance.

To enable scrubbing, add the scrub attribute under extensions in the configuration file, as shown in the following example:

\"extensions\": {\n  \"scrub\": {\n    \"enable\": true,\n    \"interval\": \"24h\"\n  }\n}\n

The following table lists the configurable attributes for scrubbing the registry.

Attribute Description enable If this attribute is missing, registry scrubbing is enabled by default. Scrubbing can be disabled by setting this attribute to false. interval The time interval between periodic scrub operations. This value must be at least two hours (2h)."},{"location":"admin-guide/admin-configuration/#scheduling-background-tasks","title":"Scheduling background tasks","text":"

Some zot functions, such as garbage collection and registry synchronization, run as background tasks. These tasks are queued and executed by the scheduler.

The scheduler is by default allowed to simultaneously run a maximum number of tasks equal to four times the number of CPUs available to the zot process. For most users, there should be no need to modify this maximum number. If such a need arises, you can configure a new maximum number of simultaneous tasks in the numWorkers property of the scheduler attribute in the configuration file, as shown in the following example.

{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"scheduler\": {\n    \"numWorkers\": 3\n  },\n...\n}\n
"},{"location":"admin-guide/admin-configuration/#enhanced-searching-and-querying-images","title":"Enhanced searching and querying images","text":"

While basic searching is always enabled for images in the zot registry, you can enable enhanced registry searching and filtering using graphQL.

Add the search attribute under extensions in the configuration file to enable and configure the enhanced search extension, as shown in the following example.

\"extensions\": {\n  \"search\": {\n    \"enable\": true,\n    \"cve\": {\n      \"updateInterval\": \"2h\"\n    }\n  }\n}\n

The following table lists the configurable attributes for enhanced search.

Attribute Description enable If this attribute is missing, enhanced search is enabled by default. Enhanced search can be disabled by setting this attribute to false. cve Extends enhanced search to allow searching of Common Vulnerabilities and Exposures (CVE). updateInterval Sets the interval at which the searchable database of CVE items is refreshed."},{"location":"admin-guide/admin-configuration/#setting-user-preferences","title":"Setting user preferences","text":"

The user preferences extension provides an API endpoint for adding configurable user preferences for a repository. This custom extension, not a part of the OCI distribution, is accessible only by authenticated users of the registry. Unauthenticated users are denied access.

The user preferences extension is enabled by default when the search and ui extensions are enabled. There are no other configuration file fields for this extension.

A userprefs API endpoint accepts as a query parameter an action to perform along with any other required parameters for the specified action. The actions currently implemented do not require an HTTP payload, nor do they return any related data other than an HTTP response code.

"},{"location":"admin-guide/admin-configuration/#current-functionality","title":"Current functionality","text":"

The current functions implemented by this extension include:

"},{"location":"admin-guide/admin-configuration/#toggle-repository-star","title":"Toggle repository star","text":"

This action sets the repository star property to true if it is false, and to false if it is true.

Action Parameter Parameter Description toggleStar repo The name of the repository whose star is to be changed

This example toggles a star on a repository named repoName:

PUT\nhttp://localhost:5000/v2/_zot/ext/userprefs?\naction=toggleStar&repo=repoName\n
"},{"location":"admin-guide/admin-configuration/#toggle-repository-bookmark","title":"Toggle repository bookmark","text":"

This action sets the repository bookmark property to true if it is false, and to false if it is true.

Action Parameter Parameter Description toggleBookmark repo The name of the repository whose bookmark is to be changed

This example toggles a bookmark on a repository named repoName:

PUT\nhttp://localhost:5000/v2/_zot/ext/userprefs?\naction=toggleBookmark&repo=repoName\n
"},{"location":"admin-guide/admin-configuration/#verifying-the-configuration-file","title":"Verifying the configuration file","text":"

Before launching zot, verify the syntax of your configuration file using the following command:

zot verify <configfile>

Verifying the configuration file protects against operator errors and any conflicts arising from zot release version changes.

After verifying your configuration file, you can launch zot with the following command:

zot serve <configfile>

"},{"location":"admin-guide/admin-getting-started/","title":"Getting Started with zot Administration","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#installing-zot","title":"Installing zot","text":""},{"location":"admin-guide/admin-getting-started/#how-to-get-zot","title":"How to get zot","text":"

The zot project is hosted on GitHub at project-zot. From GitHub, you can download zot executable binary images or full source code.

"},{"location":"admin-guide/admin-getting-started/#supported-platforms","title":"Supported platforms","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#about-binary-images","title":"About binary images","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#deployment-methods","title":"Deployment methods","text":"

Several options exist for deploying zot:

"},{"location":"admin-guide/admin-getting-started/#deploying-a-zot-binary-image","title":"Deploying a zot binary image","text":"

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.

"},{"location":"admin-guide/admin-getting-started/#example-deploying-with-a-container-manager","title":"Example: Deploying with a container manager","text":"

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\n\npodman run -p 5000:5000 ghcr.io/project-zot/zot-minimal-linux-amd64:latest\n
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\n

Each of these example commands pulls a zot binary image from the GitHub Container Registry (ghcr.io) and launches a zot image registry at http://localhost:5000.

Click here to view an example of deploying using docker.

"},{"location":"admin-guide/admin-getting-started/#building-zot-from-source","title":"Building zot from source","text":""},{"location":"admin-guide/admin-getting-started/#prerequisites","title":"Prerequisites","text":""},{"location":"admin-guide/admin-getting-started/#install-golang","title":"Install golang","text":"

Follow the golang instructions to install the golang toolchain. After installation, make sure that the path environment variable or your IDE can find the toolchain.

You must use a golang version of at least the minimum specified in go.mod or the build will fail.

"},{"location":"admin-guide/admin-getting-started/#building-an-executable-binary-from-source","title":"Building an executable binary from source","text":"

Download or clone the full zot project from GitHub at project-zot. To clone the zot project from GitHub, use this command:

git clone https://github.com/project-zot/zot.git\n

To build zot, execute the make command in the zot directory using the following general syntax:

make OS=os ARCH=architecture {binary | binary-minimal}

For example, to build a zot image with extensions for an Intel-based linux server, use the following command:

make OS=linux ARCH=amd64 binary\n

The make command builds an executable image in the zot/bin directory. The original filename of the zot executable image will indicate the build options. For example, the filename of an Intel-based linux minimal image is zot-linux-amd64-minimal.

For convenience, you can rename the binary image file to simply zot.

"},{"location":"admin-guide/admin-getting-started/#building-a-zot-container-image-from-source","title":"Building a zot container image from source","text":"

with Stacker

Using the settings in stacker.yaml, you can build a container image that runs the latest zot by running the following command:

make binary-stacker\n

with Docker

A sample Dockerfile is provided on the zot project page in GitHub. You can edit the sample file with your specific values, such as the desired operating system, hardware architecture, and full or minimal build, as in this example:

ARG OS=linux\nARG ARCH=amd64\n\nRUN make COMMIT=$COMMIT OS=$OS ARCH=$ARCH clean binary-minimal\n

Using your edited Dockerfile, you can build a container image that runs the latest zot by running the following command:

make image\n
"},{"location":"admin-guide/admin-getting-started/#deploying-the-container-image","title":"Deploying the container image","text":"

Deploy the image using your container manager, such as Podman, runc, Helm, or Docker, as in these examples:

with Podman

podman run --rm -it -p 5000:5000 -v $(pwd)/registry:/var/lib/registry zot:latest\n

with Docker

docker run --rm -it -p 5000:5000 -v $(pwd)/registry:/var/lib/registry zot:latest\n

A container image built with the sample Dockerfile and deployed with the example command results in a running registry at http://localhost:5000. Registry content is stored at .registry, which is bind mounted to /var/lib/registry in the container. By default, auth is disabled. As part of the build, a YAML configuration file is created at /etc/zot/config.yml in the container.

You can override the configuration file with custom configuration settings in the deployment command and in a local configuration file as shown in this example:

podman run --rm -p 8080:8080 \\\n  -v $(pwd)/custom-config.yml:/etc/zot/config.yml \\\n  -v $(pwd)/registry:/tmp/zot \\\n  zot:latest\n

This command causes the registry to listen on port 8080 and to use /tmp/zot for content storage.

"},{"location":"admin-guide/admin-getting-started/#additional-recommended-steps","title":"Additional recommended steps","text":"

We recommend that, when deploying zot, you also install the command line (zli) and benchmarking (zb) packages.

"},{"location":"admin-guide/admin-getting-started/#launching-zot","title":"Launching zot","text":"

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.yml

For convenience, you can rename the binary image file to simply zot.The instructions and examples in this guide use zot as the name of the zot executable file and do not include the path to the executable file.

"},{"location":"admin-guide/admin-getting-started/#next-steps","title":"Next Steps","text":""},{"location":"admin-guide/admin-getting-started/#configuring-zot","title":"Configuring zot","text":"

You configure zot primarily through adding and modifying settings in the zot configuration file. The configuration file is a JSON or YAML file that contains all configuration settings for zot functions.

When you first build zot or deploy an image or container from the distribution, a basic configuration file config.json is created. You can modify the initial file or you can create a new file.

Follow the instructions in Configuring zot, to compose a configuration file with the settings and features you require for your zot registry server.

"},{"location":"articles/authn-authz/","title":"User Authentication and Authorization with zot","text":"

A robust set of authentication/authorization options are supported:

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.

"},{"location":"articles/authn-authz/#authentication","title":"Authentication","text":""},{"location":"articles/authn-authz/#tls-authentication","title":"TLS authentication","text":"

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\": {\n...\n  \"tls\": {\n    \"cert\": \"/etc/zot/certs/server.cert\",\n    \"key\": \"/etc/zot/certs/server.key\"\n  }\n

See Mutual TLS authentication for additional information about TLS.

"},{"location":"articles/authn-authz/#http-basic-authentication","title":"HTTP basic authentication","text":"

When basic HTTP authentication is used, the username and password credentials are joined by a colon (:), base64 encoded, and passed in the HTTP Authorization header.

"},{"location":"articles/authn-authz/#http-bearer-authentication","title":"HTTP bearer authentication","text":"

To avoid passing the username and password credentials for every HTTP request, a zot client can use bearer token-based authentication. In this method, the client first authenticates with a token server and receives a short-lived token. The client then passes this token in the HTTP Authorization header, specifying Bearer as the authentication scheme.

Configure bearer authentication in the zot configuration file as shown in this example.

\"http\": {\n...\n  \"auth\": {\n    \"bearer\": {\n      \"realm\": \"https://auth.myreg.io/auth/token\",\n        \"service\": \"myauth\",\n        \"cert\": \"/etc/zot/auth.crt\"\n    }\n  }\n

The following table lists the configurable attributes.

Attribute Description realm A string typically related to the authentication scheme (BASIC and BEARER). service The name of the authentication service. cert The path and filename of the server\u2019s SSL/TLS certificate."},{"location":"articles/authn-authz/#mutual-tls-authentication","title":"Mutual TLS authentication","text":"

zot supports basic TLS and password-less mutual TLS authentication (mTLS). Specifying a cacert file in the TLS section of the zot configuration file enables mTLS. The cacert parameter is used to validate the client-side TLS certificates.

\"http\": {\n...\n  \"tls\": {\n    \"cert\": \"/etc/zot/certs/server.cert\",\n    \"key\": \"/etc/zot/certs/server.key\",\n    \"cacert\": \"/etc/zot/certs/ca.cert\"\n  }\n

The following table lists the configurable attributes.

Attribute Description cert The path and filename of the server\u2019s SSL/TLS certificate. key The path and filename of the server\u2019s registry key. cacert The path and filename of the server\u2019s cacerts file, which contains trusted certificate authority (CA) certificates."},{"location":"articles/authn-authz/#preventing-automated-attacks-with-failure-delay","title":"Preventing automated attacks with failure delay","text":"

To help prevent automated attacks, you can add a delayed response to an authentication failure. Configure the failDelay attribute in the configuration file as shown in the following example.

\"http\": {\n  \"auth\": {\n    \"failDelay\": 5\n  }\n}\n

The failDelay attribute specifies a waiting time, in seconds, before zot sends a failure notification to an authenticating user who has been denied access.

"},{"location":"articles/authn-authz/#server-side-authentication","title":"Server-side authentication","text":"

You can implement server-side authentication for zot using htpasswd or LDAP or both.

When both htpasswd and LDAP configuration are specified, LDAP authentication is given preference. Because htpasswd authentication is strictly local and requires no remote service, htpasswd serves as a fail-safe authentication mechanism should LDAP become unavailable.

"},{"location":"articles/authn-authz/#ldap","title":"LDAP","text":"

zot supports integration with an LDAP-based authentication service such as Microsoft Windows Active Directory (AD). Enable and configure LDAP authentication in the zot configuration file, as shown in the following example.

\"http\": {\n...\n  \"auth\": {\n    \"ldap\": {\n      \"credentialsFile\": \"examples/config-ldap-credentials.json\",\n      \"address\": \"ldap.example.org\",\n      \"port\": 389,\n      \"startTLS\": false,\n      \"baseDN\": \"ou=Users,dc=example,dc=org\",\n      \"userAttribute\": \"uid\",\n      \"userGroupAttribute\": \"memberOf\",\n      \"bindDN\": \"cn=ldap-searcher,ou=Users,dc=example,dc=org\",\n      \"bindPassword\": \"ldap-searcher-password\",\n      \"skipVerify\": false,\n      \"subtreeSearch\": true\n    }\n  }\n}\n

The following table lists the configurable attributes for LDAP authentication.

Attribute Description credentialsFile The path to a file containing the bind credentials for LDAP. address The IP address or hostname of the LDAP server. port The port number used by the LDAP service. startTLS Set to true to enable TLS communication with the LDAP server. baseDN Starting location within the LDAP directory for performing user searches. userAttribute Attribute name used to obtain the username. userGroupAttribute Attribute name used to obtain groups to which a user belongs. skipVerify Skip TLS verification. subtreeSearch Set to true to expand the scope for search to include subtrees of the base DN.

To allow for separation of configuration and credentials, the credentials for the LDAP server are specified in a separate file, as shown in the following example. 

{\n  \"bindDN\":\"cn=ldap-searcher,ou=Users,dc=example,dc=org\",\n  \"bindPassword\":\"ldap-searcher-password\"\n}\n

The following table lists the configurable attributes of the LDAP credentials file.

Attribute Description bindDN Base Distinguished Name for the LDAP search. bindPassword Password of the bind LDAP user."},{"location":"articles/authn-authz/#htpasswd","title":"htpasswd","text":"

Enable and configure htpasswd authentication in the zot configuration file, as shown in the following example.

  1. Create and store an htpasswd file on the server.

    $ htpasswd -bBn <username> <password> >> /etc/zot/htpasswd\n

    For strong security, make sure to use the -B option, specifying the bcrypt hashing algorithm. This is the only algorithm supported by zot for htpasswd.

  2. Enable htpasswd authentication and configure the path to the htpasswd authentication in the zot configuration file.

    \"http\": {\n...\n  \"auth\": {\n      \"htpasswd\": {\n        \"path\": \"/etc/zot/htpasswd\"\n      },\n

    The path attribute specifies the path and filename of the htpasswd file, which contains user names and hashed passwords.

"},{"location":"articles/authn-authz/#authorization","title":"Authorization","text":"

With an access scheme that relies solely on authentication, any authenticated user would be given complete access to the registry. To better control access, zot supports identity-based repository-level access control (authorization) policies. The access control policy is a function of repository, user, and the action being performed on that repository.

"},{"location":"articles/authn-authz/#access-control-policies","title":"Access control policies","text":"

Five identity-based types of access control policies are supported:

Policy type Attribute Access allowed Default defaultPolicy The default policy specifies what actions are allowed if a user is authenticated but does match any user-specific policy. User-specific users, actions A user-specific policy specifies access and actions for explicitly named users. Group-specific groups, actions A group-specific policy specifies access and actions for explicitly named groups. Anonymous anonymousPolicy An anonymous policy specifies what an unauthenticated user is allowed to do. This is an appropriate policy when you want to grant open read-only access to one or more repositories. Admin adminPolicy The admin policy is a global access control policy that grants privileges to perform actions on any repository.

Access control is organized by repositories, users, and their actions. Most users of a particular repository will have similar access control requirements and can be served by a repository-specific defaultPolicy. Should a user require an exception to the default policy, a user-specific or group-specific override policy can be configured.

With an anonymousPolicy, a repository can allow anonymous actions which do not require user authentication. Finally, one or more users can be designated as administrators, to whom the global adminPolicy applies.

A user's access to a particular repository is evaluated first by whether a user-specific policy exists, then by group-specific policies, and then (in order) by default and admin policies.

A group-specific policy can be applied within any type of access policy, including default or admin policies. The group policy name can also be used with LDAP.

"},{"location":"articles/authn-authz/#configuring-access-control","title":"Configuring access control","text":"

User identity or group identity can be used as an authorization criterion for allowing actions on one or more repository paths. For specific users, you can choose to allow any combination of read, create, update, or delete actions on specific paths.

When you define policies for specific repository paths, the paths can be specified explicitly or by using glob patterns with simple or recursive wildcards. When a repository path matches more than one path description, authorization is granted based on the policy of the longest (most specific) path matched. For example, if policies are defined for path descriptions ** and repos2/repo, the repos2/repo path will match both ** and repos2/repo descriptions. In this case, the repos2/repo policy will be applied because it is longer.

Note that ** effectively defines the default policy, as it matches any path not matched by any other per-repository policy. To override all other policies, you can specify a global admin policy.

Always include the read action in any policy that you define. The create, update, and delete actions cannot be used without the read action.

"},{"location":"articles/authn-authz/#example-access-control-configuration","title":"Example: Access control configuration","text":"

Use the accessControl attribute in the configuration file to define a set of identity-based authorization policies, as shown in the following example.

\"http\": {\n...\n  \"accessControl\": {\n    \"groups\": {\n      \"group1\": {\n        \"users\": [\"bob\", \"mary\"]\n      },\n      \"group2\": {\n        \"users\": [\"alice\", \"mallory\", \"jim\"]\n      }\n    },\n    \"repositories\": {\n      \"**\": {\n        \"policies\": [{\n          \"users\": [\"charlie\"],\n          \"groups\": [\"group2\"],\n          \"actions\": [\"read\", \"create\", \"update\"]\n        }],\n        \"defaultPolicy\": [\"read\", \"create\"]\n      },\n      \"tmp/**\": {\n        \"anonymousPolicy\": [\"read\"],\n        \"defaultPolicy\": [\"read\", \"create\", \"update\"]\n      },\n      \"infra/*\": {\n        \"policies\": [{\n            \"users\": [\"alice\", \"bob\"],\n            \"actions\": [\"create\", \"read\", \"update\", \"delete\"]\n          },\n          {\n            \"users\": [\"mallory\"],\n            \"groups\": [\"group1\"],\n            \"actions\": [\"create\", \"read\"]\n          }\n        ],\n        \"defaultPolicy\": [\"read\"]\n      },\n      \"repos2/repo\": {\n        \"policies\": [{\n            \"users\": [\"bob\"],\n            \"actions\": [\"read\", \"create\"]\n          },\n          {\n            \"users\": [\"mallory\"],\n            \"actions\": [\"create\", \"read\"]\n          }\n        ],\n        \"defaultPolicy\": [\"read\"]\n      }\n    },\n    \"adminPolicy\": {\n      \"users\": [\"admin\"],\n      \"actions\": [\"read\", \"create\", \"update\", \"delete\"]\n    }\n  }\n

In this example, five policies are defined:

In releases prior to zot v2.0.0, authorization policies were defined directly under the accessControl key in the zot configuration file. Beginning with v2.0.0, the set of authorization policies are now defined under a new repositories key.

"},{"location":"articles/authn-authz/#social-login-using-openidoauth2","title":"Social login using OpenID/OAuth2","text":"

Social login is an authentication/authorization method in which your existing credentials for another site or service can be used to log in to a service such as zot. For example, you can log in to zot using your GitHub account credentials, and zot will contact GitHub to verify your identity using OAuth 2.0 and OpenID Connect (OIDC) protocols.

Several social login providers are supported by zot:

The following example shows the zot configuration for these providers:

{\n  \"http\": {\n    \"auth\": {\n      \"openid\": {\n        \"providers\": {\n          \"github\": {\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"read:org\", \"user\", \"repo\"]\n          },\n          \"google\": {\n            \"issuer\": \"https://accounts.google.com\",\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"openid\", \"email\"]\n          },\n          \"gitlab\": {\n            \"issuer\": \"https://gitlab.com\",\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"openid\", \"read_api\", \"read_user\", \"profile\", \"email\"]\n          },\n          \"oidc\": {\n            \"issuer\": \"http://<zot-server>:5556/dex\",\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"keypath\": \"\",\n            \"scopes\": [\"openid\", \"profile\", \"email\", \"groups\"]\n          }\n        }\n      }\n    }\n  }\n}\n
"},{"location":"articles/authn-authz/#using-google-github-or-gitlab","title":"Using Google, GitHub, or GitLab","text":"

A client logging into zot by social login must specify a supported OpenID/OAuth2 provider as a URL query parameter. A client logging in using Google, GitHub, or GitLab must additionally specify a callback URL for redirection to a zot page after a successful authentication.

The login URL using Google, GitHub, or GitLab uses the following format:

http://<zot-server>/auth/login?provider=<provider>&callback_ui=<zot-server>/<page>\n

For example, a user logging in to the zot home page using GitHub as the authentication provider sends this URL:

http://zot.example.com:8080/auth/login?provider=github&callback_ui=http://zot.example.com:8080/home\n

Based on the specified provider, zot redirects the login to a provider service with the following URL:

http://<zot-server>/zot/auth/callback/<provider>\n

For the GitHub authentication example:

http://zot.example.com:8080/zot/auth/callback/github\n

If your network policy doesn't allow inbound connections, the callback will not work and this authentication method will fail.

"},{"location":"articles/authn-authz/#using-dex","title":"Using dex","text":"

dex is an identity service that uses OpenID Connect (OIDC) to drive authentication for client apps, such as zot. While this section shows how to use dex with zot, zot supports other OIDC services as well.

Like zot, dex uses a configuration file for setup. To specify zot as a client in dex, configure a staticClients entry in the dex configuration file with a zot callback, such as the following example in the dex configuration file:

staticClients:\n  - id: zot-client\n    redirectURIs:\n      - 'http://zot.example.com:8080/zot/auth/callback/oidc'\n    name: 'zot'\n    secret: ZXhhbXBsZS1hcHAtc2VjcmV0\n

In the zot configuration file, configure dex as an OpenID auth provider as in the following example:

  \"http\": {\n    \"auth\": {\n      \"openid\": {\n        \"providers\": {\n          \"oidc\": {\n            \"name\": \"Corporate SSO\",\n            \"issuer\": \"http://<zot-server>:5556/dex\",\n            \"clientid\": \"zot-client\",\n            \"clientsecret\": \"ZXhhbXBsZS1hcHAtc2VjcmV0\",\n            \"keypath\": \"\",\n            \"scopes\": [\"openid\", \"profile\", \"email\", \"groups\"]\n          }\n        }\n      }\n    }\n  }\n

A user logging in to zot using dex OpenID authentication sends a URL with dex as a URL query parameter, such as the following example:

http://zot.example.com:8080/auth/login?provider=oidc

For detailed information about configuring dex service, see the dex Getting Started documentation.

"},{"location":"articles/authn-authz/#using-openidoauth2-when-zot-is-behind-a-proxy-or-load-balancer","title":"Using OpenID/OAuth2 when zot is behind a proxy or load balancer","text":"

When the zot registry is running behind a proxy or load balancer, you must provide an external URL for OpenID/OAuth2 clients to redirect back to zot. This externalUrl attribute is the URL of the registry, as shown in this example:

  \"http\": {\n    \"address\": \"0.0.0.0\",\n    \"port\": \"8080\",\n    \"externalUrl\": \"https://zot.example.com\",\n    \"auth\": {\n      \"openid\": {\n        \"providers\": {\n          \"github\": {\n            \"clientid\": <client_id>,\n            \"clientsecret\": <client_secret>,\n            \"scopes\": [\"read:org\", \"user\", \"repo\"]\n          }\n        }\n      }\n    }\n  }\n
"},{"location":"articles/benchmarking-with-zb/","title":"Benchmarking zot with zb","text":"

The zb tool is useful for benchmarking OCI registry workloads in scenarios such as the following:

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.

"},{"location":"articles/benchmarking-with-zb/#how-to-get-zb","title":"How to get zb","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#supported-platforms-and-architectures","title":"Supported platforms and architectures","text":"

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"},{"location":"articles/benchmarking-with-zb/#downloading-zb-binaries","title":"Downloading zb binaries","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#building-zb-from-source","title":"Building zb from source","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#running-zb","title":"Running zb","text":"

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.

"},{"location":"articles/benchmarking-with-zb/#usage","title":"Usage","text":"

To view the usage and options of zb, run the command with the --help option:

bin/zb --help

Command output:

    Usage:\n      zb <url> [flags]\n\n    Flags:\n      -A, --auth-creds string \u00a0 \u00a0 \u00a0Use colon-separated BASIC auth creds\n      -c, --concurrency int \u00a0 \u00a0 \u00a0 \u00a0Number of multiple requests to make at a time (default 1)\n \u00a0    -h, --help \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 help for zb\n \u00a0    -o, --output-format string \u00a0 Output format of test results: stdout (default), json, ci-cd\n \u00a0    -r, --repo string \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0Use specified repo on remote registry for test data\n \u00a0    -n, --requests int \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 Number of requests to perform (default 1)\n \u00a0    -s, --src-cidr string \u00a0 \u00a0 \u00a0 \u00a0Use specified cidr to obtain ips to make requests from, src-ips and src-cidr are mutually exclusive\n \u00a0    -i, --src-ips string \u00a0 \u00a0 \u00a0 \u00a0 Use colon-separated ips to make requests from, src-ips and src-cidr are mutually exclusive\n \u00a0    -v, --version \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0 \u00a0Show the version and exit\n \u00a0    -d, --working-dir string \u00a0 \u00a0 Use specified directory to store test data\n
"},{"location":"articles/benchmarking-with-zb/#example","title":"Example","text":"

The following example executes a benchmark operation using zb.

bin/zb -c 10 -s 127.0.10.0/24 -n 1000 http://localhost:8080

You can also run the released docker image.

docker run --net=host -it ghcr.io/project-zot/zb-linux-amd64:latest -c 10 -n 1000 -s 127.0.10.0/24 http://localhost:8080

Command output:

    Registry URL: http://localhost:8080\n\n    Concurrency Level: 2\n    Total requests:    100\n    Working dir:\n\n    ========\n    Test name:            Get Catalog\n    Time taken for tests: 45.397205ms\n    Complete requests:    100\n    Failed requests:      0\n    Requests per second:  2202.7788\n\n    2xx responses: 100\n\n    min: 402.259\u00b5s\n    max: 3.295887ms\n    p50: 855.045\u00b5s\n    p75: 971.709\u00b5s\n    p90: 1.127389ms\n    p99: 3.295887ms\n\n    ========\n    Test name:            Push Monolith 1MB\n    Time taken for tests: 952.336383ms\n    Complete requests:    100\n    Failed requests:      0\n    Requests per second:  105.00491\n\n    2xx responses: 100\n\n    min: 11.125673ms\n    max: 26.375356ms\n    p50: 18.917253ms\n    p75: 21.753441ms\n    p90: 24.02137ms\n    p99: 26.375356ms\n\n    ...\n
"},{"location":"articles/building-ci-cd-pipeline/","title":"Building an OCI-native Container Image CI/CD Pipeline","text":"

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.

"},{"location":"articles/building-ci-cd-pipeline/#build-images","title":"Build images","text":"

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>\n
"},{"location":"articles/building-ci-cd-pipeline/#image-registry","title":"Image registry","text":"

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>\n

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 \\\n  docker://<zot-server>/image:tag\n
Click here to view an example of pushing and pulling an image using skopeo.

"},{"location":"articles/building-ci-cd-pipeline/#signing-images","title":"Signing images","text":"

cosign is a tool that performs container signing, verification, and storage in an OCI registry.

example: cosign generates keys and signs an image in the registry

cosign generate-key-pair\n\ncosign sign --key cosign.key <zot-server>/image:tag\n
Click here to view an example of cosign operations.

"},{"location":"articles/building-ci-cd-pipeline/#deploying-container-images","title":"Deploying container images","text":"

cri-o is an implementation of the Kubernetes Container Runtime Interface (CRI) to enable using OCI compatible runtimes. It is a lightweight alternative to using Docker as the runtime for Kubernetes.

zot is compatible with kubernetes/cri-o using docker:// transport, which is the default.

example: kubelet configuration file

apiVersion: v1\nkind: Pod\nmetadata:\n  name: example-pod\nspec:\n  containers:\n  - name: example-container\n    image: <zot-server>/image:tag\n
"},{"location":"articles/building-ci-cd-pipeline/#container-image-verification","title":"Container image verification","text":"

cosigned is an image admission controller that validates container images before deploying them.

example: install cosigned using Helm

kubectl create namespace cosign-system\n\nkubectl create secret generic mysecret -n \\\n  cosign-system --from-file=cosign.pub=./cosign.pub\n\nhelm repo add sigstore https://sigstore.github.io/helm-charts\n\nhelm repo update\n\nhelm install cosigned -n cosign-system sigstore/cosigned \\\n  --devel --set cosign.secretKeyRef.name=mysecret\n
"},{"location":"articles/clustering/","title":"zot Clustering","text":"

High availability of the zot registry is supported by the following features:

To ensure high-availability of the registry, zot supports a clustering scheme with stateless zot instances/replicas fronted by a loadbalancer and a shared remote backend storage. This scheme allows the registry service to remain available even if a few replicas fail or become unavailable. Loadbalancing across many zot replicas can also increase aggregate network throughput.

Clustering is supported in both bare-metal and Kubernetes environments.

The remote backend storage must be S3 API-compatible.

"},{"location":"articles/clustering/#bare-metal-deployment","title":"Bare-metal deployment","text":""},{"location":"articles/clustering/#prerequisites","title":"Prerequisites","text":""},{"location":"articles/clustering/#kubernetes-deployment","title":"Kubernetes deployment","text":""},{"location":"articles/clustering/#prerequisites_1","title":"Prerequisites","text":""},{"location":"articles/clustering/#implementing-stateless-zot","title":"Implementing stateless zot","text":"

zot maintains two types of durable state:

In a stateless clustering scheme, the image data is stored in the remote storage backend and the registry cache is disabled by turning off both deduplication and garbage collection.

"},{"location":"articles/clustering/#ecosystem-tools","title":"Ecosystem tools","text":"

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 loadbalancing and ingress gateway configuration.

"},{"location":"articles/clustering/#examples","title":"Examples","text":"

zot supports clustering by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load-balancing traffic to the replicas.

"},{"location":"articles/clustering/#yaml-configuration","title":"YAML configuration","text":"Click here to view a sample haproxy configuration. 
global\n        log /dev/log    local0\n        log /dev/log    local1 notice\n        chroot /var/lib/haproxy\n        maxconn 2000\n        stats socket /run/haproxy/admin.sock mode 660 level admin expose-fd listeners\n        stats timeout 30s\n        user haproxy\n        group haproxy\n        daemon\n\n        # Default SSL material locations\n        ca-base /etc/ssl/certs\n        crt-base /etc/ssl/private\n\n        # See: https://ssl-config.mozilla.org/#server=haproxy&server-version=2.0.3&config=intermediate\n        ssl-default-bind-ciphers ECDHE-ECDSA-AES128-GCM-SHA256:ECDHE-RSA-AES128-GCM-SHA256:ECDHE-ECDSA-AES256-GCM-SHA384:ECDHE-RSA-AES256-GCM-SHA384:ECDHE-ECDSA-CHACHA20-POLY1305:ECDHE-RSA-CHACHA20-POLY1305:DHE-RSA-AES128-GCM-SHA256:DHE-RSA-AES256-GCM-SHA384\n        ssl-default-bind-ciphersuites TLS_AES_128_GCM_SHA256:TLS_AES_256_GCM_SHA384:TLS_CHACHA20_POLY1305_SHA256\n        ssl-default-bind-options ssl-min-ver TLSv1.2 no-tls-tickets\n\ndefaults\n        log     global\n        mode    http\n        option  httplog\n        option  dontlognull\n        timeout connect 5000\n        timeout client  50000\n        timeout server  50000\n        errorfile 400 /etc/haproxy/errors/400.http\n        errorfile 403 /etc/haproxy/errors/403.http\n        errorfile 408 /etc/haproxy/errors/408.http\n        errorfile 500 /etc/haproxy/errors/500.http\n        errorfile 502 /etc/haproxy/errors/502.http\n        errorfile 503 /etc/haproxy/errors/503.http\n        errorfile 504 /etc/haproxy/errors/504.http\n\nfrontend zot\n    bind *:8080\n    mode http\n    default_backend zot-cluster\n\nbackend zot-cluster\n    mode http\n    balance roundrobin\n    server zot1 127.0.0.1:8081 check\n    server zot2 127.0.0.1:8082 check\n    server zot3 127.0.0.1:8083 check\n
"},{"location":"articles/clustering/#zot-s3-configuration","title":"zot S3 configuration","text":"Click here to view a sample zot configuration for S3. 
{\n    \"distSpecVersion\": \"1.0.1-dev\",\n    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true,\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"rootdirectory\": \"/zot\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false\n        },\n        \"cacheDriver\": {\n            \"name\": \"dynamodb\",\n            \"endpoint\": \"http://localhost:4566\",\n            \"region\": \"us-east-2\",\n            \"tableName\": \"MainTable\"\n        }\n    },\n    \"http\": {\n        \"address\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"log\": {\n        \"level\": \"debug\"\n    }\n}\n
"},{"location":"articles/graphql/","title":"Using GraphQL for Enhanced Searches","text":"

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.

"},{"location":"articles/graphql/#how-to-use-graphql-for-search-queries","title":"How to use GraphQL for search queries","text":"

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.

"},{"location":"articles/graphql/#using-the-search-api-directly","title":"Using the search API directly","text":"

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\n

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\n

The reply to your query is returned as a JSON payload in the HTML response.

"},{"location":"articles/graphql/#using-the-graphql-playground","title":"Using the GraphQL Playground","text":"

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#\n

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#\n

In the GraphQL Playground, you can construct and submit a query structure and you can view the query response in a graphical environment in the browser. You can also inspect the schema.

"},{"location":"articles/graphql/#what-graphql-queries-are-supported","title":"What GraphQL queries are supported","text":"Supported queries graphQL query Input Output Description Search images by digest ImageListForDigest digest image list Searches all repositories in the registry and returns list of images that matches given digest (manifest, config or layers) Search images affected by a given CVE id CVEListForImage CVE id image list Searches the entire registry and returns list of images affected by given CVE List CVEs for a given image CVEListForImage image CVE list Scans given image and returns list of CVEs affecting the image List images not affected by a given CVE id ImagesListWithCVEFixed repository, CVE id image list Scans all images in a given repository and returns list of latest (by date) images not affected by the given CVE Latest image from all repos RepoListWithNewestImage none repo summary list Returns the latest image from all the repos in the registry List all images with expanded information for a given repository ExpandedRepoInfo repository repo info List expanded repo information for all images in repo, alongside a repo summary All images in repo ImageList repository image list Returns all images in the specified repo Global search GlobalSearch query image summary / repo summary / layer summary Will return what's requested in the query argument Derived image list DerivedImageList image image list Returns a list of images that depend on the image specified in the argument Base image list BaseImageList image image list Returns a list of images that the specified image depends on Get details of a specific image Image image image summary Returns details about a specific image Get referrers of a specific image Referrers repo, digest, type artifact manifests Returns a list of artifacts of given type referring to a specific repo and digests"},{"location":"articles/graphql/#examples-of-zot-searches-using-graphql","title":"Examples of zot searches using GraphQL","text":"

These examples show only the GraphQL query without details on how to send them to a server. See How to use GraphQL for search queries.

The query structures shown in these examples request all fields allowed by the schema for the particular query type. The schema allows you to request a subset of the data, if desired, omitting any fields that you don't need.

"},{"location":"articles/graphql/#list-cves-of-given-image","title":"List CVEs of given image","text":"

Sample request

{\n  CVEListForImage(\n    image: \"alpine:3.17\"\n    requestedPage: {limit: 1, offset:1, sortBy: SEVERITY}\n  ) {\n    Tag\n    Page {\n      TotalCount\n      ItemCount\n    }\n    CVEList {\n      Id\n      Title\n      Description\n      Severity\n      PackageList {\n        Name\n        InstalledVersion\n        FixedVersion\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"CVEListForImage\": {\n      \"Tag\": \"3.17\",\n      \"Page\": {\n        \"TotalCount\": 9,\n        \"ItemCount\": 1\n      },\n      \"CVEList\": [\n        {\n          \"Id\": \"CVE-2023-5363\",\n          \"Title\": \"openssl: Incorrect cipher key and IV length processing\",\n          \"Description\": \"Issue summary: A bug has been identified in the processing of key and\\ninitialisation vector (IV) lengths.  This can lead to potential truncation\\nor overruns during the initialisation of some symmetric ciphers.\\n\\nImpact summary: A truncation in the IV can result in non-uniqueness,\\nwhich could result in loss of confidentiality for some cipher modes.\\n\\nWhen calling EVP_EncryptInit_ex2(), EVP_DecryptInit_ex2() or\\nEVP_CipherInit_ex2() the provided OSSL_PARAM array is processed after\\nthe key and IV have been established.  Any alterations to the key length,\\nvia the \\\"keylen\\\" parameter or the IV length, via the \\\"ivlen\\\" parameter,\\nwithin the OSSL_PARAM array will not take effect as intended, potentially\\ncausing truncation or overreading of these values.  The following ciphers\\nand cipher modes are impacted: RC2, RC4, RC5, CCM, GCM and OCB.\\n\\nFor the CCM, GCM and OCB cipher modes, truncation of the IV can result in\\nloss of confidentiality.  For example, when following NIST's SP 800-38D\\nsection 8.2.1 guidance for constructing a deterministic IV for AES in\\nGCM mode, truncation of the counter portion could lead to IV reuse.\\n\\nBoth truncations and overruns of the key and overruns of the IV will\\nproduce incorrect results and could, in some cases, trigger a memory\\nexception.  However, these issues are not currently assessed as security\\ncritical.\\n\\nChanging the key and/or IV lengths is not considered to be a common operation\\nand the vulnerable API was recently introduced. Furthermore it is likely that\\napplication developers will have spotted this problem during testing since\\ndecryption would fail unless both peers in the communication were similarly\\nvulnerable. For these reasons we expect the probability of an application being\\nvulnerable to this to be quite low. However if an application is vulnerable then\\nthis issue is considered very serious. For these reasons we have assessed this\\nissue as Moderate severity overall.\\n\\nThe OpenSSL SSL/TLS implementation is not affected by this issue.\\n\\nThe OpenSSL 3.0 and 3.1 FIPS providers are not affected by this because\\nthe issue lies outside of the FIPS provider boundary.\\n\\nOpenSSL 3.1 and 3.0 are vulnerable to this issue.\",\n          \"Severity\": \"HIGH\",\n          \"PackageList\": [\n            {\n              \"Name\": \"libcrypto3\",\n              \"InstalledVersion\": \"3.0.8-r0\",\n              \"FixedVersion\": \"3.0.12-r0\"\n            },\n            {\n              \"Name\": \"libssl3\",\n              \"InstalledVersion\": \"3.0.8-r0\",\n              \"FixedVersion\": \"3.0.12-r0\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-images-affected-by-a-given-cve-id","title":"Search images affected by a given CVE id","text":"

Sample request

{\n  ImageListForCVE(id: \"CVE-2023-0464\") {\n    Results{\n      RepoName\n      Tag\n      Digest\n      LastUpdated\n      IsSigned\n      Size\n      Vendor\n      DownloadCount\n      Licenses\n      Title\n      Manifests {\n        Digest\n        ConfigDigest\n        Platform {\n          Os\n          Arch\n        }\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageListForCVE\": {\n      \"Results\": [\n        {\n          \"RepoName\": \"alpine\",\n          \"Tag\": \"3.17\",\n          \"Digest\": \"sha256:75bfe77c8d5a76b4421cfcebbd62a28ae70d10147578d0cda45820e99b0ef1d8\",\n          \"LastUpdated\": \"2023-02-11T04:46:42.558343068Z\",\n          \"IsSigned\": true,\n          \"Size\": \"3375436\",\n          \"Vendor\": \"\",\n          \"DownloadCount\": 0,\n          \"Licenses\": \"\",\n          \"Title\": \"\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:75bfe77c8d5a76b4421cfcebbd62a28ae70d10147578d0cda45820e99b0ef1d8\",\n              \"ConfigDigest\": \"sha256:6a2bcc1c7b4c9207f791a4512d7f2fa8fc2daeae58dbc51cb2797b05415f082a\",\n              \"Platform\": {\n                \"Os\": \"linux\",\n                \"Arch\": \"amd64\"\n              }\n            }\n          ]\n        },\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#list-images-not-affected-by-a-given-cve-id","title":"List images not affected by a given CVE id","text":"

Sample request

{\n  ImageListWithCVEFixed(id: \"CVE-2023-0464\", image: \"ubuntu\") {\n    Results {\n      RepoName\n      Tag\n      Digest\n      LastUpdated\n      Manifests {\n        Digest\n        ConfigDigest\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageListWithCVEFixed\": {\n      \"Results\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"kinetic\",\n          \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\",\n          \"LastUpdated\": \"2022-10-14T15:28:55.0263968Z\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\",\n              \"ConfigDigest\": \"sha256:824c0269745923afceb9765ae24f5b331bb6fcf2a82f7eba98b3cfd543afb41e\"\n            }\n          ]\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"kinetic-20220922\",\n          \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\",\n          \"LastUpdated\": \"2022-10-14T15:27:41.2144454Z\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\",\n              \"ConfigDigest\": \"sha256:15c8dcf63970bb14ea36e41aa001b87d8d31e25a082bf6f659d12489d3e53d90\"\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-images-by-digest","title":"Search images by digest","text":"

Sample request

{\n  ImageListForDigest(\n    id: \"79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\"\n  ) {\n    Results{\n      RepoName\n      Tag\n      Title\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageListForDigest\": {\n      \"Results\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"kinetic-20220922\",\n          \"Title\": \"ubuntu\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#list-the-latest-image-across-every-repository","title":"List the latest image across every repository","text":"

Sample request

{\n  RepoListWithNewestImage(requestedPage: {limit: 2, offset:0, sortBy: ALPHABETIC_ASC}) {\n    Page {\n      TotalCount\n      ItemCount\n    }\n    Results {\n      Name\n      LastUpdated\n      Size\n      Platforms {\n        Os\n        Arch\n      }\n      NewestImage {\n        Digest\n        Tag\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"RepoListWithNewestImage\": {\n      \"Page\": {\n        \"TotalCount\": 30,\n        \"ItemCount\": 2\n      },\n      \"Results\": [\n        {\n          \"Name\": \"mariadb\",\n          \"LastUpdated\": \"2022-10-18T14:56:33.1993083+03:00\",\n          \"Size\": \"124116964\",\n          \"Platforms\": [\n            {\n              \"Os\": \"linux\",\n              \"Arch\": \"amd64\"\n            }\n          ],\n          \"NewestImage\": {\n            \"Digest\": \"sha256:49a299f5c4b1af5bc2aa6cf8e50ab5bad85db4d0095745369acfc1934ece99d0\",\n            \"Tag\": \"latest\"\n          }\n        },\n        {\n          \"Name\": \"tomcat\",\n          \"LastUpdated\": \"2022-10-18T14:55:13.8303866+03:00\",\n          \"Size\": \"311658063\",\n          \"Platforms\": [\n            {\n              \"Os\": \"linux\",\n              \"Arch\": \"amd64\"\n            }\n          ],\n          \"NewestImage\": {\n            \"Digest\": \"sha256:bbc5a3912b568fbfb5912beaf25054f1f407c32a53acae29f19ad97485731a78\",\n            \"Tag\": \"jre17\"\n          }\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#all-images-in-repo","title":"All images in repo","text":"

Sample request

{\n  ImageList (repo: \"ubuntu\") {\n    Results {\n      Tag\n      Digest\n      LastUpdated\n      Size\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ImageList\": {\n      \"Results\": [\n        {\n          \"Tag\": \"jammy\",\n          \"Digest\": \"sha256:f96fcb040c7ee00c037c758cf0ab40638e6ee89b03a9d639178fcbd0e7f96d27\",\n          \"LastUpdated\": \"2022-10-14T15:29:18.0325322Z\",\n          \"Size\": \"30472739\"\n        },\n        {\n          \"Tag\": \"jammy-20221003\",\n          \"Digest\": \"sha256:86681debca1719dff33f426a0f5c41792ebc52496c5d78a93b655b8b48fb71b2\",\n          \"LastUpdated\": \"2022-10-14T15:29:07.0004587Z\",\n          \"Size\": \"30472748\"\n        },\n        {\n          \"Tag\": \"kinetic\",\n          \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\",\n          \"LastUpdated\": \"2022-10-14T15:28:55.0263968Z\",\n          \"Size\": \"27498890\"\n        },\n        {\n          \"Tag\": \"kinetic-20220922\",\n          \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\",\n          \"LastUpdated\": \"2022-10-14T15:27:41.2144454Z\",\n          \"Size\": \"27498899\"\n        },\n        {\n          \"Tag\": \"latest\",\n          \"Digest\": \"sha256:9bc6d811431613bf2fd8bf3565b319af9998fc5c46304022b647c63e1165657c\",\n          \"LastUpdated\": \"2022-10-14T15:26:59.6707939Z\",\n          \"Size\": \"30472740\"\n        },\n        {\n          \"Tag\": \"rolling\",\n          \"Digest\": \"sha256:72e75626c5068b9d9a462c4fc80a29787d0cf61c8abc81bfd5ea69f6248d56fc\",\n          \"LastUpdated\": \"2022-10-14T15:27:21.2441356Z\",\n          \"Size\": \"30472741\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#list-all-images-with-expanded-information-for-a-given-repository","title":"List all images with expanded information for a given repository","text":"

Sample request

{\n  ExpandedRepoInfo(repo: \"ubuntu\") {\n    Images {\n      Tag\n      Digest\n    }\n    Summary {\n      LastUpdated\n      Size\n      NewestImage {\n        Tag\n        LastUpdated\n        Digest\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"ExpandedRepoInfo\": {\n      \"Images\": [\n        {\n          \"Tag\": \"jammy\",\n          \"Digest\": \"sha256:f96fcb040c7ee00c037c758cf0ab40638e6ee89b03a9d639178fcbd0e7f96d27\"\n        },\n        {\n          \"Tag\": \"jammy-20221003\",\n          \"Digest\": \"sha256:86681debca1719dff33f426a0f5c41792ebc52496c5d78a93b655b8b48fb71b2\"\n        },\n        {\n          \"Tag\": \"kinetic\",\n          \"Digest\": \"sha256:1ac35e499e330f6520e80e91b29a55ff298077211f5ed66aff5cb357cca4a28f\"\n        },\n        {\n          \"Tag\": \"kinetic-20220922\",\n          \"Digest\": \"sha256:79eae04a0e32878fef3f8c5f901c32f6704c4a80b7f3fd9d89629e15867acfff\"\n        },\n        {\n          \"Tag\": \"rolling\",\n          \"Digest\": \"sha256:72e75626c5068b9d9a462c4fc80a29787d0cf61c8abc81bfd5ea69f6248d56fc\"\n        },\n        {\n          \"Tag\": \"latest\",\n          \"Digest\": \"sha256:9bc6d811431613bf2fd8bf3565b319af9998fc5c46304022b647c63e1165657c\"\n        }\n      ],\n      \"Summary\": {\n        \"LastUpdated\": \"2022-10-14T15:29:18.0325322Z\",\n        \"Size\": \"58146896\",\n        \"NewestImage\": {\n          \"Tag\": \"jammy\",\n          \"LastUpdated\": \"2022-10-14T15:29:18.0325322Z\",\n          \"Digest\": \"sha256:f96fcb040c7ee00c037c758cf0ab40638e6ee89b03a9d639178fcbd0e7f96d27\"\n        }\n      }\n    }\n  }\n}\n
"},{"location":"articles/graphql/#global-search","title":"Global search","text":"

Sample request

{\n  GlobalSearch(query: \"ubuntu:latest\") {\n    Page {\n      ItemCount\n      TotalCount\n    }\n    Images {\n      RepoName\n      Tag\n      LastUpdated\n      Manifests {\n        Digest\n        Layers {\n          Size\n          Digest\n        }\n      }\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"GlobalSearch\": {\n      \"Page\": {\n        \"ItemCount\": 1,\n        \"TotalCount\": 1\n      },\n      \"Images\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-14T15:26:59.6707939Z\",\n          \"Manifests\": [\n            {\n              \"Digest\": \"sha256:9bc6d811431613bf2fd8bf3565b319af9998fc5c46304022b647c63e1165657c\",\n              \"Layers\": [\n                {\n                  \"Size\": \"30428928\",\n                  \"Digest\": \"sha256:cf92e523b49ea3d1fae59f5f082437a5f96c244fda6697995920142ff31d59cf\"\n                }\n              ]\n            }\n          ]\n        }\n      ]\n    }\n  }\n}\n

Sample request

{\n  GlobalSearch(query: \"\") {\n    Repos {\n      Name\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"GlobalSearch\": {\n      \"Repos\": [\n        {\n          \"Name\": \"centos\"\n        },\n        {\n          \"Name\": \"ubuntu\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-derived-images","title":"Search derived images","text":"

Sample query

{\n  DerivedImageList(image: \"ubuntu:latest\", requestedPage: {offset: 0, limit: 10}) {\n    Page {\n      TotalCount\n      ItemCount\n    }\n    Results {\n      RepoName\n      Tag\n      LastUpdated\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"DerivedImageList\": {\n      \"Page\": {\n        \"TotalCount\": 9,\n        \"ItemCount\": 9\n      },\n      \"Results\": [\n        {\n          \"RepoName\": \"mariadb\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-18T14:56:33.1993083+03:00\"\n        },\n        {\n          \"RepoName\": \"maven\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-14T18:30:12.0929807+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-18T14:50:09.7229959+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"jre17\",\n          \"LastUpdated\": \"2022-10-18T14:55:13.8303866+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"jre17-temurin\",\n          \"LastUpdated\": \"2022-10-18T14:54:46.4133521+03:00\"\n        },\n        {\n          \"RepoName\": \"tomcat\",\n          \"Tag\": \"jre17-temurin-jammy\",\n          \"LastUpdated\": \"2022-10-18T14:51:12.235475+03:00\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#search-base-images","title":"Search base images","text":"

Sample query

{\n  BaseImageList(image: \"mariadb:latest\", requestedPage: {offset: 0, limit: 10}) {\n    Page {\n      TotalCount\n      ItemCount\n    }\n    Results {\n      RepoName\n      Tag\n      LastUpdated\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"BaseImageList\": {\n      \"Page\": {\n        \"TotalCount\": 4,\n        \"ItemCount\": 4\n      },\n      \"Results\": [\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"jammy\",\n          \"LastUpdated\": \"2022-10-14T18:29:18.0325322+03:00\"\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"jammy-20221003\",\n          \"LastUpdated\": \"2022-10-14T18:29:07.0004587+03:00\"\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"latest\",\n          \"LastUpdated\": \"2022-10-14T18:26:59.6707939+03:00\"\n        },\n        {\n          \"RepoName\": \"ubuntu\",\n          \"Tag\": \"rolling\",\n          \"LastUpdated\": \"2022-10-14T18:27:21.2441356+03:00\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/graphql/#get-details-of-a-specific-image","title":"Get details of a specific image","text":"

Sample query

{\n  Image(image: \"mariadb:latest\") {\n    RepoName\n    Tag\n    LastUpdated\n    Digest\n    Description\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"Image\": {\n      \"RepoName\": \"mariadb\",\n      \"Tag\": \"latest\",\n      \"LastUpdated\": \"2022-10-18T14:56:33.1993083+03:00\",\n      \"Digest\": \"sha256:49a299f5c4b1af5bc2aa6cf8e50ab5bad85db4d0095745369acfc1934ece99d0\",\n      \"Description\": \"MariaDB Server is a high performing open source relational database, forked from MySQL.\"\n    }\n  }\n}\n
"},{"location":"articles/graphql/#get-referrers-of-a-specific-image","title":"Get referrers of a specific image","text":"

Sample query

{\n  Referrers(\n    repo: \"golang\"\n    digest: \"sha256:fed08b0eaea00aab17f82ecbb78675919d216c72eea985581758191f694aeaf7\"\n    type: \"application/vnd.example.icecream.v1\"\n  ) {\n    MediaType\n    ArtifactType\n    Digest\n    Annotations {\n      Key\n      Value\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"Referrers\": [\n      {\n        \"MediaType\": \"application/vnd.oci.artifact.manifest.v1+json\",\n        \"ArtifactType\": \"application/vnd.example.icecream.v1\",\n        \"Digest\": \"sha256:be7a3d01c35a2cf53c502e9dc50cdf36b15d9361c81c63bf319f1d5cbe44ab7c\",\n        \"Annotations\": [\n          {\n            \"Key\": \"format\",\n            \"Value\": \"oci\"\n          },\n          {\n            \"Key\": \"demo\",\n            \"Value\": \"true\"\n          }\n        ]\n      },\n      {\n        \"MediaType\": \"application/vnd.oci.artifact.manifest.v1+json\",\n        \"ArtifactType\": \"application/vnd.example.icecream.v1\",\n        \"Digest\": \"sha256:d9ad22f41d9cb9797c134401416eee2a70446cee1a8eb76fc6b191f4320dade2\",\n        \"Annotations\": [\n          {\n            \"Key\": \"demo\",\n            \"Value\": \"true\"\n          },\n          {\n            \"Key\": \"format\",\n            \"Value\": \"oci\"\n          }\n        ]\n      }\n    ]\n  }\n}\n
"},{"location":"articles/kind-deploy/","title":"Using kind for Deployment Testing","text":"

Use kind to try out zot deployment with Kubernetes.

This article describes how to create a kind cluster that includes a local zot registry.

"},{"location":"articles/kind-deploy/#deploying-the-cluster-and-registry","title":"Deploying the cluster and registry","text":"

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.

"},{"location":"articles/kind-deploy/#step-1-prepare-the-environment","title":"Step 1: Prepare the environment","text":"

The following packages must be installed:

Execute the following shell commands to set environment variables.

set -o errexit\n\n# set no_proxy if applicable\nif [ ! -z \"${no_proxy}\" ]; then \n  echo \"Updating no_proxy environment variables\";\n  export no_proxy=${no_proxy},kind-registry;\n  export NO_PROXY=${no_proxy};\nfi\n
"},{"location":"articles/kind-deploy/#step-2-create-a-registry-container","title":"Step 2: Create a registry container","text":"

Create a kind-registry container, pulling a zot binary from the GitHub Container Registry (ghcr.io).

This example pulls zot-minimal-linux-amd64:latest, a minimal (no extensions) zot image for an AMD-based linux server.

Other available images are described at the zot releases page in GitHub. You can also specify a release by replacing latest with an available release number.

# create registry container unless it already exists\nreg_name='kind-registry'\nreg_port='5001'\nif [ \"$(docker inspect -f '{{.State.Running}}' \"${reg_name}\" 2>/dev/null || true)\" != 'true' ]; then\n  docker run \\\n    -d --restart=always -p \"127.0.0.1:${reg_port}:5000\" --name \"${reg_name}\" \\\n    ghcr.io/project-zot/zot-minimal-linux-amd64:latest\nfi\n
"},{"location":"articles/kind-deploy/#step-3-create-the-kind-cluster","title":"Step 3: Create the kind cluster","text":"

Create a cluster with the local registry enabled.

# enable the local registry in containerd\ncat <<EOF | kind create cluster --config=-\nkind: Cluster\napiVersion: kind.x-k8s.io/v1alpha4\ncontainerdConfigPatches:\n- |-\n  [plugins.\"io.containerd.grpc.v1.cri\".registry.mirrors.\"localhost:${reg_port}\"]\n    endpoint = [\"http://${reg_name}:5000\"]\nEOF\n
"},{"location":"articles/kind-deploy/#step-4-connect-the-registry-to-the-cluster-network","title":"Step 4: Connect the registry to the cluster network","text":"

Connect the registry to the \"kind\" network so that it can communicate with other resources in the same network.

# check whether already connected to the network\nif [ \"$(docker inspect -f='{{json .NetworkSettings.Networks.kind}}' \\\n\"${reg_name}\")\" = 'null' ]; then\n  docker network connect \"kind\" \"${reg_name}\"\nfi\n
"},{"location":"articles/kind-deploy/#step-5-document-the-local-registry","title":"Step 5: Document the local registry","text":"

Create a ConfigMap that specifies how to interact with the local registry. This ConfigMap follows the KEP-1755 Standard for communicating a local registry.

cat <<EOF | kubectl apply -f -\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: local-registry-hosting\n  namespace: kube-public\ndata:\n  localRegistryHosting.v1: |\n    host: \"localhost:${reg_port}\"\n    help: \"https://kind.sigs.k8s.io/docs/user/local-registry/\"\nEOF\n
"},{"location":"articles/kind-deploy/#step-6-deploy-and-test","title":"Step 6: Deploy and test","text":"

Use skopeo to copy (pull) a \"hello\" app from the Google Container Registry (gcr.io) into the new zot registry. Using kubectl, deploy the app from the new local zot registry as \"hello-server\" and monitor the deployment for initial availability.

# copy an image\nskopeo copy --format=oci --dest-tls-verify=false \\\ndocker://gcr.io/google-samples/hello-app:1.0 \\\ndocker://localhost:5001/hello-app:1.0\n\n# deploy the image\nkubectl create deployment hello-server --image=localhost:5001/hello-app:1.0\n\n# check for availability\necho \"Waiting for deployment/hello-server to be ready ...\"\nkubectl wait deployment -n default hello-server \\\n  --for condition=Available=True --timeout=90s\n
"},{"location":"articles/kind-deploy/#clean-up","title":"Clean up","text":"

To clean up after testing, run the following commands to delete the kind cluster and registry.

kind delete cluster\ndocker stop kind-registry\ndocker rm kind-registry\n
"},{"location":"articles/kind-deploy/#reference-a-complete-script","title":"Reference: A complete script","text":"

The following script executes all of the preceding steps.

Click here to view the entire script 
#!/bin/sh\nset -o errexit\n\n# Reference: https://kind.sigs.k8s.io/docs/user/local-registry/\n\n# set no_proxy if applicable\nif [ ! -z \"${no_proxy}\" ]; then \n  echo \"Updating no_proxy env var\";\n  export no_proxy=${no_proxy},kind-registry;\n  export NO_PROXY=${no_proxy};\nfi\n\n# create registry container unless it already exists\nreg_name='kind-registry'\nreg_port='5001'\nif [ \"$(docker inspect -f '{{.State.Running}}' \"${reg_name}\" 2>/dev/null || true)\" != 'true' ]; then\n  docker run \\\n    -d --restart=always -p \"127.0.0.1:${reg_port}:5000\" --name \"${reg_name}\" \\\n    ghcr.io/project-zot/zot-minimal-linux-amd64:latest\nfi\n\n# create a cluster with the local registry enabled in containerd\ncat <<EOF | kind create cluster --config=-\nkind: Cluster\napiVersion: kind.x-k8s.io/v1alpha4\ncontainerdConfigPatches:\n- |-\n  [plugins.\"io.containerd.grpc.v1.cri\".registry.mirrors.\"localhost:${reg_port}\"]\n    endpoint = [\"http://${reg_name}:5000\"]\nEOF\n\n# connect the registry to the cluster network if not already connected\nif [ \"$(docker inspect -f='{{json .NetworkSettings.Networks.kind}}' \"${reg_name}\")\" = 'null' ]; then\n  docker network connect \"kind\" \"${reg_name}\"\nfi\n\n# https://github.com/kubernetes/enhancements/tree/master/keps/sig-cluster-lifecycle/generic/1755-communicating-a-local-registry\n#\n# document the local registry\ncat <<EOF | kubectl apply -f -\napiVersion: v1\nkind: ConfigMap\nmetadata:\n  name: local-registry-hosting\n  namespace: kube-public\ndata:\n  localRegistryHosting.v1: |\n    host: \"localhost:${reg_port}\"\n    help: \"https://kind.sigs.k8s.io/docs/user/local-registry/\"\nEOF\n\n# copy an image\nskopeo copy --format=oci --dest-tls-verify=false docker://gcr.io/google-samples/hello-app:1.0 docker://localhost:5001/hello-app:1.0\n\n# deploy the image\nkubectl create deployment hello-server --image=localhost:5001/hello-app:1.0\n\n# check for availability\necho \"Waiting for deployment/hello-server to be ready ...\"\nkubectl wait deployment -n default hello-server --for condition=Available=True --timeout=90s\n\n# cleanup\necho \"Press a key to begin cleanup ...\"\nread KEYPRESS\nkind delete cluster\ndocker stop kind-registry\ndocker rm kind-registry\n
"},{"location":"articles/mirroring/","title":"OCI Registry Mirroring With zot","text":"

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.

"},{"location":"articles/mirroring/#mirroring-modes","title":"Mirroring modes","text":"

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.

"},{"location":"articles/mirroring/#migrating-or-updating-a-registry-using-mirroring","title":"Migrating or updating a registry using mirroring","text":"

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.

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: 

  {\n    \"urls\": [\n        \"https://registry1:5000\"\n    ],\n    \"pollInterval\": \"12h\",\n    \"onDemand\": true,\n    \"content\": [\n        {\n            \"prefix\": \"**\"\n        }\n    ]\n  }\n
"},{"location":"articles/mirroring/#basic-configuration-for-mirroring-with-sync","title":"Basic configuration for mirroring with sync","text":"

The sync feature of zot is an extension of the OCI-compliant registry implementation. You can configure the sync feature under the extensions section of the zot configuration file, as shown in this example:

  \"extensions\": {\n    \"sync\": {\n      \"credentialsFile\": \"./examples/sync-auth-filepath.json\",\n      \"registries\": [\n        {\n          \"urls\": [\n            \"https://registry1:5000\"\n          ],\n          \"onDemand\": false,\n          \"pollInterval\": \"6h\",\n          \"tlsVerify\": true,\n          \"certDir\": \"/home/user/certs\",\n          \"maxRetries\": 3,\n          \"retryDelay\": \"5m\", \n          \"onlySigned\": true,\n          \"content\": [\n            {\n              \"prefix\": \"/repo2/repo\",\n              \"tags\": {\n                \"regex\": \"4.*\",\n                \"semver\": true\n              }\n              \"destination\": \"/repo2\",\n              \"stripPrefix\": true\n            }\n          ]\n        }\n      ]\n    }\n  }\n

The following table lists the configurable attributes for the sync feature:

Attribute Description

credentialsFile

The location of a local file containing credentials for other registries, as in the following example: 

{\u2003\u2003\"127.0.0.1:8080\": {\u2003\u2003\u2003\u2003\"username\": \"user\",\u2003\u2003\u2003\u2003\"password\": \"pass\"\u2003\u2003},\u2003\u2003\u2003\u2003\"registry2:5000\": {\u2003\u2003\u2003\u2003\"username\": \"user2\",\u2003\u2003\u2003\u2003\"password\": \"pass2\"\u2003\u2003}}

urls

A list of one or more URLs to an upstream image registry. If the main URL fails, the sync process will try the next URLs in the listed order.

onDemand

pollInterval

The period in seconds between polling of a remote registry. If no value is specified, no periodic polling will occur. If a value is set and the content attributes are configured, periodic synchronization is enabled and will run at the specified value.Note: Because Docker Hub rate-limits pulls and does not support catalog listing, do not use polled mirroring with Docker Hub. Use only onDemand mirroring with Docker Hub.

tlsVerify

certDir

If a path is specified, use certificates (*.crt, *.cert, *.key files) at this path when connecting to the destination registry or daemon. If no path is specified, use the default certificates directory.

maxRetries

The maximum number of retries if an error occurs during either an on-demand or periodic synchronization. If no value is specified, no retries will occur.

retryDelay

The interval in seconds between retries. This attribute is mandatory when maxRetries is configured.

onlySigned

content

The included attributes in this section specify which content will be pulled. If this section is not populated, periodic polling will not occur. The included attributes can also filter which on-demand images are pulled.

prefix

On the remote registry, the path from which images will be pulled. This path can be a string that exactly matches the remote path, or it can be a glob pattern. For example, the path can include a wildcard (*) or a recursive wildcard (**).

tags

The included attributes in this optional section specify how remote images will be selected for synchronization based on image tags.

tags.regex

Specifies a regular expression for matching image tags. Images whose tags do not match the expression are not pulled.

tags.semver

Specifies whether image tags are to be filtered by semantic versioning (semver) compliance.

destination

Specifies the local path in which pulled images are to be stored.

stripPrefix

Specifies whether the prefix path from the remote registry will be retained or replaced when the image is stored in the zot registry.

"},{"location":"articles/mirroring/#configuration-examples-for-mirroring","title":"Configuration examples for mirroring","text":""},{"location":"articles/mirroring/#example-multiple-repositories-with-polled-mirroring","title":"Example: Multiple repositories with polled mirroring","text":"

The following is an example of sync configuration for mirroring multiple repositories with polled mirroring.

\"sync\": {\n  \"enable\": true,\n  \"credentialsFile\": \"./examples/sync-auth-filepath.json\",\n  \"registries\": [\n    {\n      \"urls\": [\"https://registry1:5000\"],\n      \"onDemand\": false,\n      \"pollInterval\": \"6h\",\n      \"tlsVerify\": true,\n      \"certDir\": \"/home/user/certs\",\n      \"maxRetries\": 3,\n      \"retryDelay\": \"5m\",\n      \"onlySigned\": true,\n      \"content\": [\n        {\n          \"prefix\": \"/repo1/repo\",\n          \"tags\": {\n            \"regex\": \"4.*\",\n            \"semver\": true\n          }\n        },\n        {\n          \"prefix\": \"/repo2/repo\",\n          \"destination\": \"/repo2\",\n          \"stripPrefix\": true\n        },\n        {\n          \"prefix\": \"/repo3/repo\"\n        }\n      ]\n    }\n  }\n

The configuration in this example will result in the following behavior:

"},{"location":"articles/mirroring/#example-multiple-registries-with-on-demand-mirroring","title":"Example: Multiple registries with on-demand mirroring","text":"

The following is an example of sync configuration for mirroring multiple registries with on-demand mirroring.

{\n  \"distSpecVersion\": \"1.0.1\",\n  \"storage\": {\n    \"rootDirectory\": \"/tmp/zot\",\n    \"gc\": true\n  },\n  \"http\": {\n    \"address\": \"0.0.0.0\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  },\n  \"extensions\": {\n    \"sync\": {\n      \"enable\": true,\n      \"registries\": [\n        {\n          \"urls\": [\"https://k8s.gcr.io\"],\n          \"content\": [\n            {\n              \"prefix\": \"**\", \n              \"destination\": \"/k8s-images\"\n            }\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true\n        },\n        {\n          \"urls\": [\"https://docker.io/library\"],\n          \"content\": [\n            {\n              \"prefix\": \"**\", \n              \"destination\": \"/docker-images\"\n            }\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true\n        }\n      ]\n    }\n  }\n}\n

With this zot configuration, the sync behavior is as follows:

  1. This initial user request for content from the zot registry: skopeo copy --src-tls-verify=false docker://localhost:8080/docker-images/alpine <dest>causes zot to synchronize the content with the docker.io registry: docker.io/library/alpine:latestto the zot registry: localhost:8080/docker-images/alpine:latestbefore delivering the content to the requestor at <dest>.

  2. This initial user request for content from the zot registry: skopeo copy --src-tls-verify=false docker://localhost:8080/k8s-images/kube-proxy:v1.19.2 <dest>causes zot to synchronize the content with the gcr.io registry: k8s.gcr.io/kube-proxy:v1.19.2 to the zot registry: localhost:8080/k8s-images/kube-proxy:v1.19.2before delivering the content to the requestor at <dest>.

You can use this command: curl http://localhost:8080/v2/_catalogto display the local repositories:

  {\n    \"repositories\":[\n      \"docker-images/alpine\",\n      \"k8s-images/kube-proxy\"\n    ]\n  }\n
"},{"location":"articles/mirroring/#example-multiple-registries-with-mixed-mirroring-modes","title":"Example: Multiple registries with mixed mirroring modes","text":"

The following is an example of a zot configuration file for mirroring multiple upstream registries.

{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n    \"rootDirectory\": \"/tmp/zot\"\n  },\n  \"http\": {\n    \"address\": \"127.0.0.1\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  },\n  \"extensions\": {\n    \"sync\": {\n      \"enable\": true,\n      \"credentialsFile\": \"./examples/sync-auth-filepath.json\",\n      \"registries\": [\n        {\n          \"urls\": [\n            \"https://registry1:5000\"\n          ],\n          \"onDemand\": false,\n          \"pollInterval\": \"6h\",\n          \"tlsVerify\": true,\n          \"certDir\": \"/home/user/certs\",\n          \"maxRetries\": 3,\n          \"retryDelay\": \"5m\",\n          \"onlySigned\": true,\n          \"content\": [\n            {\n              \"prefix\": \"/repo1/repo\",\n              \"tags\": {\n                \"regex\": \"4.*\",\n                \"semver\": true\n              }\n            },\n            {\n              \"prefix\": \"/repo1/repo\",\n              \"destination\": \"/repo\",\n              \"stripPrefix\": true\n            },\n            {\n              \"prefix\": \"/repo2/repo\"\n            }\n          ]\n        },\n        {\n          \"urls\": [\n            \"https://registry2:5000\",\n            \"https://registry3:5000\"\n          ],\n          \"pollInterval\": \"12h\",\n          \"tlsVerify\": false,\n          \"onDemand\": false,\n          \"content\": [\n            {\n              \"prefix\": \"/repo2\",\n              \"tags\": {\n                \"semver\": true\n              }\n            }\n          ]\n        },\n        {\n          \"urls\": [\n            \"https://docker.io/library\"\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true,\n          \"maxRetries\": 6,\n          \"retryDelay\": \"5m\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/mirroring/#example-support-for-subpaths-in-local-storage","title":"Example: Support for subpaths in local storage","text":"

{\n  \"distSpecVersion\": \"1.0.1\",\n  \"storage\": {\n    \"subPaths\":{\n      \"/kube-proxy\":{\n        \"rootDirectory\": \"/tmp/kube-proxy\",\n        \"dedupe\": true,\n        \"gc\": true\n       }\n     },\n    \"rootDirectory\": \"/tmp/zot\",\n    \"gc\": true\n  },\n  \"http\": {\n    \"address\": \"0.0.0.0\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  },\n  \"extensions\": {\n    \"sync\": {\n      \"enable\": true,\n      \"registries\": [\n        {\n          \"urls\": [\"https://k8s.gcr.io\"],\n          \"content\": [\n            {\n              \"destination\": \"/kube-proxy\", \n              \"prefix\": \"**\"\n            }\n          ],\n          \"onDemand\": true,\n          \"tlsVerify\": true,\n          \"maxRetries\": 2,\n          \"retryDelay\": \"5m\"\n        }\n      ]\n    }\n  }\n}\n
With this zot configuration, the sync behavior is as follows:

You can use this command: curl http://localhost:8080/v2/_catalogto display the local repositories:

  {\n    \"repositories\":[\n      \"docker-images/alpine\",\n      \"k8s-images/kube-proxy\",\n      \"kube-proxy/kube-proxy\"\n    ]\n  }\n

In zot storage, the requested content is located here: /tmp/zot/kube-proxy/kube-proxy/kube-proxy/This subpath is created from the following path components:

"},{"location":"articles/monitoring/","title":"Monitoring the registry","text":"

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.

"},{"location":"articles/monitoring/#logging","title":"Logging","text":"

Logging for zot operations is configured with the log attribute in the configuration file, as shown in the following example.

\"log\":{\n  \"level\":\"debug\",\n  \"output\":\"/tmp/zot.log\",\n  \"audit\": \"/tmp/zot-audit.log\"\n}\n

The following table lists the configurable attributes.

Attribute Description

level

The minimum level for logged events. The levels are: panic, fatal, error, warn, info, debug, and trace.

output

The filesystem path for the log output file. The default is stdout.

audit

(Optional) If a filesystem path is specified for audit logging, an audit log is enabled and will be stored at the specified path.

"},{"location":"articles/monitoring/#metrics","title":"Metrics","text":"

The available methods for collecting metrics varies depending on whether your zot installation is a minimal (distribution-spec-only) image or a full image including extensions.

"},{"location":"articles/monitoring/#enabling-metrics-for-a-full-zot-image-with-extensions","title":"Enabling metrics for a full zot image with extensions","text":"

Add the metrics attribute under extensions in the configuration file to enable and configure metrics, as shown in the following example.

\"extensions\": {\n    \"metrics\": {\n        \"enable\": true,\n        \"prometheus\": {\n            \"path\": \"/metrics\"\n        }\n    }\n}\n

The following table lists the configurable attributes for metrics collection.

Attribute Description enable If this attribute is missing, metrics collection is enabled by default. Metrics collection can be disabled by setting this attribute to false. prometheus Attributes under prometheus contain configuration settings for the Prometheus node exporter. path The server path on which metrics will be exposed."},{"location":"articles/monitoring/#collecting-metrics-from-a-minimal-zot-image-using-a-node-exporter","title":"Collecting metrics from a minimal zot image using a node exporter","text":"

Although a minimal zot image does not contain a node exporter, it exposes internal metrics in a Prometheus format for collection by a separate node exporter tool such as zxp. The zot companion binary zxp is a node exporter that can be deployed with a minimal zot image in order to scrape metrics from the zot server.

Metrics are automatically enabled in the zot server upon first scrape from the node exporter and the metrics are automatically disabled when the node exporter has not performed any scraping for some period. No extra zot configuration is needed for this behavior.

You can download the zxp 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. For example, the binary for an Intel-based MacOS server is zxp-darwin-amd64. To configure the zxp example image, run this command:

zxp-darwin-amd64 config zxp-config-file

For convenience, you can rename the binary image file to simply zxp.

A sample Dockerfile for zxp is available at Dockerfile-zxp.

The configuration file of zxp contains connection details for the zot server from which it will scrape metrics. The following JSON structure is an example of the zxp-config-file contents:

{\n    \"Server\": {\n        \"protocol\": \"http\",\n        \"host\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"Exporter\": {\n        \"port\": \"8081\",\n        \"log\": {\n            \"level\": \"debug\"\n        }\n    }\n}\n

The zxp module does not have Prometheus integration.

The zxp module is not needed with a full zot image.

"},{"location":"articles/pprofiling/","title":"Performance Profiling in zot","text":"

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.

"},{"location":"articles/pprofiling/#what-data-is-available","title":"What data is available?","text":"

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/\n

If authentication is enabled, only an admin user can access this API.

"},{"location":"articles/pprofiling/#how-do-i-export-profile-data","title":"How do I export profile data?","text":"

To collect and export any available profile, use the following API command format:

/v2/_zot/pprof/<profile-type>[?<query-parameters>]\n

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\n

This command example creates an output data file named \"cpu.prof\".

"},{"location":"articles/pprofiling/#analyzing-the-cpu-usage-profile-using-go-tool-pprof","title":"Analyzing the CPU usage profile using go tool pprof","text":"

Go's pprof package provides a variety of presentation formats for analyzing runtime performance.

For detailed information, see the pprof documentation.

"},{"location":"articles/pprofiling/#generating-a-pprof-web-presentation","title":"Generating a pprof web presentation","text":"

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\nServing web UI on http://localhost:9090\n

The pprof web view offers several options for viewing and interpreting the collected performance data. Select VIEW to see the available options:

A Flame Graph can be very useful for analyzing CPU usage:

"},{"location":"articles/pprofiling/#generating-a-graphic-image","title":"Generating a graphic image","text":"

The pprof package can generate graphic representations of profile data in many formats. This example generates a PNG file representing the CPU usage in the \"cpu.prof\" file.

$ go tool pprof -png cpu.prof\nGenerating report in profile001.png\n
"},{"location":"articles/pprofiling/#opening-a-pprof-interactive-session","title":"Opening a pprof interactive session","text":"

This example opens an interactive session with pprof and executes the pprof top command, which displays the top ten modules by CPU usage during the profiling capture window.

$ go tool pprof cpu.prof\nType: cpu\nTime: Sep 26, 2023 at 10:01am (PDT)\nDuration: 30s, Total samples = 10ms (  0.1%)\nEntering interactive mode (type \"help\" for commands, \"o\" for options)\n(pprof) top\nShowing nodes accounting for 10ms, 100% of 10ms total\n    flat  flat%   sum%        cum   cum%\n    10ms   100%   100%       10ms   100%  runtime.pthread_cond_signal\n        0     0%   100%       10ms   100%  runtime.findRunnable\n        0     0%   100%       10ms   100%  runtime.mcall\n        0     0%   100%       10ms   100%  runtime.notewakeup\n        0     0%   100%       10ms   100%  runtime.park_m\n        0     0%   100%       10ms   100%  runtime.runSafePointFn\n        0     0%   100%       10ms   100%  runtime.schedule\n        0     0%   100%       10ms   100%  runtime.semawakeup\n(pprof)\n
"},{"location":"articles/pprofiling/#analyzing-the-trace-profile-using-go-tool-trace","title":"Analyzing the trace profile using go tool trace","text":"

You can collect trace data with the trace profile, as in this example:

  $ curl -s -v http://localhost:8080/v2/_zot/pprof/trace?seconds=30 > trace.prof\n

Using the go tool trace package, you can analyze the trace data captured in the \"trace.prof\" example file:

$ go tool trace trace.prof\n2023/09/21 16:58:58 Parsing trace...\n2023/09/21 16:58:58 Splitting trace...\n2023/09/21 16:58:58 Opening browser. Trace viewer is listening on http://127.0.0.1:62606\n

The go tool trace command installs and opens a local web server that provides a web interface for viewing and analyzing the trace data.

As an alternative, you can generate a pprof-like profile from the trace file using the following command:

$ go tool trace -pprof=[net|sync|syscall|sched] <filename>\n

For example:

$ go tool trace -pprof=net trace.prof\n
"},{"location":"articles/retention/","title":"Configuring zot Tag Retention Policies","text":"

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:

"},{"location":"articles/retention/#configuring-retention-policies","title":"Configuring retention policies","text":"

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.

"},{"location":"articles/retention/#configuration-example","title":"Configuration example","text":"

The following example is a simple retention configuration with two policies:

simple policy example

  \"storage\": {\n    \"retention\": {\n      \"dryRun\": false,\n      \"delay\": \"24h\",\n      \"policies\": [\n        {\n          \"repoNames\": [\"infra/*\", \"tmp/**\"],\n          \"deleteReferrers\": false,\n          \"deleteUntagged\": true,\n          \"KeepTags\": [{\n            \"patterns\": [\"v2.*\", \".*-prod\"],\n            \"mostRecentlyPushedCount\": 10,\n            \"mostRecentlyPulledCount\": 10,\n            \"pulledWithin\": \"720h\",\n            \"pushedWithin\": \"720h\"\n          }]  \n        },\n        {\n          \"keepTags\": [{\n            \"patterns\": [\".*\"]\n          }]\n        }\n      ]\n    }\n  }\n
"},{"location":"articles/retention/#configurable-attributes","title":"Configurable attributes","text":"

The following table lists the attributes available in the retention policy configuration.

Attribute Value Description dryRun boolean If true, will log a removal action without actually removing the image. Default is false. delay time Remove untagged and referrers only if they are older than the specified <time> hours, such as 24h. policies list A list of policies. repositories list A list of glob patterns to match repositories. deleteReferrers boolean If true, delete manifests with a missing Subject. Default is false. deleteUntagged boolean If true, delete untagged manifests. Default is true. keepTags list Criteria for tags to retain always. mostRecentlyPushedCount count Retains the top <count> most recently pushed tags. mostRecentlyPulledCount count Retains the top <count> most recently pulled tags. pushedWithin time Retains the tags pushed during the last <time> hours, such as 24h. pulledWithin time Retains the tags pulled during the last <time> hours, such as 24h. patterns regex See Notes."},{"location":"articles/retention/#configuration-notes","title":"Configuration notes","text":"

We recommend defining a default keepTags policy, such as the following example, as the last policy in the policy list. All tags that don't match the preceding policies will be retained by this default policy:

default policy example

  {\n    \"keepTags\": [{                               \n        \"patterns\": [\".*\"]\n      }]\n  }\n
"},{"location":"articles/retention/#complete-configuration-file-example","title":"Complete configuration file example","text":"

The following example shows the configuration of multiple retention policies in the context of a complete configuration file.

{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n    \"rootDirectory\": \"/tmp/zot\",\n    \"gc\": true,\n    \"gcDelay\": \"2h\",\n    \"gcInterval\": \"1h\",\n    \"retention\": {\n      \"dryRun\": false,\n      \"delay\": \"24h\",\n      \"policies\": [\n        {\n          \"repositories\": [\"infra/*\", \"prod/*\"],\n          \"deleteReferrers\": false,\n          \"keepTags\": [{\n            \"patterns\": [\"v2.*\", \".*-prod\"]\n          },\n          {\n            \"patterns\": [\"v3.*\", \".*-prod\"],\n            \"pulledWithin\": \"168h\"\n          }]\n        },\n        {\n          \"repositories\": [\"tmp/**\"],\n          \"deleteReferrers\": true,\n          \"deleteUntagged\": true,\n          \"keepTags\": [{\n            \"patterns\": [\"v1.*\"],\n            \"pulledWithin\": \"168h\",\n            \"pushedWithin\": \"168h\"\n          }]\n        },\n        {\n          \"repositories\": [\"**\"],\n          \"deleteReferrers\": true,\n          \"deleteUntagged\": true,\n          \"keepTags\": [{\n            \"mostRecentlyPushedCount\": 10,\n            \"mostRecentlyPulledCount\": 10,\n            \"pulledWithin\": \"720h\",\n            \"pushedWithin\": \"720h\"\n          }]\n        }\n      ]\n    },\n    \"subPaths\": {\n      \"/a\": {\n        \"rootDirectory\": \"/tmp/zot1\",\n        \"dedupe\": true,\n        \"retention\": {\n          \"policies\": [\n            {\n              \"repositories\": [\"infra/*\", \"prod/*\"],\n              \"deleteReferrers\": false\n            }\n          ]\n        }\n      }\n    }\n  },\n  \"http\": {\n    \"address\": \"127.0.0.1\",\n    \"port\": \"8080\"\n  },\n  \"log\": {\n    \"level\": \"debug\"\n  }\n}\n
"},{"location":"articles/security-posture/","title":"zot Security Posture","text":"

An overview of zot build-time and runtime security hardening features, including:

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.

"},{"location":"articles/security-posture/#build-time-hardening","title":"Build-time hardening","text":"

The following are the steps taken during build-time.

"},{"location":"articles/security-posture/#pie-build-mode","title":"PIE build-mode","text":"

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.

"},{"location":"articles/security-posture/#conditional-builds","title":"Conditional builds","text":"

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:

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.

"},{"location":"articles/security-posture/#cicd-pipeline","title":"CI/CD pipeline","text":"

zot CI/CD process attempts to align with the Open Source Security Foundation (OSSF) best practices guidelines to achieve high code quality.

"},{"location":"articles/security-posture/#code-reviews","title":"Code reviews","text":"

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.

"},{"location":"articles/security-posture/#cicd-checks","title":"CI/CD checks","text":"

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.

"},{"location":"articles/security-posture/#runtime-hardening","title":"Runtime hardening","text":"

The following steps can be taken to harden a zot deployment.

"},{"location":"articles/security-posture/#unprivileged-runtime-process","title":"Unprivileged runtime process","text":"

Running zot doesn\u2019t require root privileges. In fact, the recommended approach is to create a separate user/group ID for the zot process.

"},{"location":"articles/security-posture/#authentication","title":"Authentication","text":"

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.

"},{"location":"articles/security-posture/#access-control","title":"Access control","text":"

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.

"},{"location":"articles/security-posture/#vulnerability-scans","title":"Vulnerability scans","text":"

Apart from hardening the deployment itself, zot also supports security scanning of stored container images.

"},{"location":"articles/security-posture/#reporting-security-issues","title":"Reporting security issues","text":"

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.

"},{"location":"articles/storage/","title":"Storage Planning with zot","text":"

zot supports the following features to provide OCI standards-based, vendor-agnostic image storage:

"},{"location":"articles/storage/#storage-model","title":"Storage model","text":"

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.

"},{"location":"articles/storage/#hosting-an-oci-image-layout","title":"Hosting an OCI image layout","text":"

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.

"},{"location":"articles/storage/#storage-features","title":"Storage features","text":"

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.

"},{"location":"articles/storage/#commit","title":"Commit","text":"

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.

"},{"location":"articles/storage/#deduplication","title":"Deduplication","text":"

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.

"},{"location":"articles/storage/#garbage-collection","title":"Garbage collection","text":"

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.

"},{"location":"articles/storage/#scrub","title":"Scrub","text":"

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.

"},{"location":"articles/storage/#storage-backends","title":"Storage backends","text":"

The following types of storage backends are supported.

"},{"location":"articles/storage/#local-filesystem","title":"Local filesystem","text":"

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.

"},{"location":"articles/storage/#remote-filesystem","title":"Remote filesystem","text":"

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.

"},{"location":"articles/storage/#example-configuration-for-remote-s3-storage","title":"Example: configuration for remote (s3) storage","text":"Click here to view a sample zot configuration for remote storage. 
{\n    \"distSpecVersion\": \"1.0.1-dev\",\n    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true,\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"rootdirectory\": \"/zot\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false\n        },\n        \"cacheDriver\": {\n            \"name\": \"dynamodb\",\n            \"endpoint\": \"http://localhost:4566\",\n            \"region\": \"us-east-2\",\n            \"tableName\": \"MainTable\"\n        },\n    },\n    \"http\": {\n        \"address\": \"127.0.0.1\",\n        \"port\": \"8080\"\n    },\n    \"log\": {\n        \"level\": \"debug\"\n    }\n}\n
"},{"location":"articles/storage/#configuring-zot-storage","title":"Configuring zot storage","text":"

Filesystem storage is configured with the storage attribute in the zot configuration file, as shown in the following example.

    \"storage\":{\n        \"rootDirectory\":\"/tmp/zot\",\n        \"commit\": true,\n        \"dedupe\": true,\n        \"gc\": true,\n        \"gcDelay\": \"1h\",\n        \"gcInterval\": \"24h\"\n    }\n
"},{"location":"articles/storage/#configurable-attributes","title":"Configurable attributes","text":"

The following table lists the attributes of the storage configuration.

Attribute Description

rootDirectory

Location of the images stored in the server file system.

commit

For faster performance, data written by zot is retained in memory before being periodically committed to disk by the operating system. To eliminate this retention time and cause data to be written to disk immediately, set to true. This prevents data loss but reduces performance.

dedupe

If the server filesystem supports hard links, you can optimize storage space by enabling inline deduplication of layers and blobs that are shared among multiple container images. Deduplication is enabled by default. Set to false to disable deduplication.

gc

When an image is deleted, either by tag or by reference, orphaned blobs can lead to wasted storage. Garbage collection (gc) is enabled by default to reclaim this space. Set to false to disable garbage collection.

gcDelay

(Optional) If garbage collection is enabled, causes it to run once after the specified delay time. The default is 1 hour. Requires the gc attribute to be true.

gcInterval

(Optional) If garbage collection is enabled, causes periodic collection at the specified interval. Must be set based on use cases and user workloads. If no value is specified, there is no periodic collection. Requires the gc attribute to be true.

subpaths

You can store and serve images from multiple filesystems, each with their own repository paths and settings. The following example shows three subpaths.

\"storage\":{\n  \"subPaths\": {\n    \"/a\": {\n      \"rootDirectory\": \"/tmp/zot1\",\n      \"dedupe\": true,\n      \"gc\": true\n    },\n    \"/b\": {\n      \"rootDirectory\": \"/tmp/zot2\",\n      \"dedupe\": true\n    },\n    \"/c\": {\n      \"rootDirectory\": \"/tmp/zot3\",\n      \"dedupe\": false\n    }\n  }\n}

storageDriver

(Remote storage only) Contains settings for a remote storage service. See Configuring remote storage with s3 for details.

cacheDriver

Specifies which database is used to store duplicate blobs when deduplication is enabled. See Cache drivers for details.

"},{"location":"articles/storage/#configuring-garbage-collection","title":"Configuring garbage collection","text":"

The zot configuration model allows for enabling and disabling garbage collection (gc) and specifying a periodic interval (gcInterval) for collection.

gc gcInterval Result false n/a GC disabled omitted n/a GC enabled with 1 hour interval (default) true omitted GC enabled with 1 hour interval true 0 GC runs only once true >0 GC enabled with specified interval

The configuration model also allows the configuration of a tunable delay (gcDelay), which can be set depending on client network speeds and the size of blobs. The gcDelay attribute causes collection to run once after the specified delay time. This attribute has a default value of one hour (1h).

"},{"location":"articles/storage/#configuring-remote-storage-with-s3","title":"Configuring remote storage with s3","text":"

To configure an Amazon Simple Storage Service (s3) bucket for zot, use the storageDriver attribute in the zot configuration file, as shown in the following example:

    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false,\n            \"accesskey\": \"<YOUR_ACCESS_KEY_ID>\",\n            \"secretkey\": \"<YOUR_SECRET_ACCESS_KEY>\"\n        }\n    }\n

For descriptions of the configurable attributes for storageDriver, see the s3 storage driver project in GitHub.

"},{"location":"articles/storage/#s3-credentials","title":"s3 Credentials","text":"

In the s3 configuration file example, the s3 credentials were configured with the attributes accesskey and secretkey. As an alternative, you can omit these attributes from the configuration file and you can configure them using environment variables or a credential file.

For more details about specifying s3 credentials, see the AWS documentation.

"},{"location":"articles/storage/#s3-permissions-scopes","title":"S3 permissions scopes","text":"

The following AWS policy is required by zot for push and pull.

Replace S3_BUCKET_NAME with the name of your s3 bucket.

[AWS CONFIGURATION]\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"s3:ListBucket\",\n        \"s3:GetBucketLocation\",\n        \"s3:ListBucketMultipartUploads\"\n      ],\n      \"Resource\": \"arn:aws:s3:::<S3_BUCKET_NAME>\"\n    },\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"s3:PutObject\",\n        \"s3:GetObject\",\n        \"s3:DeleteObject\",\n        \"s3:ListMultipartUploadParts\",\n        \"s3:AbortMultipartUpload\"\n      ],\n      \"Resource\": \"arn:aws:s3:::<S3_BUCKET_NAME>/*\"\n    }\n  ]\n}\n

For more details about configuring AWS policies, see the AWS documentation.

"},{"location":"articles/storage/#cache-drivers","title":"Cache drivers","text":"

A cache driver is used to store duplicate blobs when dedupe is enabled. zot supports database caching using BoltDB as the cache driver for local filesystems and DynamoDB for remote filesystems.

"},{"location":"articles/storage/#boltdb","title":"BoltDB","text":"

If you don't specify a cache driver, zot defaults to BoltDB. BoltDB is stored either in zot's root directory or in the subpath root directory.

    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true\n    }\n

In this example, BoltDB can be found at /tmp/zot/cache.db.

"},{"location":"articles/storage/#dynamodb","title":"DynamoDB","text":"

To use DynamoDB as the cache driver, the following storage configuration must be present:

    \"storage\": {\n        \"rootDirectory\": \"/tmp/zot\",\n        \"dedupe\": true,\n        \"remoteCache\": true,\n        \"cacheDriver\": {\n            \"name\": \"dynamodb\",                  // driver name\n            \"endpoint\": \"http://localhost:4566\", // aws endpoint\n            \"region\": \"us-east-2\"                // aws region\n            \"cacheTablename\": \"ZotBlobTable\"     // table to store deduped blobs\n        }\n    },\n

The AWS GO SDK loads additional configuration and credentials values from your environment variables, shared credentials, and shared configuration files.

If the search extension is enabled, additional parameters are required:

        \"cacheDriver\": {\n            \"name\": \"dynamodb\",\n            \"endpoint\": \"http://localhost:4566\",\n            \"region\": \"us-east-2\",\n            \"cacheTablename\": \"ZotBlobTable\",\n            // used by search extensions\n            \"repoMetaTablename\": \"ZotRepoMetadataTable\",\n            \"manifestDataTablename\": \"ZotManifestDataTable\",\n            \"versionTablename\": \"ZotVersion\"\n        }\n
"},{"location":"articles/storage/#dynamodb-permission-scopes","title":"DynamoDB permission scopes","text":"

The following AWS policy is required by zot for caching blobs.

Replace DYNAMODB_TABLE with the name of your table, which should be the value of cacheTablename in the zot configuration.

In this case, the AWS Resource value would be arn:aws:dynamodb:*:*:table/ZotBlobTable

[AWS CONFIGURATION]\n{\n  \"Version\": \"2012-10-17\",\n  \"Statement\": [\n    {\n      \"Effect\": \"Allow\",\n      \"Action\": [\n        \"dynamodb:CreateTable\",\n        \"dynamodb:GetItem\",\n        \"dynamodb:UpdateItem\",\n        \"dynamodb:DeleteItem\"\n      ],\n      \"Resource\": \"arn:aws:dynamodb:*:*:table/<DYNAMODB_TABLE>\"\n    }\n  ]\n}\n

For more details about configuring AWS DynamoDB, see the AWS documentation.

"},{"location":"articles/storage/#remote-storage-subpaths","title":"Remote storage subpaths","text":"

As in the case with local filesystem storage, you can use multiple remote storage locations using the subpath attribute, as in the following example.

\"subPaths\": {\n    \"/a\": {\n        \"rootDirectory\": \"/zot-a\",\n        \"storageDriver\": {\n            \"name\": \"s3\",\n            \"region\": \"us-east-2\",\n            \"bucket\": \"zot-storage\",\n            \"secure\": true,\n            \"skipverify\": false\n        }\n    },\n    \"/b\": {\n       .\n       .\n       .\n    }\n}\n

The subPaths feature ties together several separate storage filesystems and backends behind the same HTTP API interface. In the example above, both repository paths \"/a\" and \"/b\" are exposed to clients. Content on these two paths can be hosted completely separately by different storage services, locations, or filesystems, with no difference to the user interface and no perceptible difference to the user experience. This is useful if one wants to serve existing OCI images from different backends or if storage can be expanded only by using different backing stores.

zot also supports different storage drivers for each subpath.

"},{"location":"articles/verifying-signatures/","title":"Verifying image signatures","text":"

Images stored in zot can be signed with a digital signature to verify the source and integrity of the image. The digital signature can be verified by zot using public keys or certificates uploaded by the user.

To verify image signatures, zot supports the following tools:

"},{"location":"articles/verifying-signatures/#enabling-image-signature-verification","title":"Enabling image signature verification","text":"

To enable image signature verification, add the trust attribute under extensions in the zot configuration file and enable one or more verification tools, as shown in the following example:

\"extensions\": {\n  \"trust\": {\n    \"enable\": true,\n    \"cosign\": true,\n    \"notation\": true\n  }\n}\n

The following table lists the configurable attributes of the trust extension.

Attribute Description enable If this attribute is missing, signature verification is disabled by default. Signature verification is enabled by including this attribute and setting it to true. You must also enable at least one of the verification tools. cosign Set to true to enable signature verification using the cosign tool. notation Set to true to enable signature verification using the notation tool."},{"location":"articles/verifying-signatures/#what-is-needed-for-verifying-signatures","title":"What is needed for verifying signatures","text":"

To verify the validity of a signature for an image, zot makes use of two types of files:

Upload these files using an extension of the zot API, as shown in the following examples:

"},{"location":"articles/verifying-signatures/#where-needed-files-are-stored","title":"Where needed files are stored","text":"

Uploaded public keys and certificates are stored in the local filesystem, in specific directories named _cosign and _notation under $rootDir, or in the Secrets Manager.

"},{"location":"articles/verifying-signatures/#how-signature-verification-works","title":"How signature verification works","text":"

Based on the uploaded files and the information about images stored in zot's database, signature verification is performed for all signed images. The verification result for each signed image is stored in the database and is visible from GraphQL. The stored information about a signature includes:

"},{"location":"articles/verifying-signatures/#example-of-graphql-output","title":"Example of GraphQL output","text":"

Sample request

{\n  Image(image: \"busybox:latest\") {\n    Digest\n    IsSigned\n    Tag\n    SignatureInfo {\n        Tool\n        IsTrusted\n        Author\n    }\n  }\n}\n

Sample response

{\n  \"data\": {\n    \"Image\": {\n      \"Digest\":\"sha256:6c19fba547b87bde9a45df2f8563e0c61826d098dd30192a2c8b86da1e1a6360\",\n      \"IsSigned\": true,\n      \"Tag\": \"latest\",\n      \"SignatureInfo\":[\n        {\n          \"Tool\":\"cosign\",\n          \"IsTrusted\":false,\n          \"Author\":\"\"\n        },\n        {\n          \"Tool\":\"cosign\",\n          \"IsTrusted\":false,\n          \"Author\":\"\"\n        },\n        {\n          \"Tool\":\"cosign\",\n          \"IsTrusted\": true,\n          \"Author\":\"-----BEGIN PUBLIC KEY-----\\nMFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAE9pN+/hGcFlh4YYaNvZxNvuh8Qyhl\\npURz77qScOHe3DqdmiWiuqIseyhEdjEDwpL6fHRwu3a2Nd9wbKqm0la76w==\\n-----END PUBLIC KEY-----\\n\"\n        },\n        {\n          \"Tool\":\"notation\",\n          \"IsTrusted\": false,\n          \"Author\":\"CN=v4-test,O=Notary,L=Seattle,ST=WA,C=US\"\n        },\n        {\n          \"Tool\":\"notation\",\n          \"IsTrusted\": true,\n          \"Author\":\"CN=multipleSig,O=Notary,L=Seattle,ST=WA,C=US\"\n        }\n      ]\n    }\n  }\n}\n
"},{"location":"articles/workflow/","title":"Software Provenance Workflow Using OCI Artifacts","text":"

This article demonstrates an end-to-end workflow for installing a zot registry, then pushing and signing an image and a related artifact, such as an SBOM.

"},{"location":"articles/workflow/#workflow","title":"Workflow","text":"

The following sections describe the step-by-step workflow. To view the steps combined into a single script, see Reference: Full workflow script.

For the workflow examples, the zot registry is assumed to be installed and running at localhost:8080.

"},{"location":"articles/workflow/#step-1-download-the-client-tools","title":"Step 1: Download the client tools","text":"

This workflow uses the regctl registry client and the cosign image signing tool. As a first step, we download binaries for these tools in a tools directory. 

TEST_TMPDIR=$(mktemp -d \"${PWD}/artifact-test-${1:+-$1}.XXXXXX\")\n\nTOOLSDIR=$(pwd)/hack/tools\nmkdir -p ${TOOLSDIR}/bin\n\nREGCLIENT=${TOOLSDIR}/bin/regctl\nREGCLIENT_VERSION=v0.5.1\ncurl -Lo ${REGCLIENT} https://github.com/regclient/regclient/releases/download/${REGCLIENT_VERSION}/regctl-linux-amd64\nchmod +x ${REGCLIENT}\n\nCOSIGN=${TOOLSDIR}/bin/cosign\nCOSIGN_VERSION=2.1.1\ncurl -Lo ${COSIGN} https://github.com/sigstore/cosign/releases/download/v${COSIGN_VERSION}/cosign-linux-amd64 \nchmod +x ${COSIGN}\n
"},{"location":"articles/workflow/#step-2-deploy-an-oci-registry-with-referrers-support-zot","title":"Step 2: Deploy an OCI registry with referrers support (zot)","text":"

Next, we execute the following tasks to deploy an OCI registry:

ZOT=${TOOLSDIR}/bin/zot\nZOT_VERSION=2.0.0-rc6\ncurl -Lo ${ZOT} https://github.com/project-zot/zot/releases/download/v${ZOT_VERSION}/zot-linux-amd64-minimal\nchmod +x ${ZOT}\n\nZOT_HOST=localhost\nZOT_PORT=8080\n\n# function to start zot and test for readiness\nfunction zot_setup() {\ncat > $TEST_TMPDIR/zot-config.json << EOF\n{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n      \"rootDirectory\": \"$TEST_TMPDIR/zot\"\n  },\n  \"http\": {\n      \"address\": \"$ZOT_HOST\",\n      \"port\": \"$ZOT_PORT\"\n  },\n  \"log\": {\n      \"level\": \"error\"\n  }\n}\nEOF\n  # start zot as a background task\n  ${ZOT} serve $TEST_TMPDIR/zot-config.json &\n  pid=$!\n        # wait until service is up\n  count=5\n  up=0\n  while [[ $count -gt 0 ]]; do\n    if [ ! -d /proc/$pid ]; then\n      echo \"zot failed to start or died\"\n      exit 1\n    fi\n    up=1\n    curl -f http://$ZOT_HOST:$ZOT_PORT/v2/ || up=0\n    if [ $up -eq 1 ]; then break; fi\n    sleep 1\n    count=$((count - 1))\n  done\n  if [ $up -eq 0 ]; then\n    echo \"Timed out waiting for zot\"\n    exit 1\n  fi\n  # setup an OCI client\n  ${REGCLIENT} registry set --tls=disabled $ZOT_HOST:$ZOT_PORT\n}\n\n# call the function to start zot\nzot_setup\n
"},{"location":"articles/workflow/#step-3-copy-an-image-to-the-oci-registry","title":"Step 3: Copy an image to the OCI registry","text":"

This step copies a busybox container image into the registry.

skopeo copy --format=oci --dest-tls-verify=false docker://busybox:latest docker://${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n
"},{"location":"articles/workflow/#step-4-copy-a-related-artifact-to-the-oci-registry","title":"Step 4: Copy a related artifact to the OCI registry","text":"

This step creates a simple artifact file and associates it with the busybox image in the registry.

cat > ${TEST_TMPDIR}/artifact.yaml << EOF\nkey:\n  val: artifact\nEOF\n${REGCLIENT} artifact put --artifact-type application/yaml -f ${TEST_TMPDIR}/artifact.yaml --subject ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n

The --subject command flag associates the artifact file with the specified subject (in this case, the busybox image). If no subject is specified by the command, the artifact is considered independent and not associated with any existing image.

"},{"location":"articles/workflow/#step-5-display-the-artifact-tree","title":"Step 5: Display the artifact tree","text":"

This step prints the artifact tree of the busybox image. The tree includes the artifact yaml file, showing the association of the artifact to the busybox image.

These script commands define REF0 as the artifact that was uploaded referring to the first container image. 

REF0=$(${REGCLIENT} artifact tree --format '{{jsonPretty .}}' localhost:8080/busybox:latest | jq .referrer[0].reference.Digest)\nREF0=\"${REF0:1:-1}\"\n

The following example shows the command and its output:

$ regctl artifact tree localhost:8080/busybox:latest\n\nRef: localhost:8080/busybox:latest  \nDigest: sha256:9172c5f692f2c65e4f773448503b21dba2de6454bd159905c4bf6d83176e4ea3\nReferrers:  \n   - sha256:9c0655368b10ca4b2ffe39e4dd261fb89df25a46ae92d6eb4e6e1792a451883e: application/yaml\n

The displayed artifact tree shows that the original image (localhost:8080/busybox:latest) has one direct referrer (sha256:9c06...883e: application/yaml), the artifact yaml file.

"},{"location":"articles/workflow/#step-6-sign-the-image-and-artifact","title":"Step 6: Sign the image and artifact","text":"

This step creates a key pair for cosign in a separate directory, then uses cosign to sign both the image and the artifact file. Both signatures, like the artifact file itself, are associated with the busybox image. 

# create a key pair in a different directory\npushd ${TEST_TMPDIR}\nCOSIGN_PASSWORD= ${COSIGN} generate-key-pair\npopd\n# sign the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n# sign the artifact referring to the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox@${REF0}\n
"},{"location":"articles/workflow/#step-7-display-the-artifact-tree","title":"Step 7: Display the artifact tree","text":"

This step again prints the artifact tree, which should now show the artifact and the two signatures, all associated to the busybox image.

${REGCLIENT} artifact tree localhost:8080/busybox:latest\n

The following example shows the command and its output:

$ regctl artifact tree localhost:8080/busybox:latest\n\nRef: localhost:8080/busybox:latest\nDigest: sha256:9172c5f692f2c65e4f773448503b21dba2de6454bd159905c4bf6d83176e4ea3\nReferrers:\n  - sha256:9c0655368b10ca4b2ffe39e4dd261fb89df25a46ae92d6eb4e6e1792a451883e: application/yaml\n    Referrers:\n      - sha256:06792b209137486442a2b804b2225c0014e3e238d363cdbea088bbd73207fb34: application/vnd.dev.cosign.artifact.sig.v1+json\n  - sha256:995b6a78bf04a7a9676dac76b4598ccb645c17e30b02f294de9fdfa2f28eb7b2: application/vnd.dev.cosign.artifact.sig.v1+json\n

The displayed artifact tree shows that the original image now has two direct referrers \u2014 the artifact and the cosign signature of the original image. In addition, there is a second-level referrer \u2014 the cosign signature of the artifact, which is a referrer of the artifact file.

"},{"location":"articles/workflow/#step-8-end-of-demonstration","title":"Step 8: End of demonstration","text":"

This step halts the zot registry server, ending the workflow demonstration.

# function for stopping zot after demonstration\nfunction zot_teardown() {\n  killall zot\n}\n\n# stop zot\nzot_teardown\n
"},{"location":"articles/workflow/#reference-full-workflow-script","title":"Reference: Full workflow script","text":"

Expand the text box below to view the entire workflow as a single executable shell script.

To copy the script to the clipboard, click the copy icon that appears in the upper right corner of the expanded text box.

Click here to view the all-in-one script 
#!/bin/bash -xe\n\nTEST_TMPDIR=$(mktemp -d \"${PWD}/artifact-test-${1:+-$1}.XXXXXX\")\n\nTOOLSDIR=$(pwd)/hack/tools\nmkdir -p ${TOOLSDIR}/bin\n\nREGCLIENT=${TOOLSDIR}/bin/regctl\nREGCLIENT_VERSION=v0.5.1\ncurl -Lo ${REGCLIENT} https://github.com/regclient/regclient/releases/download/${REGCLIENT_VERSION}/regctl-linux-amd64\nchmod +x ${REGCLIENT}\n\nCOSIGN=${TOOLSDIR}/bin/cosign\nCOSIGN_VERSION=2.1.1\ncurl -Lo ${COSIGN} https://github.com/sigstore/cosign/releases/download/v${COSIGN_VERSION}/cosign-linux-amd64 \nchmod +x ${COSIGN}\n\n# OCI registry\nZOT=${TOOLSDIR}/bin/zot\nZOT_VERSION=2.0.0-rc6\ncurl -Lo ${ZOT} https://github.com/project-zot/zot/releases/download/v${ZOT_VERSION}/zot-linux-amd64-minimal\nchmod +x ${ZOT}\n\nZOT_HOST=localhost\nZOT_PORT=8080\n\nfunction zot_setup() {\ncat > $TEST_TMPDIR/zot-config.json << EOF\n{\n  \"distSpecVersion\": \"1.1.0-dev\",\n  \"storage\": {\n      \"rootDirectory\": \"$TEST_TMPDIR/zot\"\n  },\n  \"http\": {\n      \"address\": \"$ZOT_HOST\",\n      \"port\": \"$ZOT_PORT\"\n  },\n  \"log\": {\n      \"level\": \"error\"\n  }\n}\nEOF\n# start as a background task\n${ZOT} serve $TEST_TMPDIR/zot-config.json &\npid=$!\n        # wait until service is up\ncount=5\nup=0\nwhile [[ $count -gt 0 ]]; do\n    if [ ! -d /proc/$pid ]; then\n    echo \"zot failed to start or died\"\n    exit 1\n    fi\n    up=1\n    curl -f http://$ZOT_HOST:$ZOT_PORT/v2/ || up=0\n    if [ $up -eq 1 ]; then break; fi\n    sleep 1\n    count=$((count - 1))\ndone\nif [ $up -eq 0 ]; then\n    echo \"Timed out waiting for zot\"\n    exit 1\nfi\n# setup a OCI client\n${REGCLIENT} registry set --tls=disabled $ZOT_HOST:$ZOT_PORT\n}\n\n# function for stopping zot after demonstration\nfunction zot_teardown() {\nkillall zot\n}\n\n# call the function to start zot\nzot_setup\n\n# copy an image\nskopeo copy --format=oci --dest-tls-verify=false docker://busybox:latest docker://${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n\n# copy an artifact referring to the above image\ncat > ${TEST_TMPDIR}/artifact.yaml << EOF\nkey:\nval: artifact\nEOF\n${REGCLIENT} artifact put --artifact-type application/yaml -f ${TEST_TMPDIR}/artifact.yaml --subject ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\nREF0=$(${REGCLIENT} artifact tree --format '{{jsonPretty .}}' localhost:8080/busybox:latest | jq .referrer[0].reference.Digest)\nREF0=\"${REF0:1:-1}\"\n\n# create a key pair in a different directory\npushd ${TEST_TMPDIR}\nCOSIGN_PASSWORD= ${COSIGN} generate-key-pair\npopd\n# sign the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox:latest\n# sign the artifact referring to the image\nCOSIGN_PASSWORD= COSIGN_OCI_EXPERIMENTAL=1 COSIGN_EXPERIMENTAL=1 ${COSIGN} sign -y --key ${TEST_TMPDIR}/cosign.key --registry-referrers-mode=oci-1-1 ${ZOT_HOST}:${ZOT_PORT}/busybox@${REF0}\n\n# list the reference tree\n${REGCLIENT} artifact tree localhost:8080/busybox:latest\n\n# stop zot\nzot_teardown\n
"},{"location":"developer-guide/api-reference/","title":"zot API Command Reference","text":"

This article describes the zot REST API commands, parameters, and responses.

The information presented here is adapted from the interactive OpenAPI (formerly swagger) JSON file in the zot Github project.

For instructions and examples of how to use the zot API, see Using the zot API.

"},{"location":"developer-guide/api-reference/#zotauthapikey","title":"/zot/auth/apikey","text":""},{"location":"developer-guide/api-reference/#delete-zotauthapikey","title":"DELETE /zot/auth/apikey","text":"

Revokes one current user API key based on given key ID

Parameters

Name In Type Required Description id query string true api token id (UUID)

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request string 401 Unauthorized unauthorized string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-zotauthapikey","title":"GET /zot/auth/apikey","text":"

Get list of all API keys for a logged in user

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 401 Unauthorized unauthorized string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#post-zotauthapikey","title":"POST /zot/auth/apikey","text":"

Can create an api key for a logged in user, based on the provided label and scopes.

Body parameter

{\n  \"expirationDate\": \"string\",\n  \"label\": \"string\",\n  \"scopes\": [\n    \"string\"\n  ]\n}\n

Parameters

Name In Type Required Description body body api.APIKeyPayload true api token id (UUID)

Example responses

201 Response

\"string\"\n

Responses

Status Meaning Description Schema 201 Created created string 400 Bad Request bad request string 401 Unauthorized unauthorized string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#zotauthlogout","title":"/zot/auth/logout","text":""},{"location":"developer-guide/api-reference/#post-zotauthlogout","title":"POST /zot/auth/logout","text":"

Logout by removing current session

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok\". string 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#orasartifactsv1namemanifestsdigestreferrers","title":"/oras/artifacts/v1/{name}/manifests/{digest}/referrers","text":""},{"location":"developer-guide/api-reference/#get-orasartifactsv1namemanifestsdigestreferrers","title":"GET /oras/artifacts/v1/{name}/manifests/{digest}/referrers","text":"

Get references for an image given a digest and artifact type

Parameters

Name In Type Required Description name path string true repository name digest path string true image digest artifactType query string true artifact type

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2","title":"/v2/","text":""},{"location":"developer-guide/api-reference/#get-v2","title":"GET /v2/","text":"

Check if this API version is supported

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_catalog","title":"/v2/_catalog","text":""},{"location":"developer-guide/api-reference/#get-v2_catalog","title":"GET /v2/_catalog","text":"

List all image repositories

Example responses

200 Response

{\n  \"repositories\": [\n    \"string\"\n  ]\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.RepositoryList 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_ociextdiscover","title":"/v2/_oci/ext/discover","text":""},{"location":"developer-guide/api-reference/#get-v2_ociextdiscover","title":"GET /v2/_oci/ext/discover","text":"

List all extensions present on registry

Example responses

200 Response

{\n  \"extensions\": [\n    {\n      \"description\": \"string\",\n      \"endpoints\": [\n        \"string\"\n      ],\n      \"name\": \"string\",\n      \"url\": \"string\"\n    }\n  ]\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ExtensionList

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextcosign","title":"/v2/_zot/ext/cosign","text":""},{"location":"developer-guide/api-reference/#post-v2_zotextcosign","title":"POST /v2/_zot/ext/cosign","text":"

Upload cosign public keys for verifying signatures

Body parameter

string\n

Parameters

Name In Type Required Description body body string true Public key content

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request\". string 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextmgmt","title":"/v2/_zot/ext/mgmt","text":""},{"location":"developer-guide/api-reference/#get-v2_zotextmgmt","title":"GET /v2/_zot/ext/mgmt","text":"

Get current server configuration

Parameters

Name In Type Required Description resource query string false specify resource

Enumerated Values

Parameter Value resource config

Example responses

200 Response

{\n  \"binaryType\": \"string\",\n  \"distSpecVersion\": \"string\",\n  \"http\": {\n    \"auth\": {\n      \"bearer\": {\n        \"realm\": \"string\",\n        \"service\": \"string\"\n      },\n      \"htpasswd\": {\n        \"path\": \"string\"\n      },\n      \"ldap\": {\n        \"address\": \"string\"\n      },\n      \"openid\": {\n        \"providers\": {\n          \"property1\": {\n            \"name\": \"string\"\n          },\n          \"property2\": {\n            \"name\": \"string\"\n          }\n        }\n      }\n    }\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK extensions.StrippedConfig 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextnotation","title":"/v2/_zot/ext/notation","text":""},{"location":"developer-guide/api-reference/#post-v2_zotextnotation","title":"POST /v2/_zot/ext/notation","text":"

Upload notation certificates for verifying signatures

Body parameter

string\n

Parameters

Name In Type Required Description truststoreType query string false truststore type body body string true Certificate content

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request\". string 500 Internal Server Error internal server error\". string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2_zotextuserprefs","title":"/v2/_zot/ext/userprefs","text":""},{"location":"developer-guide/api-reference/#put-v2_zotextuserprefs","title":"PUT /v2/_zot/ext/userprefs","text":"

Add bookmarks/stars info

Parameters

Name In Type Required Description action query string true specify action repo query string true repository name

Enumerated Values

Parameter Value action toggleBookmark action toggleStar

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 400 Bad Request bad request\". string 403 Forbidden forbidden string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nameblobsdigest","title":"/v2/{name}/blobs/{digest}","text":""},{"location":"developer-guide/api-reference/#delete-v2nameblobsdigest","title":"DELETE /v2/{name}/blobs/{digest}","text":"

Delete an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true blob/layer digest

Example responses

202 Response

\"string\"\n

Responses

Status Meaning Description Schema 202 Accepted accepted string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-v2nameblobsdigest","title":"GET /v2/{name}/blobs/{digest}","text":"

Get an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true blob/layer digest

Example responses

200 Response

Responses

Status Meaning Description Schema 200 OK OK api.ImageManifest

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#head-v2nameblobsdigest","title":"HEAD /v2/{name}/blobs/{digest}","text":"

Check an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true blob/layer digest

Example responses

200 Response

{\n  \"annotations\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"artifactType\": \"string\",\n  \"config\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  },\n  \"layers\": [\n    {\n      \"annotations\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"artifactType\": \"string\",\n      \"data\": [\n        0\n      ],\n      \"digest\": \"string\",\n      \"mediaType\": \"string\",\n      \"platform\": {\n        \"architecture\": \"string\",\n        \"os\": \"string\",\n        \"os.features\": [\n          \"string\"\n        ],\n        \"os.version\": \"string\",\n        \"variant\": \"string\"\n      },\n      \"size\": 0,\n      \"urls\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"mediaType\": \"string\",\n  \"schemaVersion\": 0,\n  \"subject\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ImageManifest

Response Headers

Status Header Type Format Description 200 constants.DistContentDigestKey object none

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nameblobsuploads","title":"/v2/{name}/blobs/uploads","text":""},{"location":"developer-guide/api-reference/#post-v2nameblobsuploads","title":"POST /v2/{name}/blobs/uploads","text":"

Create a new image blob/layer upload

Parameters

Name In Type Required Description name path string true repository name

Example responses

202 Response

\"string\"\n

Responses

Status Meaning Description Schema 202 Accepted accepted string 401 Unauthorized unauthorized string 404 Not Found not found string 500 Internal Server Error internal server error string

Response Headers

Status Header Type Format Description 202 Location string /v2/{name}/blobs/uploads/{session_id} 202 Range string 0-0

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nameblobsuploadssession_id","title":"/v2/{name}/blobs/uploads/{session_id}","text":""},{"location":"developer-guide/api-reference/#delete-v2nameblobsuploadssession_id","title":"DELETE /v2/{name}/blobs/uploads/{session_id}","text":"

Delete an image's blob/layer given a digest

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-v2nameblobsuploadssession_id","title":"GET /v2/{name}/blobs/uploads/{session_id}","text":"

*Get an image's blob/layer upload given a session_id

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id

Example responses

204 Response

\"string\"\n

Responses

Status Meaning Description Schema 204 No Content no content string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#patch-v2nameblobsuploadssession_id","title":"PATCH /v2/{name}/blobs/uploads/{session_id}","text":"

Resume an image's blob/layer upload given an session_id

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id

Example responses

202 Response

\"string\"\n

Responses

Status Meaning Description Schema 202 Accepted accepted string 400 Bad Request bad request string 404 Not Found not found string 416 Range Not Satisfiable range not satisfiable string 500 Internal Server Error internal server error string

Response Headers

Status Header Type Format Description 202 Location string /v2/{name}/blobs/uploads/{session_id} 202 Range string 0-128

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#put-v2nameblobsuploadssession_id","title":"PUT /v2/{name}/blobs/uploads/{session_id}","text":"

Update and finish an image's blob/layer upload given a digest

Parameters

Name In Type Required Description name path string true repository name session_id path string true upload session_id digest query string true blob/layer digest

Example responses

201 Response

\"string\"\n

Responses

Status Meaning Description Schema 201 Created created string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2namemanifestsreference","title":"/v2/{name}/manifests/{reference}","text":""},{"location":"developer-guide/api-reference/#delete-v2namemanifestsreference","title":"DELETE /v2/{name}/manifests/{reference}","text":"

Delete an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#get-v2namemanifestsreference","title":"GET /v2/{name}/manifests/{reference}","text":"

Get an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

200 Response

{\n  \"annotations\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"artifactType\": \"string\",\n  \"config\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  },\n  \"layers\": [\n    {\n      \"annotations\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"artifactType\": \"string\",\n      \"data\": [\n        0\n      ],\n      \"digest\": \"string\",\n      \"mediaType\": \"string\",\n      \"platform\": {\n        \"architecture\": \"string\",\n        \"os\": \"string\",\n        \"os.features\": [\n          \"string\"\n        ],\n        \"os.version\": \"string\",\n        \"variant\": \"string\"\n      },\n      \"size\": 0,\n      \"urls\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"mediaType\": \"string\",\n  \"schemaVersion\": 0,\n  \"subject\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size20\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ImageManifest 404 Not Found not found string 500 Internal Server Error internal server error string

Response Headers

Status Header Type Format Description 200 constants.DistContentDigestKey object none

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#head-v2namemanifestsreference","title":"HEAD /v2/{name}/manifests/{reference}","text":"

Check an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

200 Response

\"string\"\n

Responses

Status Meaning Description Schema 200 OK ok string 404 Not Found not found string 500 Internal Server Error internal server error\". string

Response Headers

Status Header Type Format Description 200 constants.DistContentDigestKey object none

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#put-v2namemanifestsreference","title":"PUT /v2/{name}/manifests/{reference}","text":"

Update an image's manifest given a reference or a digest

Parameters

Name In Type Required Description name path string true repository name reference path string true image reference or digest

Example responses

201 Response

\"string\"\n

Responses

Status Meaning Description Schema 201 Created created string 400 Bad Request bad request string 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2namereferrersdigest","title":"/v2/{name}/referrers/{digest}","text":""},{"location":"developer-guide/api-reference/#get-v2namereferrersdigest","title":"GET /v2/{name}/referrers/{digest}","text":"

Get referrers given a digest

Parameters

Name In Type Required Description name path string true repository name digest path string true digest artifactType query string false artifact type

Example responses

200 Response

{\n  \"annotations\": {\n    \"property1\": \"string\",\n    \"property2\": \"string\"\n  },\n  \"artifactType\": \"string\",\n  \"manifests\": [\n    {\n      \"annotations\": {\n        \"property1\": \"string\",\n        \"property2\": \"string\"\n      },\n      \"artifactType\": \"string\",\n      \"data\": [\n        0\n      ],\n      \"digest\": \"string\",\n      \"mediaType\": \"string\",\n      \"platform\": {\n        \"architecture\": \"string\",\n        \"os\": \"string\",\n        \"os.features\": [\n          \"string\"\n        ],\n        \"os.version\": \"string\",\n        \"variant\": \"string\"\n      },\n      \"size\": 0,\n      \"urls\": [\n        \"string\"\n      ]\n    }\n  ],\n  \"mediaType\": \"string\",\n  \"schemaVersion\": 0,\n  \"subject\": {\n    \"annotations\": {\n      \"property1\": \"string\",\n      \"property2\": \"string\"\n    },\n    \"artifactType\": \"string\",\n    \"data\": [\n      0\n    ],\n    \"digest\": \"string\",\n    \"mediaType\": \"string\",\n    \"platform\": {\n      \"architecture\": \"string\",\n      \"os\": \"string\",\n      \"os.features\": [\n        \"string\"\n      ],\n      \"os.version\": \"string\",\n      \"variant\": \"string\"\n    },\n    \"size\": 0,\n    \"urls\": [\n      \"string\"\n    ]\n  }\n}\n

Responses

Status Meaning Description Schema 200 OK OK api.ImageIndex 404 Not Found not found string 500 Internal Server Error internal server error string

This operation does not require authentication

"},{"location":"developer-guide/api-reference/#v2nametagslist","title":"/v2/{name}/tags/list","text":""},{"location":"developer-guide/api-reference/#get-v2nametagslist","title":"GET /v2/{name}/tags/list","text":"

List all image tags in a repository

Parameters

Name In Type Required Description name path string true repository name n query integer true limit entries for pagination last query string true last tag value for pagination

Example responses

200 Response

{\n  \"name\": \"string\",\n  \"tags\": [\n    \"string\"\n  ]\n}\n

Responses

Status Meaning Description Schema 200 OK OK common.ImageTags 400 Bad Request bad request\". string 404 Not Found not found string

This operation does not require authentication

"},{"location":"developer-guide/api-user-guide/","title":"Using the zot API","text":"

This document describes how to use the zot REST API and provides a number of examples.

For comprehensive details of all zot API commands, see Viewing the complete zot API reference.

The zot API implements the OCI Distribution endpoints along with additional endpoints for supported extensions. You can access the REST API at the same URL and port number used by the GUI and by datapath tools.

The examples in this article assume that the zot registry is located at localhost:8080.

"},{"location":"developer-guide/api-user-guide/#supported-api-endpoints","title":"Supported API endpoints","text":"

The following is a list of zot API endpoints along with the conditions under which each endpoint is available.

Some API endpoints are available only when a specific extension is enabled in the zot configuration file, or when an extension build label is specified in the make command (for example, make binary EXTENSIONS=ui), or both.

For comprehensive details of the API endpoints, see Viewing the complete zot API reference.

"},{"location":"developer-guide/api-user-guide/#oci-endpoints","title":"OCI endpoints","text":"Endpoint Actions Description /v2/ GET OCI specification endpoints /v2/_catalog GET Lists repositories in a registry. /v2/_oci/ext/discover GET Discover extensions per the OCI specification /v2/{repo}/blobs/{digest} DELETE, GET, HEAD Lists or deletes an image's blob/layer given a digest /v2/{repo}/blobs/uploads POST Creates an image blob/layer upload /v2/{repo}/blobs/uploads/{session_id} DELETE, GET, PATCH, PUT Creates, lists, or deletes an image's blob/layer upload given a session_id /v2/{repo}/manifests/{reference} DELETE, GET, HEAD, PUT Creates, lists, or deletes references for an image /v2/{repo}/referrers/{digest} GET Lists referrers given a digest /v2/{repo}/tags/list GET List all image tags in a repository"},{"location":"developer-guide/api-user-guide/#zot-oci-extension-endpoints","title":"zot OCI extension endpoints","text":"Endpoint Actions Description Availability /v2/_zot/ext/mgmt GET Mgmt extension endpoints Enabled by using the mgmt build label and enabling the search extension in the configuration file. /v2/_zot/ext/notation POST With query parameters, uploads certificates for signature verification Enabled by using the imagetrust build label and enabling the trust extension with the notation option enabled. /v2/_zot/ext/search Enhanced search Enabled by using the search build label and enabling the search extension in the configuration file. /v2/_zot/ext/cosign POST Uploads keys for signature verification Enabled by using the imagetrust build label and enabling the trust extension with the cosign option enabled. /v2/_zot/ext/userprefs PUT User preferences endpoints Enabled by using the userprefs build label and enabling both the search and the ui extensions in the configuration file."},{"location":"developer-guide/api-user-guide/#zot-auth-endpoints","title":"zot auth endpoints","text":"Endpoint Actions Description Availability /zot/auth/apikey DELETE, GET, POST Creates, lists, or deletes API keys Available when API key authentication is enabled in the configuration file (\"apikey\": true). /zot/auth/login POST Opens an API session Available when authentication is available. This includes not only OpenID, but all session-based authentication. /zot/auth/logout POST Ends an API session Available when authentication is available. This includes not only OpenID, but all session-based authentication. /zot/auth/callback/\\<provider> POST Specifies a social authentication service provider for redirecting logins, such as Google or dex. Enabled when an OpenID authentication service provider is specified in the configuration file."},{"location":"developer-guide/api-user-guide/#other-zot-endpoints","title":"other zot endpoints","text":"Endpoint Actions Description Availability /v2/_zot/pprof/ GET Returns a current HTML-format profile list along with a count of currently available records for each profile. See Performance Profiling in zot for usage details. Always enabled. /v2/_zot/debug/graphql-playground# See Using GraphQL for details. Enabled only in a binary-debug zot build or when the zot registry has been built with the debug extension label."},{"location":"developer-guide/api-user-guide/#oras-endpoints","title":"ORAS endpoints","text":"Endpoint Actions Description Availability /oras/artifacts/v1/{repo}/ manifests/{digest}/referrers GET OCI Registry As Storage (ORAS) endpoints Always enabled."},{"location":"developer-guide/api-user-guide/#prometheus-endpoint","title":"prometheus endpoint","text":"Endpoint Actions Description Availability /metrics GET Returns extended metrics for monitoring by prometheus Enabled when the metrics extension is enabled in the configuration file."},{"location":"developer-guide/api-user-guide/#openapi-swagger-endpoints","title":"OpenAPI (swagger) endpoints","text":"

This endpoint is accessed with a browser.

Endpoint Action Description Availability /swagger/v2/ (browser) Displays an interactive OpenAPI (swagger) API reference. Enabled only in a binary-debug zot build or when the zot registry has been built with the debug extension label."},{"location":"developer-guide/api-user-guide/#api-authentication","title":"API authentication","text":"

If zot authentication is not configured, any user can access the zot API.

When pushing and pulling images using API calls, your identity can be authenticated by either a password or an API key.

With a valid password, you can specify your credentials in a cURL request as shown in this example:

curl -u <user>:<password> -X GET http://<server>/<endpoint>\n

An API key has advantages in situations where the primary zot authentication does not use the command line, such as a GUI login or social login. Also, you can reduce your security exposure by using an API key instead of your broader credentials, such as an LDAP username and password.

"},{"location":"developer-guide/api-user-guide/#using-api-keys","title":"Using API keys","text":""},{"location":"developer-guide/api-user-guide/#enabling-api-keys","title":"Enabling API keys","text":"

To enable the use of API keys, you must set the apikey attribute to true in the zot configuration file, as shown in the following example:

  \"http\": {\n    \"auth\": {\n      \"apikey\": true\n    }\n  }\n
"},{"location":"developer-guide/api-user-guide/#creating-your-api-key","title":"Creating your API key","text":"

Before you can create or revoke an API key, you must first log in using a different authentication mechanism, such as logging in through the zot GUI. When you are logged in, you can create an API key for your identity using the following API command:

POST /zot/auth/apikey\n

cURL command example:

curl -u user:password -X POST http://localhost:8080/zot/auth/apikey -d '{\"label\": \"myAPIKEY\", \"scopes\": [\"repo1\", \"repo2\"], \"expirationDate\": \"2023-08-28T17:10:05+03:00\"}'\n

The scopes and expiration date in this example are optional. By default, an API key has the same permissions as the user who created it.

Command output:

{\n  \"createdAt\":\"2023-08-28T17:09:59.2603515+03:00\",\n  \"expirationDate\":\"2023-08-28T17:10:05+03:00\",\n  \"isExpired\":false,\n  \"creatorUa\":\"curl/7.68.0\",\n  \"generatedBy\":\"manual\",\n  \"lastUsed\":\"0001-01-01T00:00:00Z\",\n  \"label\":\"myAPIKEY\",\n  \"scopes\": [\n    \"repo1\",\n    \"repo2\"\n  ],\n  \"uuid\":\"c931e635-a80d-4b52-b035-6b57be5f6e74\",\n  \"apiKey\":\"zak_ac55a8693d6b4370a2003fa9e10b3682\"\n}\n

The API key (apiKey) is shown to the user only in the command output when the key is created. It cannot be later retrieved from zot with any other command.

"},{"location":"developer-guide/api-user-guide/#using-your-api-key-in-an-api-command","title":"Using your API key in an API command","text":"

The API key replaces a password in the API command, as shown in the following cURL example:

curl -u user:zak_e77bcb9e9f634f1581756abbf9ecd269 http://localhost:8080/v2/_catalog\n
"},{"location":"developer-guide/api-user-guide/#removing-your-api-key","title":"Removing your API key","text":"

When logged in, you can revoke your own API key with the following API command:

DELETE /zot/auth/apikey?id=$uuid\n

cURL command example:

curl -u user:password -X DELETE http://localhost:8080/v2/zot/auth/apikey?id=46a45ce7-5d92-498a-a9cb-9654b1da3da1\n
"},{"location":"developer-guide/api-user-guide/#listing-your-current-api-keys","title":"Listing your current API keys","text":"

When logged in, you can display a list of your API keys with the following API command:

GET /zot/auth/apikey\n

cURL command example:

curl -u user:password -X GET http://localhost:8080/zot/auth/apikey\n

Command output:

{\n  \"apiKeys\": [\n    {\n      \"createdAt\": \"2023-05-05T15:39:28.420926+03:00\",\n      \"expirationDate\": \"0001-01-01T00:00:00Z\",\n      \"isExpired\": true,\n      \"creatorUa\": \"curl/7.68.0\",\n      \"generatedBy\": \"manual\",\n      \"lastUsed\": \"0001-01-01T00:00:00Z\",\n      \"label\": \"git\",\n      \"scopes\": [\n        \"repo1\",\n        \"repo2\"\n      ],\n      \"uuid\": \"46a45ce7-5d92-498a-a9cb-9654b1da3da1\"\n    },\n    {\n      \"createdAt\": \"2023-08-11T14:43:00.6459729+03:00\",\n      \"expirationDate\": \"2023-08-17T18:24:05+03:00\",\n      \"isExpired\": false,\n      \"creatorUa\": \"curl/7.68.0\",\n      \"generatedBy\": \"manual\",\n      \"lastUsed\": \"2023-08-11T14:43:47.5559998+03:00\",\n      \"label\": \"myAPIKEY\",\n      \"scopes\": null,\n      \"uuid\": \"294abf69-b62f-4e58-b214-dad2aec0bc52\"\n    }\n  ]\n}\n

This command output example shows an expired key and a current key for this user.

The actual API key (apiKey) is not shown. The key is shown to the user only when it is created.

"},{"location":"developer-guide/api-user-guide/#api-examples","title":"API examples","text":"

The following examples assume that the zot registry is located at localhost:8080.

"},{"location":"developer-guide/api-user-guide/#listing-repositories","title":"Listing repositories","text":"

To get a list of all image repositories in the registry, use the following API endpoint:

GET /v2/_catalog\n

cURL command example:

curl -X GET http://localhost:8080/v2/_catalog\n

Command output:

{\n    \"repositories\": [\"alpine\", \"busybox\"]\n}\n
"},{"location":"developer-guide/api-user-guide/#discovering-extension-endpoints","title":"Discovering extension endpoints","text":"

To list the installed and enabled zot extensions that can be accessed through the API, use the following OCI API endpoint:

GET /v2/_oci/ext/discover\n

cURL command example:

curl -X GET http://localhost:8080/v2/_oci/ext/discover\n

Command output:

{\n  \"extensions\": [\n  {\n    \"name\": \"_zot\",\n    \"url\": \"https://github.com/project-zot/zot/blob//pkg/extensions/_zot.md\",\n    \"description\": \"zot registry extensions\",\n    \"endpoints\": [\"/v2/_zot/ext/search\", \"/v2/_zot/ext/userprefs\", \"/v2/_zot/ext/mgmt\"]\n  }]\n}\n
"},{"location":"developer-guide/api-user-guide/#uploading-a-certificate-for-notation","title":"Uploading a certificate for Notation","text":"

To upload a certificate for notation, use the following endpoint:

POST /v2/_zot/ext/notation\n

cURL command example:

curl --data-binary @certificate.crt -X POST \"http://localhost:8080/v2/_zot/ext/notation?truststoreType=ca\"\n
"},{"location":"developer-guide/api-user-guide/#viewing-the-complete-zot-api-reference","title":"Viewing the complete zot API reference","text":"

You can find comprehensive details of all zot API commands in either of the following locations:

There are many ways to view a swagger file as an interactive document. If you have the npm package installed, for example, you can execute the following command:

  $ npx open-swagger-ui swagger.json\n

This command creates a local web server at localhost:3355 where you can interact with the API reference using a browser.

"},{"location":"developer-guide/contributing/","title":"Contributing to zot Development","text":"

The zot project is built for developers by developers. The zot project welcomes the participation of the open source community in extending and improving zot.

"},{"location":"developer-guide/contributing/#submission-requirements","title":"Submission Requirements","text":"

Summary: All contributions must meet these requirements:

"},{"location":"developer-guide/contributing/#license","title":"License","text":"

zot is released under the Apache License 2.0. All contributions must adhere to this license and must explicitly state adherence.

"},{"location":"developer-guide/contributing/#submitting-a-pull-request-pr","title":"Submitting a Pull Request (PR)","text":"

First, fork the zot project on GitHub and submit a commit to your fork. Then open a new pull request (PR) to the zot project. All pull requests must meet these requirements:

Either the commit message or the PR description must contain the following statement:

\"By submitting this pull request, I confirm that my contribution is made under the terms of the Apache 2.0 license.\"

All commits require a Developer Certificate of Origin via the \"Signed-off-by:\" commit message and commit signatures using GPG keys. Include the -s flag in your git commit command.

The commit message must follow the Convention Commits format. The message must begin with a keyword that categorizes the commit, followed by a colon. Validation of a commit message is determined by this expression:

\"^((build|chore|ci|docs|feat|fix|perf|refactor|revert|style|test)(\\(.+\\))?(!)?(: (.*\\s*)*))\"

An example of a valid commit message is \"docs: Fixes a typo in module.md.\"

In addition, any new PR requires a brief form to be completed by the submitter with details about the PR. Appropriate code owners are automatically identified and will be notified of the new PR.

"},{"location":"developer-guide/contributing/#cicd-checks","title":"CI/CD Checks","text":"

We take code quality very seriously. All PRs must pass various CI/CD checks that enforce code quality such as code coverage, security scanning, performance regressions, distribution spec conformance, ecosystem client tool compatibility, etc.

"},{"location":"developer-guide/contributing/#reporting-issues","title":"Reporting Issues","text":"

Issues are broadly classified as functional bugs and security issues. The latter is treated a little differently due to the sensitive nature.

"},{"location":"developer-guide/contributing/#filing-a-functional-issue","title":"Filing a Functional Issue","text":"

No software is perfect, and we expect users to find issues with the zot code base. First, check whether your issue has already been filed by someone else by performing an issue search. If the issue is not found, file a new issue by clicking the New issue button on the zot/issues page and answering the questions. The more information that you can provide, the easier it becomes to triage the issue.

"},{"location":"developer-guide/contributing/#filing-a-security-issue","title":"Filing a Security Issue","text":"

Security issues are best filed by sending an email to security@zotregistry.dev. After 45 days, we will make the issue public and give credit to the original filer of the issue.

"},{"location":"developer-guide/contributing/#code-of-conduct","title":"Code of Conduct","text":"

The zot project follows the CNCF Code of Conduct.

"},{"location":"developer-guide/contributing/#reporting-conduct-incidents","title":"Reporting Conduct Incidents","text":"

To report a conduct-related incident occurring on the zot project, contact the zot project conduct committee by sending an email to conduct@zotregistry.dev. You can expect a response within three business days.

"},{"location":"developer-guide/extensions-dev/","title":"Developing New Extensions","text":"

You can add new functionality to the zot registry by developing extensions for integration into zot.

The OCI Distribution Specification supports extending the functionality of an OCI-compliant registry implementation by adding extensions. Extensions are new APIs developed outside of the core OCI specs. Developers may propose their extensions to the OCI for possible future addition to the Distribution Specification.

When planning the development of a new extension, be sure to familiarize yourself with the OCI documentation and guidelines for extensions.

"},{"location":"developer-guide/extensions-dev/#current-extensions","title":"Current extensions","text":"

The following extensions are currently available in the zot project:

You can examine the implementation of these extensions in the zot project extensions section. The operation and configuration of the current extensions is described in Configuring zot.

"},{"location":"developer-guide/extensions-dev/#guidelines-for-developing-new-extensions","title":"Guidelines for developing new extensions","text":" 
  //go:build foo\n  // +build foo\n\n  package foo\n\n  ...\n
- The first line (`//go:build foo`) is added automatically by the linter if not already present.\n\n- The second line and the third (blank) line are mandatory.\n

    //go:build !foo\n    // +build !foo\n\n    package foo\n\n    ...\n
See extension lint-disabled.go in the zot project for an example of a \"no-op\" file.

"},{"location":"developer-guide/extensions-dev/#building-zot-with-extensions","title":"Building zot with extensions","text":"

When you build the full zot image (for example, make binary), all extensions listed in the EXTENSIONS variable in Makefile are included in the build. When you've created a new extension, you must modify the EXTENSIONS variable in Makefile by adding the new extension.

To build an image with only selected extensions, you can specify the desired extensions by declaring them in the build command:

make binary EXTENSIONS=extension1,extension2,extension3...\n

For example, to build with only sync and scrub, the command would be:

make binary EXTENSIONS=sync,scrub\n
"},{"location":"developer-guide/onboarding/","title":"Onboarding zot for Development","text":"

zot is a production-ready, open-source, extensible OCI-native image registry, built for developers by developers.

"},{"location":"developer-guide/onboarding/#getting-started","title":"Getting Started","text":""},{"location":"developer-guide/onboarding/#supported-developer-platforms","title":"Supported Developer Platforms","text":"

Development is officially supported on Linux and Apple MacOS platforms. 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 (Apple M1)

Supported platforms and architectures

"},{"location":"developer-guide/onboarding/#prerequisites","title":"Prerequisites","text":""},{"location":"developer-guide/onboarding/#install-golang","title":"Install golang","text":"

Follow the golang instructions to install the golang toolchain. After installation, make sure that the path environment variable or your IDE can find the toolchain.

You must use a golang version of at least the minimum specified in go.mod or the build will fail.

"},{"location":"developer-guide/onboarding/#cloning-zot","title":"Cloning zot","text":"

The zot registry code base is hosted on GitHub at https://github.com/project-zot/zot.

To clone the zot project, use this command:

$ git clone https://github.com/project-zot/zot.git\n
"},{"location":"developer-guide/onboarding/#building-zot","title":"Building zot","text":"

To build zot, execute the make command in the zot directory using the following general syntax:

$ make OS=os ARCH=architecture {binary | binary-minimal}

For example, to build a zot image with extensions for an Intel-based linux server, use the following command:

make OS=linux ARCH=amd64 binary\n

The make command builds an executable image in the zot/bin directory. The original filename of the zot executable image will indicate the build options. For example, the filename of an Intel-based linux minimal image is zot-minimal-linux-amd64.

Click here to view an example of the getting started process.

"},{"location":"developer-guide/onboarding/#running-zot","title":"Running zot","text":"

The behavior of zot is controlled via configuration only. To launch the zot server, execute the following command:

$  bin/zot-linux-amd64 serve examples/config-minimal.json\n
"},{"location":"developer-guide/onboarding/#debugging-zot","title":"Debugging zot","text":"

To produce a zot binary that includes extensive debugging information, build zot with the binary-debug option, as shown in this example:

make OS=linux ARCH=amd64 binary-debug\n

You can then attach and run a debugging tool such as Delve to the running zot process.

Delve is a powerful open-source debugger for the Go programming language. Downloads and documentation for Delve are available on GitHub at https://github.com/go-delve/delve.

"},{"location":"developer-guide/onboarding/#performance-profiling","title":"Performance profiling","text":"

Performance 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.

For detailed information about performance profiling, see Performance Profiling in zot.

"},{"location":"developer-guide/onboarding/#code-organization","title":"Code Organization","text":"

The zot project codebase is organized as follows:

/\n- pkg/              # Source code for all libraries\n  - api/            # Source code for HTTP APIs\n    - config/       # Global configuration model\n  - storage/        # Source code for storage backends\n  - cli/            # Source code for command line interface (cli)\n  - common/         # Source code for common utility routines\n  - compliance/     # Source code for dist-spec conformance tests\n  - log/            # Source code for logging framework\n  - test/           # Internal test scripts/data\n  - extensions/     # Source code for all extensions\n    - config/\n    - sync/\n    - monitoring/\n    - sync/\n  - exporter/       # Source code for metrics exporter\n- cmd/              # Source code for binary main()s\n  - zot/            # Source code for zot binary\n  - zli/            # Source code for zot cli\n  - zb/             # Source code for zb, the dist-spec benchmarking tool\n- errors/           # Source code for error codes\n- examples/         # Configuration examples\n- swagger/          # Swagger integration\n- docs/             # Documentation\n
"},{"location":"developer-guide/onboarding/#additional-state-in-zot","title":"Additional state in zot","text":"

In addition to the storage of repository images, zot stores data for various processes in local and remote storage and databases. The following table shows the storage locations for different processes and types of data.

Data or Process Storage Location Description images local andAWS S3 Image blobs repository synchronization local/<repo_name>/.sync The sync operation temporarily copies the upstream blobs to: /<repo_name>/.sync/${UUID}/<repo_name>, then copies to /<repo_name> and deletes the temporary directory ${UUID} deduplication local/cache.db Cache for deduplication of files stored locally AWS DynamoDB Cache for deduplication of files stored in AWS CVE local/_trivy Database of Common Vulnerabilities and Exposures (CVE) information and scan results user sessions local/_sessions zot user session authentication (for zui) PKI authentication documents local/_cosign Private keys for signature verification using cosign local/_notation Certificates for signature verification using notation metadata local/repo.db Local storage of manifests, configurations, download counters, signature verification results AWS DynamoDB Cloud storage of manifests, configurations, download counters, signature verification results"},{"location":"general/architecture/","title":"Architecture","text":"

zot is an OCI-native container image registry. This document discusses the design goals, the overall architecture, and the design choices made in the implementation of the design goals.

"},{"location":"general/architecture/#design-goals","title":"Design Goals","text":""},{"location":"general/architecture/#oci-first","title":"OCI-first","text":""},{"location":"general/architecture/#single-binary-model","title":"Single binary model","text":"

zot is a single binary image with all features included so that deployment is extremely simple in various environments, including bare-metal, cloud, and embedded devices. Behavior is controlled by a single configuration file.

"},{"location":"general/architecture/#enable-only-what-you-need","title":"Enable Only What You Need","text":"

A clear separation exists between (1) the core OCI-compliant HTTP APIs and storage functionality, and (2) other add-on features modeled as extensions. The extension features can be selectively enabled both at build-time and run-time.

For more information, see \"Conditional Builds\" in zot's security posture document.

"},{"location":"general/architecture/#overall-architecture","title":"Overall Architecture","text":"

As shown in the following figure, the architecture of zot is organized as:

zot-full = zot-minimal + extensions

The minimal build is the core OCI-compliant registry functionality as described by the OCI Distribution Specification.

The full build adds features that are not a part of the Distribution Specification, but are allowed to be added as Extensions.

"},{"location":"general/architecture/#external-interaction","title":"External Interaction","text":"

External interaction with zot consists of the following two types:

All client-side interaction occurs over HTTP APIs. The core data path queries are governed by the OCI Distribution Specification. All additional meta-data queries are handled based on the setting of the search extension:

"},{"location":"general/architecture/#configuration","title":"Configuration","text":"

A single configuration file governs zot instance behavior. An exception can be made for security concerns, wherein configuration items containing sensitive credentials can be stored in separate files referenced by the main configuration file. Using separate files allows stricter permissions to be enforced on those files if stored locally. Also, modeling as external files allows for storing Kubernetes Secrets.

The configuration file is divided into sections for http, storage, log, and extension, governing the behavior of the respective components.

"},{"location":"general/architecture/#authentication-and-authorization","title":"Authentication and Authorization","text":"

A robust set of authentication and authorization options are supported natively in zot. These controls are enforced before access is allowed into the storage layer.

For more information, see User Authentication and Authorization with zot.

"},{"location":"general/architecture/#storage-driver-support","title":"Storage Driver Support","text":"

zot supports any modern local filesystem. Remote filesystems, such as AWS S3 or any AWS S3-compatible storage system, are supported. Additional driver support is planned in the roadmap.

Deduplication is supported for both local and remote filesystems, but deduplication requires a filesystem with hard-link support.

For more information, see Storage Planning with zot.

"},{"location":"general/architecture/#security-scanning","title":"Security Scanning","text":"

zot integrates with the trivy security scanner to scan container images for vulnerabilities. The database is kept current by periodically downloading any vulnerability database updates at a configurable interval. The user remains agnostic of the actual scanner implementation, which may change over time.

"},{"location":"general/architecture/#extensions","title":"Extensions","text":"

Additional registry features that are not a part of the Distribution Specification are added as Extensions.

Extension features of zot are available only with a full zot image. They are not supported in a minimal zot image.

For more information about zot's extensions, see Extensions.

"},{"location":"general/architecture/#background-tasks","title":"Background Tasks","text":"

Several periodic tasks occur in the registry, such as garbage collection, sync mirroring, and scrubbing. A task scheduler handles these tasks in the background, taking care not to degrade or interrupt foreground tasks running in the context of HTTP APIs.

"},{"location":"general/concepts/","title":"Concepts","text":""},{"location":"general/concepts/#what-is-zot","title":"What is zot?","text":"

zot is a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

Two broad trends are changing how we build, distribute, and consume software. The first trend is the increasing adoption of container technologies. The second trend is that software solutions are being composed by combining elements from various sources rather than being built entirely from scratch. The latter trend raises the importance of software provenance and supply chain security. In both trends, zot intends to play an important role by providing a production-ready, open-source, vendor-neutral container image registry server based purely on OCI standards.

"},{"location":"general/concepts/#what-is-an-oci-image-registry","title":"What is an OCI image registry?","text":"

An OCI image registry is a server-based application that allows you to store, manage, and share container images. A developer uploads (pushes) an image to the registry for distribution. Users can then download (pull) the image to run on their systems. The OCI Distribution Specification, published by the Open Container Initiative (OCI), defines a standard API protocol for these and other image registry operations.

An image registry can be a part of your continuous integration and continuous deployment (CI/CD) pipeline when you host zot on your public or private server. In its minimal form, you can also embed a zot registry in a product. In either case, zot provides a secure software supply chain for container images.

"},{"location":"general/concepts/#why-zot","title":"Why zot?","text":"

zot = OCI Distribution Specification + OCI Image Format

At its heart, zot is a production-ready, vendor-neutral OCI image registry with images stored in the OCI image format and with the OCI distribution specification on-the-wire. zot is built for developers by developers, offering features such as minimal deployment using a single binary image, built-in authentication and authorization, and inline garbage collection and storage deduplication.

Some of the principal advantages of zot are:

zot fully conforms to the OCI Distribution Specification.

The following table lists additional advantages of zot:

Distribution Spec conformance yes CNCF project accepted as a Sandbox Project License Apache 2.0 On-premises deployment yes OCI conformance* yes Single binary image* yes Minimal build* yes Storage Layout OCI v1 Image Layout Authentication built-in Authorization built-in Garbage collection inline Storage deduplication inline Cloud storage support yes Delete by tag yes Vulnerability scanning built-in Command line interface (cli) yes UI yes External contributions beta available Image signatures built-in

* The minimal build feature is the ability to build a minimal Distribution Spec compliant registry in order to reduce library dependencies and the possible attack surface.

"},{"location":"general/extensions/","title":"Extensions","text":"

Extensions provide additional registry features that are not a part of the Distribution Specification.

The following extensions are currently available with zot:

For detailed information about configuring zot extensions, see Configuring zot.

"},{"location":"general/extensions/#about-extensions","title":"About extensions","text":"

The OCI Distribution Specification supports extending the functionality of an OCI-compliant registry implementation by adding extensions. Extensions are new APIs developed outside of the core OCI specs. Developers may propose their extensions to the OCI for possible future addition to the Distribution Specification.

Wherever applicable, extensions can be dynamically discovered using the extensions support of the OCI Distribution Specification.

Extension features of zot are available only with a full zot image. They are excluded from the minimal zot image.

"},{"location":"general/extensions/#extensions-implemented-in-zot","title":"Extensions implemented in zot","text":"

The extensions implemented in zot include administrator-configured functionality and end-user features.

Currently, search, trust, and userprefs are the only zot extensions operable by end users. Only these extensions are accessible through HTTP APIs and are discoverable using the OCI extensions mechanism.

The following extensions are currently supported by zot:

"},{"location":"general/extensions/#search","title":"Search","text":"

One of the key functions of a container image registry (which is essentially a graph of blobs) is the ability to perform interesting image and graph traversal queries. The user interacts with the search extension via a graphQL endpoint. The schema is published with every release.

Examples of queries are:

"},{"location":"general/extensions/#sync","title":"Sync","text":"

You can deploy a local mirror pointing to an upstream zot instance with various container image download policies, including on-demand and periodic downloads. The sync function is useful to avoid overwhelming the upstream instance, or if the upstream instance has rate-limited access.

docker.io is supported as an upstream mirror.

"},{"location":"general/extensions/#lint","title":"Lint","text":"

The lint extension helps to avoid image compliance issues by enforcing certain policies about the image or the image metadata. Currently, lint can check an uploaded image to enforce the presence of required annotations such as the author or the license.

"},{"location":"general/extensions/#scrub","title":"Scrub","text":"

Although container images are content-addressable with their SHA256 checksums, and validations are performed during storage and retrieval, it is possible that bit-rot sets in when not in use. The scrub extension actively scans container images in the background to proactively detect errors.

"},{"location":"general/extensions/#trust","title":"Trust","text":"

Images stored in zot can be signed with a digital signature to verify the source and integrity of the image. The digital signature can be verified by zot using public keys or certificates uploaded by the user through the zot API. The trust extension enables and configures this function.

"},{"location":"general/extensions/#metrics","title":"Metrics","text":"

The metrics extension adds a node exporter, which is not present in the minimal build.

"},{"location":"general/extensions/#graphical-user-interface","title":"Graphical user interface","text":"

Using the zot graphical user interface (GUI), you can browse a zot registry for container images and artifacts. From the web interface, you can copy the shell commands for downloading an image using popular third-party tools such as docker, podman, and skopeo.

"},{"location":"general/extensions/#user-preferences","title":"User preferences","text":"

The userprefs extension provides an API endpoint for adding configurable user preferences for a repository. This custom extension, not a part of the OCI distribution, is accessible only by authenticated users of the registry. Unauthenticated users are denied access.

The functions currently implemented by this extension include:

For information about configuring zot extensions, see Configuring zot.

"},{"location":"general/features/","title":"Summary of Key Features","text":""},{"location":"general/glossary/","title":"Glossary","text":""},{"location":"general/glossary/#documentation-icons","title":"Documentation Icons","text":"Icon Description Note \u2014 A point of emphasis or caution. Tip \u2014 A helpful suggestion or a reference to additional material not covered in this document. Warning \u2014 A suggestion or advisory intended to avoid a loss of service or data."},{"location":"general/glossary/#definitions","title":"Definitions","text":"Term Description artifact A file of any kind produced during a container build process or associated with the operation of a container. For example, a Helm chart is an artifact that might be stored along with a container. CNCF As part of the Linux Foundation, the Cloud Native Computing Foundation provides support, oversight, and direction for open-source, cloud native projects. cosign cosign is a tool that performs container signing, verification, and storage in an OCI registry. cosigned cosigned is an image admission controller that validates container images before deploying them. cri-o cri-o is an implementation of the Kubernetes Container Runtime Interface (CRI) to enable using OCI compatible runtimes. It is a lightweight alternative to using Docker as the runtime for Kubernetes. deduplication 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. digest A hashed checksum, such as SHA-256, for verifying the integrity of the downloaded image. Distribution Specification The OCI Distribution Specification project defines an API protocol to facilitate and standardize the distribution of content. extensions Additional registry features (APIs) that are not a part of the Distribution Specification can be added as Extensions. helm chart A helm chart is a package of files that orchestrate the deployment of Kubernetes resources into a Kubernetes cluster. manifest An image manifest provides a configuration and set of layers for a single container image for a specific architecture and operating system. node exporter A software component that collects hardware and operating system level metrics exposed by the kernel. OCI The Open Container Initiative (OCI) is an open governance structure for the express purpose of creating open industry standards around container formats and runtimes. ORAS OCI Registry as Storage (ORAS) is a tool for distributing OCI artifacts across OCI registries. prometheus Prometheus is a node exporter that exposes a wide variety of hardware- and kernel-related metrics. referrer An image containing a non-nil subject field with a descriptor to the referred image. registry A service that stores and distributes container images and artifacts. repository A collection of images with the same name, differentiated by tags. skopeo skopeo is a command line utility that performs various operations on container images and image repositories. stacker 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. tag A label applied to an image that distinguishes the image from other images in the same repository. A common example is a version tag. zb A benchmarking tool, available as a zot companion binary, for benchmarking a zot registry or any other container image registry that conforms to the OCI Distribution Specification. zli A zot companion binary that implements a set of command line commands for interacting with the zot registry server. zui A zot companion binary that implements a graphical user interface (GUI) for interacting with the zot registry server. zxp A node exporter, available as a zot companion binary, that can be deployed with a minimal zot image in order to scrape metrics from the zot server."},{"location":"general/project/","title":"About the zot Project","text":""},{"location":"general/project/#project-repository","title":"Project Repository","text":"

The zot project is hosted on GitHub:

project-zot/zot

"},{"location":"general/project/#sponsors","title":"Sponsors","text":"

Cisco Systems, Inc.

"},{"location":"general/project/#adopters","title":"Adopters","text":"

Cisco Systems, Inc.

"},{"location":"general/project/#presentations","title":"Presentations","text":"

OCI Weekly Discussion - Oct 2, 2019

"},{"location":"general/releases/","title":"Released Images for zot","text":"

This document describes the available zot images for the various supported hardware and software platforms, along with information about image variations, image locations, and image naming formats.

"},{"location":"general/releases/#supported-platforms","title":"Supported platforms","text":"

zot is supported on Linux and Apple MacOS platforms with Intel or ARM processors.

Table: Supported platforms and 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 (Apple M1) 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."},{"location":"general/releases/#full-and-minimal-binary-images","title":"Full and minimal binary images","text":"

In addition to variations for specific platforms and architectures, binary images are also available in full and minimal flavors:

"},{"location":"general/releases/#binary-image-file-naming","title":"Binary image file naming","text":"

An executable binary image for zot is named using the target platform and architecture from the Supported platforms and architectures table. The general format of a binary image file name is one of these two:

zot-<os>-<architecture>

zot-<os>-<architecture>-minimal

For convenience, you can rename the binary image file to simply zot after downloading.

"},{"location":"general/releases/#where-to-get-zot","title":"Where to get zot","text":"

You can download native executable binary images or container (Docker) images.

"},{"location":"general/releases/#getting-binary-images","title":"Getting binary images","text":"

The zot project is hosted on GitHub at project-zot.

To download a binary image, go to the zot releases and select a release. Go to the Assets section of the release page and download the binary for your platform and architecture.

You may need to use the chmod command to make the image executable.

When downloading a binary image for MacOS, download the darwin image.

"},{"location":"general/releases/#getting-container-images","title":"Getting container images","text":"

You can download a container image from ghcr.io by forming a URL with the desired image name, such as:

https://ghcr.io/project-zot/zot-<os>-<architecture>[-<build>]\n

If <build> is not specified, the default is full. For example, to download the minimal binary image for an Intel-based linux server. The URL is:

https://ghcr.io/project-zot/zot-linux-amd64-minimal\n

When downloading a container image for MacOS, download the linux image, not the darwin image.

"},{"location":"general/releases/#licensing","title":"Licensing","text":"

zot is released under the Apache License 2.0.

"},{"location":"general/whats-new/","title":"What's New","text":""},{"location":"general/whats-new/#v201","title":"v2.0.1","text":""},{"location":"general/whats-new/#support-for-hot-reloading-of-ldap-credentials-file","title":"Support for hot reloading of LDAP credentials file","text":"

Since v2.0.0, LDAP credentials have been specified in a separate file. Starting with this version, the file is watched and changes applied without restarting zot.

"},{"location":"general/whats-new/#bugfixes-and-performance-improvements","title":"Bugfixes and performance improvements","text":"

Under some configurations, zot consumes significant CPU and memory resources. This has been fixed in this release.

"},{"location":"general/whats-new/#v200","title":"v2.0.0","text":""},{"location":"general/whats-new/#updated-oci-support","title":"Updated OCI support","text":""},{"location":"general/whats-new/#built-in-ui-support","title":"Built-in UI support","text":""},{"location":"general/whats-new/#support-for-social-logins","title":"Support for social logins","text":""},{"location":"general/whats-new/#group-policies-for-authorization","title":"Group policies for authorization","text":""},{"location":"general/whats-new/#signature-verification","title":"Signature verification","text":""},{"location":"general/whats-new/#ldap-credentials-stored-separately-from-configuration","title":"LDAP credentials stored separately from configuration","text":""},{"location":"general/whats-new/#storage-deduplication-on-startup","title":"Storage deduplication on startup","text":""},{"location":"general/whats-new/#retention-policies","title":"Retention policies","text":""},{"location":"general/whats-new/#cve-scanning-support-for-image-indexes","title":"CVE scanning support for image indexes","text":""},{"location":"general/whats-new/#bookmarks","title":"Bookmarks","text":""},{"location":"general/whats-new/#ability-to-delete-tags-from-the-ui","title":"Ability to delete tags from the UI","text":""},{"location":"general/whats-new/#command-line-search","title":"Command line search","text":""},{"location":"general/whats-new/#search-by-digest","title":"Search by digest","text":""},{"location":"general/whats-new/#graphql-support-for-search","title":"GraphQL support for search","text":""},{"location":"general/whats-new/#scheduling-of-background-tasks","title":"Scheduling of background tasks","text":""},{"location":"general/whats-new/#performance-profiling-for-troubleshooting","title":"Performance profiling for troubleshooting","text":""},{"location":"general/whats-new/#binaries-for-freebsd","title":"Binaries for FreeBSD","text":""},{"location":"general/whats-new/#v143","title":"v1.4.3","text":""},{"location":"general/whats-new/#remote-only-storage-support","title":"Remote-only Storage Support","text":""},{"location":"general/whats-new/#digest-collision-detection-during-image-deletion","title":"Digest Collision Detection During Image Deletion","text":""},{"location":"install-guides/install-guide-k8s/","title":"Installing zot with Kubernetes and Helm","text":"

Using Kubernetes with Helm charts for zot, you can easily deploy zot as an application in a Kubernetes cluster.

"},{"location":"install-guides/install-guide-k8s/#before-you-begin","title":"Before you begin","text":""},{"location":"install-guides/install-guide-k8s/#prerequisites","title":"Prerequisites","text":""},{"location":"install-guides/install-guide-k8s/#supported-platforms","title":"Supported platforms","text":"

You can install zot on standard Linux platforms with Intel or ARM processors and with systemd installed.

OS ARCH Platform linux amd64 Intel-based Linux servers linux arm64 ARM-based servers and Raspberry Pi4

Supported platforms and architectures

"},{"location":"install-guides/install-guide-k8s/#about-binary-images","title":"About binary images","text":"

Refer to Released Images for zot for information about available zot images along with information about image variations, image locations, and image naming formats.

"},{"location":"install-guides/install-guide-k8s/#installing-zot","title":"Installing zot","text":""},{"location":"install-guides/install-guide-k8s/#step-1-locate-the-helm-charts-in-a-remote-repository","title":"Step 1: Locate the Helm charts in a remote repository","text":"

  1. Specify a remote repository that contains the Helm charts for zot. Give the repo a local name, such as project-zot, as in this example:

    helm repo add project-zot http://zotregistry.dev/helm-charts

    \"project-zot\" has been added to your repositories\n

    The Helm charts for zot are currently hosted in these publicly-accessible repositories: - zotregistry.dev - artifacthub.io

  2. Search the repository to see the Helm charts for zot installation. Search using the keyword 'project-zot' or 'zot', as in this example:

    helm search repo project-zot

    NAME             CHART VERSION  APP VERSION  DESCRIPTION\nproject-zot/zot  <chart-version>          v2.0.1       A Helm chart for Kubernetes\n

    The APP VERSION is the version/tag of the zot image used for the deployment.

  3. Update to the latest information of available charts from the chart repository, as shown in this example:

    helm repo update project-zot

    Hang tight while we grab the latest from your chart repositories...\n...Successfully got an update from the \"project-zot\" chart repository\nUpdate Complete. \u2388Happy Helming!\u2388\n

  4. Display the default information of the Helm chart, as shown in this example:

helm show all project-zot/zot

    apiVersion: v2\n    appVersion: v2.0.1\n    description: A Helm chart for Kubernetes\n    name: zot\n    type: application\n    version: <chart-version>\n\n    # Default values for zot.\n    # This is a YAML-formatted file.\n    # Declare variables to be passed into your templates.\n    replicaCount: 1\n    image:\n      repository: ghcr.io/project-zot/zot-linux-amd64\n      pullPolicy: IfNotPresent\n      tag: \"v2.0.1\"\n    serviceAccount:\n      create: true\n      annotations: {}\n      name: \"\"\n    service:\n      type: NodePort\n      port: 5000\n
"},{"location":"install-guides/install-guide-k8s/#step-2-determine-any-needed-changes-from-the-helm-charts-defaults","title":"Step 2: Determine any needed changes from the Helm chart\u2019s defaults","text":"

Inspect the default information of the Helm chart, as shown in the previous step. In many cases, the default chart values may be acceptable. If your installation requires any non-default settings, you may be able to specify them during the installation. Not all chart values are configurable, but you can display those that are configurable using the command in the following example:

helm show values project-zot/zot

  # Default values for zot.\n  # This is a YAML-formatted file.\n  # Declare variables to be passed into your templates.\n  replicaCount: 1\n  image:\n    repository: ghcr.io/project-zot/zot-linux-amd64\n    pullPolicy: IfNotPresent\n    tag: \"v2.0.1\"\n  serviceAccount:\n    create: true\n    annotations: {}\n    name: \"\"\n  service:\n    type: NodePort\n    port: 5000\n

The configurable settings in the chart are listed in the following table:

parameter description

replicaCount

Desired number of replicas of the application

image.repository

Repository and image name for the application

image.pullPolicy

Whether to pull the image from the repository. If not specified, the policy depends on image.tag:

image.tag

Identifies different versions the image. default is the chart appVersion.

Examples: :latest (the default) or :v2.0.1

serviceAccount.create

Specifies whether a service account should be created

serviceAccount.annotations

Annotations to add to the service account

serviceAccount.name

Name of the service account to use. If name is not set and create is true, a name is generated using the fullname template.

service.type

ClusterIP (default), NodePort, LoadBalancer, ExternalName, or Headless

service.port

Port number for calling the service

strategy.type

Kubernetes deployment strategy type. [More Info](https://kubernetes.io/docs/concepts/workloads/controllers/deployment/#strategy)

"},{"location":"install-guides/install-guide-k8s/#customizing-the-helm-chart-using-set","title":"Customizing the Helm chart using 'set'","text":"

To override the default values in the chart, you can pass your custom values by adding the --set flag in the helm install command.

For example, if your servers use an ARM processor instead of Intel, you must change the image.repository name from zot-linux-amd64 to zot-linux-arm64:

--set image.repository=ghcr.io/project-zot/zot-linux-arm64

You can change multiple settings with one --set statement. For example, you might want your installation to have more replicas or a different port number:

--set replicaCount=2,service.port=5050

"},{"location":"install-guides/install-guide-k8s/#customizing-the-helm-chart-using-a-file","title":"Customizing the Helm chart using a file","text":"

You can also create a YAML file with your overrides and then add the new file by adding the -f flag to the helm install command. For example, to override the replica count and port number, the contents of your YAML file (for example, \"myfile.yaml\") would be:

replicaCount: 2\nservice:\n  port: 5050\n

and the following flag would be added to the helm install command:

-f myfile.yaml

"},{"location":"install-guides/install-guide-k8s/#additional-information","title":"Additional information","text":"

See the Helm documentation for further information about modifying the Helm chart.

"},{"location":"install-guides/install-guide-k8s/#step-3-install-zot","title":"Step 3: Install zot","text":"

Install zot using the helm install command. The first example shows how to perform a default installation. The additional examples show different ways to modify the helm install command to override default settings in the Helm chart:

Example 1: use default chart parameters

helm install zot project-zot/zot

NAME: zot\nLAST DEPLOYED: Thu Aug 11 19:13:02 2022\nNAMESPACE: default\nSTATUS: deployed\nREVISION: 1\nNOTES:\n Get the application URL by running these commands:\n export NODE_PORT=$(kubectl get --namespace default -o jsonpath=\"{.spec.ports[0].nodePort}\" services zot)\n export NODE_IP=$(kubectl get nodes --namespace default -o jsonpath=\"{.items[0].status.addresses[0].address}\")\n echo http://$NODE_IP:$NODE_PORT\n

Example 2: modify specific chart parameters with 'set'

helm install --set replicaCount=2,service.port=5050 zot project-zot/zot

Example 3: modify specific chart parameters with a file

helm install -f myfile.yaml zot project-zot/zot

Example 4: use a specific version of the Helm chart

helm install zot project-zot/zot --version 0.1.0

Example 5: link to a kubeconfig file

helm install zot project-zot/zot --kubeconfig $HOME/.kube/config

"},{"location":"install-guides/install-guide-k8s/#after-the-installation","title":"After the installation","text":""},{"location":"install-guides/install-guide-k8s/#verify-the-installation","title":"Verify the installation","text":"

  1. List all releases that are either deployed or failed.

    helm list

    NAME  NAMESPACE  REVISION  UPDATED    STATUS    CHART      APP VERSION\nzot   default    1         <datetime> deployed  <chart-version>  v2.0.1\n

    This response indicates that zot is deployed.

  2. After making sure that your pods are up and running, execute the following commands:

    $ export NODE_PORT=$(kubectl get --namespace default -o jsonpath=\"{.spec.ports[0].nodePort}\" services zot)\n$ export NODE_IP=$(kubectl get nodes --namespace default -o jsonpath=\"{.items[0].status.addresses[0].address}\")\n$ echo http://$NODE_IP:$NODE_PORT\n$ curl http://$NODE_IP:$NODE_PORT/v2/_catalog\n

    The response should display the current contents of your zot repository, which should be empty immediately after installation:

    {\"repositories\":[]}\n
"},{"location":"install-guides/install-guide-k8s/#edit-the-zot-configuration-file","title":"Edit the zot configuration file","text":"

The zot configuration file is a JSON or YAML file that contains all configuration settings for zot functions such as:

The Helm chart installs a minimal JSON configuration file as shown below:

{\n    \"storage\":\n    {\n        \"rootDirectory\": \"/var/lib/registry\"\n    },\n    \"http\":\n    {\n        \"address\": \"0.0.0.0\",\n        \"port\": \"5000\"\n    },\n    \"log\":\n    {\n        \"level\": \"debug\"\n    }\n}\n

The zot configuration file is located at /etc/zot/config.json.

Refer to Configuring zot for complete information on configuring the zot server with the zot configuration file.

"},{"location":"install-guides/install-guide-k8s/#uninstalling-zot","title":"Uninstalling zot","text":"

Should you need to uninstall zot, use the helm uninstall command, as in this example:

helm uninstall zot

"},{"location":"install-guides/install-guide-linux/","title":"Installing zot on Bare Metal Linux","text":"

Using an available executable zot image, you can easily deploy zot on a Linux server.

"},{"location":"install-guides/install-guide-linux/#before-you-begin","title":"Before you begin","text":""},{"location":"install-guides/install-guide-linux/#about-binary-images","title":"About binary images","text":"

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.

"},{"location":"install-guides/install-guide-linux/#installation","title":"Installation","text":""},{"location":"install-guides/install-guide-linux/#step-1-get-zot","title":"Step 1: Get zot","text":"

Using wget, download the appropriate zot binary image for your platform from the zot GitHub project. Download the image to the`/usr/bin/` directory and rename it to zot, as in this example:

sudo wget -O /usr/bin/zot https://github.com/project-zot/zot/releases/download/v2.0.1/zot-linux-amd64\n

Then fix permissions to it:

sudo chmod +x /usr/bin/zot\nsudo chown root:root /usr/bin/zot\n
"},{"location":"install-guides/install-guide-linux/#step-2-create-a-zot-configuration-file","title":"Step 2: Create a zot configuration file","text":"

Create a zot configuration file as /etc/zot/config.json.

See Configuration file options for an example file with options and recommendations. You can find other configuration file examples in the zot GitHub project and in Configuring zot.

"},{"location":"install-guides/install-guide-linux/#step-3-configure-a-local-authentication-account","title":"Step 3: Configure a local authentication account","text":"

If you want to use local authentication with zot, create a /etc/zot/htpasswd file with an initial account entry using the htpasswd command as in this example:

htpasswd -bnB myUserName myPassword > /etc/zot/htpasswd\n

To add additional local users, use the >> redirect as in this example:

htpasswd -bnB myUserName2 myPassword2 >> /etc/zot/htpasswd\n
"},{"location":"install-guides/install-guide-linux/#step-4-define-the-zot-service","title":"Step 4: Define the zot service","text":"

Create a /etc/systemd/system/zot.service file to define the zot service in systemd. The following is an example service file for zot:

[Unit]\nDescription=OCI Distribution Registry\nDocumentation=https://zotregistry.dev/\nAfter=network.target auditd.service local-fs.target\n\n[Service]\nType=simple\nExecStart=/usr/bin/zot serve /etc/zot/config.json\nRestart=on-failure\nUser=zot\nGroup=zot\nLimitNOFILE=500000\nMemoryHigh=30G\nMemoryMax=32G\n\n[Install]\nWantedBy=multi-user.target\n

Be sure to configure a dedicated non-root user ID as the User and Group in the zot service definition. The 'zot' user ID in this example is created in the next step.

"},{"location":"install-guides/install-guide-linux/#step-5-create-a-user-id-to-own-the-zot-service","title":"Step 5: Create a user ID to own the zot service","text":"

Create a non-root user ID to be the owner of the zot service and its resources.

In this example, the user ID 'zot' is created with the adduser command, and resource ownership is assigned.

sudo adduser --no-create-home --disabled-password --gecos --disabled-login zot\n\nsudo mkdir -p /data/zot\nsudo chown -R zot:zot /data/zot\n\nsudo mkdir -p /var/log/zot\nsudo chown -R zot:zot /var/log/zot\n\nsudo chown -R root:root /etc/zot/\n

With the adduser options shown, the 'zot' user ID has no local directory. There is no ability to log into the zot user account, and the account has no finger information.

"},{"location":"install-guides/install-guide-linux/#step-6-start-zot","title":"Step 6: Start zot","text":"

Reload systemd config:

sudo systemctl daemon-reload\n

Enable and start the zot service with these commands:

sudo systemctl enable zot\nsudo systemctl start zot\n

Check if zot config is valid:

sudo -u zot zot verify /etc/zot/config.json\n

When the zot service has started, you can check its status with this command:

sudo systemctl status zot\n
"},{"location":"install-guides/install-guide-linux/#after-the-installation","title":"After the installation","text":"

If your zot registry server is public facing, we recommend that you test your TLS configuration using a service such as the Qualys SSL Server Test.

Refer to Configuring zot for further information about maintaining your zot registry server.

"},{"location":"install-guides/install-guide-linux/#configuration-file-options-and-recommendations","title":"Configuration file options and recommendations","text":"

The following zot configuration file (config.json) can be used as a template for your own installation. You can modify this file to suit your own environment.

Click here to view the sample configuration file. 
{\n  \"distSpecVersion\":\"1.0.1\",\n  \"storage\":{\n    \"dedupe\": true,\n    \"gc\": true,\n    \"gcDelay\": \"1h\",\n    \"gcInterval\": \"6h\",\n    \"rootDirectory\":\"/data/zot/\"\n  },\n  \"http\": {\n    \"address\":\"0.0.0.0\",\n    \"port\":\"443\",\n    \"realm\":\"zot\",\n    \"tls\": {\n      \"cert\": \"/etc/letsencrypt/live/zothub.io/fullchain.pem\",\n      \"key\": \"/etc/letsencrypt/live/zothub.io/privkey.pem\"\n    },\n    \"auth\": {\n      \"htpasswd\": {\n        \"path\": \"/etc/zot/htpasswd\"\n      },\n      \"failDelay\": 5\n    },\n    \"allowReadAccess\": true\n  },\n  \"log\":{\n    \"level\":\"debug\",\n    \"output\":\"/var/log/zot/zot.log\",\n    \"audit\":\"/var/log/zot/zot-audit.log\"\n  },\n  \"extensions\": {\n    \"search\": {\n      \"enable\": true,\n      \"cve\": {\n        \"updateInterval\": \"24h\"\n      }\n    },\n    \"sync\": {\n      \"enable\": false,\n      \"registries\": [\n        {\n          \"urls\": [\"https://mirror.gcr.io/library\"],\n          \"onDemand\": true,\n          \"maxRetries\": 3,\n          \"retryDelay\": \"5m\",\n          \"pollInterval\": \"6h\"\n        },\n        {\n          \"urls\": [\"https://docker.io/library\"],\n          \"onDemand\": true\n        }\n      ]\n    },\n    \"scrub\": {\n      \"interval\": \"24h\"\n    }\n  }\n}\n

Refer to Configuring zot for more details about configuration file options.

"},{"location":"install-guides/install-guide-linux/#tls-encryption","title":"TLS encryption","text":"

We recommend using a certificate authority such as Let\u2019s Encrypt that offers TLS encryption, as shown in this configuration example:

\"tls\": {\n  \"cert\": \"/etc/letsencrypt/live/zothub.io/fullchain.pem\",\n  \"key\": \"/etc/letsencrypt/live/zothub.io/privkey.pem\"\n}\n
"},{"location":"install-guides/install-guide-linux/#registry-synchronization","title":"Registry synchronization","text":"

The example file enables registry synchronization with two other container registries. In the example, the zot server synchronizes with the Google and Docker container registries, as shown here:

\"sync\": {\n  \"enable\": false,\n  \"registries\": [\n    {\n      \"urls\": [\"https://mirror.gcr.io/library\"],\n      \"onDemand\": true,\n      \"maxRetries\": 3,\n      \"retryDelay\": \"5m\",\n      \"pollInterval\": \"6h\"\n    },\n    {\n      \"urls\": [\"https://docker.io/library\"],\n      \"onDemand\": true\n    }\n  ]\n}\n
"},{"location":"user-guides/user-guide-datapath/","title":"Push and Pull Image Content","text":"

zot is an OCI image registry that allows you to store, manage, and share container images.

A zot registry can store and serve a variety of content, but the type of content may dictate your choice of a client tool.

For various content types, this document shows examples of using a third-party client tool that supports the content. The following table shows which content and client tools are demonstrated.

Content Type Client OCI images skopeo OCI images regclient (regctl) OCI images crane OCI artifacts oras Helm charts helm

zot is compatible with kubernetes/cri-o using docker:// transport, which is the default.

In the following examples, the zot registry is located at localhost, using port number 5000.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-skopeo-for-oci-images","title":"Common tasks using skopeo for OCI images","text":"

skopeo is a command line client that performs various operations on OCI container images and image repositories.

For detailed information about using skopeo, see the skopeo man page.

"},{"location":"user-guides/user-guide-datapath/#push-an-oci-image","title":"Push an OCI image","text":"

This example pushes the latest container image for the busybox application to a zot registry.

$ skopeo --insecure-policy copy --dest-tls-verify=false --multi-arch=all \\\n   --format=oci docker://busybox:latest \\\n   docker://localhost:5000/busybox:latest\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image","title":"Pull an OCI image","text":"

This example pulls the latest container image for the busybox application and stores the image to a local OCI-layout directory (/oci/images).

$ skopeo --insecure-policy copy --src-tls-verify=false --multi-arch=all \\\n   docker://localhost:5000/busybox:latest \\\n   oci:/oci/images:busybox:latest\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image-to-a-private-docker-registry","title":"Pull an OCI image to a private docker registry","text":"

This example pulls the latest container image for the busybox application and stores the image to a local private docker registry.

$ skopeo --insecure-policy copy --src-tls-verify=false --multi-arch=all \\\n   docker://localhost:5000/busybox:latest \\\n   docker://localhost:5000/busybox:latest\n
Click here to view an example of pushing and pulling an image using skopeo.

"},{"location":"user-guides/user-guide-datapath/#authentication","title":"Authentication","text":"

In these examples, authentication is disabled for the source and destination. You can enable authentication by changing the command line options as follows:

--src-tls-verify=true\n--dest-tls-verify=true\n

You can also add credentials for authenticating with a source or destination repository:

--src-creds username:password\n--dest-creds username:password\n
"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-regclient-for-oci-images","title":"Common tasks using regclient for OCI images","text":"

regclient is a client interface that performs various operations on OCI container images and image repositories. The command line interface for regclient is regctl.

For detailed information about regctl commands, see the regctl Documentation.

"},{"location":"user-guides/user-guide-datapath/#push-an-oci-image_1","title":"Push an OCI image","text":"

This example pushes version 1.20 of golang to a tools repository within the registry.

$ regctl registry set --tls=disabled localhost:5000\n$ regctl image copy ocidir://path/to/golang:1.20 localhost:5000/tools\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image_1","title":"Pull an OCI image","text":"

This example pulls version 1.20 of golang to a local OCI-layout directory.

$ regctl image copy localhost:5000/tools ocidir://path/to/golang:1.20\n
"},{"location":"user-guides/user-guide-datapath/#list-all-repositories-in-registry","title":"List all repositories in registry","text":"

This example list all repositories in the registry.

$ regctl repo ls localhost:5000\n
"},{"location":"user-guides/user-guide-datapath/#list-tags","title":"List tags","text":"

This example lists all tags in the tools repository within the registry.

$ regctl tag ls localhost:5000/tools\n
"},{"location":"user-guides/user-guide-datapath/#pull-and-push-manifest","title":"Pull and push manifest","text":"

This example pulls and pushes the manifest in the tools repository within the registry.

$ regctl manifest get localhost:5000/tools --format=raw-body\n$ regctl manifest put localhost:5000/tools:1.0.0 \\\n--format oci --content-type application/vnd.oci.image.manifest.v1+json \\\n--format oci\n
"},{"location":"user-guides/user-guide-datapath/#authentication_1","title":"Authentication","text":"

In the preceding examples, TLS authentication with the zot registry was disabled by the following command:

$ regctl registry set --tls=disabled localhost:5000\n

This command allows regctl to accept an HTTP response from the zot server. If TLS authentication is enabled on the zot registry server, you can omit this command from your regctl session.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-oras-for-oci-artifacts","title":"Common tasks using oras for OCI artifacts","text":"

ORAS (OCI Registry As Storage) is a command line client for storing OCI artifacts on OCI repositories.

For detailed information about the oras commands in these examples, see the ORAS CLI documentation.

"},{"location":"user-guides/user-guide-datapath/#push-an-artifact","title":"Push an artifact","text":"

This example pushes version 2 of an artifact file named hello-artifact to a zot registry.

$ oras push --plain-http localhost:5000/hello-artifact:v2 \\\n        --config config.json:application/vnd.acme.rocket.config.v1+json \\\n        artifact.txt:text/plain -d -v\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-artifact","title":"Pull an artifact","text":"

This example pulls version 2 of an artifact file named hello-artifact from a zot registry.

$ oras pull --plain-http localhost:5000/hello-artifact:v2 -d -v\n
Click here to view an example of pushing and pulling an artifact using oras.

"},{"location":"user-guides/user-guide-datapath/#attach-a-reference","title":"Attach a reference","text":"
$ echo '{\"artifact\": \"localhost:5000/hello-artifact:v2\", \"signature\": \"pat hancock\"}' > signature.json\n\n$ oras push localhost:5000/hello-artifact \\\n  --artifact-type 'signature/example' \\\n  --subject localhost:5000/hello-artifact:v2 \\\n  ./signature.json:application/json\n\n$ oras discover -o tree localhost:5000/hello-artifact:v2\n
"},{"location":"user-guides/user-guide-datapath/#authentication_2","title":"Authentication","text":"

To authenticate with the zot server, log in at the start of your session using the following command:

$ oras login -u myUsername -p myPassword localhost:5000\n

You can also add credentials in the push or pull commands as in this example:

$ oras pull -u myUsername -p myPassword localhost:5000/hello-artifact:v2 -d -v\n

For additional authentication options, including interactive credential entry and disabling TLS, see the ORAS authentication documentation.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-helm-for-helm-charts","title":"Common tasks using helm for helm charts","text":"

Helm is a package manager for Kubernetes. Among many other capabilities, helm can store and retrieve helm charts on OCI image repositories.

For detailed information about the helm commands in these examples, see Commands for working with registries in the helm documentation.

"},{"location":"user-guides/user-guide-datapath/#push-a-helm-chart","title":"Push a helm chart","text":"

This example pushes version 1.2.3 of a zot helm chart to a zot-chart repository within the registry.

$ helm package path/to/helm-charts/charts/zot\n$ helm push zot-1.2.3.tgz oci://localhost:5000/zot-chart\n
"},{"location":"user-guides/user-guide-datapath/#pull-a-helm-chart","title":"Pull a helm chart","text":"

This example pulls version 1.2.3 of a zot helm chart from a zot-chart repository within the registry.

$ helm pull oci://localhost:5000/zot-chart/zot --version 1.2.3\n
"},{"location":"user-guides/user-guide-datapath/#authentication_3","title":"Authentication","text":"

To authenticate with the zot server, log in at the start of your session using the following command:

$ helm registry login -u myUsername localhost:5000\n

You will be prompted to manually enter a password.

"},{"location":"user-guides/user-guide-datapath/#common-tasks-using-crane-for-oci-images","title":"Common tasks using crane for OCI images","text":"

crane is an open-source project that provides a command-line interface (CLI) for interacting with container registries, such as Docker Hub and Google Container Registry.

For detailed information about crane commands, see the crane Documentation.

"},{"location":"user-guides/user-guide-datapath/#push-an-oci-image_2","title":"Push an OCI image","text":"

This example pushes the latest container image for the alpine application to a registry.

$ crane --insecure push \\\n   oci/images/alpine:latest \\\n   localhost:5000/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#pull-an-oci-image_2","title":"Pull an OCI image","text":"

This example pulls the latest container image for the alpine application and stores the image to a local OCI-layout directory (/oci/images).

$ crane --insecure pull \\\n   --format oci \\\n   localhost:5000/alpine:latest \\\n   oci/images/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#copy-an-oci-image-to-a-private-docker-registry","title":"Copy an OCI image to a private docker registry","text":"

This example pulls the latest container image for the alpine application and stores the image to a local private docker registry.

$ crane --insecure copy \\\n   alpine:latest \\\n   localhost:5000/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#list-tags_1","title":"List tags","text":"

This example lists all tags in the alpine image within the registry.

$ crane ls localhost:5000/alpine\n
"},{"location":"user-guides/user-guide-datapath/#find-the-digest-of-an-image","title":"Find the digest of an image","text":"

This example gets the digest of the alpine image within the registry.

$ crane digest localhost:5000/alpine:latest\n
"},{"location":"user-guides/user-guide-datapath/#authentication_4","title":"Authentication","text":"

To authenticate with the registry server, log in at the start of your session using the following command:

$ crane auth login -u myUsername localhost:5000\n
"},{"location":"user-guides/user-guide-gui/","title":"Use the Web Interface to Find Images","text":"

Using a browser, you can browse a zot repository for container images and artifacts. The web interface also provides the commands for downloading an image using popular third-party tools.

If a zot registry is built with the optional zui package, the registry has a web interface.

"},{"location":"user-guides/user-guide-gui/#access-the-registry","title":"Access the registry","text":"

Depending on the security configuration of the zot registry, you might need to authenticate before being given access.

The initial page of the registry displays a sampling of the most popular images and recently updated images. To view all available images in the registry, click the View all link in the upper right of the page to go to the /explore page.

Wherever an image name appears, two icons follow the name, indicating the results of the vulnerability scan and the signature status. These icons are described in Icons and their meanings.

"},{"location":"user-guides/user-guide-gui/#find-an-image","title":"Find an image","text":"

To assist you in finding images specific to your requirements, the /explore page provides several sorting options along with faceted navigation in addition to a general search box.

When you locate the desired image, click its tile.

"},{"location":"user-guides/user-guide-gui/#inspect-the-image-properties","title":"Inspect the image properties","text":"

The OVERVIEW tab of the initial image description page contains a brief description of the image along with several details, such as the repository URL, number of downloads, last published, size, and license type.

Click the TAGS tab to view the available versions of the image.

Click the tag link of the desired version of the image. In the resulting page, you can view detailed information about the image, including its digest hash, and you can obtain a command to pull the image from the repository.

Tabs on this page provide the following information:

Tab Description LAYERS The build command and the digest hash USES A list of images used by this image USED BY A list of images that use this image VULNERABILITIES A list of known vulnerabilities

From the LAYERS tab, click Details to view an example of the image build command and the layer's digest hash.

"},{"location":"user-guides/user-guide-gui/#pull-an-image","title":"Pull an image","text":"

After opening the tag link of the desired image, click the Pull Image drop-down list to display the available pull commands. Docker, podman, and skopeo image management tools are supported.

Select a tool and click the pages icon next to the command to copy the full command to your clipboard. An example of the pull command using podman is:

podman pull zothub.io/c3/debian/base-amd64:bullseye

Paste the pull command into your terminal to pull the image.

For information about using image management tools to pull images, see Push and Pull Image Content.

"},{"location":"user-guides/user-guide-gui/#adding-bookmarks","title":"Adding Bookmarks","text":"

To mark an image so that it can be easily found later, click the bookmark icon on the image page. Bookmarked images appear in search queries when the Bookmarked option is enabled.

The bookmark icon before selection:

The bookmark icon after selection:

"},{"location":"user-guides/user-guide-gui/#icons-and-their-meanings","title":"Icons and their meanings","text":"

These icons appear next to the image name, indicating the results of the vulnerability scan and the signature status.

Icon Description A vulnerability scan of the image found no vulnerabilities A vulnerability scan of the image failed(See severity icon in VULNERABILITIES tab) Critical severity High severity Medium severity Low severity The image signature is verified The image signature is not verified The image is not bookmarked by the user The image is bookmarked by the user"},{"location":"user-guides/zli/","title":"Using the command line interface (zli)","text":"

zli: The command line tool for zot servers

"},{"location":"user-guides/zli/#what-is-zli","title":"What is zli?","text":"

zli is a binary that implements a set of command line commands for interacting with the zot registry server.

We recommend installing zli when you install zot.

"},{"location":"user-guides/zli/#how-to-get-zli","title":"How to get zli","text":"

zli is hosted with zot on GitHub at project-zot. From GitHub, you can download the zli binary or you can build zli from the source.

"},{"location":"user-guides/zli/#supported-platforms","title":"Supported platforms","text":"

zli 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"},{"location":"user-guides/zli/#downloading-zli-binaries","title":"Downloading zli binaries","text":"

You can 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 OS and architecture from the Supported platforms table. For example, the binary for an Intel-based MacOS server is zli-darwin-amd64.

"},{"location":"user-guides/zli/#building-zli-from-source","title":"Building zli from source","text":"

To build the zli binary, copy or clone the zot project from GitHub and execute the make cli command in the zot directory. Use the same command options that you used to build zot, as shown:

make OS=os ARCH=architecture cli

For example, the following command builds zli for an Intel-based MacOS server:

make OS=darwin ARCH=amd64 cli\n

In this example, the resulting executable file is zli-darwin-amd64 in the zot/bin directory.

"},{"location":"user-guides/zli/#common-tasks-using-zli","title":"Common tasks using zli","text":"

This section includes examples of common zot server tasks using the zli command line interface. For a detailed listing of zli commands, see the zli Command Reference in this guide.

The original filename of the zli executable file will reflect the build options, such as zli-linux-amd64. For convenience, you can rename the executable to simply zli. The instructions and examples in this guide use zli as the name of the executable file.

"},{"location":"user-guides/zli/#adding-a-zot-server-url","title":"Adding a zot server URL","text":"

You can modify the zot server configuration using the zli config add command. This example adds a zot server URL with an alias of remote-zot:

$ bin/zli config add remote-zot https://server-example:8080\n

Use the zli config command to list all configured URLs with their aliases:

$ bin/zli config -l\n\nremote-zot   https://server-example:8080\nlocal        http://localhost:8080\n
"},{"location":"user-guides/zli/#listing-images","title":"Listing images","text":"

You can list all images hosted on a zot server using the zli image list command with the server\u2019s alias:

$ bin/zli image list --config local\n\nREPOSITORY        TAG       OS/ARCH         DIGEST      SIGNED      SIZE        \nalpine            latest    linux/amd64     3fc10231    false       84MB        \nbusybox           latest    linux/amd64     9172c5f6    false       2.2MB\n

You can also filter the image list to view a specific image by specifying the image name:

$ bin/zli image name busybox:latest --config local\n\nREPOSITORY        TAG       OS/ARCH         DIGEST      SIGNED      SIZE              \nbusybox           latest    linux/amd64     9172c5f6    false       2.2MB\n
"},{"location":"user-guides/zli/#scanning-images-for-known-vulnerabilities","title":"Scanning images for known vulnerabilities","text":"

Using the zli cve list command, you can fetch the CVE (Common Vulnerabilities and Exposures) information for images hosted on the zot server. This example shows how to learn which images are affected by a specific CVE:

$ bin/zli cve affected CVE-2017-9935 --config remote-zot\n\nIMAGE NAME        TAG               DIGEST    SIZE\nc3/openjdk-dev    commit-5be4d92    ac3762e2  335MB\n

This example displays a list of all CVEs affecting a specific image:

$ bin/zli cve list c3/openjdk-dev:0.3.19 --config remote-zot\n\nID                SEVERITY  TITLE\nCVE-2015-8540     LOW       libpng: underflow read in png_check_keyword()\nCVE-2017-16826    LOW       binutils: Invalid memory access in the coff_s...\n

This example displays the detailed CVEs in JSON format:

$ bin/zli cve list c3/openjdk-dev:0.3.19 --config remote-zot -f json\n{\n  \"Tag\": \"0.3.19\",\n  \"CVEList\": [\n    {\n      \"Id\": \"CVE-2019-17006\",\n      \"Severity\": \"MEDIUM\",\n      \"Title\": \"nss: Check length of inputs for cryptographic primitives\",\n      \"Description\": \"A vulnerability was discovered in nss where input text length was not checked when using certain cryptographic primitives. This could lead to a heap-buffer overflow resulting in a crash and data leak. The highest threat is to confidentiality and integrity of data as well as system availability.\",\n      \"PackageList\": [\n        {\n          \"Name\": \"nss\",\n          \"InstalledVersion\": \"3.44.0-7.el7_7\",\n          \"FixedVersion\": \"Not Specified\"\n        },\n        {\n          \"Name\": \"nss-sysinit\",\n          \"InstalledVersion\": \"3.44.0-7.el7_7\",\n          \"FixedVersion\": \"Not Specified\"\n        },\n        {\n          \"Name\": \"nss-tools\",\n          \"InstalledVersion\": \"3.44.0-7.el7_7\",\n          \"FixedVersion\": \"Not Specified\"\n        }]\n    }]\n}\n

This example lists all images on a specific zot server that are affected by a specific CVE:

$ bin/zli cve affected --config remote-zot CVE-2017-9935 --repo c3/openjdk-dev\n\nIMAGE NAME        TAG               DIGEST    SIZE\nc3/openjdk-dev    commit-2674e8a    71046748  338MB\nc3/openjdk-dev    commit-bd5cc94    0ab7fc76\n

This example lists all images on a specific zot server where the CVE has been fixed:

$ bin/zli cve fixed c3/openjdk-dev CVE-2017-9935 --config remote-zot\n\nIMAGE NAME        TAG                       DIGEST    SIZE\nc3/openjdk-dev    commit-2674e8a-squashfs   b545b8ba  321MB\nc3/openjdk-dev    commit-d5024ec-squashfs   cd45f8cf  321MB\n
"},{"location":"user-guides/zli/#listing-repositories","title":"Listing repositories","text":"

You can list all repositories hosted on a zot server using the zli repo command with the server\u2019s alias:

Searching... \ud83c\udf0d\n\nREPOSITORY NAME\nalpine\nbusybox\n
"},{"location":"user-guides/zli/#searching-for-repositories-and-images","title":"Searching for repositories and images","text":"

You can locate repositories and images hosted on a zot server using the zli search command.

This example searches the zot registry named 'local' for a repository whose name contains the substring 'ng':

$ bin/zli search query ng --config local\n\nNAME            SIZE        LAST UPDATED                             DOWNLOADS   STARS\nnginx           794MB       2023-03-01 18:44:17.707690369 +0000 UTC  0           0\nmongo           232MB       2022-10-18 15:03:40.7646203 +0300 +0300  0           0\ngolang          1.1GB       2023-06-22 00:32:38.613354854 +0000 UTC  0           0\n

This example searches the zot registry named 'local' for a repository named 'nginx'. Because the repository name is followed by a colon, the search results must match the name exactly. 

$ bin/zli search query nginx: --config local\n\nREPOSITORY  TAG          OS/ARCH         DIGEST      SIGNED      SIZE\nnginx       1.23.1       linux/amd64     d2ad9089    true        57MB\nnginx       latest       *               c724afdf    true        448MB\n                         linux/amd64     009c6fda    false       57MB\n                         linux/arm/v5    1d5d4f53    false       54MB\n                         linux/arm/v7    f809744c    false       50MB\n                         linux/arm64/v8  ebb807a9    false       56MB\n                         linux/386       19cf4b3c    false       59MB\n                         linux/mips64le  45ab60e6    false       55MB\n                         linux/ppc64le   89511bee    false       63MB\n                         linux/s390x     713b9329    false       55MB\nnginx       stable-perl  *               4383a0b8    true        534MB\n                         linux/amd64     308a37a0    false       68MB\n                         linux/arm/v5    0fb8fb71    false       64MB\n                         linux/arm/v7    6868f552    false       60MB\n                         linux/arm64/v8  aed72c86    false       66MB\n                         linux/386       5c7ed456    false       69MB\n                         linux/mips64le  546d2bae    false       65MB\n                         linux/ppc64le   7db02f5a    false       74MB\n                         linux/s390x     800fd86f    false       66MB\n
"},{"location":"user-guides/zli/#sorting-the-output-of-a-zli-command","title":"Sorting the output of a zli command","text":"

For a zli command that can result in a lengthy output list, you can use the command flag --sort-by <option> to cause the output to be sorted by a specified property of the output data. The available sorting criteria vary for different commands, but examples of sorting criteria options are described in the following table:

flag option criteria alpha-asc alphabetical, ascending alpha-dsc alphabetical, descending relevance quality of match severity severity of condition update-time timestamp

For a given command that results in an output list, you can see the available sorting criteria in the usage information returned by the --help flag. For example, bin/zli image name --help returns usage information containing the following line under \"Flags\":

--sort-by string Options for sorting the output: [update-time, alpha-asc, alpha-dsc] (default \"alpha-asc\")

According to this information, the list of image names returned by the bin/zli image name command can be sorted in order of alphabetical ascending, alphabetical descending, or the timestamp of the latest update of the image. The default sorting method for this command, if no --sort-by flag is present, is alphabetical ascending.

"},{"location":"user-guides/zli/#command-reference","title":"Command reference","text":"

This section provides detailed usage information for basic first-level zli commands. Many zli commands also support subcommands, which are listed as \"Available Commands\" in each command description. For example, zli search can be extended with either the query or subject subcommand. To see the detailed usage for each subcommand, type the command with the subcommand and append --help, such as zli search query --help. The zli search description below includes the subcommand help as an example.

"},{"location":"user-guides/zli/#zli","title":"zli","text":"
$ bin/zli --help\n\nUsage:\n  zli [flags]\n  zli [command]\n\nAvailable Commands:\n  completion  Generate the autocompletion script for the specified shell\n  config      Configure zot registry parameters for CLI\n  cve         Lookup CVEs in images hosted on the zot registry\n  help        Help about any command\n  image       List images hosted on the zot registry\n  repo        List all repositories\n  search      Search images and their tags\n\nFlags:\n  -h, --help      help for zli\n  -v, --version   show the version and exit\n\nUse \"zli [command] --help\" for more information about a command.\n
"},{"location":"user-guides/zli/#zli-completion","title":"zli completion","text":"

This command generates the autocompletion script for zli for the specified shell. See each subcommand\u2019s help for details on how to use the generated script.

$ bin/zli completion --help\n\nUsage:\n  zli completion [command]\n\nAvailable Commands:\n  bash        Generate the autocompletion script for bash\n  fish        Generate the autocompletion script for fish\n  powershell  Generate the autocompletion script for powershell\n  zsh         Generate the autocompletion script for zsh\n\nFlags:\n  -h, --help   help for completion\n\nUse \"zli completion [command] --help\" for more information about a command.\n
"},{"location":"user-guides/zli/#zli-config","title":"zli config","text":"

This command configures zot registry parameters for CLI.

$ bin/zli config --help\n\nUsage:\n  zli config <config-name> [variable] [value] [flags]\n  zli config [command]\n\nExamples:\n  zli config add main https://zot-foo.com:8080\n  zli config --list\n  zli config main url\n  zli config main --list\n  zli config remove main\n\nAvailable Commands:\n  add         Add configuration for a zot registry\n  remove      Remove configuration for a zot registry\n\nFlags:\n  -h, --help    help for config\n  -l, --list    List configurations\n      --reset   Reset a variable value\n\nUse \"zli config [command] --help\" for more information about a command.\n\nUseful variables:\n  url       zot server URL\n  showspinner   show spinner while loading data [true/false]\n  verify-tls    enable TLS certificate verification of the server [default: true]\n
"},{"location":"user-guides/zli/#zli-cve","title":"zli cve","text":"

This command lists CVEs (Common Vulnerabilities and Exposures) of images hosted on the zot registry

$ ./zli cve --help\n\nUsage:\n  zli cve [command]\n\nAvailable Commands:\n  affected    List images affected by a CVE\n  fixed       List tags where a CVE is fixedRetryWithContext\n  list        List CVEs by REPO:TAG or REPO@DIGEST\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n  -h, --help            help for cve\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nUse \"zli cve [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-image","title":"zli image","text":"

This command lists images hosted on the zot registry.

$ ./zli image --help\n\nUsage:\n  zli image [command]\n\nAvailable Commands:\n  base        List images that are base for the given image\n  cve         List all CVE's of the image\n  derived     List images that are derived from given image\n  digest      List images that contain a blob(manifest, config or layer) with the given digest\n  list        List all images\n  name        List image details by name\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n  -h, --help            help for image\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nUse \"zli image [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-repo","title":"zli repo","text":"

This command lists all repositories in the zot registry.

$ ./zli repo --help\n\nUsage:\n  zli repo [command]\n\nAvailable Commands:\n  list        List all repositories\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -h, --help            help for repo\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n\nUse \"zli repo [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-search","title":"zli search","text":"

The search command allows smart searching for a repository by its name or for an image by its repo:tag.

$ ./zli search --help\n\nSearch repos or images\n\nUsage:\n  zli search [command]\n\nAvailable Commands:\n  query       Fuzzy search for repos and their tags.\n  subject     List all referrers for this subject.\n\nFlags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n  -h, --help            help for search\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nUse \"zli search [command] --help\" for more information about a command.\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-search-query","title":"zli search query","text":"
$ ./zli search query --help\n\nUsage:\n  zli search query [repo]|[repo:tag] [flags]\n\nExamples:\n# For repo search specify a substring of the repo name without the tag\n  zli search query \"test/repo\"\n\n# For image search specify the full repo name followed by the tag or a prefix of the tag.\n  zli search query \"test/repo:2.1.\"\n\nFlags:\n  -h, --help             help for query\n      --sort-by string   Options for sorting the output: [relevance, update-time, alpha-asc, alpha-dsc] (default \"relevance\")\n\nGlobal Flags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nRun 'zli config -h' for details on [config-name] argument\n
"},{"location":"user-guides/zli/#zli-search-subject","title":"zli search subject","text":"
$ ./zli search subject --help\n\nList all referrers for this subject. The subject can be specified by tag(repo:tag) or by digest\" or (repo@digest)\n\nUsage:\n  zli search subject [repo:tag]|[repo@digest] [flags]\n\nExamples:\n# For referrers search specify the referred subject using it's full digest or tag:\n  zli search subject \"repo@sha256:f9a0981...\"\n  zli search subject \"repo:tag\"\n\nFlags:\n  -h, --help             help for subject\n      --sort-by string   Options for sorting the output: [update-time, alpha-asc, alpha-dsc] (default \"alpha-asc\")\n\nGlobal Flags:\n      --config string   Specify the registry configuration to use for connection\n      --debug           Show debug output\n  -f, --format string   Specify output format [text/json/yaml]\n      --url string      Specify zot server URL if config-name is not mentioned\n  -u, --user string     User Credentials of zot server in \"username:password\" format\n      --verbose         Show verbose output\n\nRun 'zli config -h' for details on [config-name] argument\n
"}]} \ No newline at end of file diff --git a/v2.0.1/sitemap.xml b/v2.0.1/sitemap.xml index 5555ea8..bb6ff13 100644 --- a/v2.0.1/sitemap.xml +++ b/v2.0.1/sitemap.xml @@ -2,177 +2,177 @@ https://zotregistry.dev/v2.0.1/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/admin-guide/admin-configuration/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/admin-guide/admin-getting-started/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/authn-authz/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/benchmarking-with-zb/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/building-ci-cd-pipeline/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/clustering/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/graphql/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/kind-deploy/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/mirroring/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/monitoring/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/pprofiling/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/retention/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/security-posture/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/storage/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/verifying-signatures/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/articles/workflow/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/developer-guide/api-reference/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/developer-guide/api-user-guide/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/developer-guide/contributing/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/developer-guide/extensions-dev/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/developer-guide/onboarding/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/architecture/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/concepts/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/extensions/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/features/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/glossary/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/project/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/releases/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/general/whats-new/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/install-guides/install-guide-k8s/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/install-guides/install-guide-linux/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/user-guides/user-guide-datapath/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/user-guides/user-guide-gui/ - 2024-02-02 + 2024-02-22 daily https://zotregistry.dev/v2.0.1/user-guides/zli/ - 2024-02-02 + 2024-02-22 daily \ No newline at end of file diff --git a/v2.0.1/sitemap.xml.gz b/v2.0.1/sitemap.xml.gz index 394c109..89923af 100644 Binary files a/v2.0.1/sitemap.xml.gz and b/v2.0.1/sitemap.xml.gz differ diff --git a/v2.0.1/user-guides/user-guide-datapath/index.html b/v2.0.1/user-guides/user-guide-datapath/index.html index cee5dba..d953c87 100644 --- a/v2.0.1/user-guides/user-guide-datapath/index.html +++ b/v2.0.1/user-guides/user-guide-datapath/index.html @@ -52,4 +52,4 @@

List tags

This example lists all tags in the alpine image within the registry.

$ crane ls localhost:5000/alpine

Find the digest of an image

This example gets the digest of the alpine image within the registry.

$ crane digest localhost:5000/alpine:latest

Authentication

To authenticate with the registry server, log in at the start of your session using the following command:

$ crane auth login -u myUsername localhost:5000
-
Last update: September 13, 2023
\ No newline at end of file +
Last update: September 13, 2023
\ No newline at end of file diff --git a/v2.0.1/user-guides/user-guide-gui/index.html b/v2.0.1/user-guides/user-guide-gui/index.html index 70ed826..76300f0 100644 --- a/v2.0.1/user-guides/user-guide-gui/index.html +++ b/v2.0.1/user-guides/user-guide-gui/index.html @@ -1 +1 @@ - Use the Web Interface to Find Images - zotregistry.dev
Skip to content

Use the Web Interface to Find Images

👉 Using a browser, you can browse a zot repository for container images and artifacts. The web interface also provides the commands for downloading an image using popular third-party tools.

If a zot registry is built with the optional zui package, the registry has a web interface.

Access the registry

✏ Depending on the security configuration of the zot registry, you might need to authenticate before being given access.

The initial page of the registry displays a sampling of the most popular images and recently updated images. To view all available images in the registry, click the View all link in the upper right of the page to go to the /explore page.

screen-initial

💡 Wherever an image name appears, two icons follow the name, indicating the results of the vulnerability scan and the signature status. These icons are described in Icons and their meanings.

Find an image

To assist you in finding images specific to your requirements, the /explore page provides several sorting options along with faceted navigation in addition to a general search box.

  • Sorting criteria include relevance, most recently updated, alphabetical, and most downloaded.

  • Navigation facets include operating system, CPU architecture, and signature status.

screen-initial

When you locate the desired image, click its tile.

tile

Inspect the image properties

The OVERVIEW tab of the initial image description page contains a brief description of the image along with several details, such as the repository URL, number of downloads, last published, size, and license type.

Click the TAGS tab to view the available versions of the image.

screen-tags

Click the tag link of the desired version of the image. In the resulting page, you can view detailed information about the image, including its digest hash, and you can obtain a command to pull the image from the repository.

screen-layers

Tabs on this page provide the following information:

Tab Description
LAYERS The build command and the digest hash
USES A list of images used by this image
USED BY A list of images that use this image
VULNERABILITIES A list of known vulnerabilities

From the LAYERS tab, click Details to view an example of the image build command and the layer's digest hash.

layers-details

Pull an image

After opening the tag link of the desired image, click the Pull Image drop-down list to display the available pull commands. Docker, podman, and skopeo image management tools are supported.

pull-image

Select a tool and click the pages icon next to the command to copy the full command to your clipboard. An example of the pull command using podman is:

podman pull zothub.io/c3/debian/base-amd64:bullseye

Paste the pull command into your terminal to pull the image.

💡 For information about using image management tools to pull images, see Push and Pull Image Content.

Adding Bookmarks

To mark an image so that it can be easily found later, click the bookmark icon on the image page. Bookmarked images appear in search queries when the Bookmarked option is enabled.

The bookmark icon before selection:

The bookmark icon after selection:

Icons and their meanings

These icons appear next to the image name, indicating the results of the vulnerability scan and the signature status.

Icon Description
A vulnerability scan of the image found no vulnerabilities
A vulnerability scan of the image failed
(See severity icon in VULNERABILITIES tab)
      Critical severity
      High severity
      Medium severity
      Low severity
The image signature is verified
The image signature is not verified
The image is not bookmarked by the user
The image is bookmarked by the user
Last update: August 4, 2023
\ No newline at end of file + Use the Web Interface to Find Images - zotregistry.dev
Skip to content

Use the Web Interface to Find Images

👉 Using a browser, you can browse a zot repository for container images and artifacts. The web interface also provides the commands for downloading an image using popular third-party tools.

If a zot registry is built with the optional zui package, the registry has a web interface.

Access the registry

✏ Depending on the security configuration of the zot registry, you might need to authenticate before being given access.

The initial page of the registry displays a sampling of the most popular images and recently updated images. To view all available images in the registry, click the View all link in the upper right of the page to go to the /explore page.

screen-initial

💡 Wherever an image name appears, two icons follow the name, indicating the results of the vulnerability scan and the signature status. These icons are described in Icons and their meanings.

Find an image

To assist you in finding images specific to your requirements, the /explore page provides several sorting options along with faceted navigation in addition to a general search box.

  • Sorting criteria include relevance, most recently updated, alphabetical, and most downloaded.

  • Navigation facets include operating system, CPU architecture, and signature status.

screen-initial

When you locate the desired image, click its tile.

tile

Inspect the image properties

The OVERVIEW tab of the initial image description page contains a brief description of the image along with several details, such as the repository URL, number of downloads, last published, size, and license type.

Click the TAGS tab to view the available versions of the image.

screen-tags

Click the tag link of the desired version of the image. In the resulting page, you can view detailed information about the image, including its digest hash, and you can obtain a command to pull the image from the repository.

screen-layers

Tabs on this page provide the following information:

Tab Description
LAYERS The build command and the digest hash
USES A list of images used by this image
USED BY A list of images that use this image
VULNERABILITIES A list of known vulnerabilities

From the LAYERS tab, click Details to view an example of the image build command and the layer's digest hash.

layers-details

Pull an image

After opening the tag link of the desired image, click the Pull Image drop-down list to display the available pull commands. Docker, podman, and skopeo image management tools are supported.

pull-image

Select a tool and click the pages icon next to the command to copy the full command to your clipboard. An example of the pull command using podman is:

podman pull zothub.io/c3/debian/base-amd64:bullseye

Paste the pull command into your terminal to pull the image.

💡 For information about using image management tools to pull images, see Push and Pull Image Content.

Adding Bookmarks

To mark an image so that it can be easily found later, click the bookmark icon on the image page. Bookmarked images appear in search queries when the Bookmarked option is enabled.

The bookmark icon before selection:

The bookmark icon after selection:

Icons and their meanings

These icons appear next to the image name, indicating the results of the vulnerability scan and the signature status.

Icon Description
A vulnerability scan of the image found no vulnerabilities
A vulnerability scan of the image failed
(See severity icon in VULNERABILITIES tab)
      Critical severity
      High severity
      Medium severity
      Low severity
The image signature is verified
The image signature is not verified
The image is not bookmarked by the user
The image is bookmarked by the user
Last update: August 4, 2023
\ No newline at end of file diff --git a/v2.0.1/user-guides/zli/index.html b/v2.0.1/user-guides/zli/index.html index 2f85e0d..9e06f75 100644 --- a/v2.0.1/user-guides/zli/index.html +++ b/v2.0.1/user-guides/zli/index.html @@ -293,4 +293,4 @@ --verbose Show verbose output Run 'zli config -h' for details on [config-name] argument -
Last update: September 22, 2023
\ No newline at end of file +
Last update: September 22, 2023
\ No newline at end of file diff --git a/versions.json b/versions.json index 3ca0e95..8ed6485 100644 --- a/versions.json +++ b/versions.json @@ -1 +1 @@ -[{"version": "v2.0.1", "title": "v2.0.1", "aliases": ["latest", "zot"]}, {"version": "v2.0.0", "title": "v2.0.0", "aliases": []}, {"version": "v1.4.3", "title": "v1.4.3", "aliases": []}] \ No newline at end of file +[{"version": "v2.0.1", "title": "v2.0.1", "aliases": ["zot", "latest"]}, {"version": "v2.0.0", "title": "v2.0.0", "aliases": []}, {"version": "v1.4.3", "title": "v1.4.3", "aliases": []}] \ No newline at end of file