Migrate to the GitLab agent for Kubernetes

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

• A GitOps workflow.
• A GitLab CI/CD workflow.
• A certificate-based integration.

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

• for GitLab.com customers.
• for 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.

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.

Migrate generic deployments

To migrate generic deployments:

1. Install the GitLab agent for Kubernetes.
2. Follow the CI/CD workflow to authorize the agent to access groups and projects, or to [secure access with impersonation].(../../clusters/agent/ci_cd_workflow.md#restrict-project-and-group-access-by-using-impersonation).
3. On the left sidebar, select Operate > Kubernetes clusters.
4. From the certificate-based clusters section, open the cluster that serves the same environment scope.
5. Select the Details tab and turn off the cluster.

Migrate from GitLab-managed clusters to Kubernetes resources

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:

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

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

   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

3. 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:

   objects:
     - apiVersion: v1
       kind: Namespace
       metadata:
         name: {{ .project.slug }}-{{ .project.id }}-{{ .environment.slug }}
     - apiVersion: rbac.authorization.k8s.io/v1
       kind: RoleBinding
       metadata:
         name: bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}
         namespace: {{ .project.slug }}-{{ .project.id }}-{{ .environment.slug }}
       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:

   objects:
     - apiVersion: v1
       kind: Namespace
       metadata:
         name: {{ .project.slug }}-{{ .project.id }}
     - apiVersion: rbac.authorization.k8s.io/v1
       kind: RoleBinding
       metadata:
         name: bind-{{ .agent.id }}-{{ .project.id }}-{{ .environment.slug }}
         namespace: {{ .project.slug }}-{{ .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

4. In your CI/CD configuration, use the agent with the environment.kubernetes.agent: <path/to/agent/project:agent-name> syntax.

5. On the left sidebar, select Operate > Kubernetes clusters.

6. From the certificate-based clusters section, open the cluster that serves the same environment scope.

7. Select the Details tab and turn off the cluster.

Migrate from Auto DevOps

In your Auto DevOps project, you can use the GitLab agent 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:

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

2. Add three variables. On 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:

      deploy:
       image:
         name: bitnami/kubectl:latest
         entrypoint: [""]
       script:
       - 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.

3. Select Add variable.

4. On the left sidebar, select Operate > Kubernetes clusters.

5. From the certificate-based clusters section, open the cluster that serves the same environment scope.

6. Select the Details tab and disable the cluster.

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

   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"

8. To test your pipeline, on 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:

1. Migrate from GitLab-managed Apps to a cluster management project.
2. Migrate the cluster management project to use the agent.

Migrate a cluster management project

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

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.