Terraform Gitlab Kubernetes Agent

This module creates all the necessary resources to deploy a Gitlab Agent on a Kubernetes cluster.

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.

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)

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

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

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.

How to configure the Gitlab provider

This module requires a Gitlab provider to be configured in your Terraform project. The following snippet shows how to configure the provider:

provider "gitlab" {
  base_url = "https://gitlab.com/api/v4/"
  token    = var.gitlab_token
}

ATTENTION: as described in the Gitlab provider documentation, the CI_JOB_TOKEN could cause issues when used as token for the Gitlab provider. For this module in particular, the gitlab_cluster_agent and gitlab_cluster_agent_token resources require authorization to access to the /users Gitlab API endpoint, which is not granted by the CI_JOB_TOKEN. You have to use a Gitlab personal access token with the api scope to authenticate the provider.

GitLab Agents user membership

The current user used by the provider must be added as maintainer to the "GitLab Agents" project. By default, this behavior is disabled; just set the variable var.autoassign_current_user_as_maintainer to true if you want to enable it.

Adding the user as maintainer to the newly created project ensures they have the permissions to commit and push to it.

ATTENTION: If the current user is already added to the project the apply will fail saying that a membership already exists

Providers

Name	Version
gitlab	18.4.1
helm	3.0.2
kubernetes	2.38.0

Requirements

Name	Version
terraform	>= 1.5
gitlab	>= 15.7
helm	>= 2.0
kubernetes	>= 2.23

Inputs

Name	Description	Type	Default	Required
agent_replicas	The number of replicas of the Gitlab Agent.	number	1	no
create_default_pod_anti_affinity	Create default podAntiAffinity rules for the Gitlab Agent pods.	bool	true	no
create_namespace	Create namespace for the helm release. If false, the namespace must be created before using this module.	bool	true	no
gitlab_agent_append_to_config_file	Append custom configuration to the Gitlab Agent configuration file. This content will be added at the end of the generated configuration.	string	""	no
gitlab_agent_branch_name	The branch name where the Gitlab Agent configuration will be stored.	string	"main"	no
gitlab_agent_commmit_message	The commit message to use when committing the Gitlab Agent configuration file. You can use the placeholder {{gitlab_agent_name}} to reference the Gitlab Agent name.	string	"[CI] Add agent config file for {{gitlab_agent_name}}"	no
gitlab_agent_custom_config_file_content	The content of the Gitlab Agent configuration file. If not provided, the default configuration file will be generated based on operate_at_root_group_level, groups_enabled, and projects_enabled. If you set this variable, it takes precedence over the automatic configuration generation.	string	""	no
gitlab_agent_deploy_enabled	Whether to deploy the GitLab Agent components. If false, only creates the GitLab Agent token, Kubernetes namespace and secret without deploying the agent itself.	bool	true	no
gitlab_agent_grant_user_access_to_root_namespace	Grant user_access to the root namespace.	bool	false	no
gitlab_agent_name	The name of the Gitlab Agent.	string	n/a	yes
gitlab_agent_token_description	The description of the Gitlab Agent token. You can use the placeholder {{gitlab_agent_name}} to reference the Gitlab Agent name.	string	"Token for the Gitlab Agent {{gitlab_agent_name}}."	no
gitlab_agent_token_name	The name of the Gitlab Agent token. You can use the placeholder {{gitlab_agent_name}} to reference the Gitlab Agent name.	string	"{{gitlab_agent_name}}-token"	no
gitlab_agent_variable_name_agent_id	The name of the Gitlab CI/CD variable that stores the Gitlab Agent ID.	string	"GITLAB_AGENT_ID"	no
gitlab_agent_variable_name_agent_project	The name of the Gitlab CI/CD variable that stores the Gitlab Agent project path.	string	"GITLAB_AGENT_PROJECT"	no
gitlab_project_name	The name of the Gitlab project that hosts the Gitlab Agent configuration. If not provided, the module will use the project defined in gitlab_project_path_with_namespace.	string	""	no
gitlab_project_path_with_namespace	The path with namespace of the Gitlab project that hosts the Gitlab Agent configuration. The project must be created in Gitlab before running this module. The configured Gitlab provider must have write access to the project.	string	n/a	yes
groups_enabled	List of group paths where the GitLab Agent should be enabled. Only used when operate_at_root_group_level is false. If empty and projects_enabled is also empty, the parent group of the agent project will be used automatically.	list(string)	[]	no
helm_additional_values	Additional values to be passed to the Helm chart.	list(string)	[]	no
helm_chart_version	The version of the gitlab-agent Helm chart. You can see the available versions at https://gitlab.com/gitlab-org/charts/gitlab-agent/-/tags, or using the command helm search repo gitlab/gitlab-agent -l after adding the Gitlab Helm repository.	string	"2.14.1"	no
helm_release_name	The name of the Helm release.	string	"gitlab-agent"	no
k8s_additional_labels	Additional labels to apply to the kubernetes resources.	map(string)	{}	no
k8s_default_labels	Labels to apply to the kubernetes resources. These are opinionated labels, you can add more labels using the variable additional_k8s_labels. If you want to remove a label, you can override it with an empty map(string).	map(string)	{ "managed-by": "terraform", "scope": "gitlab-agent" }	no
k8s_gitlab_agent_token_secret_name	The name of the Kubernetes secret that will store the Gitlab Agent token. You can use the placeholder {{gitlab_agent_name}} to reference the Gitlab Agent name.	string	"{{gitlab_agent_name}}-token"	no
namespace	The namespace in which the Gitlab Agent resources will be created.	string	"gitlab-agent"	no
operate_at_root_group_level	Operate at root group level. If true, grants access to entire root namespace and creates variables in root group. If false, behavior depends on groups_enabled and projects_enabled. This replaces gitlab_agent_grant_access_to_entire_root_namespace and gitlab_agent_create_variables_in_root_namespace.	bool	true	no
projects_enabled	List of project paths (with namespace) where the GitLab Agent should be enabled. Only used when operate_at_root_group_level is false. If empty and groups_enabled is also empty, the parent group of the agent project will be used automatically.	list(string)	[]	no

