docs: revised for comments

Signed-off-by: mbshields <[email protected]>

docs/articles/clustering.md

@@ -16,7 +16,7 @@ aggregate network throughput.
 
 ![504569](../assets/images/504569.jpg){width="500"}
 
-> :pencil2: Beginning with zot release v2.1.0, you can design a highly scalable cluster that does not require configuring the load balancer to direct repository queries to specific zot instances within the cluster. See [Easy scaling of a zot cluster](scaleout.md). This is the preferred method if you are running v2.1.0 or later.
+> :pencil2: Beginning with zot release v2.1.0, you can design a highly scalable cluster that does not require configuring the load balancer to direct repository queries to specific zot instances within the cluster. See [Scale-out clustering](scaleout.md). Scale-out clustering is the preferred method if you are running v2.1.0 or later.
 
 Clustering is supported in both bare-metal and Kubernetes environments.
 > :pencil2:
@@ -59,8 +59,8 @@ zot maintains two types of durable state:
 -   the image metadata in the registry’s cache
 
 In a stateless clustering scheme, the image data is stored in the remote
-storage backend and the registry cache is disabled by turning off both
-deduplication and garbage collection.
+storage backend and the registry cache is disabled by turning off
+deduplication.
 
 ## Ecosystem tools
 
@@ -72,7 +72,7 @@ prefixes during load balancing and ingress gateway configuration.
 
 ## Examples
 
-Clustering is supported by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load balancing traffic to the replicas.
+Clustering is supported by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load balancing traffic to the replicas. Each replica is responsible for one or more repositories.
 
 ### HAProxy YAML configuration
 
@@ -120,16 +120,27 @@ defaults
 frontend zot
     bind *:8080
     mode http
+    use_backend zot-instance1 if { path_beg /v2/repo1/ }
+    use_backend zot-instance2 if { path_beg /v2/repo2/ }
+    use_backend zot-instance3 if { path_beg /v2/repo3/ }
     default_backend zot-cluster
 
 backend zot-cluster
     mode http
     balance roundrobin
     cookie SERVER insert indirect nocache
-    server zot0 127.0.0.1:9000 check cookie zot0
-    server zot1 127.0.0.2:9000 check cookie zot1
-    server zot2 127.0.0.3:9000 check cookie zot2
+    server zot-server1 127.0.0.1:9000 check cookie zot-server1
+    server zot-server2 127.0.0.2:9000 check cookie zot-server2
+    server zot-server3 127.0.0.3:9000 check cookie zot-server3
 
