Migrate to the GitLab agent for Kubernetes - Gitlabhq

Tier: Free, Premium, Ultimate
Offering: GitLab.com, GitLab Self-Managed, GitLab Dedicated

To connect your Kubernetes cluster with GitLab, you can use:

The certificate-based integration is deprecated in GitLab 14.5. The sunsetting plans are described:

for GitLab.com customers.
for GitLab Self-Managed customers.

If you are using the certificate-based integration, you should move to another workflow as soon as possible.

As a general rule, to migrate clusters that rely on GitLab CI/CD, you can use the CI/CD workflow. This workflow uses an agent to connect to your cluster. The agent:

Is not exposed to the internet.
Does not require full cluster-admin access to GitLab.

[!note] The certificate-based integration was used for popular GitLab features like GitLab-managed Apps, GitLab-managed clusters, and Auto DevOps.

Find certificate-based clusters

You can find all the certificate-based clusters within a GitLab instance or group, including subgroups and projects, using a dedicated API. Querying the API with a group ID returns all the certificate-based clusters defined at or below the provided group.

Clusters defined in parent groups are not returned in this case. This behavior helps group Owners find all the clusters they need to migrate.

Disabled clusters are returned as well to avoid accidentally leaving clusters behind.

[!note] The cluster discovery API does not work for personal namespaces.

Migrate generic deployments

To migrate generic deployments:

Install the GitLab agent for Kubernetes.
Follow the CI/CD workflow to authorize the agent to access groups and projects, or to secure access with impersonation.
In the left sidebar, select Operate > Kubernetes clusters.
From the certificate-based clusters section, open the cluster that serves the same environment scope.
Select the Details tab and turn off the cluster.

Migrate from GitLab-managed clusters to Kubernetes resources

Tier: Premium, Ultimate

With GitLab-managed clusters, GitLab creates separate service accounts and namespaces for every branch and deploys by using these resources.

Now, you can use GitLab-managed Kubernetes resources to self-serve resources with enhanced security controls.

With GitLab-managed Kubernetes resources, you can:

Set up environments securely without manual intervention.
Control resource creation and access without giving developers administrative cluster permissions.
Provide self-service capabilities for developers when they create a new project or environment.
Allow developers to deploy testing and development versions in dedicated or shared namespaces.

Prerequisites:

Install the GitLab agent for Kubernetes.
Authorize the agent to access relevant projects or groups.
Check the status of the Namespace per environment checkbox in your certificate-based cluster integration page.

To migrate from GitLab-managed clusters to GitLab-managed Kubernetes resources:

If you're migrating an existing environment, configure an agent for the environment either through the dashboard for Kubernetes or the Environments API.

Configure the agent to turn on resource management in your agent configuration file:

yaml

ci_access:
   projects:
     - id: <your_group/your_project>
       access_as:
         ci_job: {}
       resource_management:
         enabled: true
   groups:
     - id: <your_other_group>
       access_as:
         ci_job: {}
       resource_management:
         enabled: true

Create an environment template under .gitlab/agents/<agent-name>/environment_templates/default.yaml. Check the status of the Namespace per environment checkbox in your certificate-based cluster integration page.

If Namespace per environment was checked, use the following template:

yaml

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      # the `.legacy_namespace` produces something like:
      # '{{ .project.slug }}-{{ .project.id }}-{{ .environment.slug }}'
      # that is compatible with what the certificate-based cluster integration
      # would have generated.
      name: '{{ .legacy_namespace }}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: 'bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}'
      namespace: '{{ .legacy_namespace }}'
    subjects:
      - kind: Group
        apiGroup: rbac.authorization.k8s.io
        name: 'gitlab:project_env:{{ .project.id }}:{{ .environment.slug }}'
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: admin

If Namespace per environment was unchecked, use the following template:

yaml

