Merge branch 'main' into docs_mishield_workflow

.wordlist.txt

@@ -10,6 +10,7 @@ authz
 autocompletion
 backend
 backends
+balancer
 bcrypt
 benchmarking
 blackbox
@@ -59,6 +60,7 @@ freebsd
 FreeBSD
 fullname
 gc
+gcInterval
 gcr
 ghcr
 github
@@ -76,6 +78,7 @@ htpasswd
 html
 http
 https
+ImageTrust
 inlinehilite
 in-place
 io
@@ -87,6 +90,7 @@ kubectl
 kubelet
 kubernetes
 Kubernetes
+ldap
 LDAP
 licensable
 LICENSE
@@ -104,6 +108,7 @@ MacOS
 maxRetries
 md
 MERCHANTABILITY
+mgmt
 minify
 mkdocs
 mTLS
@@ -115,6 +120,7 @@ NodePort
 OAuth
 OCI
 OIDC
+oidc
 onboarding
 Onboarding
 onDemand
@@ -160,6 +166,9 @@ SSL
 stacker
 stripPrefix
 stylesheets
+subcommand
+subcommands
+subcommand's
 subdirectory
 sublicense
 subpath
@@ -179,6 +188,9 @@ transactional
 trivy
 Trivy
 truststore
+truststores
+trustStore
+trustStores
 tunable
 twemoji
 UI

docs/admin-guide/admin-configuration.md

@@ -64,7 +64,9 @@ With a full (not minimal) zot image, the following extension features can be ena
     "sync": {},
     "search": {},
     "scrub": {},
-    "lint": {}
+    "lint": {},
+    "trust": {},
+    "ui": {}
   }
 }
 ```
@@ -80,10 +82,18 @@ The following features are configured under the `extensions` attribute.
 -   [Search](#search_config)
 -   [Scrub](#scrub_config)
 -   [Lint](#lint_config)
+-   [ImageTrust](#trust_config)
+-   [UI](#ui_config)
 
 An extension feature is usually enabled by the presence of the feature’s 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`.
 
