2020-05-07 21:09:26 +00:00
---
2021-06-22 19:11:50 +00:00
stage: Configure
group: Configure
2020-11-26 06:09:20 +00:00
info: To determine the technical writer assigned to the Stage/Group associated with this page, see https://about.gitlab.com/handbook/engineering/ux/technical-writing/#assignments
2020-05-07 21:09:26 +00:00
---
2021-01-28 06:08:59 +00:00
# Kubernetes clusters **(FREE)**
2017-10-05 15:24:51 +00:00
2020-05-22 03:08:28 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/35954) in GitLab 10.1 for projects.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/34758) in
2019-07-29 10:23:29 +00:00
> GitLab 11.6 for [groups](../../group/clusters/index.md).
2020-05-22 03:08:28 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab-foss/-/issues/39840) in
2019-07-29 10:23:29 +00:00
> GitLab 11.11 for [instances](../../instance/clusters/index.md).
2018-01-12 16:23:10 +00:00
2021-06-22 19:11:50 +00:00
We offer extensive integrations to help you connect and manage your Kubernetes clusters from GitLab.
2019-07-25 14:12:45 +00:00
2021-06-22 19:11:50 +00:00
Read through this document to get started.
2021-06-18 15:10:16 +00:00
## Benefit from the GitLab-Kubernetes integration
Using the GitLab-Kubernetes integration, you can benefit of GitLab
features such as:
2021-06-22 19:11:50 +00:00
- Create [CI/CD Pipelines ](../../../ci/pipelines/index.md ) to build, test, and deploy to your cluster.
2021-06-18 15:10:16 +00:00
- Use [Auto DevOps ](#auto-devops ) to automate the CI/CD process.
- Use [role-based or attribute-based access controls ](cluster_access.md ).
2019-07-25 14:12:45 +00:00
- Run serverless workloads on [Kubernetes with Knative ](serverless/index.md ).
2021-06-18 15:10:16 +00:00
- Connect GitLab to in-cluster applications using [cluster integrations ](../../clusters/integrations.md ).
2021-08-20 15:10:24 +00:00
- Use [deploy boards ](../deploy_boards.md ) to see the health and status of each CI [environment ](../../../ci/environments/index.md ) running on your Kubernetes cluster.
2021-06-22 19:11:50 +00:00
- Use [Canary deployments ](../canary_deployments.md ) to update only a portion of your fleet with the latest version of your application.
- View your [Kubernetes podlogs ](kubernetes_pod_logs.md ) directly in GitLab.
- Connect to your cluster through GitLab [web terminals ](deploy_to_cluster.md#web-terminals-for-kubernetes-clusters ).
2019-07-25 14:12:45 +00:00
2021-06-18 15:10:16 +00:00
## Supported cluster versions
2020-05-11 18:09:55 +00:00
2020-06-30 18:09:13 +00:00
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
2020-10-21 21:09:00 +00:00
provide a three-month deprecation period before we remove support of a specific
2020-06-30 18:09:13 +00:00
version. The range of supported versions is based on the evaluation of:
2020-05-11 18:09:55 +00:00
- The versions supported by major managed Kubernetes providers.
2021-07-02 18:08:28 +00:00
- The versions [supported by the Kubernetes community ](https://kubernetes.io/releases/version-skew-policy/#supported-versions ).
2020-05-11 18:09:55 +00:00
2020-10-29 18:09:11 +00:00
GitLab supports the following Kubernetes versions, and you can upgrade your
Kubernetes version to any supported version at any time:
2020-05-11 18:09:55 +00:00
2021-09-14 12:10:35 +00:00
- 1.20 (support ends on April 22, 2022)
2020-12-08 21:10:06 +00:00
- 1.19 (support ends on February 22, 2022)
- 1.18 (support ends on November 22, 2021)
- 1.17 (support ends on September 22, 2021)
2020-05-11 18:09:55 +00:00
Some GitLab features may support versions outside the range provided here.
2021-06-18 15:10:16 +00:00
## Add and remove clusters
2021-09-02 21:08:51 +00:00
You can create new or add existing clusters to GitLab through different [levels ](#cluster-levels ),
2021-09-02 18:10:52 +00:00
using different methods.
2021-05-27 18:10:52 +00:00
2021-09-02 18:10:52 +00:00
### Methods to connect existing clusters
2021-06-18 15:10:16 +00:00
2021-09-02 18:10:52 +00:00
To safely connect and configure an existing cluster on the **project level** , we
**recommend** using the [GitLab Kubernetes Agent ](../../clusters/agent/index.md ).
We are working to support [the Agent for connecting a
cluster at the group level](https://gitlab.com/groups/gitlab-org/-/epics/5784).
2019-07-25 14:12:45 +00:00
2021-09-02 18:10:52 +00:00
You can use [cluster certificates ](add_existing_cluster.md ) to connect
clusters in all levels (projects, group, instance). However, for
[security implications ](#security-implications ), this method is no longer recommended.
2019-07-25 14:12:45 +00:00
2021-09-06 12:11:14 +00:00
To create new clusters, we **recommend** using
[Infrastructure as Code ](../../infrastructure/iac/index.md#create-a-new-cluster-through-iac ).
2021-09-02 21:08:51 +00:00
### Cluster levels
You can connect clusters to GitLab in different levels, according to their purpose:
- On the project level, to have a cluster dedicated to a project.
- On the [group level ](../../group/clusters/index.md ), to use the same cluster across multiple projects within your group.
- On the [instance level ](../../instance/clusters/index.md ), to use the same cluster across multiple groups and projects. ** (FREE SELF)**
2021-09-02 18:10:52 +00:00
## Security implications
2018-03-07 18:58:08 +00:00
2020-12-04 21:09:29 +00:00
WARNING:
2018-03-07 18:58:08 +00:00
The whole cluster security is based on a model where [developers ](../../permissions.md )
are trusted, so **only trusted users should be allowed to control your clusters** .
The default cluster configuration grants access to a wide set of
functionalities needed to successfully build and deploy a containerized
2018-12-14 12:31:09 +00:00
application. Bear in mind that the same credentials are used for all the
2018-03-07 18:58:08 +00:00
applications running on the cluster.
2021-09-02 18:10:52 +00:00
## View your clusters
To view your project-level Kubernetes clusters, to go **Infrastructure > Kubernetes clusters**
from your project. On this page, you can add a new cluster
and view information about your existing clusters, such as:
- Nodes count.
- Rough estimates of memory and CPU usage.
2021-06-22 19:11:50 +00:00
## Multiple Kubernetes clusters
2021-01-19 18:11:04 +00:00
2021-06-22 19:11:50 +00:00
See how to associate [multiple Kubernetes clusters ](multiple_kubernetes_clusters.md )
with your GitLab project.
2021-01-19 18:11:04 +00:00
2021-06-18 15:10:16 +00:00
## Cluster integrations
See the available [cluster integrations ](../../clusters/integrations.md )
to integrate third-party applications with your clusters through GitLab.
2021-06-08 21:10:05 +00:00
## Cluster management project
2017-11-16 17:17:27 +00:00
2021-06-08 21:10:05 +00:00
Attach a [Cluster management project ](../../clusters/management_project.md )
to your cluster to manage shared resources requiring `cluster-admin` privileges for
installation, such as an Ingress controller.
2019-04-03 09:01:44 +00:00
2021-06-22 19:11:50 +00:00
## GitLab-managed clusters
See how to allow [GitLab to manage your cluster for you ](gitlab_managed_clusters.md ).
2020-06-30 18:09:13 +00:00
## Auto DevOps
2021-06-18 15:10:16 +00:00
You can use [Auto DevOps ](../../../topics/autodevops/index.md ) to automatically
detect, build, test, deploy, and monitor your applications.
2020-06-30 18:09:13 +00:00
2019-07-25 14:12:45 +00:00
## Deploying to a Kubernetes cluster
2018-12-14 12:31:09 +00:00
2021-06-22 19:11:50 +00:00
See how to [deploy to your Kubernetes cluster ](deploy_to_cluster.md ) from GitLab.
2019-06-28 08:39:12 +00:00
2020-06-30 18:09:13 +00:00
## Monitoring your Kubernetes cluster
Automatically detect and monitor Kubernetes metrics. Automatic monitoring of
[NGINX Ingress ](../integrations/prometheus_library/nginx.md ) is also supported.
[Read more about Kubernetes monitoring ](../integrations/prometheus_library/kubernetes.md )
2020-07-13 18:09:16 +00:00
### Visualizing cluster health
2018-12-14 12:31:09 +00:00
2020-07-13 18:09:16 +00:00
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/merge_requests/4701) in [GitLab Ultimate](https://about.gitlab.com/pricing/) 10.6.
2021-01-30 00:09:06 +00:00
> - [Moved](https://gitlab.com/gitlab-org/gitlab/-/issues/208224) to GitLab Free in 13.2.
2018-12-14 12:31:09 +00:00
2021-06-08 21:10:05 +00:00
When [the Prometheus cluster integration is enabled ](../../clusters/integrations.md#prometheus-cluster-integration ), GitLab monitors the cluster's health. At the top of the cluster settings page, CPU and Memory utilization is displayed, along with the total amount available. Keeping an eye on cluster resources can be important, if the cluster runs out of memory pods may be shutdown or fail to start.
2018-12-14 12:31:09 +00:00
2019-05-05 12:29:36 +00:00
![Cluster Monitoring ](img/k8s_cluster_monitoring.png )