Add inventory object and template docs

doc/user/clusters/agent/index.md

@@ -16,8 +16,8 @@ tasks in a secure and cloud-native way. It enables:
 
 - Integrating GitLab with a Kubernetes cluster behind a firewall or NAT
   (network address translation).
-- Pull-based GitOps deployments by leveraging the
-  [GitOps Engine](https://github.com/argoproj/gitops-engine).
+- Pull-based GitOps deployments.
+- [Inventory object](../../infrastructure/clusters/deploy/inventory_object.md) to keep track of objects applied to your cluster.
 - Real-time access to API endpoints in a cluster.
 - Alert generation based on [Container network policy](../../application_security/threat_monitoring/index.md#container-network-policy).
 - [CI/CD Tunnel](ci_cd_tunnel.md) that enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network connectivity between GitLab Runner and a cluster.
@@ -38,7 +38,9 @@ sequenceDiagram
   participant M as Manifest repository
   participant K as Kubernetes Agent
   participant C as Agent configuration repository
-  K->C: Grab the configuration
+  loop Regularly
+    K-->>C: Grab the configuration
+  end
   D->>+A: Pushing code changes
   A->>M: Updating manifest
   loop Regularly

doc/user/clusters/agent/repository.md

@@ -8,7 +8,7 @@ info: To determine the technical writer assigned to the Stage/Group associated w
 
 > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.7.
 > - [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in GitLab 13.11, the Kubernetes Agent became available on GitLab.com.
-> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed.
+> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0, the `resource_inclusions` and `resource_exclusions` attributes were removed and `reconcile_timeout`, `dry_run_strategy`, `prune`, `prune_timeout`, `prune_propagation_policy`, and `inventory_policy` attributes were added.
 
 WARNING:
 This feature might not be available to you. Check the **version history** note above for details.
@@ -51,6 +51,7 @@ gitops:
     # in YAML or JSON format.
   - id: gitlab-org/cluster-integration/gitlab-agent
     # Namespace to use if not set explicitly in object manifest.
+    # Also used for inventory ConfigMap objects.
     default_namespace: my-ns
     # Paths inside of the repository to scan for manifest files.
     # Directories with names starting with a dot are ignored.
@@ -84,13 +85,13 @@ gitops:
     # https://github.com/kubernetes/apimachinery/blob/44113beed5d39f1b261a12ec398a356e02358307/pkg/apis/meta/v1/types.go#L456-L470
     # Can be: orphan, background, foreground
     prune_propagation_policy: foreground # 'foreground' by default
-    # InventoryPolicy defines if an inventory object can take over
+    # Inventory policy defines if an inventory object can take over
     # objects that belong to another inventory object or don't
     # belong to any inventory object.
     # This is done by determining if the apply/prune operation
     # can go through for a resource based on the comparison
     # the inventory-id value in the package and the owning-inventory
-    # annotation in the live object.
+    # annotation (config.k8s.io/owning-inventory) in the live object.
     # https://github.com/kubernetes-sigs/cli-utils/blob/d6968048dcd80b1c7b55d9e4f31fc25f71c9b490/pkg/inventory/policy.go#L12-L66
     # Can be: must_match, adopt_if_no_inventory, adopt_all
     inventory_policy: must_match # 'must_match' by default

doc/user/infrastructure/clusters/deploy/inventory_object.md

+---
+stage: Configure
+group: Configure
+info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
+---
+
+# Inventory object **(PREMIUM)**
+
+> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/332227) in GitLab 14.0.
+
+An inventory object is a `ConfigMap` object for keeping track of the set of objects applied to a cluster.
+When you remove objects from a manifest repository, GitLab Kubernetes Agent uses a corresponding inventory object to
+prune (delete) objects from the cluster.
+
+The GitLab Kubernetes Agent creates an inventory object for each manifest project specified in the
+`gitops.manifest_projects` configuration section. The inventory object has to be stored somewhere in the cluster.
+The default behavior is:
+
+- The `namespace` used comes from `gitops.manifest_projects[].default_namespace`. If you don't specify this parameter
+  explicitly, the inventory object is stored in the `default` namespace.
+- The `name` is generated from the numeric project ID of the manifest project and the numeric agent ID.
+
+  This way the GitLab Kubernetes Agent constructs the name and local where the inventory object is
+  stored in the cluster.
+
+The GitLab Kubernetes Agent cannot locate the existing inventory object if you:
+
+- Change `gitops.manifest_projects[].default_namespace` parameter.
+- Move manifests into another project.
+
+## Inventory object template
+
+The inventory object template is a `ConfigMap` object that allows you to configure the namespace and the name of the inventory
+object. Store this template with manifest files in a single group.
+
+Example inventory object template:
+
+```yaml
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: unique-name-for-the-inventory
+  namespace: my-project-namespace
+  labels:
+    cli-utils.sigs.k8s.io/inventory-id: unique-name-for-the-inventory
+```
+
+- The `namespace` and `name` fields configure where the real inventory object is created.
+- The `cli-utils.sigs.k8s.io/inventory-id` label with its corresponding value is set on the inventory object, created
+  from this template. Make sure that the value is unique (for example, a string of random characters) and doesn't clash
+  with any existing or future inventory object templates.
+- Objects tracked by this inventory object have the `config.k8s.io/owning-inventory` annotation set to the value of
+  the `cli-utils.sigs.k8s.io/inventory-id` label.
+- The label's value doesn't have to match the `name` but it's convenient to have them set to the same value.
+- Make sure that the `name` is unique so that it doesn't conflict with another inventory object in the same
+  namespace in the future.
+
+## Using GitOps with pre-existing Kubernetes objects
+
+The GitLab Kubernetes Agent treats manifest files in the manifest repository as the source of truth. When it applies
+objects from the files to the cluster, it tracks them in an inventory object. If an object already exists,
+GitLab Kubernetes Agent behaves differently based on the `gitops.manifest_projects[].inventory_policy` configuration.
+Check the table below with the available options and when to use them.
+
+`inventory_policy` value | Description                                                                                 |
+------------------------ | ------------------------------------------------------------------------------------------- |
+`must_match`             | This is the default policy. A live object must have the `config.k8s.io/owning-inventory` annotation set to the same value as the `cli-utils.sigs.k8s.io/inventory-id` label on the corresponding inventory object to be updated. Object is not updated and an error is reported if the values don't match or the object doesn't have the annotation. |
+`adopt_if_no_inventory`  | This mode allows to "adopt" an object if it doesn't have the `config.k8s.io/owning-inventory` annotation. Use this mode if you want to start managing existing objects using the GitOps feature. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. |
+`adopt_all`              | This mode allows to "adopt" an object even if it has the `config.k8s.io/owning-inventory` annotation set to a different value. This mode can be useful if you want to migrate a set of objects from one agent to another one or from some other tool to the GitLab Kubernetes Agent. Once all objects have been "adopted", we recommend you to put the setting back into the default `must_match` mode to avoid any unexpected adoptions. |