The integration of GitLab with Kubernetes represents a sophisticated convergence of version control, continuous integration, and container orchestration, designed to facilitate the full lifecycle of cloud-native application development. By bridging the gap between the source code repository and the runtime environment, GitLab provides a unified platform that eliminates the friction typically associated with deploying container-packaged, microservice-oriented systems. This synergy allows organizations to achieve higher development velocity while maintaining rigorous operational stability, effectively transforming the software delivery pipeline into a streamlined, automated process. At its core, this integration is built to handle the complexities of modern infrastructure, enabling the automation of application container management, from initial deployment and scaling to long-term operation. Through the use of Kubernetes orchestration, users can dynamically partition resources, scaling workloads up or down based on real-time customer demand, which optimizes hardware utilization within production environments and minimizes the risk of disruption during feature rollouts.
The Tripartite Model of GitLab and Kubernetes Interaction
GitLab does not interact with Kubernetes through a single channel; rather, it employs three distinct operational modes that can be utilized independently or in a combined configuration to suit various organizational needs.
- Deploying software from GitLab to Kubernetes: This is the primary functional path where GitLab acts as the orchestrator, pushing application code or triggers to a cluster to ensure the desired state of the software is achieved.
- Managing runners via Kubernetes: In this mode, Kubernetes is used to host and manage GitLab Runners. This allows the CI/CD infrastructure to scale horizontally and automatically, providing the compute power necessary to run automated tests in parallel without manual intervention.
- Running GitLab services on Kubernetes: This involves the deployment of the entire GitLab application and its associated services onto a Kubernetes cluster, treating the GitLab instance itself as a cloud-native application.
The flexibility of this model is demonstrated by the fact that these approaches are mutually inclusive. For instance, a legacy omnibus GitLab instance residing on a virtual machine can still leverage a Docker runner to deploy software into a remote Kubernetes cluster, blending traditional VM-based infrastructure with modern container orchestration.
Architectural Components of the GitLab Agent for Kubernetes
The GitLab agent for Kubernetes is a comprehensive offering that comprises several critical components designed to maintain secure, scalable communication between the GitLab instance and the target cluster.
The Role of agentk
The agentk component serves as the cluster-side agent. Its primary responsibility is to maintain a secure, persistent connection to the GitLab instance. By residing within the cluster, agentk acts as the bridge that allows GitLab to manage the cluster and automate deployments. It ensures that the communication channel remains open and authenticated, facilitating the execution of commands and the monitoring of cluster health.
The Role of the GitLab Agent Server for Kubernetes (KAS)
On the GitLab side, the GitLab Agent Server for Kubernetes, known as kas, handles the operational logic. kas is the central hub that manages the connections and communication between the various agents deployed across multiple clusters and the main GitLab application. It translates high-level requests from the GitLab user interface or CI/CD pipelines into instructions that the agentk components can execute.
Integration with Flux for GitOps
Flux is an open-source GitOps tool that integrates directly with the GitLab agent to enable pull-based deployments. In this paradigm, Flux monitors a Git repository for changes to manifests. When a change is detected, Flux automatically applies these changes to the cluster. This shifts the deployment responsibility from a "push" mechanism (where GitLab tells the cluster to update) to a "pull" mechanism (where the cluster observes the repository and updates itself), enhancing security and consistency.
Deployment Methodologies: Push-Based vs. Pull-Based
The choice between push-based and pull-based deployments significantly impacts the security posture and operational flow of a project.
Push-Based Deployment
In a push-based model, updates are sent directly from GitLab CI/CD pipelines to the Kubernetes cluster. This typically requires the cluster to expose an API endpoint that the pipeline can reach, or the use of temporary credentials to authenticate the request. While efficient for rapid iteration, it is generally advised that this workflow should not be used for production deployments due to the security risks associated with managing long-lived credentials within CI/CD variables.
Pull-Based Deployment
Pull-based deployment utilizes the GitOps philosophy, where Git serves as the single source of truth for the infrastructure state. Flux, integrated with the agent, continuously polls the repository. If the desired state defined in Git differs from the actual state in the cluster, Flux synchronizes them. This method is inherently more secure as the cluster does not need to expose its API to the external internet; instead, the agent pulls information from GitLab.
Technical Specifications of Agent Connection and Communication
The communication between the agent and kas is engineered for high performance and reliability, utilizing gRPC streams over a bidirectional channel.
Communication Constraints and Lifetimes
The connectivity is governed by specific technical parameters to ensure stability and prevent resource exhaustion:
- Logical gRPC Streams: Each agent is capable of maintaining up to 500 logical gRPC streams. This includes both active streams currently transmitting data and idle streams waiting for requests.
- TCP Connection Management: The actual number of TCP connections used to support these gRPC streams is determined by the gRPC protocol itself, rather than a static number.
- Connection Lifetimes: Each connection has a maximum lifetime of two hours. To prevent abrupt disconnection, a one-hour grace period is provided.
- Proxy Influence: When a proxy is positioned in front of
kas, it may affect the maximum lifetime of connections. On GitLab.com, the maximum lifetime is two hours, with a grace period calculated as 50% of that maximum lifetime.
Receptive Agents for Restricted Environments
For specific organizational constraints, GitLab offers Receptive Agents, a feature available for the Ultimate tier in GitLab Self-Managed environments.
Receptive agents are designed for scenarios where the Kubernetes cluster cannot initiate a network connection to the GitLab instance. This typically occurs in the following environments:
- Private Networks: When GitLab runs within a private network or is shielded by a firewall, making it accessible only via a VPN.
- Cloud-Hosted Clusters: When the Kubernetes cluster is hosted by a cloud provider and is exposed to the internet or reachable from a private network, but cannot "call home" to the GitLab instance.
In this configuration, the roles are reversed: GitLab connects to the agent using a provided URL, allowing management to occur even when the cluster is isolated from the GitLab server's network.
Operational Management and User Access Control
Managing access to the Kubernetes cluster through GitLab requires a precise configuration of Role-Based Access Control (RBAC) to ensure that users have the necessary permissions to view and interact with the cluster dashboard.
Resolving Dashboard Access Errors
If a user encounters an error message on the Kubernetes dashboard, it typically indicates that the access is restricted. To resolve this, a ClusterRoleBinding must be deployed to grant the necessary permissions. For example, to grant read access to all GitLab users, the following configuration should be applied to the clusters/testing/gitlab-user-read.yaml file:
yaml
apiVersion: rbac.authorization.k8s.io/v1
kind: ClusterRoleBinding
metadata:
name: gitlab-user-view
roleRef:
name: view
kind: ClusterRole
apiGroup: rbac.authorization.k8s.io
subjects:
- name: gitlab:user
kind: Group
Once this manifest is added, a short waiting period is required for Flux to apply the changes. After the synchronization, the dashboard returns to normal operation, providing the user with the required visibility into the cluster.
Maintaining and Upgrading the Environment
To ensure the stability and security of the integration, both Flux and agentk must be kept up to date. Upgrading these components involves rerunning the bootstrap commands to apply the latest versions:
- To upgrade Flux:
flux bootstrap gitlab - To upgrade the agent:
glab cluster agent bootstrap
Advanced Feature Integration and Cloud Native Development
The integration with Kubernetes unlocks a suite of advanced features that accelerate the transition to cloud-native development. Cloud-native applications, characterized by their container-packaged and microservice-oriented architecture, rely on these tools to maintain stability while increasing development velocity.
CI/CD and Environment Management
GitLab CI/CD allows for the seamless management of deployments across multiple environments. This includes:
- Parallel Testing: Utilizing auto-scaling GitLab Runners to execute automated tests in parallel, drastically reducing the time to feedback.
- Review Apps: The ability to manually test changes in a live, production-like environment before the code is merged, which reduces the risk of regressions.
- Flexible Deployment: Runners, Review Apps, and the application itself can be deployed to the Kubernetes cluster or any other chosen environment.
Auto DevOps and Helm Integration
GitLab provides streamlined paths for deployment through Auto DevOps and Helm. Auto DevOps automatically handles the building, testing, and deploying of applications. For those requiring more granular control, GitLab provides step-by-step guidance for creating CI/CD pipelines that utilize Helm for deploying to Kubernetes, allowing for complex application packaging and versioning.
Summary of Key Integration Terms
The following table provides a structured overview of the core components and concepts involved in the GitLab Kubernetes integration.
| Term | Definition | Scope |
|---|---|---|
| GitLab agent for Kubernetes | The overall offering, including related features and the underlying components agentk and kas. | GitLab, Kubernetes, Flux |
| agentk | The cluster-side component that maintains a secure connection to GitLab for Kubernetes management and deployment automation. | GitLab |
| GitLab agent server for Kubernetes (kas) | The GitLab-side component of GitLab that handles operations and logic for the Kubernetes agent integration. Manages the connection and communication between GitLab and Kubernetes clusters. | GitLab |
| Pull-based deployment | A deployment method where Flux checks for changes in a Git repository and automatically applies these changes to the cluster. | GitLab, Kubernetes |
| Push-based deployment | A deployment method where updates are sent from GitLab CI/CD pipelines to the Kubernetes cluster. | GitLab |
| Flux | An open-source GitOps tool that integrates with the agent for pull-based deployments. | GitOps, Kubernetes |
| GitOps | A set of practices that involve using Git for version control and collaboration in the management and automation of cloud and Kubernetes resources. | DevOps, Kubernetes |
| Kubernetes namespace | A logical partition in a Kubernetes cluster that divides cluster resources between multiple users or environments. | Kubernetes |
Conclusion
The integration between GitLab and Kubernetes is not merely a connection between two tools, but a holistic approach to software engineering. By leveraging agentk and kas, GitLab establishes a robust communication channel that supports both traditional push-based pipelines and modern GitOps pull-based workflows via Flux. This flexibility allows organizations to scale their infrastructure, manage multi-tenant environments, and secure their production deployments by removing the need for sensitive credentials in CI/CD variables. The ability to utilize Receptive Agents further extends this reach to highly restricted networks, ensuring that cloud-native development can occur regardless of network topology. Ultimately, the synergy of these technologies enables a high-velocity development cycle where the distance between a code commit and a production deployment is minimized, and the stability of the system is guaranteed through automated orchestration and rigorous RBAC management.