diff options
Diffstat (limited to 'doc/user/clusters/agent/ci_cd_tunnel.md')
| -rw-r--r-- | doc/user/clusters/agent/ci_cd_tunnel.md | 71 |
1 files changed, 35 insertions, 36 deletions
diff --git a/doc/user/clusters/agent/ci_cd_tunnel.md b/doc/user/clusters/agent/ci_cd_tunnel.md index f1c49b87383..5fe772d9686 100644 --- a/doc/user/clusters/agent/ci_cd_tunnel.md +++ b/doc/user/clusters/agent/ci_cd_tunnel.md @@ -12,53 +12,52 @@ info: To determine the technical writer assigned to the Stage/Group associated w > - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) to GitLab Free in 14.5. > - Support for Omnibus installations was [introduced](https://gitlab.com/gitlab-org/omnibus-gitlab/-/merge_requests/5686) in GitLab 14.5. -The CI/CD Tunnel enables users to access Kubernetes clusters from GitLab CI/CD jobs even if there is no network -connectivity between GitLab Runner and a cluster. GitLab Runner does not have to be running in the same cluster. +To use GitLab CI/CD to safely deploy your application to a cluster, you can use the CI/CD Tunnel. -Only CI/CD jobs set in the configuration project can access one of the configured agents. +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. -## Prerequisites - -- An existing Kubernetes cluster. -- An agent [installed on your cluster](install/index.md#install-the-agent-into-the-cluster). +To ensure access to your cluster is safe, only the projects you +authorize can access your Agent through the CI/CD Tunnel. -## Use the CI/CD Tunnel to run Kubernetes commands from GitLab CI/CD - -If your project has access to one or more Agent records available, its CI/CD -jobs provide a `KUBECONFIG` variable compatible with `kubectl`. +## Prerequisites -Also, each Agent has a separate context (`kubecontext`). By default, -there isn't any context selected. -Contexts are named in the following format: `<agent-configuration-project-path>:<agent-name>`. -To get the list of available contexts, run `kubectl config get-contexts`. +To use the CI/CD Tunnel, you need an existing Kubernetes cluster connected to GitLab through the +[GitLab Agent](install/index.md#install-the-agent-onto-the-cluster). -## Share the CI/CD Tunnel provided by an Agent with other projects and groups +To run your CI/CD jobs using the CI/CD Tunnel, you do not need to have a runner in the same cluster. -The Agent can be configured to enable access to the CI/CD Tunnel to other projects or all the projects under a given group. This way you can have a single agent serving all the requests for several projects saving on resources and maintenance. +## How the CI/CD Tunnel works -You can read more on how to [authorize access in the Agent configuration reference](repository.md#authorize-projects-and-groups-to-use-an-agent). +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. -## Restrict access of authorized projects and groups **(PREMIUM)** +When you authorize a group, all the projects that belong to that group +become authorized to access the selected Agent. -You can [configure various impersonations](repository.md#use-impersonation-to-restrict-project-and-group-access) to restrict the permissions of a shared CI/CD Tunnel. +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. -## Example for a `kubectl` command using the CI/CD Tunnel +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. -The following example shows a CI/CD job that runs a `kubectl` command using the CI/CD Tunnel. -You can run any Kubernetes-specific commands similarly, such as `kubectl`, `helm`, -`kpt`, and so on. To do so: +### `~/.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. -1. Set your Agent's context in the first command with the format `<agent-configuration-project-path>:<agent-name>`. -1. Run Kubernetes commands. +## Configure the CI/CD Tunnel -For example: +The CI/CD Tunnel is configured directly through the +Agent's configuration file ([`config.yaml`](repository.md)) to: -```yaml - deploy: - image: - name: bitnami/kubectl:latest - entrypoint: [""] - script: - - kubectl config use-context path/to/agent-configuration-project:your-agent-name - - kubectl get pods -``` +- Authorize [projects](repository.md#authorize-projects-to-use-an-agent) and [groups](repository.md#authorize-groups-to-use-an-agent) to use the same Agent. +- [Run `kubectl` commands using the CI/CD Tunnel](repository.md#run-kubectl-commands-using-the-cicd-tunnel). +- [Restrict access of authorized projects and groups through impersonation strategies](repository.md#use-impersonation-to-restrict-project-and-group-access). |