Merge branch 'ash2k/concurrent-projects' into 'master'

Document using distinct configuration for concurrent project sync

See merge request gitlab-org/gitlab!54538

doc/user/clusters/agent/index.md

@@ -462,7 +462,7 @@ The setup process follows the same steps as [GitOps](#get-started-with-gitops-an
 with the following differences:
 
 - When you define a configuration repository, you must do so with [Cilium settings](#define-a-configuration-repository-with-cilium-settings).
-- You do not need to create a `manifest.yaml`.
+- You do not need to specify the `gitops` configuration section.
 
 ### Define a configuration repository with Cilium settings
 

doc/user/clusters/agent/repository.md

@@ -95,6 +95,56 @@ gitops:
     - glob: '/**/*.{yaml,yml,json}'
 ```
 
+### Using multiple manifest projects
+
+Storing Kubernetes manifests in more than one repository can be handy, for example:
+
+- You may store manifests for different applications in separate repositories.
+- Different teams can work on manifests of independent projects in separate repositories.
+
+To use multiple repositories as the source of Kubernetes manifests, specify them in the list of
+`manifest_projects` in your `config.yaml`:
+
+```yaml
+gitops:
+  manifest_projects:
+  - id: group1/project1
+  - id: group2/project2
+```
+
+Note that repositories are synchronized **concurrently** and **independently** from each other,
+which means that, ideally, there should **not** be any dependencies shared by these repositories.
+Storing a logical group of manifests in a single repository may work better than distributing it across several
+repositories.
+
+You cannot use a single repository as a source for multiple concurrent synchronization
+operations. If such functionality is needed, you may use multiple agents reading
+manifests from the same repository.
+
+Ensure not to specify "overlapping" globs to avoid synchronizing the same files more than once.
+This is detected by the GitLab Kubernetes Agent and leads to an error.
+
+INCORRECT - both globs match `*.yaml` files in the root directory:
+
+```yaml
+gitops:
+  manifest_projects:
+  - id: project1    
+    paths:
+    - glob: '/**/*.yaml'
+    - glob: '/*.yaml'
+```
+
+CORRECT - single globs matches all `*.yaml` files recursively:
+
+```yaml
+gitops:
+  manifest_projects:
+  - id: project1    
+    paths:
+    - glob: '/**/*.yaml'
+```
+
 ## Surface network security alerts from cluster to GitLab
 
 The GitLab Agent provides an [integration with Cilium](index.md#kubernetes-network-security-alerts).