1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
|
---
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
---
# Installing the agent for Kubernetes **(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.
> - [Introduced](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/merge_requests/603) ARM architecture support in GitLab 14.9.
To connect a Kubernetes cluster to GitLab, you must install an agent in your cluster.
## Prerequisites
Before you can install the agent in your cluster, you need:
- An existing Kubernetes cluster. If you don't have a cluster, you can create one on a cloud provider, like:
- [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 must set up the [agent server](../../../../administration/clusters/kas.md).
On GitLab.com, the agent server is available at `wss://kas.gitlab.com`.
## Installation steps
To install the agent in your cluster:
1. [Register the agent with GitLab](#register-the-agent-with-gitlab).
1. [Install the agent in your cluster](#install-the-agent-in-the-cluster).
<i class="fa fa-youtube-play youtube" aria-hidden="true"></i> Watch a GitLab 14.2 [walk-through of this process](https://www.youtube.com/watch?v=XuBpKtsgGkE).
### 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.
> - [Introduced](https://gitlab.com/gitlab-org/gitlab/-/issues/347240) in GitLab 14.9, the agent can be registered without creating an agent configuration file.
You must register an agent with GitLab.
Prerequisites:
- For a [GitLab CI/CD workflow](../ci_cd_tunnel.md), ensure that
[GitLab CI/CD is enabled](../../../../ci/enable_or_disable_ci.md#enable-cicd-in-a-project).
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:
- 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**.
1. GitLab generates an access token for the agent. Securely store this token. You need it to install the agent in 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 when you use the one-liner installation method to install the agent in your cluster.
### Create an agent configuration file
> - [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:
- 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).
To create an agent configuration file, go to the GitLab project. In the repository, create a file called `config.yaml` at this path:
```plaintext
.gitlab/agents/<agent-name>/config.yaml
```
- Ensure the agent name follows the [naming convention](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/identity_and_auth.md#agent-identity-and-name).
- Ensure the filename has the `.yaml` file extension (`config.yaml`). The `.yml` extension is not accepted.
- Add content to the `config.yaml` file:
- 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).
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 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.
Optionally, you can [customize the one-liner installation command](#customize-the-one-liner-installation).
##### Customize the one-liner installation
By default, the one-liner 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 `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.
#### 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.
## 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 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:
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.
You should also change the RBAC for the installed `agentk`.
## Example projects
The following example projects can help you get started with the agent.
- [Configuration repository with minimal manifests](https://gitlab.com/gitlab-examples/ops/gitops-demo/k8s-agents)
- [Distinct application and manifest repository example](https://gitlab.com/gitlab-examples/ops/gitops-demo/hello-world-service-gitops)
- [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.
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 are available in
[the Container Registry](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/container_registry/).
### 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).
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
kubectl get namespaces
```
1. To retrieve the secret, run:
```shell
kubectl -n <namespace> get secrets
```
1. To retrieve the access token, run:
```shell
kubectl -n <namespace> get secret <secret-name> --template={{.data.token}} | base64 --decode
```
|