-> :pencil2: An additional extension feature, [User Preferences](#userprefs_config), is enabled when the Search feature is enabled, and is not configured under the `extensions` section.
+> :pencil2: Two API-only extensions, [User Preferences](#userprefs_config) and [Mgmt](#mgmt_config), are not enabled or configured under the `extensions` section of the configuration file.  These API-only extensions are enabled as follows:
+>
+> - [Mgmt](#mgmt_config) is enabled when the `Search` extension is enabled.
+>
+> - [User Preferences](#userprefs_config) is enabled when both the `Search` and `UI` extensions are enabled. 
+
+#### Enabling and disabling extensions
 
 Following is an example of enabling or disabling a feature in the `extensions` section. The scrub feature is enabled in these two configurations:
 
@@ -116,8 +126,10 @@ The scrub feature is disabled in these two configurations:
 }
 ```
 
-> :pencil2:
-> 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_](../developer-guide/extensions-dev.md).
+#### Developing custom extensions
+
+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_](../developer-guide/extensions-dev.md).
+
 
 <a name="network_config"></a>
 
@@ -327,7 +339,7 @@ For detailed information about clustering with zot, see [zot Clustering](../arti
 
 ## Syncing and mirroring registries
 
-A zot registry can mirror one or more upstream OCI registries, including popular cloud registries such as [Docker Hub](https://hub.docker.com/) and [Google Container Registry](gcr.io).  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.
+A zot registry can mirror one or more upstream OCI registries, including popular cloud registries such as [Docker Hub](https://hub.docker.com/) and [Google Container Registry](https://cloud.google.com/artifact-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.
 
@@ -361,6 +373,52 @@ The following table lists the configurable attributes of the `lint` extension.
 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.
 
 
+<a name="trust_config"></a>
+
+## Verifying the signatures of uploaded images
+
+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:
+
+```json
+"extensions": {
+  "trust": {
+    "enable": true,
+    "cosign": true,
+    "notation": true
+  }
+}
+```
+
+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](../articles/verifying-signatures.md).
+
+
+<a name="ui_config"></a>
+
+## Enabling the registry's graphical user interface
+
+Using the zot [graphical user interface (GUI)](../user-guides/user-guide-gui.md), 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:
+
+```json
+"extensions": {
+  "ui": {
+    "enable": true
+  }
+}
+```
+
+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`. |
+
+
 <a name="scrub_config"></a>
 
 ## Scrubbing the image registry
@@ -414,12 +472,12 @@ Add the `search` attribute under `extensions` in the configuration file to enabl
 
 ``` json
 "extensions": {
-    "search": {
-        "enable": true,
-        "cve": {
-            "updateInterval": "2h"
-        }
+  "search": {
+    "enable": true,
+    "cve": {
+      "updateInterval": "2h"
     }
+  }
 }
 ```
 
@@ -437,7 +495,7 @@ The following table lists the configurable attributes for enhanced search.
 
 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` extension is enabled. There are no other configuration file fields for this extension.
+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.
 

docs/admin-guide/admin-getting-started.md

@@ -29,7 +29,7 @@ possible on any platform that supports the `golang` toolchain.
 | freebsd | amd64 | Intel-based FreeBSD<sup>*</sup>    |
 | freebsd | arm64 | ARM-based FreeBSD<sup>*</sup>      |
 
-<sup>*</sup> **NOTE:** While binary images are available for FreeBSD, building container images is not supported at this time.
+<sup>*</sup> NOTE: While binary images are available for FreeBSD, building container images is not supported at this time.
 
 #### About binary images
 
@@ -77,7 +77,7 @@ install a zot binary image, as in the following examples.
 
     podman run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64:latest
 
-    podman run -p 5000:5000 ghcr.io/project-zot/zot-linux-amd64-minimal:latest
+    podman run -p 5000:5000 ghcr.io/project-zot/zot-minimal-linux-amd64:latest
 
 <details>
   <summary markdown="span">Click here to view an example of deploying using podman.</summary>
@@ -94,7 +94,7 @@ install a zot binary image, as in the following examples.
 
 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>.
+image registry at `http://localhost:5000`.
 
 <details>
   <summary markdown="span">Click here to view an example of deploying using docker.</summary>
@@ -109,12 +109,11 @@ image registry at <http://localhost:5000>.
 
 #### Prerequisites
 
-##### Install golang (1.17+)
+##### Install golang
 
-The zot project requires `golang 1.17` or newer. You can follow [these
-instructions](https://go.dev/learn/) to install the `golang` toolchain.
-After installation, make sure that the `path` environment variable or
-your IDE can find the toolchain.
+Follow the [golang instructions](https://go.dev/learn/) to install the `golang` toolchain. After installation, make sure that the `path` environment variable or your IDE can find the toolchain.
+
+> :pencil2: You must use a golang version of at least the minimum specified in [go.mod](https://github.com/project-zot/zot/go.mod) or the build will fail.
 
 #### Building an executable binary from source
 
@@ -169,8 +168,8 @@ runs the latest zot by running the following command:
 
 **with Docker**
 
-A sample Dockerfile is provided on the [zot project
-page](https://github.com/project-zot/zot/tree/main/build/Dockerfile) in
+A [sample Dockerfile](https://github.com/project-zot/zot/tree/main/build/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:

docs/articles/authn-authz.md

@@ -282,6 +282,10 @@ In this example, five policies are defined:
 
 -   An admin policy (`adminPolicy`) gives the user "admin" global authorization to read, create, update, or delete content in any repository, overriding all other policies.
 
+:pencil2:  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.
+
+<a name="_social-login"></a>
+
 ### Social login using OpenID/OAuth2 
 
 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)](https://openid.net/connect/) protocols. 
@@ -291,7 +295,7 @@ Several social login providers are supported by zot:
 - github
 - google
 - gitlab
-- dex
+- oidc (for example, dex)
 
 The following example shows the zot configuration for these providers:
 
@@ -318,7 +322,7 @@ The following example shows the zot configuration for these providers:
             "clientsecret": <client_secret>,
             "scopes": ["openid", "read_api", "read_user", "profile", "email"]
           },
-          "dex": {
+          "oidc": {
             "issuer": "http://<zot-server>:5556/dex",
             "clientid": <client_id>,
             "clientsecret": <client_secret>,
@@ -332,39 +336,39 @@ The following example shows the zot configuration for these providers:
 }
 ```
 
-A client logging into zot by social login must specify a supported OpenID/OAuth2 provider as a URL query parameter.
+#### Using Google, GitHub, or GitLab
 
-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. 
+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
+    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
+    http://zot.example.com:8080/auth/callback/github
 
 :pencil2: If your network policy doesn't allow inbound connections, the callback will not work and this authentication method will fail.
 
 #### Using dex
 
-[dex](https://dexidp.io/) is an identity service that uses OpenID Connect to drive authentication for client apps, such as zot.
+[dex](https://dexidp.io/) 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:
 
 ```yaml
 staticClients:
   - id: zot-client
     redirectURIs:
-      - 'http://zot-example.com:8080/auth/callback/dex'
+      - 'http://zot.example.com:8080/auth/callback/oidc'
     name: 'zot'
     secret: ZXhhbXBsZS1hcHAtc2VjcmV0
 ```
@@ -376,7 +380,8 @@ In the zot configuration file, configure dex as an OpenID auth provider as in th
     "auth": {
       "openid": {
         "providers": {
-          "dex": {
+          "oidc": {
+            "name": "Corporate SSO",
             "issuer": "http://<zot-server>:5556/dex",
             "clientid": "zot-client",
             "clientsecret": "ZXhhbXBsZS1hcHAtc2VjcmV0",
@@ -389,8 +394,32 @@ In the zot configuration file, configure dex as an OpenID auth provider as in th
   }
 ```
 
-A user logging in to zot using dex OpenID authentication sends a URL such as the following example:
+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](https://dexidp.io/docs/getting-started/) documentation.
+
+
+#### Using OpenID/OAuth2 when zot is behind a proxy or load balancer
 
-`http://zot-example.com:8080/auth/login?provider=dex`
+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:
 
-For detailed information about configuring dex service, see the dex [Getting Started](https://dexidp.io/docs/getting-started/) documentation.
+```json
+  "http": {
+    "address": "0.0.0.0",
+    "port": "8080",
+    "externalUrl": "https://zot.example.com",
+    "auth": {
+      "openid": {
+        "providers": {
+          "github": {
+            "clientid": <client_id>,
+            "clientsecret": <client_secret>,
+            "scopes": ["read:org", "user", "repo"]
+          }
+        }
+      }
+    }
+  }
+```

docs/articles/kind-deploy.md

@@ -111,8 +111,9 @@ Use `skopeo` to copy (pull) a "hello" app from the Google Container Registry (gc
 
 ```shell
 # copy an image
-skopeo copy --format=oci --dest-tls-verify=false docker://gcr.io/ \
-google-samples/hello-app:1.0 docker://localhost:5001/hello-app:1.0
+skopeo copy --format=oci --dest-tls-verify=false \
+docker://gcr.io/google-samples/hello-app:1.0 \
+docker://localhost:5001/hello-app:1.0
 
 # deploy the image
 kubectl create deployment hello-server --image=localhost:5001/hello-app:1.0