The convergence of GitLab and Kubernetes represents the pinnacle of cloud-native development, where the boundaries between software development and operational execution are effectively erased. Cloud-native applications are characterized by being container-packaged, dynamically managed, and microservice-oriented. This architectural shift enables a significantly higher development velocity because it allows teams to iterate on small, independent components rather than monolithic structures, all while maintaining rigorous operational stability. GitLab positions itself as a single application designed to handle the entirety of the end-to-end software development and operations lifecycle. By consolidating issue tracking, source code management, continuous integration (CI), continuous delivery (CD), and monitoring into a unified interface, GitLab eliminates the friction inherent in fragmented toolchains. This consolidation reduces the cognitive load on developers and speeds up cycle times, as there is no need to pivot between disparate tools for different stages of the pipeline. With an integrated container registry and native Kubernetes integration, GitLab simplifies the transition to containerization and allows organizations to optimize their cloud application development processes for maximum efficiency.
The Fundamentals of Kubernetes Orchestration
Kubernetes serves as an open-source container orchestration platform, acting as the engine that automates the management of application containers. Its primary function is to handle the lifecycle of these containers, spanning from the initial deployment and scaling to the ongoing operation of the services.
Kubernetes orchestration provides the capability to partition resources and scale applications up or down dynamically based on real-time requirements. This elasticity allows organizations to respond rapidly and efficiently to fluctuations in customer demand. For example, during a traffic spike, Kubernetes can scale out the number of pods to maintain performance; conversely, during low-traffic periods, it can scale down to limit hardware usage within the production environment. This optimization not only reduces infrastructure costs but also minimizes the risk of disruption during feature rollouts, as updates can be managed with precision and reverted quickly if failures occur.
GitLab and Kubernetes Operational Models
GitLab does not merely integrate with Kubernetes; it offers three distinct operational paradigms that can be utilized independently or in tandem to achieve a desired state of automation and management.
The first model involves deploying software from GitLab to Kubernetes. In this scenario, GitLab serves as the orchestration hub that pushes applications into a Kubernetes cluster. This is often achieved through GitLab CI/CD, which allows users to manage deployments across multiple environments with ease, ensuring that the version of the code tested in staging is the exact version deployed to production.
The second model utilizes Kubernetes to manage runners attached to a GitLab instance. By leveraging the scaling capabilities of Kubernetes, GitLab runners can be dynamically provisioned. This means that when a CI/CD pipeline is triggered, a pod is created to execute the job and is destroyed immediately upon completion, optimizing resource utilization and ensuring a clean environment for every build.
The third model is running the GitLab application and services themselves on a Kubernetes cluster. This involves deploying the entire GitLab platform as a set of services within a cluster, turning the tool used for management into a cloud-native application itself.
These models are highly flexible. A common hybrid implementation involves using an omnibus GitLab instance running on a traditional virtual machine, which then employs a docker runner to deploy software into a remote Kubernetes cluster.
The GitLab Agent for Kubernetes
Connecting a Kubernetes cluster with GitLab requires the installation of an agent within the cluster. This agent is the primary bridge that enables the deployment, management, and monitoring of cloud-native solutions. The agent is available across all tiers, including Free, Premium, and Ultimate, and is compatible with GitLab.com, GitLab Self-Managed, and GitLab Dedicated offerings.
The agent operates inside the cluster to perform several critical functions:
- Communicate with a cluster that is situated behind a firewall or Network Address Translation (NAT), removing the need for complex inbound firewall rules.
- Access API endpoints within the cluster in real time, allowing for immediate state interrogation.
- Push information regarding events occurring within the cluster back to GitLab for monitoring and logging purposes.
- Enable a high-performance cache of Kubernetes objects, ensuring that the state of the cluster is kept up-to-date with very low latency.
To ensure optimal maintenance and operational stability, the architectural recommendation is to run only one agent per cluster. However, the agent was designed with strong multi-tenancy support. While a separate agent must be deployed to every cluster intended for connection, the connection established by a registered agent can be shared across various projects, groups, and users. This means that while the installation is singular per cluster, the management and configuration can be scaled to multiple tenants directly from the GitLab interface.
Kubernetes Integration Architecture and Componentry
The GitLab Kubernetes integration is composed of several specialized components that handle communication and logic between the GitLab platform and the target cluster.
| 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 that handles operations and logic for the Kubernetes agent integration, managing connection and communication. | 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 involving the use of 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 |
The interaction between agentk and kas ensures that the cluster remains synchronized with the GitLab project in which the agent is registered. Users have the flexibility to use both agents and receptive agents simultaneously, depending on their specific infrastructure needs.
GitOps and Deployment Methodologies
GitOps is a central pillar of the GitLab and Kubernetes integration. It leverages Git as the single source of truth for the desired state of the cluster. In a GitOps workflow, any change to the infrastructure or application configuration is made via a Git commit, which then triggers an update in the cluster.
There are two primary deployment methods supported:
Push-based deployment: In this model, the GitLab CI/CD pipeline actively sends updates to the Kubernetes cluster. This is a traditional approach where the pipeline has the authority to push changes to the API.
Pull-based deployment: This method integrates with Flux, an open-source GitOps tool. Instead of the pipeline pushing changes, Flux monitors the Git repository for changes and automatically pulls those changes into the cluster. This increases security by removing the need for the CI/CD pipeline to have direct write access to the cluster.
The GitLab Operator for Kubernetes
The GitLab Operator provides a method for deploying the GitLab application itself onto a Kubernetes or OpenShift cluster using manifests. This approach is available for GitLab Self-Managed users across Free, Premium, and Ultimate tiers.
However, the GitLab Operator has known limitations and is specifically suited for certain scenarios rather than general production use. The default values of the GitLab custom resource are not intended for production workloads because they deploy all services, including persistent data, inside the Kubernetes cluster. For production environments, GitLab mandates the use of Cloud Native Hybrid reference architectures. Specifically, GitLab does not provide support for any issues related to the following components when they are deployed inside a Kubernetes cluster:
- PostgreSQL
- Redis
- Gitaly
- Praefect
- MinIO
For those utilizing OpenShift, installation is typically handled via the Operator Lifecycle Manager (OLM). It is important to note that OLM installation is considered experimental, and GitLab does not support issues related to instances deployed through this method.
Operator Technical Specifications and Compatibility
The GitLab Operator is designed to support both x86-64 and ARM64 architectures. While ARM64 builds have been available since version 16.7, full support and comprehensive testing coverage were established starting with version 18.8.
Regarding version support, GitLab aims to provide Operator support for new minor releases of Kubernetes and OpenShift within three months of their initial availability. When support for a new version is introduced, testing for the oldest supported version is discontinued. This rolling support window ensures that the Operator remains compatible with the modern evolving Kubernetes ecosystem.
Ingress and Network Configuration
An Ingress controller is a mandatory requirement for providing external access to the application and ensuring secure communication between the various internal components.
By default, the GitLab Operator deploys a forked NGINX chart derived from the GitLab Helm Chart. This provides a pre-configured path for handling external traffic. However, users who prefer to use an external Ingress controller are encouraged to use NGINX Ingress by the Kubernetes community.
When utilizing an external Ingress controller, users must perform specific configuration steps:
- Identify and record the Ingress class value, which typically defaults to
nginx. - Within the GitLab Custom Resource (CR) configuration, set the following value to disable the default NGINX objects from the GitLab Helm Chart:
nginx-ingress.enabled=false
Security and Certificate Management
Security in the GitLab Operator environment requires specific attention to TLS certificates. Because the operator requires a dedicated certificate for the Kubernetes webhook, the cert-manager that is bundled with the GitLab Chart cannot be used. This necessitates a separate strategy for certificate management to ensure that the webhook remains secure and functional.
Analysis of GitLab's Cloud-Native Strategy
The integration of GitLab with Kubernetes is not merely a feature addition but a fundamental architectural alignment. By bridging the gap between the version control system and the orchestration layer, GitLab addresses the most critical pain point in the DevOps lifecycle: the "hand-off" between development and operations.
The implementation of the GitLab Agent for Kubernetes represents a shift toward a more secure, pull-based architecture. By allowing the agent to operate behind firewalls and NATs, GitLab removes the security risks associated with opening wide ranges of ports to the public internet. The ability to share a single agent's connection across multiple projects and groups demonstrates a sophisticated understanding of enterprise multi-tenancy, allowing organizations to centralize their cluster connectivity while decentralizing their project management.
Furthermore, the distinction between the GitLab Operator and the Cloud Native Hybrid reference architecture highlights a critical lesson in distributed systems: the challenges of state management. By explicitly stating that components like PostgreSQL, Redis, and Gitaly should not be run inside Kubernetes for production workloads, GitLab acknowledges the operational complexity of managing stateful sets in a containerized environment. This guidance steers users toward a hybrid approach where the application logic resides in Kubernetes for scalability, while the persistent data resides in managed services or dedicated instances for reliability.
The support for ARM64 and the commitment to a three-month window for new Kubernetes minor releases indicate that GitLab is positioning itself to be compatible with the next generation of hardware and software. The convergence of Flux for GitOps and the native agent capabilities ensures that whether a team prefers the immediacy of push-based deployments or the security of pull-based synchronization, GitLab provides the necessary tooling.