diff options
Diffstat (limited to 'doc/user/clusters/agent/install/index.md')
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 182 |
1 files changed, 65 insertions, 117 deletions
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index fca80a4a291..e76ef9e827d 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -39,6 +39,9 @@ To install the agent in your cluster: You must register an agent with GitLab. +FLAG: +In GitLab 14.10, a [flag](../../../../administration/feature_flags.md) named `certificate_based_clusters` changed the **Actions** menu to focus on the agent rather than certificates. The flag is [enabled on GitLab.com and self-managed](https://gitlab.com/groups/gitlab-org/configure/-/epics/8). + Prerequisites: - For a [GitLab CI/CD workflow](../ci_cd_tunnel.md), ensure that @@ -48,8 +51,7 @@ To register an agent with GitLab: 1. On the top bar, select **Menu > Projects** and find your project. 1. From the left sidebar, select **Infrastructure > Kubernetes clusters**. -1. Select **Actions**. -1. From the **Select an agent** dropdown list: +1. Select **Connect a cluster (agent)**. - If you want to create a configuration with CI/CD defaults, type a name for the agent. - If you already have an [agent configuration file](#create-an-agent-configuration-file), select it from the list. 1. Select **Register an agent**. @@ -61,11 +63,12 @@ To register an agent with GitLab: > - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the agent configuration file can be added to multiple directories (or subdirectories) of the repository. > - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3. -You can use an agent configuration file to specify details about your implementation. -Creating a file is optional but is needed if: +The agent is configured through a configuration file. This file is optional. Without a configuration file, you can still use the CI/CD workflow in the project where the agent is registered. + +You need a configuration file if: -- You use [a GitOps workflow](../gitops.md#gitops-configuration-reference) and you want a more advanced configuration. -- You use a GitLab CI/CD workflow. In that workflow, you must [authorize the agent](../ci_cd_tunnel.md#authorize-the-agent). +- You want to use [a GitOps workflow](../gitops.md#gitops-configuration-reference). +- You want to authorize a different project to use the agent for a [GitLab CI/CD workflow](../ci_cd_tunnel.md#authorize-the-agent). To create an agent configuration file, go to the GitLab project. In the repository, create a file called `config.yaml` at this path: @@ -79,104 +82,62 @@ To create an agent configuration file, go to the GitLab project. In the reposito - For a GitOps workflow, view [the configuration reference](../gitops.md#gitops-configuration-reference) for details. - For a GitLab CI/CD workflow, you can leave the file blank for now. -The agent bootstraps with the GitLab installation URL and an access token, -and you provide the rest of the configuration in your repository, following -Infrastructure as Code (IaaC) best practices. - ### Install the agent in the cluster -To connect your cluster to GitLab, install the registered agent -in your cluster. To install it, you can use either: +> Introduced in GitLab 14.10, GitLab recommends using Helm to install the agent. -- [The one-liner installation method](#one-liner-installation). -- [The advanced installation method](#advanced-installation). +To connect your cluster to GitLab, install the registered agent +in your cluster. You can either: -You can use the one-liner installation for trying to use the agent for the first time, to do internal setups with -high trust, and to quickly get started. For long-term production usage, you may want to use the advanced installation -method to benefit from more configuration options. +- [Install the agent with Helm](#install-the-agent-with-helm). +- Or, follow the [advanced installation method](#advanced-installation-method). -#### One-liner installation +If you do not know which one to choose, we recommend starting with Helm. -The one-liner installation is the simplest process, but you need -Docker installed locally. If you don't have it, you can either install -it or opt to the [advanced installation method](#advanced-installation). +#### Install the agent with Helm -To install the agent on your cluster using the one-liner installation: +To install the agent on your cluster using Helm: +1. [Install Helm](https://helm.sh/docs/intro/install/) 1. In your computer, open a terminal and [connect to your cluster](https://kubernetes.io/docs/tasks/access-application-cluster/access-cluster/). -1. Run the command you copied when registering your cluster in the previous step. +1. Run the command you copied when registering your agent with GitLab. -Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation). +Optionally, you can [customize the Helm installation](#customize-the-helm-installation). -##### Customize the one-liner installation +##### Customize the Helm installation -By default, the one-liner command generated by GitLab: +By default, the Helm installation command generated by GitLab: -- Creates a namespace for the deployment (`gitlab-agent`). -- Sets up a service account with `cluster-admin` rights (see [how to restrict this service account](#customize-the-permissions-for-the-agentk-service-account)). -- Creates a `Secret` resource for the agent's access token. +- Creates a namespace `gitlab-agent` for the deployment (`--namespace gitlab-agent`). You can skip creating the namespace by omitting the `--create-namespace` flag. +- Sets up a service account for the agent with `cluster-admin` rights. You can: + - Skip creating the service account by adding `--set serviceAccount.create=false` to the `helm install` command. In this case, you must set `serviceAccount.name` to a pre-existing service account. + - Skip creating the RBAC permissions by adding `--set rbac.create=false` to the `helm install` command. In this case, you must bring your own RBAC permissions for the agent. Otherwise, it has no permissions at all. +- Creates a `Secret` resource for the agent's access token. To instead bring your own secret with a token, omit the token (`--set token=...`) and instead use `--set config.secretName=<your secret name>`. - Creates a `Deployment` resource for the `agentk` pod. -You can edit these parameters to customize the one-liner installation command. -To view all available options, open a terminal and run this command: - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help - -Usage: - cli generate [flags] - -Flags: - --agent-token string Access token registered for agent - --agent-version string Version of the agentk image to use (default "v14.8.1") - -h, --help help for generate - --kas-address string GitLab agent server for Kubernetes address - --name-prefix string The prefix to use for names of Kubernetes objects - --namespace string Kubernetes namespace to create resources in (default "gitlab-agent") - --no-rbac Do not include corresponding Roles and RoleBindings for the agent service account -``` - -WARNING: -Use `--agent-version stable` to refer to the latest stable -release at the time when the command runs. For production, however, -you should explicitly specify a matching version. - -#### Advanced installation - -For advanced installation options, use [the `kpt` installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). - -##### Customize the permissions for the `agentk` service account - -You own your cluster and can grant GitLab the permissions you want. -By default, however, the generated manifests provide `cluster-admin` rights to the agent. - -You can restrict the agent's access rights by using Kustomize overlays. [An example is commented out](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/build/deployment/gitlab-agent/cluster/kustomization.yaml) in the `kpt` package you retrieved as part of the installation. - -To restrict permissions: +To see the full list of customizations available, see the Helm chart's [default values file](https://gitlab.com/gitlab-org/charts/gitlab-agent/-/blob/main/values.yaml). -1. Copy the `cluster` directory. -1. Edit the `kustomization.yaml` and `components/*` files based on your requirements. -1. Run `kustomize build <your copied directory> | kubectl apply -f -` to apply your configuration. +#### Advanced installation method -#### Update the advanced installation base layer - -Now you can update from the upstream package by using `kpt pkg update gitlab-agent --strategy resource-merge`. -When the advanced installation setup changes, you will not need to change your custom overlays. +GitLab also provides a [KPT package for the agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent). This method provides greater flexibility, but is only recommended for advanced users. ## Install multiple agents in your cluster -For total separation between teams, you might need to run multiple `agentk` instances in your cluster. -You might want multiple agents so you can restrict RBAC for every `agentk` deployment. +To install a second agent in your cluster, you can follow the [previous steps](#register-the-agent-with-gitlab) a second time. To avoid resource name collisions within the cluster, you must either: + +- Use a different release name for the agent, e.g. `second-gitlab-agent`: -To install multiple agents, follow the -[advanced installation steps](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent) -a second time and: + ```shell + helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ... + ``` -1. Change the agent name and create a new configuration file. -1. Register the new agent. You receive a new access token. Each token should be used only with one agent. -1. Change the namespace or prefix you use for the installation. +- Or, install the agent in a different namespace, e.g. `different-namespace`: -You should also change the RBAC for the installed `agentk`. + ```shell + helm upgrade --install gitlab-agent gitlab/gitlab-agent \ + --namespace different-namespace \ + ... + ``` ## Example projects @@ -187,50 +148,37 @@ The following example projects can help you get started with the agent. - [Auto DevOps setup that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service) - [Cluster management project template example that uses the CI/CD workflow](https://gitlab.com/gitlab-examples/ops/gitops-demo/cluster-management) -## Upgrades and version compatibility - -The agent has two major components: `agentk` and `kas`. -GitLab provides `kas` installers built into the various GitLab installation methods. -The required `kas` version corresponds to the GitLab `major.minor` (X.Y) versions. - -At the same time, `agentk` and `kas` can differ by 1 minor version in either direction. For example, -`agentk` 14.4 supports `kas` 14.3, 14.4, and 14.5 (regardless of the patch). +## Updates and version compatibility -A feature introduced in a given GitLab minor version might work with other `agentk` or `kas` versions. -To ensure it works, use at least the same `agentk` and `kas` minor version. For example, -if your GitLab version is 14.2, use at least `agentk` 14.2 and `kas` 14.2. - -We recommend upgrading your `kas` installations together with GitLab instances' upgrades, and to -[upgrade the `agentk` installations](#update-the-agent-version) after upgrading GitLab. +> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the agent's list page to update the agent version installed on your cluster. -The available `agentk` and `kas` versions are available in -[the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/). +For the best experience, the version of the agent installed in your cluster should match the GitLab major and minor version. The previous minor version is also supported. For example, if your GitLab version is v14.9.4 (major version 14, minor version 9), then versions v14.9.0 and v14.9.1 of the agent are ideal, but any v14.8.x version of the agent is also supported. See [this page](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/releases) of releases of the GitLab agent. ### Update the agent version -> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8, GitLab warns you on the agent's list page to update the agent version installed on your cluster. - -To update the agent's version, re-run the [installation command](#install-the-agent-in-the-cluster) -with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`. -The available `agentk` versions are in [the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc). +To update the agent to the latest version, you can run: -If you don't have access to your agent's access token, you can retrieve it from your cluster: - -1. Open a terminal and connect to your cluster. -1. To retrieve the namespace, run: +```shell +helm repo update +helm upgrade --install gitlab-agent gitlab/gitlab-agent \ + --namespace gitlab-agent \ + --reuse-values +``` - ```shell - kubectl get namespaces - ``` +To set a specific version, you can override the `image.tag` value. For example, to install version `v14.9.1`, run: -1. To retrieve the secret, run: +```shell +helm upgrade gitlab-agent gitlab/gitlab-agent \ + --namespace gitlab-agent \ + --reuse-values \ + --set image.tag=v14.9.1 +``` - ```shell - kubectl -n <namespace> get secrets - ``` +## Uninstall the agent -1. To retrieve the access token, run: +If you [installed the agent with Helm](#install-the-agent-with-helm), then you can also uninstall with Helm. For example, if the release and namespace are both called `gitlab-agent`, then you can uninstall the agent using the following command: - ```shell - kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode - ``` +```shell +helm uninstall gitlab-agent \ + --namespace gitlab-agent +``` |