+backend zot-instance1
+    server zot-server1 127.0.0.1:9000 check maxconn 30
+
+backend zot-instance2
+    server zot-server2 127.0.0.2:9000 check maxconn 30
+
+backend zot-instance3
+    server zot-server3 127.0.0.3:9000 check maxconn 30
 ```
 
 </details>
@@ -145,7 +156,7 @@ backend zot-cluster
     "distSpecVersion": "1.0.1-dev",
     "storage": {
         "rootDirectory": "/tmp/zot",
-        "dedupe": true,
+        "dedupe": false,
         "storageDriver": {
             "name": "s3",
             "rootdirectory": "/zot",

docs/articles/scaleout.md

@@ -1,22 +1,24 @@
-# Easy scaling of a zot cluster
+# Scale-out clustering
 
-> :point_right: A cluster of zot replicas can easily be scaled with no repo-specific programming of the load balancer using:
+> :point_right: A cluster of zot instances can easily be scaled with no repo-specific programming of the load balancer using:
 >
 > -   Stateless zot instances to simplify scale out
 > -   Shared remote storage
 > -   zot release v2.1.0 or later
 
-Beginning with zot release v2.1.0, a new "scale-out" architecture greatly reduces the configuration required when deploying large numbers of zot instances.  As before, multiple identical zot replicas run simultaneously using the same shared reliable storage, but with improved scale and performance in large deployments. 
+Beginning with zot release v2.1.0, a new "scale-out" architecture greatly reduces the configuration required when deploying large numbers of zot instances. As before, multiple identical zot instances run simultaneously using the same shared reliable storage, but with improved scale and performance in large deployments. Scale-out is achieved by automatically sharding based on repository name so that each zot instance is responsible for a subset of repositories.
 
 ![504569](../assets/images/504569.jpg){width="500"}
 
-The number of replicas can easily be expanded by simply adding the IP addresses of the new replicas in the load balancer configuration. No repo-specific programming of the load balancer is needed. The shared storage can also be easily increased or decreased.
+The number of instances can easily be expanded by simply adding the IP addresses of the new instances in the load balancer configuration. No repo-specific programming of the load balancer is needed. 
+
+In a cloud deployment, the shared backend storage (such as AWS S3) and metadata storage (such as DynamoDB) can also be easily scaled along with the zot instances.
 
 > :pencil2: For high availability clustering with earlier zot releases, see [zot Clustering](clustering.md).
 
 ## Prerequisites
 
-For easy scaling of replicas, the following conditions must be met:
+For easy scaling of instances (replicas), the following conditions must be met:
 
 - All zot replicas must be running zot release v2.1.0 (or later) with identical configurations.
 - All zot replicas in the cluster use remote storage at a single shared S3 backend. There is no local caching in the zot replicas.
@@ -25,23 +27,26 @@ For easy scaling of replicas, the following conditions must be met:
 - Each zot replica in the cluster has its own IP address, but all replicas use the port number.
 - The URI format sent to the load balancer must be /v2/<repo\>/<manifest\>:<tag\>
 
-Beginning with zot release v2.1.0, garbage collection is allowed in the shared cluster storage.
 
 ## How it works
 
 A highly scalable cluster can be architected by sharding on the repository name. In the cluster, each replica is the owner of a small subset of the repository. The load balancer does not need to know which replica owns which repo. The replicas themselves can determine this.  
 
-When the load balancer receives an image push or pull request, it forwards the request to any replica in the cluster. The receiving replica hashes the repo path and consults a hash table in shared storage to determine which replica is responsible for the repo. The receiving replica forwards the request to the responsible replica and then acts as a proxy, returning the requested image to the requestor.
+When the load balancer receives an image push or pull request, it forwards the request to any replica in the cluster. The receiving replica hashes the repo path and consults a hash table to determine whether the request can be handled locally or must be forwarded to another replica that is responsible for the repo. If the latter, the receiving replica forwards the request to the responsible replica and then acts as a proxy, returning the requested image to the requestor.
+
+> :pencil2: For better resistance to collisions and preimage attacks, zot uses SipHash as the hashing algorithm.
 
-When an image push request is received but no responsible replica is found for the requested repo, the receiving replica becomes the responsible replica and updates the hash table.
+> :bulb: Because this scale-out scheme greatly simplifies the role of the load balancer, it may be possible to eliminate the load balancer entirely by using a scheme such as DNS-based routing, exposing the zot replicas directly to the clients.
 
 ## Configuration examples
 
 Clustering is supported by using multiple stateless zot replicas with shared S3 storage and an HAProxy (with sticky session) load balancing traffic to the replicas.
 
 ### Cluster member configuration
 
-In the replica configuration, each replica must have a list of its peers. The replica must also have a hash key for hashing the repo path of the image request and a TLS certificate for authenticating with its peers.  
+In the replica configuration, each replica must have a list of its peers configured in the "members" section of the JSON structure. This is a list of reachable addresses or hostnames.  Each replica owns one of these addresses.
+
+The replica must also have a hash key for hashing the repo path of the image request and a TLS certificate for authenticating with its peers.
 
 <details>
   <summary markdown="span">Click here to view a sample cluster configuration for each replica. See the "cluster" section in the JSON structure.</summary>
@@ -76,8 +81,8 @@ In the replica configuration, each replica must have a list of its peers. The re
     }
   },
   "http": {
-    "address": "127.0.0.1",
-    "port": "9001",
+    "address": "0.0.0.0",
+    "port": "9000",
     "tls": {
       "cert": "test/data/server.cert",
       "key": "test/data/server.key"
@@ -88,9 +93,9 @@ In the replica configuration, each replica must have a list of its peers. The re
   },
   "cluster": {
     "members": [
-      "127.0.0.1:9000",
-      "127.0.0.2:9000",
-      "127.0.0.3:9000"
+      "zot-server1:9000",
+      "zot-server2:9000",
+      "zot-server3:9000"
     ],
     "hashKey": "loremipsumdolors",
     "tls": {
@@ -135,20 +140,20 @@ backend zot-cluster
     mode http
     balance roundrobin
     cookie SERVER insert indirect nocache
-    server zot0 127.0.0.1:9000 check cookie zot0
-    server zot1 127.0.0.2:9000 check cookie zot1
-    server zot2 127.0.0.3:9000 check cookie zot2
+    server zot-server1 127.0.0.1:9000 check cookie zot-server1
+    server zot-server2 127.0.0.2:9000 check cookie zot-server2
+    server zot-server3 127.0.0.3:9000 check cookie zot-server3
 
 ```
 
 </details>
 
 ## When a replica fails
 
-Unlike the earlier [simple clustering scheme](clustering.md), the scale-out scheme described in this article is not self-healing when a replica fails. In case of a replica failure, you must bring down the cluster, repair the failed replica, and reestablish the cluster.
+The scale-out scheme described in this article is not self-healing when a replica fails. In case of a replica failure, only those repositories that are mapped to the failed replica are affected. If the error is not transient, the cluster must be resized and restarted to exclude that replica.
 
-With an HAProxy load balancer, we recommend implementing an [HAProxy circuit breaker](https://www.haproxy.com/blog/circuit-breaking-haproxy) to monitor and protect the cluster.
+> :pencil2: With an HAProxy load balancer, we recommend implementing an [HAProxy circuit breaker](https://www.haproxy.com/blog/circuit-breaking-haproxy) to monitor and protect the cluster.
 
 ## CVE repository in a zot cluster environment
 
-In the scale-out clustering scheme described in this article, CVE scanning is disabled. In this case, we recommend implementing a CVE repository with a zot instance outside of the cluster using a local disk for storage and [Trivy](https://trivy.dev/) as the detection engine.
+CVE scanning is not supported for cloud deployments. In the scale-out clustering scheme described in this article, CVE scanning is disabled. In this case, we recommend implementing a CVE repository with a zot instance outside of the cluster using a local disk for storage and [Trivy](https://trivy.dev/) as the detection engine.

mkdocs.yml

@@ -126,7 +126,7 @@ nav:
     - Retention Policies: articles/retention.md
     - Mirroring: articles/mirroring.md
     - Clustering: articles/clustering.md
-    - Easy scaling of a cluster: articles/scaleout.md
+    - Scale-out clustering: articles/scaleout.md
     - Monitoring: articles/monitoring.md
     - Using GraphQL for Enhanced Searches: articles/graphql.md
     - Benchmarking with zb: articles/benchmarking-with-zb.md