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.

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.

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.

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.

Providers

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

Requirements

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

Inputs

Name	Description	Type	Default	Required
agent_kas_address	The address of the Gitlab Kubernetes Agent Server (KAS).	string	"kas.gitlab.com"	no
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 the Gitlab Agent configuration to the configuration file created for the entire root namespace. This variable is only used when gitlab_agent_grant_access_to_entire_root_namespace is true.	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_create_variables_in_root_namespace	Create two Gitlab CI/CD variables in the root namespace useful to configure the Kubernetes context and use the Gitlab Agent. These variables are created in the root namespace of the project defined in gitlab_project_path_with_namespace, which is the project that hosts the Gitlab Agent configuration.	bool	true	no
gitlab_agent_custom_config_file_content	The content of the Gitlab Agent configuration file. If not provided and gitlab_agent_grant_access_to_entire_root_namespace is true, the default configuration file will be used and the root namespace will be granted access to the Gitlab Agent. If you set this variable, it takes precedence over gitlab_agent_grant_access_to_entire_root_namespace.	string	""	no
gitlab_agent_grant_access_to_entire_root_namespace	Grant access to the entire root namespace. If false, you can provide a custom configuration file content using the variable gitlab_agent_custom_config_file_content. Otherwise, you will have to manually manage the access to the Gitlab Agent committing the proper configuration to the Gitlab project.	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_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
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.5.0"	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

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_root_namespace_id	The ID of the root namespace of the Gitlab Agents project.
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.this	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.root_namespace	data source
gitlab_project.this	data source
kubernetes_namespace_v1.this	data source

Modules

No modules.