Tracking cluster resources managed by GitLab

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

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 annotation.

Default location of the inventory object

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

  - 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.
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
      name: unique-name-for-the-inventory
      namespace: my-project-namespace
      labels: 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 is unique. This value is used for objects tracked by this inventory object. Their 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.

inventory_policy valueDescription
must_matchThe default policy. To be updated, a live object must have the annotation set to the same value as the label on the corresponding inventory object. If the values don’t match or the object doesn’t have the annotation, the object is not updated and an error is reported.
adopt_if_no_inventoryAdopt an object if it doesn’t have the annotation. Use this mode if you want to start managing existing objects by using the GitOps feature. To avoid unexpected adoptions, after all objects have been adopted, put the setting back to the default must_match mode.
adopt_allAdopt an object even if it has the annotation set to a different value. Use this mode if you want to migrate a set of objects from one agent to another, or from some other tool to the agent. To avoid unexpected adoptions, after all objects have been adopted, put the setting back to the default must_match mode.