@@ -8,110 +8,134 @@ info: To determine the technical writer assigned to the Stage/Group associated w
> [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
To get started with the Agent, install it in your cluster.
To connect a cluster to GitLab, you need to install the GitLab Agent
onto your cluster.
## Prerequisites **(SELF)**
## Prerequisites
- An existing Kubernetes cluster.
- On self-managed GitLab instances, a GitLab administrator needs to set up the [GitLab Agent Server (KAS)](../../../../administration/clusters/kas.md).
## Installation steps
To install the [Agent](../index.md) in your cluster:
To install the GitLab Agent on your cluster:
1.[Define a configuration repository](#define-a-configuration-repository).
1.[Register an agent with GitLab](#register-an-agent-with-gitlab).
1.[Install the agent into the cluster](#install-the-agent-into-the-cluster).
1.[Register the Agent with GitLab](#register-the-agent-with-gitlab).
1.[Install the Agent onto the cluster](#install-the-agent-onto-the-cluster).
<iclass="fa fa-youtube-play youtube"aria-hidden="true"></i> Watch a GitLab 14.2 [walking-through video](https://www.youtube.com/watch?v=XuBpKtsgGkE) with this process.
When you complete the installation process, you can
[view your Agent's status and activity information](#view-your-agents).
You can also [configure](#configure-the-agent) it to your needs.
### Define a configuration repository
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/259669) in GitLab 13.7, the Agent manifest configuration can be added to multiple directories (or subdirectories) of its repository.
> - Group authorization was [introduced](https://gitlab.com/groups/gitlab-org/-/epics/5784) in GitLab 14.3.
To create an agent, you need a GitLab repository to hold the configuration file.
To create an Agent, you need a GitLab repository to hold its
configuration file. If you already have a repository holding your
cluster's manifest files, you can use it to store your
Agent's configuration file and sync them with no further steps.
After installed, when you update the configuration file, GitLab transmits the
information to the cluster automatically without downtime.
#### Create the Agent's configuration file
In your repository, add the Agent configuration file under:
To create an Agent, go to the repository where you want to store
it and add the Agent's configuration file under:
```plaintext
.gitlab/agents/<agent-name>/config.yaml
```
Make sure that `<agent-name>` conforms to the [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name).
WARNING:
The agent is only recognized if you use `.yaml` extension for the `config.yaml` file. The extension `.yml` is **not** recognized.
You **don't have to add any content** to this file at the moment you
create it. The fact that the file exists tells GitLab that this is
an Agent. You can edit it later to [configure the Agent](#configure-the-agent).
You **don't have to add any content** to this file when you create it. The fact that the file exists
tells GitLab that this is an agent configuration file and enables the [CI/CD tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel). Later on, you can use this
file to [configure the agent](../repository.md) by setting up parameters such as:
When creating this file, pay special attention to:
- Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md).
-[Manifest projects to synchronize](../repository.md#synchronize-manifest-projects).
- The address of the `hubble-relay` for the [Network Security policy integrations](../../../project/clusters/protect/index.md).
- The [Agent's naming format](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name).
- The file extension: use the `.yaml` extension (`config.yaml`). The `.yml` extension is **not** recognized.
To see all the settings available, read the [Agent configuration repository documentation](../repository.md).
### Register an agent with GitLab
### Register the Agent with GitLab
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/5786) in GitLab 14.1, you can create a new Agent record directly from the GitLab UI.
Next, create a GitLab Rails Agent record to associate it with
the configuration repository project. Creating this record also creates a Secret needed to configure
the Agent in subsequent steps.
Now that you've created your Agent's configuration file, register it
with GitLab.
When you register the Agent, GitLab generates a token that you need for
installing the Agent onto your cluster.
In GitLab:
In GitLab, go to the project where you added your Agent's configuration
file and:
1. Ensure that [GitLab CI/CD is enabled in your project](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project).
1. From your project's sidebar, select **Infrastructure > Kubernetes clusters**.
1. Select **Actions**.
1. From the **Select an agent** dropdown, select the agent you want to connect and select **Register an agent** to access the installation form.
1. The form reveals your registration token. Securely store this secret token as you cannot view it again.
1. Copy the command under **Recommended installation method**.
1. From the **Select an Agent** dropdown list, select the Agent you want to register and select **Register an Agent**.
1. GitLab generates a registration token for this Agent. Securely store this secret token as you cannot view it again.
1. Copy the command under **Recommended installation method**. You need it to install the Agent onto your cluster through the one-liner installation method.
### Install the Agent onto the cluster
To connect your cluster to GitLab, install the registered Agent
onto your cluster. To install it, you can use 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.
1. Open your local terminal and connect to your cluster.
#### One-liner installation
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).
To install the Agent on your cluster using the one-liner installation:
1. In your computer, open the terminal and connect to your cluster.
1. Run the command you copied when registering your cluster in the previous step.
See the following sections to learn about customizing the installation.
Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation).
## Simple installation method
##### Customize the one-liner installation
The command provided by GitLab does the following things:
The one-liner command generated by GitLab:
- Creates a namespace for the deployment (`gitlab-kubernetes-agent`).
- Sets up a service account with `cluster-admin` rights. Read more on [how you can restrict this service account](#customize-the-permissions-for-the-agentk-service-account).
- Creates a `Secret` resource for the agent registration token.
- 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 registration token.
- Creates a `Deployment` resource for the `agentk` pod.
The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run:
You can edit these parameters according to your needs to customize the
one-liner installation command at the command line. To find all available
options, run in your terminal:
```shell
docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help
```
WARNING:
`--agent-version stable` can be used to refer to the latest stable release at the time when the command runs. It's fine for
testing purposes but for production please make sure to specify a matching version explicitly.
## Advanced installation method
`--agent-version stable` can be used to refer to the latest stable
release at the time when the command runs. It's fine for testing
purposes but for production please make sure to specify a matching
version explicitly.
For more advanced configurations, we recommend to use [the `kpt` based installation method](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/tree/master/build/deployment/gitlab-agent).
#### Advanced installation
Otherwise, follow the manual installation steps described below.
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
##### Customize the permissions for the `agentk` service account
The GitLab Agent for Kubernetes allows you to fully own your cluster and requires only the permissions you give. Still, for easy getting started, by default the generated manifests provide `cluster-admin` rights to the agent.
The GitLab Agent allows you to fully own your cluster and grant GitLab
the permissions you want. Still, to facilitate the process, by default the
generated manifests provide `cluster-admin` rights to the Agent.
As part of the advanced installation method, you can restrict the agent access rights 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.
You can restrict the Agent's access rights 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 create restricted permissions:
...
...
@@ -121,50 +145,67 @@ To create restricted permissions:
The above setup allows you to regularly update from the upstream package using `kpt pkg update gitlab-agent --strategy resource-merge` and maintain your customizations at the same time.
## Example projects
## Configure the Agent
The following example projects can help you get started with the Agent.
When successfully installed, you can [configure the Agent](../repository.md)
by editing its configuration file.
When you update the configuration file, GitLab transmits the
information to the cluster automatically without downtime.
