refs sparkfabrik-innovation-team/board#3833: update CHANGELOG and README with new variables and configuration modes; deprecate old variables

Author: Stevesibilia

CHANGELOG.md

@@ -8,6 +8,27 @@ to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
 ## [Unreleased]
 
+### Added
+
+- New variable `operate_at_root_group_level` to simplify configuration and replace the combination of `gitlab_agent_grant_access_to_entire_root_namespace` and `gitlab_agent_create_variables_in_root_namespace`
+- New variable `groups_enabled` to specify groups where the GitLab Agent should be enabled (when not operating at root group level)
+- New variable `projects_enabled` to specify projects where the GitLab Agent should be enabled (when not operating at root group level)
+- Auto-detection of parent group when `operate_at_root_group_level = false` and no groups/projects are specified
+- Support for creating CI/CD variables in multiple groups and projects simultaneously
+- Dynamic generation of agent configuration file based on enabled groups/projects using `yamlencode()`
+- New outputs: `gitlab_enabled_groups`, `gitlab_enabled_projects`, `gitlab_parent_group_auto_detected`, `operate_at_root_group_level`
+
+### Changed
+
+- Agent configuration file is now dynamically generated based on `operate_at_root_group_level` and enabled groups/projects
+- CI/CD variables can now be created in multiple targets (root group, specific groups, or specific projects) depending on configuration
+- Output `gitlab_root_namespace_id` now returns `null` when not operating at root group level
+
+### Deprecated
+
+- Variable `gitlab_agent_grant_access_to_entire_root_namespace` - use `operate_at_root_group_level` instead
+- Variable `gitlab_agent_create_variables_in_root_namespace` - behavior is now determined by `operate_at_root_group_level`
+
 ## [0.12.0] - 2025-05-19
 
 [Compare with previous version](https://github.com/sparkfabrik/terraform-gitlab-kubernetes-gitlab-agent/compare/0.11.0...0.12.0)

README.md

@@ -4,12 +4,60 @@ This module creates all the necessary resources to deploy a Gitlab Agent on a Ku
 
 It uses the Gitlab provider to register the agent on the Gitlab server. The generated registration token is use to create an Helm release of the Gitlab Agent in the cluster.
 
-If required (`gitlab_agent_grant_access_to_entire_root_namespace` configured to `true`), it also creates the necessary configuration files in the given Gitlab project, granting access to all the projects in the root namespace and subgroups.
+The module supports multiple configuration modes:
+
+- **Root Group Level** (default): The agent has access to the entire root namespace and CI/CD variables are created in the root group
+- **Auto-detect Parent**: When not operating at root level and no specific groups/projects are provided, the module automatically detects the parent group of the agent project
+- **Specific Groups/Projects**: Enable the agent only for specific groups or projects, with variables created in those locations
 
 **ATTENTION**: you have to manually create the project that will host the Gitlab Agent configuration in Gitlab before running this module.
 
 From version `0.7.0`, if you set `gitlab_project_name` the module will create Gitlab project automatically. This new behavior requires the provider to have the proper permissions to create the project in the namespace.
 
+## Configuration Examples
+
+### Example 1: Root Group (Default)
+```hcl
+module "gitlab_agent" {
+  source = "github.com/sparkfabrik/terraform-gitlab-kubernetes-gitlab-agent"
+
+  gitlab_project_path_with_namespace = "my-org/agents-project"
+  gitlab_agent_name                  = "production-agent"
+  namespace                          = "gitlab-agent"
+}
+```
+
+### Example 2: Auto-detect Parent Group
+```hcl
+module "gitlab_agent" {
+  source = "github.com/sparkfabrik/terraform-gitlab-kubernetes-gitlab-agent"
+
+  gitlab_project_path_with_namespace = "my-org/team-a/subgroup/agents"
+  gitlab_agent_name                  = "team-agent"
+  namespace                          = "gitlab-agent"
+  
+  operate_at_root_group_level = false
+  # Parent group "my-org/team-a/subgroup" will be automatically detected
+}
+```
+
+### Example 3: Specific Groups
+```hcl
+module "gitlab_agent" {
+  source = "github.com/sparkfabrik/terraform-gitlab-kubernetes-gitlab-agent"
+
+  gitlab_project_path_with_namespace = "my-org/infrastructure/agents"
+  gitlab_agent_name                  = "shared-agent"
+  namespace                          = "gitlab-agent"
+  
+  operate_at_root_group_level = false
+  groups_enabled = [
+    "my-org/team-a",
+    "my-org/team-b"
+  ]
+}
+```
+
 ## RBAC configuration for the Gitlab Agent service account
 
 This module uses the default configuration of the Gitlab Agent Helm chart. The default configuration grants to the Gitlab Agent service account the `cluster-admin` ClusterRole. If you want to change this configuration, you can use the `helm_additional_values` variable to pass additional values to the Helm chart.

variables.tf

@@ -50,7 +50,7 @@ variable "projects_enabled" {
 }
 
 variable "gitlab_agent_grant_user_access_to_root_namespace" {
-  description = "Grant `user_access` to the root namespace."
+  description = "DEPRECATED: Use operate_at_root_group_level instead.Grant `user_access` to the root namespace."
   type        = bool
   default     = false
 }