Migrate to the GitLab agent for Kubernetes
DETAILS: Tier: Free, Premium, Ultimate Offering: SaaS, self-managed
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:
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-adminaccess to GitLab.
NOTE: The certificate-based integration was used for popular GitLab features like GitLab Managed Apps, GitLab-managed clusters, and Auto DevOps. Some features are currently available only when using certificate-based integration.
Migrate cluster application deployments
Migrate from GitLab-managed clusters
With GitLab-managed clusters, GitLab creates separate service accounts and namespaces for every branch and deploys by using these resources.
The GitLab agent uses impersonation strategies to deploy to your cluster with restricted account access. To do so:
- Choose the impersonation strategy that suits your needs.
- Use Kubernetes RBAC rules to manage impersonated account permissions in Kubernetes.
- Use the
access_asattribute in your agent configuration file to define the impersonation.
Migrate from Auto DevOps
In your Auto DevOps project, you can use the GitLab agent to connect with your Kubernetes cluster.
Install an agent in your cluster.
In GitLab, go to the project where you use Auto DevOps.
Add three variables. On the left sidebar, select Settings > CI/CD and expand Variables.
Add a key called
KUBE_INGRESS_BASE_DOMAINwith the application deployment domain as the value.
Add a key called
KUBE_CONTEXTwith 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.ymlfile 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_NAMESPACEwith a value of the Kubernetes namespace for your deployments to target. Set the same environment scope.
Select Add variable.
On 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.
.gitlab-ci.ymlfile and ensure it's using the Auto DevOps template. For example:
include: template: Auto-DevOps.gitlab-ci.yml variables: KUBE_INGRESS_BASE_DOMAIN: 22.214.171.124.nip.io KUBE_CONTEXT: "gitlab-examples/ops/gitops-demo/k8s-agents:demo-agent" KUBE_NAMESPACE: "demo-agent"
To test your pipeline, on the left sidebar, select Build > Pipelines and then Run pipeline.
For an example, view this project.
Migrate generic deployments
Follow the process for the CI/CD workflow.
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 from GitLab Managed Apps to a cluster management project.
- Migrate the cluster management project to use the agent.
Migrate a cluster management project
Migrate cluster monitoring features
Cluster monitoring features are not yet supported by the GitLab agent for Kubernetes.