objects:
  - apiVersion: v1
    kind: Namespace
    metadata:
      name: '{{ .project.slug | slugify }}-{{ .project.id }}'
  - apiVersion: rbac.authorization.k8s.io/v1
    kind: RoleBinding
    metadata:
      name: 'bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}'
      namespace: '{{ .project.slug | slugify }}-{{ .project.id }}'
    subjects:
      - kind: Group
        apiGroup: rbac.authorization.k8s.io
        name: 'gitlab:project_env:{{ .project.id }}:{{ .environment.slug }}'
    roleRef:
      apiGroup: rbac.authorization.k8s.io
      kind: ClusterRole
      name: admin

In your CI/CD configuration, use the agent with the environment.kubernetes.agent: <path/to/agent/project:agent-name> syntax.
In the left sidebar, select Operate > Kubernetes clusters.
From the certificate-based clusters section, open the cluster that serves the same environment scope.
Select the Details tab and turn off the cluster.

Migrate from Auto DevOps

In your Auto DevOps project, you can use the GitLab agent for Kubernetes to connect with your Kubernetes cluster.

Prerequisites

Install the GitLab agent for Kubernetes.
Authorize the agent to access relevant projects or groups.

To migrate from Auto DevOps:

In GitLab, go to the project where you use Auto DevOps.

Add three variables. In the left sidebar, select Settings > CI/CD and expand Variables.

Add a key called KUBE_INGRESS_BASE_DOMAIN with the application deployment domain as the value.

Add a key called KUBE_CONTEXT with a value like path/to/agent/project:agent-name. Select the environment scope of your choice. If you are not sure what your agent's context is, edit your .gitlab-ci.yml file and add a job to see the available contexts:

yaml

deploy:
  image: debian:13-slim
  variables:
    KUBECTL_VERSION: v1.34
    DEBIAN_FRONTEND: noninteractive
  script:
    # Follows https://kubernetes.io/docs/tasks/tools/install-kubectl-linux/#install-using-native-package-management
    - apt-get update
    - apt-get install -y --no-install-recommends apt-transport-https ca-certificates curl gnupg
    - curl --fail --silent --show-error --location "https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/Release.key" | gpg --dearmor --output /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - chmod 644 /etc/apt/keyrings/kubernetes-apt-keyring.gpg
    - echo "deb [signed-by=/etc/apt/keyrings/kubernetes-apt-keyring.gpg] https://pkgs.k8s.io/core:/stable:/${KUBECTL_VERSION}/deb/ /" | tee /etc/apt/sources.list.d/kubernetes.list
    - chmod 644 /etc/apt/sources.list.d/kubernetes.list
    - apt-get update
    - apt-get install -y --no-install-recommends kubectl
    - kubectl config get-contexts

Add a key called KUBE_NAMESPACE with a value of the Kubernetes namespace for your deployments to target. Set the same environment scope.

Select Add variable.
In the left sidebar, select Operate > Kubernetes clusters.
From the certificate-based clusters section, open the cluster that serves the same environment scope.
Select the Details tab and disable the cluster.

Edit your .gitlab-ci.yml file and ensure it's using the Auto DevOps template. For example:

yaml

include:
  template: Auto-DevOps.gitlab-ci.yml

variables:
  KUBE_INGRESS_BASE_DOMAIN: 74.220.23.215.nip.io
  KUBE_CONTEXT: "gitlab-examples/ops/gitops-demo/k8s-agents:demo-agent"
  KUBE_NAMESPACE: "demo-agent"

To test your pipeline, in the left sidebar, select Build > Pipelines and then New pipeline.

For an example, view this project.

Migrate from GitLab-managed applications

GitLab-managed Apps (GMA) were deprecated in GitLab 14.0, and removed in GitLab 15.0. The agent for Kubernetes does not support them. To migrate from GMA to the agent, go through the following steps:

Migrate a cluster management project

See how to use a cluster management project with the GitLab agent for Kubernetes.

Migrate cluster monitoring features

Once you connect a Kubernetes cluster to GitLab using the agent for Kubernetes, you can use the dashboard for Kubernetes after enabling user access.