Outputs

Name	Description
gitlab_agent_kubernetes_context_variables	The Gitlab Agent information to be used to configure the Kubernetes context.
gitlab_agent_token	The token of the Gitlab Agent.
gitlab_agents_project_id	The ID of the Gitlab project where the Gitlab Agents are installed.
gitlab_enabled_groups	List of groups where the GitLab Agent has been enabled with variables.
gitlab_enabled_projects	List of projects where the GitLab Agent has been enabled with variables.
gitlab_parent_group_auto_detected	Whether the parent group was automatically detected.
gitlab_root_namespace_id	The ID of the root namespace of the Gitlab Agents project. Only available when operate_at_root_group_level is true.
k8s_common_labels	Common labels to apply to the kubernetes resources.
k8s_gitlab_agent_token_secret_name	The name of the Kubernetes secret that will store the Gitlab Agent token.

Resources

Name	Type
gitlab_cluster_agent.this	resource
gitlab_cluster_agent_token.this	resource
gitlab_group_variable.enabled_groups	resource
gitlab_group_variable.root_namespace	resource
gitlab_project.project	resource
gitlab_project_variable.enabled_projects	resource
gitlab_repository_file.this	resource
helm_release.this	resource
kubernetes_namespace_v1.this	resource
kubernetes_secret_v1.gitlab_agent_token_secret	resource
gitlab_group.enabled_groups	data source
gitlab_group.parent_group	data source
gitlab_group.root_namespace	data source
gitlab_metadata.this	data source
gitlab_project.enabled_projects	data source
gitlab_project.this	data source
kubernetes_namespace_v1.this	data source

Modules

No modules.