debian-mirror-gitlab/doc/user/clusters/agent/ci_cd_tunnel.md

stage	group	info
Configure	Configure	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

CI/CD Tunnel (FREE)

• Introduced in GitLab 14.1.
• The pre-configured KUBECONFIG was introduced in GitLab 14.2.
• The ability to authorize groups was introduced in GitLab 14.3.
• Moved to GitLab Free in 14.5.
• Support for Omnibus installations was introduced in GitLab 14.5.

To use GitLab CI/CD to safely deploy your application to a cluster, you can use the CI/CD Tunnel.

You can authorize multiple projects to access the same cluster, so you can keep your application's codebase in one repository and configure your cluster in another. This method is scalable and can save you resources.

To ensure access to your cluster is safe, only the projects you authorize can access your Agent through the CI/CD Tunnel.

Prerequisites

To use the CI/CD Tunnel, you need an existing Kubernetes cluster connected to GitLab through the GitLab Agent.

To run your CI/CD jobs using the CI/CD Tunnel, you do not need to have a runner in the same cluster.

How the CI/CD Tunnel works

When you authorize a project to use an Agent, the Tunnel automatically injects a KUBECONFIG variable into its CI/CD jobs. This way, you can run kubectl commands from GitLab CI/CD scripts that belong to the authorized project.

When you authorize a group, all the projects that belong to that group become authorized to access the selected Agent.

An Agent can only authorize projects or groups in the same group hierarchy as the Agent's configuration project. You can authorize up to 100 projects and 100 groups per Agent.

Also, each Agent has a separate context (kubecontext). The Tunnel uses this information to safely allow access to the cluster from jobs running in the projects you authorized.

~/.kube/cache permissions

kubectl and other tools based on the same libraries (such as Helm, kpt, and kustomize) cache information about the cluster in ~/.kube/cache. If this directory is not writable, the tool fetches information on each invocation, making interactions slower and creating unnecessary load on the cluster. Make sure that this directory in the container image you use is writable for the best experience.

Configure the CI/CD Tunnel

The CI/CD Tunnel is configured directly through the Agent's configuration file (config.yaml) to:

• Authorize projects and groups to use the same Agent.
• Run kubectl commands using the CI/CD Tunnel.
• Restrict access of authorized projects and groups through impersonation strategies.