Recommend Helm for installing the GitLab agent

The GitLab agent now has a Helm chart, see
https://gitlab.com/gitlab-org/charts/gitlab-agent

This is now the recommended installation method as Helm is ubiquitous
and provides better support for day-two operations.

Changelog: changed

app/assets/javascripts/clusters_list/clusters_util.js

 export function generateAgentRegistrationCommand(agentToken, kasAddress) {
-  return `docker run --pull=always --rm \\
-    registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate \\
-    --agent-token=${agentToken} \\
-    --kas-address=${kasAddress} \\
-    --agent-version stable \\
-    --namespace gitlab-kubernetes-agent | kubectl apply -f -`;
+  return `helm repo add gitlab https://charts.gitlab.io
+helm repo update
+helm upgrade --install gitlab-agent gitlab/gitlab-agent \\
+    --namespace gitlab-agent \\
+    --create-namespace \\
+    --set config.token=${agentToken} \\
+    --set config.kasAddress=${kasAddress}`;
 }
 
 export function getAgentConfigPath(clusterAgentName) {

app/assets/javascripts/clusters_list/components/agent_token.vue

@@ -9,7 +9,7 @@ import { I18N_AGENT_TOKEN } from '../constants';
 export default {
   i18n: I18N_AGENT_TOKEN,
   advancedInstallPath: helpPagePath('user/clusters/agent/install/index', {
-    anchor: 'advanced-installation',
+    anchor: 'advanced-installation-method',
   }),
   components: {
     GlAlert,

app/assets/javascripts/clusters_list/constants.js

@@ -96,9 +96,9 @@ export const I18N_AGENT_TOKEN = {
   ),
   tokenSubtitle: s__('ClusterAgents|The agent uses the token to connect with GitLab.'),
 
-  basicInstallTitle: s__('ClusterAgents|Recommended installation method'),
+  basicInstallTitle: s__('ClusterAgents|Install using Helm (recommended)'),
   basicInstallBody: s__(
-    'ClusterAgents|From a terminal, connect to your cluster and run this command. The token is included.',
+    'ClusterAgents|From a terminal, connect to your cluster and run this command. The token is included in the command.',
   ),
 
   advancedInstallTitle: s__('ClusterAgents|Advanced installation methods'),

doc/user/clusters/agent/install/index.md

@@ -63,13 +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 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 need a configuration file if:
 
-If you do not create an agent configuration file, you can use the CI/CD workflow in the project where the agent is registered only.
+- 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:
 
@@ -83,108 +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:
-
-- [The one-liner installation method](#one-liner-installation).
-- [The advanced installation method](#advanced-installation).
+> Introduced in GitLab 14.10, GitLab recommends using Helm to install the agent.
 
-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.
+To connect your cluster to GitLab, install the registered agent
+in your cluster. You can either:
 
-#### One-liner installation
+- [Install the agent with Helm](#install-the-agent-with-helm).
+- Or, follow the [advanced installation method](#advanced-installation-method).
 
-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).
+If you do not know which one to choose, we recommend starting with Helm.
 
-Use the one-liner process for simple use cases or to get started with the agent for Kubernetes.
-For production use, opt for the [advanced installation method](#advanced-installation)
-as it gives you more customization options and access to all settings.
+#### 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:
-
-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.
+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).
 
-#### Update the advanced installation base layer
+#### Advanced installation method
 
-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:
 
-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:
+- Use a different release name for the agent, e.g. `second-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.
+  ```shell
+  helm upgrade --install second-gitlab-agent gitlab/gitlab-agent ...
+  ```
 
-You should also change the RBAC for the installed `agentk`.
+- Or, install the agent in a different namespace, e.g. `different-namespace`:
+
+  ```shell
+  helm upgrade --install gitlab-agent gitlab/gitlab-agent \
+    --namespace different-namespace \
+    ...
+  ```
 
 ## Example projects
 
@@ -195,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).
-
-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.
+## Updates and version compatibility
 
-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
+```

locale/gitlab.pot

@@ -8001,7 +8001,7 @@ msgstr ""
 msgid "ClusterAgents|Failed to register an agent"
 msgstr ""
 
-msgid "ClusterAgents|From a terminal, connect to your cluster and run this command. The token is included."
+msgid "ClusterAgents|From a terminal, connect to your cluster and run this command. The token is included in the command."
 msgstr ""
 
 msgid "ClusterAgents|GitLab agent"
@@ -8019,6 +8019,9 @@ msgstr ""
 msgid "ClusterAgents|How to update an agent?"
 msgstr ""
 
+msgid "ClusterAgents|Install using Helm (recommended)"
+msgstr ""
+
 msgid "ClusterAgents|Last connected %{timeAgo}."
 msgstr ""
 
@@ -8052,9 +8055,6 @@ msgstr ""
 msgid "ClusterAgents|Recommended"
 msgstr ""
 
-msgid "ClusterAgents|Recommended installation method"
-msgstr ""
-
 msgid "ClusterAgents|Register"
 msgstr ""
 

spec/features/clusters/create_agent_spec.rb

@@ -34,7 +34,7 @@ RSpec.describe 'Cluster agent registration', :js do
 
     expect(page).to have_content('You cannot see this token again after you close this window.')
     expect(page).to have_content('example-agent-token')
-    expect(page).to have_content('docker run --pull=always --rm')
+    expect(page).to have_content('helm upgrade --install')
 
     within find('.modal-footer') do
       click_button('Close')

spec/frontend/clusters_list/components/agent_token_spec.js

@@ -69,8 +69,8 @@ describe('InstallAgentModal', () => {
     });
 
     it('shows code block with agent installation command', () => {
-      expect(findCodeBlock().props('code')).toContain(`--agent-token=${agentToken}`);
-      expect(findCodeBlock().props('code')).toContain(`--kas-address=${kasAddress}`);
+      expect(findCodeBlock().props('code')).toContain(`--set config.token=${agentToken}`);
+      expect(findCodeBlock().props('code')).toContain(`--set config.kasAddress=${kasAddress}`);
     });
   });
 });