278 lines
13 KiB
Markdown
278 lines
13 KiB
Markdown
---
|
|
stage: Configure
|
|
group: Configure
|
|
info: 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
|
|
---
|
|
|
|
# Install the GitLab Agent **(FREE)**
|
|
|
|
> - [Moved](https://gitlab.com/groups/gitlab-org/-/epics/6290) from GitLab Premium to GitLab Free in 14.5.
|
|
> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/594) multi-arch images in GitLab 14.8. The first multi-arch release is `v14.8.1`. It supports AMD64 and ARM64 architectures.
|
|
|
|
To connect a cluster to GitLab, you need to install the GitLab Agent
|
|
onto your cluster.
|
|
|
|
## Prerequisites
|
|
|
|
- An existing Kubernetes cluster. If you don't have a cluster yet, you can create a new cluster on cloud providers, such as:
|
|
- [Google Kubernetes Engine (GKE)](https://cloud.google.com/kubernetes-engine/docs/quickstart)
|
|
- [Amazon Elastic Kubernetes Service (EKS)](https://docs.aws.amazon.com/eks/latest/userguide/getting-started.html)
|
|
- [Digital Ocean](https://docs.digitalocean.com/products/kubernetes/quickstart/)
|
|
- 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 GitLab Agent on your cluster:
|
|
|
|
1. [Define a configuration repository](#define-a-configuration-repository).
|
|
1. [Register the Agent with GitLab](#register-the-agent-with-gitlab).
|
|
1. [Install the Agent onto the cluster](#install-the-agent-onto-the-cluster).
|
|
|
|
<i class="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 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.
|
|
|
|
#### Create the Agent's configuration file
|
|
|
|
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
|
|
```
|
|
|
|
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).
|
|
|
|
When creating this file, pay special attention 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).
|
|
- The file extension: use the `.yaml` extension (`config.yaml`). The `.yml` extension is **not** recognized.
|
|
|
|
### 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.
|
|
|
|
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, 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 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 need it to install the Agent onto your cluster and to [update the Agent](#update-the-agent-version) to another version.
|
|
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:
|
|
|
|
- [The one-liner installation method](#one-liner-installation).
|
|
- [The advanced installation method](#advanced-installation).
|
|
|
|
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.
|
|
|
|
#### 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.
|
|
|
|
Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation).
|
|
|
|
##### Customize the one-liner installation
|
|
|
|
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 (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.
|
|
|
|
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
|
|
|
|
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
|
|
|
|
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.
|
|
|
|
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:
|
|
|
|
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.
|
|
|
|
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.
|
|
|
|
## Configure 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.
|
|
|
|
## View your Agents
|
|
|
|
> The version of installed `agentk` shown on the Agent tab [introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/340882) in GitLab 14.8.
|
|
If you have at least the Developer role, you can access the Agent's
|
|
configuration repository and view the Agent's list:
|
|
|
|
1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
|
|
1. Select **Agent** tab to view clusters connected to GitLab through the Agent.
|
|
|
|
On this page, you can view:
|
|
|
|
- All the registered Agents for the current project.
|
|
- The connection status.
|
|
- The version of `agentk` installed on your cluster.
|
|
- The path to each Agent's configuration file.
|
|
|
|
Furthermore, if you select one of the Agents on your list, you can view its
|
|
[activity information](#view-the-agents-activity-information).
|
|
|
|
### View the Agent's activity information
|
|
|
|
> [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/277323) in GitLab 14.6.
|
|
|
|
The activity logs help you to identify problems and get the information
|
|
you need for troubleshooting. You can see events from a week before the
|
|
current date. To access an Agent's activity:
|
|
|
|
1. In your Agent's repository, go to the Agents list as described [above](#view-your-agents).
|
|
1. Select the Agent you want to see the activity.
|
|
|
|
The activity list includes:
|
|
|
|
- Agent registration events: when a new token is **created**.
|
|
- Connection events: when an Agent is successfully **connected** to a cluster.
|
|
|
|
Note that the connection status is logged when you connect an Agent for
|
|
the first time or after more than an hour of inactivity.
|
|
|
|
To check what else is planned for the Agent's UI and provide feedback,
|
|
see the [related epic](https://gitlab.com/groups/gitlab-org/-/epics/4739).
|
|
|
|
### View vulnerabilities in cluster images **(ULTIMATE)**
|
|
|
|
> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/6346) in GitLab 14.8 [with a flag](../../../../administration/feature_flags.md) named `cluster_vulnerabilities`. Enabled by default.
|
|
|
|
Users with at least the [Developer role](../../../permissions.md)
|
|
can view cluster vulnerabilities. You can access them through the [vulnerability report](../../../application_security/vulnerabilities/index.md)
|
|
or in your cluster's image through the following process:
|
|
|
|
1. Configure [cluster image scanning](../../../application_security/cluster_image_scanning/index.md)
|
|
to your build process.
|
|
1. Go to your Agent's configuration repository.
|
|
1. On the left sidebar, select **Infrastructure > Kubernetes clusters**.
|
|
1. Select the **Agent** tab.
|
|
1. Select the Agent you want to see the vulnerabilities for.
|
|
|
|
|
|
|
|
## Create multiple Agents
|
|
|
|
You can create and install multiple Agents using the same process
|
|
documented above. Give each Agent's configuration file a unique name
|
|
and you're good to go. You can create multiple Agents, for example:
|
|
|
|
- To reach your cluster from different projects.
|
|
- To connect multiple clusters to GitLab.
|
|
|
|
## 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 on your cluster, you need to re-run the [installation command](#install-the-agent-onto-the-cluster)
|
|
with a newer `--agent-version`. Make sure to specify the other required parameters: `--kas-address`, `--namespace`, and `--agent-token`.
|
|
You can find the available `agentk` versions in [the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/1223205?sort=desc).
|
|
|
|
If you don't have access to your Agent's token, you can retrieve it from your cluster:
|
|
|
|
1. On your computer, open the terminal and connect to your cluster.
|
|
1. To retrieve the namespace, run:
|
|
|
|
```shell
|
|
kubectl get namespaces
|
|
```
|
|
|
|
1. To retrieve the secret, run:
|
|
|
|
```shell
|
|
kubectl -n <namespace> get secrets
|
|
```
|
|
|
|
1. To retrieve the token, run:
|
|
|
|
```shell
|
|
kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode
|
|
```
|
|
|
|
## Example projects
|
|
|
|
The following example projects can help you get started with the Agent.
|
|
|
|
- [Configuration repository](https://gitlab.com/gitlab-org/configure/examples/kubernetes-agent)
|
|
- This basic GitOps example deploys NGINX: [Manifest repository](https://gitlab.com/gitlab-org/configure/examples/gitops-project)
|
|
|
|
## Upgrades and version compatibility
|
|
|
|
The Agent is comprised of two major components: `agentk` and `kas`.
|
|
As we provide `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 make sure that 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.
|
|
|
|
The available `agentk` and `kas` versions can be found in
|
|
[the container registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/).
|