Tracking cluster resources managed by GitLab (deprecated)

DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed

• Introduced in GitLab 14.0.
• Moved from GitLab Premium to GitLab Free in 15.3.

WARNING: This feature was deprecated in GitLab 16.2. To manage cluster resources with GitOps, you should use the Flux integration.

GitLab uses an inventory object to track the resources you deploy to your cluster. The inventory object is a ConfigMap that contains a list of controlled objects. The managed resources use the cli-utils.sigs.k8s.io/inventory-id annotation.

Default location of the inventory object

In the agent configuration file, you specify a list of projects. For example:

gitops:
  manifest_projects:
  - id: gitlab-org/cluster-integration/gitlab-agent
    default_namespace: my-ns

The agent creates an inventory object for every item in the manifest_projects list. The inventory object is stored in the namespace you specify for default_namespace.

The name and location of the inventory object is based on:

• The default_namespace. If you don't specify this parameter, the inventory object is stored in the default namespace.
• The name, which is the ID of the project with the manifest and the ID of the agent.

WARNING: The agent cannot locate the existing inventory object if you change the default_namespace parameter or move manifests to another project.

Change the location of the inventory object

You can configure the namespace and the name of the inventory object. This action changes the location of the object in the cluster.

1. Create an inventory object template, which is a ConfigMap object. For example:

   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

2. Specify a namespace and name. Ensure that the name is unique so it doesn't conflict with other inventory objects in the same namespace in the future.

3. Ensure the value for cli-utils.sigs.k8s.io/inventory-id is unique. This value is used for objects tracked by this inventory object. Their config.k8s.io/owning-inventory annotation is set to this value.

   The value doesn't have to match the name but it's convenient to set them to the same value.

4. Save the file with the manifest files as a single logical group.

inventory_policy options

Sometimes your manifest changes affect resources that aren't tracked by the GitLab inventory object.

To change how the agent behaves when it overwrites existing and previously untracked resources, change the inventory_policy value.