Connect a cluster to GitLab (FREE)
You can create new or connect existing clusters to GitLab through different levels, using different methods.
Before getting started:
- Check the supported Kubernetes cluster versions.
- Define the cluster level according to your case.
After that:
- Choose the method to connect your cluster according to your case.
- View your clusters connected to GitLab.
Methods to connect a cluster to GitLab
GitLab offers three methods to connect existing and create new clusters:
- GitLab Kubernetes Agent: the best solution to connect existing clusters.
- Infrastructure as Code: it's a broader infrastructure management toolset that includes managing your cluster. It's the recommended solution to create a new cluster from GitLab.
- Certificate-based method: our first and legacy solution uses cluster certificates to connect your cluster to GitLab. It is no longer recommended for security implications.
Connect existing clusters to GitLab
To safely connect and configure an existing cluster on the project level, we recommend using the GitLab Kubernetes Agent. We are working to support the Agent for connecting a cluster at the group level.
Alternatively, you can use cluster certificates to connect clusters in all levels (projects, group, instance). However, for security implications, we don't recommend using this method.
Create new clusters from GitLab
To safely create new clusters from GitLab, use Infrastructure as Code.
The certificate-based method to create a new cluster is still available through the GitLab UI but was deprecated in GitLab 14.0. If possible, we don't recommend using this method.
Connect multiple clusters to a single project
To connect multiple clusters to a single project in GitLab, we recommend using the GitLab Kubernetes Agent.
You can also use the certificate-based method, but, for security implications, we don't recommend using this method.
Cluster levels
Choose your cluster's level according to its purpose:
| Level | Purpose |
|---|---|
| Project level | Use your cluster for a single project. |
| Group level | Use the same cluster across multiple projects within your group. |
| Instance level (FREE SELF) | Use the same cluster across groups and projects within your instance. |
Supported cluster versions
GitLab is committed to support at least two production-ready Kubernetes minor versions at any given time. We regularly review the versions we support, and provide a three-month deprecation period before we remove support of a specific version. The range of supported versions is based on the evaluation of:
- The versions supported by major managed Kubernetes providers.
- The versions supported by the Kubernetes community.
GitLab supports the following Kubernetes versions, and you can upgrade your Kubernetes version to any supported version at any time:
- 1.19 (support ends on February 22, 2022)
- 1.18 (support ends on November 22, 2021)
- 1.17 (support ends on September 22, 2021)
Some GitLab features may support versions outside the range provided here.
View your clusters
To view the Kubernetes clusters connected to your project, group, or instance, open the cluster's page according to the level of your cluster.
Project-level clusters:
- Go to your project's homepage.
- On the left sidebar, select Infrastructure > Kubernetes clusters.
Group-level clusters:
- Go to your group's homepage.
- On the left sidebar, select Kubernetes.
Instance-level clusters: (FREE SELF)
- On the top bar, select Menu > Admin.
- On the left sidebar, select Kubernetes.
Security implications for clusters connected with certificates
WARNING: The whole cluster security is based on a model where developers are trusted, so only trusted users should be allowed to control your clusters.
The use of cluster certificates to connect your cluster grants access to a wide set of functionalities needed to successfully build and deploy a containerized application. Bear in mind that the same credentials are used for all the applications running on the cluster.