diff options
Diffstat (limited to 'doc/user/clusters/agent/install/index.md')
| -rw-r--r-- | doc/user/clusters/agent/install/index.md | 258 |
1 files changed, 25 insertions, 233 deletions
diff --git a/doc/user/clusters/agent/install/index.md b/doc/user/clusters/agent/install/index.md index cf8467a8d28..b2372789284 100644 --- a/doc/user/clusters/agent/install/index.md +++ b/doc/user/clusters/agent/install/index.md @@ -10,42 +10,27 @@ info: To determine the technical writer assigned to the Stage/Group associated w To get started with the Agent, install it in your cluster. -Pre-requisites: +## Prerequisites **(SELF)** - An existing Kubernetes cluster. -- An account on GitLab. +- 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: -1. [Set up the Agent Server](#set-up-the-agent-server) for your GitLab instance. 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. [Generate and copy a Secret token used to connect to the agent](#create-the-kubernetes-secret). -1. [Create manifest files](#create-manifest-files). <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. -### Set up the Agent Server - -> [Introduced](https://gitlab.com/groups/gitlab-org/-/epics/3834) in [GitLab Premium](https://about.gitlab.com/pricing/) 13.10, the GitLab Agent Server (KAS) became available on GitLab.com under `wss://kas.gitlab.com`. - -To use the KAS: - -- If you are a self-managed user, follow the instructions to [install the Agent Server](../../../../administration/clusters/kas.md). -- If you are a GitLab.com user, when you [set up the configuration repository](#define-a-configuration-repository) for your agent, use `wss://kas.gitlab.com` as the `--kas-address`. - ### 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: - -1. A GitLab repository to hold the configuration file. -1. Install the Agent in a cluster. +To create an agent, you need a GitLab repository to hold the configuration file. After installed, when you update the configuration file, GitLab transmits the information to the cluster automatically without downtime. @@ -62,7 +47,7 @@ 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 when you create it. The fact that the file exists -tells GitLab that this is an agent configuration file. It doesn't do anything so far, but, later on, you can use this +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: - Groups and projects that can access the agent via the [CI/CD Tunnel](../ci_cd_tunnel.md). @@ -71,10 +56,6 @@ file to [configure the agent](../repository.md) by setting up parameters such as To see all the settings available, read the [Agent configuration repository documentation](../repository.md). -### Access your cluster from GitLab CI/CD - -Use the [CI/CD Tunnel](../ci_cd_tunnel.md#example-for-a-kubectl-command-using-the-cicd-tunnel) to access your cluster from GitLab CI/CD. - ### Register an 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. @@ -92,242 +73,53 @@ In GitLab: 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**. +### Install the agent into the cluster + In your computer: 1. Open your local terminal and connect to your cluster. -1. Run the command you copied from the installation form. +1. Run the command you copied when registering your cluster in the previous step. -### Install the agent into the cluster +See the following sections to learn about customizing the installation. -To install the in-cluster component of the Agent, first you need to define a namespace. To create a new namespace, -for example, `gitlab-kubernetes-agent`, run: +## Simple installation method -```shell -kubectl create namespace gitlab-kubernetes-agent -``` +The command provided by GitLab does the following things: -To perform a one-liner installation, run the command below. Make sure to replace: +- 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. +- Creates a `Deployment` resource for the `agentk` pod. -- `your-agent-token` with the token received from the previous step (identified as `secret` in the JSON output). -- `gitlab-kubernetes-agent` with the namespace you defined in the previous step. -- `wss://kas.gitlab.example.com` with the configured access of the Agent Server (KAS). For GitLab.com users, the KAS is available under `wss://kas.gitlab.com`. -- `--agent-version=vX.Y.Z` with the latest released patch version matching your GitLab installation's major and minor versions. For example, for GitLab v13.9.0, use `--agent-version=v13.9.1`. You can find your GitLab version under the "Help/Help" menu. +The one-liner installer can be customized at the command line. To find out the various options the above Docker container supports, run: ```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --agent-token=your-agent-token --kas-address=wss://kas.gitlab.example.com --agent-version=vX.Y.Z --namespace gitlab-kubernetes-agent | kubectl apply -f - +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. -To find out the various options the above Docker container supports, run: - -```shell -docker run --pull=always --rm registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/cli:stable generate --help -``` - -## Advanced installation +## Advanced installation method 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). Otherwise, follow the manual installation steps described below. -### Create the Kubernetes secret - -After generating the token, you must apply it to the Kubernetes cluster. - -To create your Secret, run: - -```shell -kubectl create secret generic -n gitlab-kubernetes-agent gitlab-kubernetes-agent-token --from-literal=token='YOUR_AGENT_TOKEN' -``` - -The following example file contains the -Kubernetes resources required for the Agent to be installed. You can modify this -example [`resources.yml` file](#example-resourcesyml-file) in the following ways: - -- Replace `namespace: gitlab-kubernetes-agent` with `namespace: <YOUR-DESIRED-NAMESPACE>`. -- You can configure `kas-address` (Agent Server) in several ways. - The agent can use the WebSockets or gRPC protocols to connect to the Agent Server. - Select the option appropriate for your cluster configuration and GitLab architecture: - - The `wss` scheme (an encrypted WebSockets connection) is specified by default - after you install the `gitlab-kas` sub-chart, or enable `gitlab-kas` for Omnibus GitLab. - When using the sub-chart, you must set `wss://kas.host.tld:443` as - `kas-address`, where `host.tld` is the domain you've setup for your GitLab installation. - When using Omnibus GitLab, you must set `wss://GitLab.host.tld:443/-/kubernetes-agent/` as - `kas-address`, where `GitLab.host.tld` is your GitLab hostname. - - When using the sub-chart, specify the `ws` scheme (such as `ws://kas.host.tld:80`) - to use an unencrypted WebSockets connection. - When using the Omnibus GitLab, specify the `ws` scheme (such as `ws://GitLab.host.tld:80/-/kubernetes-agent/`). - - Specify the `grpc` scheme if both Agent and Server are installed in one cluster. - In this case, you may specify `kas-address` value as - `grpc://gitlab-kas.<your-namespace>:8150`) to use gRPC directly, where `gitlab-kas` - is the name of the service created by `gitlab-kas` chart, and `<your-namespace>` - is the namespace where the chart was installed. - - Specify the `grpcs` scheme to use an encrypted gRPC connection. - - When deploying KAS through the [GitLab chart](https://docs.gitlab.com/charts/), it's possible to customize the - `kas-address` for `wss` and `ws` schemes to whatever you need. - Check the [chart's KAS Ingress documentation](https://docs.gitlab.com/charts/charts/gitlab/kas/#ingress) - to learn more about it. - - In the near future, Omnibus GitLab intends to provision `gitlab-kas` under a sub-domain by default, instead of the `/-/kubernetes-agent/` path. Please follow [this issue](https://gitlab.com/gitlab-org/omnibus-gitlab/-/issues/5784) for details. -- If you defined your own secret name, replace `gitlab-kubernetes-agent-token` with your - secret name in the `secretName:` section. - -To apply this file, run the following command: +### Customize the permissions for the `agentk` service account -```shell -kubectl apply -n gitlab-kubernetes-agent -f ./resources.yml -``` - -To review your configuration, run the following command: - -```shell -$ kubectl get pods -n gitlab-kubernetes-agent - -NAMESPACE NAME READY STATUS RESTARTS AGE -gitlab-kubernetes-agent gitlab-kubernetes-agent-77689f7dcb-5skqk 1/1 Running 0 51s -``` - -#### Example `resources.yml` file - -```yaml ---- -apiVersion: v1 -kind: Namespace -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: v1 -kind: ServiceAccount -metadata: - name: gitlab-kubernetes-agent ---- -apiVersion: apps/v1 -kind: Deployment -metadata: - name: gitlab-kubernetes-agent -spec: - replicas: 1 - selector: - matchLabels: - app: gitlab-kubernetes-agent - template: - metadata: - labels: - app: gitlab-kubernetes-agent - spec: - serviceAccountName: gitlab-kubernetes-agent - containers: - - name: agent - # Make sure to specify a matching version for production - image: "registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/agentk:vX.Y.Z" - args: - - --token-file=/config/token - - --kas-address - - wss://kas.host.tld:443 # replace this line with the line below if using Omnibus GitLab or GitLab.com. - # - wss://gitlab.host.tld:443/-/kubernetes-agent/ - # - wss://kas.gitlab.com # for GitLab.com users, use this KAS. - # - grpc://host.docker.internal:8150 # use this attribute when connecting from Docker. - volumeMounts: - - name: token-volume - mountPath: /config - volumes: - - name: token-volume - secret: - secretName: gitlab-kubernetes-agent-token - strategy: - type: RollingUpdate - rollingUpdate: - maxSurge: 0 - maxUnavailable: 1 ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-write -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - create - - update - - delete - - patch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-write-binding -roleRef: - name: gitlab-kubernetes-agent-write - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRole -metadata: - name: gitlab-kubernetes-agent-read -rules: -- resources: - - '*' - apiGroups: - - '*' - verbs: - - get - - list - - watch ---- -apiVersion: rbac.authorization.k8s.io/v1 -kind: ClusterRoleBinding -metadata: - name: gitlab-kubernetes-agent-read-binding -roleRef: - name: gitlab-kubernetes-agent-read - kind: ClusterRole - apiGroup: rbac.authorization.k8s.io -subjects: -- name: gitlab-kubernetes-agent - kind: ServiceAccount - namespace: gitlab-kubernetes-agent -``` - -### Create manifest files +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. -In a previous step, you configured a `config.yaml` to point to the GitLab projects -the Agent should synchronize. Agent monitors each of those projects for changes to the manifest files it contains. You can auto-generate manifest files with a -templating engine or other means. +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. -The agent is authorized to download manifests for the configuration -project, and public projects. Support for other private projects is -planned in the issue [Agent authorization for private manifest -projects](https://gitlab.com/gitlab-org/gitlab/-/issues/220912). +To create restricted permissions: -Each time you push a change to a monitored manifest repository, the Agent logs the change: +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. -```plaintext -2020-09-15_14:09:04.87946 gitlab-k8s-agent : time="2020-09-15T10:09:04-04:00" level=info msg="Config: new commit" agent_id=1 commit_id=e6a3651f1faa2e928fe6120e254c122451be4eea -``` - -#### Example manifest file - -This file creates a minimal `ConfigMap`: - -```yaml -apiVersion: v1 -kind: ConfigMap -metadata: - name: demo-map - namespace: gitlab-kubernetes-agent # Can be any namespace managed by you that the agent has access to. -data: - key: value -``` +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 |