index.md 6.93 KB
Newer Older
Matt Kasa's avatar
Matt Kasa committed
1 2 3 4 5 6 7 8 9 10 11 12
---
stage: Enablement
group: Distribution
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/#designated-technical-writers
---

# Using the GitLab-Kas chart

The `kas` sub-chart provides a configurable deployment of the [Kubernetes Agent Server](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent#gitlab-kubernetes-agent-server-kas), which is the server-side component of the [GitLab Kubernetes Agent](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent) implementation.

## Requirements

13
This chart depends on access to the GitLab API and the Gitaly Servers. An Ingress is deployed if this chart is enabled.
Matt Kasa's avatar
Matt Kasa committed
14 15 16

## Design Choices

17
The `kas` container used in this chart use a distroless image for minimal resource consumption. The deployed services are exposed by an Ingress which uses [WebSocket proxying](https://nginx.org/en/docs/http/websocket.html) to permit communication in long lived connections with the external component [`agentk`](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent#gitlab-kubernetes-agent-agentk), which is its Kubernetes cluster-side agent counterpart.
Matt Kasa's avatar
Matt Kasa committed
18

19
The route to access the service will depend on your [Ingress configuration](#ingress).
Matt Kasa's avatar
Matt Kasa committed
20

21
Follow the link for further information about the [GitLab Kubernetes Agent architecture](https://gitlab.com/gitlab-org/cluster-integration/gitlab-agent/-/blob/master/doc/architecture.md).
Matt Kasa's avatar
Matt Kasa committed
22 23 24

## Configuration

25 26 27 28 29 30 31 32 33
### Enable

`kas` is deployed turned off by default. To enable it on your GitLab server, use the Helm property `global.kas.enabled`, like: `helm install --set global.kas.enabled=true`.

### Ingress

When using the chart's Ingress with default configuration, the KAS service will be reachable via a subdomain. For example, if you have `global.hosts.domain: example.com`, then by default KAS will be reachable at `kas.example.com`.

The [KAS Ingress](https://gitlab.com/gitlab-org/charts/gitlab/-/blob/master/charts/gitlab/charts/kas/templates/ingress.yaml) can use a different domain than what is used globally under `global.hosts.domain` by setting `global.hosts.kas.name`. For example, setting `global.hosts.kas.name=kas.my-other-domain.com` will set `kas.my-other-domain.com` as the host for the KAS Ingress alone, while the rest of the services (including GitLab, Registry, MinIO, etc.) will use the domain specified in `global.hosts.domain`.
Matt Kasa's avatar
Matt Kasa committed
34 35 36 37 38 39 40 41 42 43 44

### Installation command line options

The table below contains all the possible charts configurations that can be supplied to
the `helm install` command using the `--set` flags.

| Parameter                   | Default        | Description                      |
| --------------------------- | -------------- | ---------------------------------|
| `annotations`               | `{}`           | Pod annotations                  |
| `extraContainers`           |                | List of extra containers to include      |
| `image.repository`          | `registry.gitlab.com/gitlab-org/cluster-integration/gitlab-agent/kas` | image repository |
45
| `image.tag`                 | `v13.7.0`      | Image tag                        |
46
| `hpa.targetAverageValue`    | `100m`         | Set the autoscaling target value (CPU) |
47
| `ingress.enabled`           |  `true` if `global.kas.enabled=true` | You can use `kas.ingress.enabled` to explicitly turn it on or off. If not set, you can optionally use `global.ingress.enabled` for the same purpose. |
Matt Kasa's avatar
Matt Kasa committed
48
| `ingress.annotations`       | `{}`           | Ingress annotations              |
49
| `ingress.tls`               | `{}`           | Ingress TLS configuration        |
50 51 52
| `metrics.enabled`           | `true`         | Toggle Prometheus metrics exporter |
| `metrics.port`              | `8151`         | Port number to use for the metrics exporter |
| `metrics.path`              | `/metrics`     | Path to use for the metrics exporter |
Matt Kasa's avatar
Matt Kasa committed
53 54 55
| `maxReplicas`               | `10`           | HPA `maxReplicas`                |
| `maxUnavailable`            | `1`            | HPA `maxUnavailable`             |
| `minReplicas`               | `2`            | HPA `maxReplicas`                |
56
| `nodeSelector`              |                | Define a [nodeSelector](https://kubernetes.io/docs/concepts/scheduling-eviction/assign-pod-node/#nodeselector) for the `Pod`s of this `Deployment`, if present. |
Matt Kasa's avatar
Matt Kasa committed
57
| `serviceAccount.annotations`| `{}`       | Service account annotations      |
58
| `podLabels`                 | `{}`           | Supplemental Pod labels. Not used for selectors. |
59 60
| `serviceLabels`             | `{}`           | Supplemental service labels |
| `common.labels`             |                | Supplemental labels that are applied to all objects created by this chart. |
61
| `redis.enabled`             | `true`         | Allows opting-out of using Redis for KAS features. Warnings: Redis will become a hard dependency soon, so this key is already deprecated. |
62
| `resources.requests.cpu`    | `75m`                 | GitLab Exporter minimum CPU                    |
Matt Kasa's avatar
Matt Kasa committed
63
| `resources.requests.memory` | `100M`                | GitLab Exporter minimum memory                 |
Thong Kuah's avatar
Thong Kuah committed
64 65
| `service.externalPort`      | `8150`         | External port                    |
| `service.internalPort`      | `8150`         | Internal port                    |
Matt Kasa's avatar
Matt Kasa committed
66 67
| `service.type`              | `ClusterIP`    | Service type                     |
| `tolerations`               | `[]`           | Toleration labels for pod assignment     |
68
| `customConfig`              | `{}`           | When given, merges the default `kas` configuration with these values giving precedence to those defined here. |
Matt Kasa's avatar
Matt Kasa committed
69

70
## Development (how to manual QA)
Matt Kasa's avatar
Matt Kasa committed
71

72
To install the chart:
Matt Kasa's avatar
Matt Kasa committed
73

74 75 76 77
1. Create your own Kubernetes cluster.
1. Check out the merge request's working branch.
1. Install (or upgrade) GitLab with `kas` enabled from your local chart branch,
   using `--set global.kas.enabled=true`, for example:
Matt Kasa's avatar
Matt Kasa committed
78 79 80

   ```shell
   helm upgrade --force --install gitlab . \
81
     --timeout 600s \
Matt Kasa's avatar
Matt Kasa committed
82 83 84 85 86 87
     --set global.hosts.domain=your.domain.com \
     --set global.hosts.externalIP=XYZ.XYZ.XYZ.XYZ \
     --set certmanager-issuer.email=your@email.com \
     --set global.kas.enabled=true
   ```

88 89 90
1. Use the GDK to run the process to configure and use the
   [GitLab Kubernetes Agent](https://docs.gitlab.com/ee/user/clusters/agent/):
   (You can also follow the steps to configure and use the Agent manually.)
Matt Kasa's avatar
Matt Kasa committed
91

92
   1. From your GDK GitLab repository, move into the QA folder: `cd qa`.
93
   1. Run the following command to run the QA test:
Matt Kasa's avatar
Matt Kasa committed
94

95 96 97 98 99 100 101
      ```shell
      GITLAB_USERNAME=$ROOT_USER
      GITLAB_PASSWORD=$ROOT_PASSWORD
      GITLAB_ADMIN_USERNAME=$ROOT_USER
      GITLAB_ADMIN_PASSWORD=$ROOT_PASSWORD
      bundle exec bin/qa Test::Instance::All https://your.gitlab.domain/ -- --tag orchestrated --tag quarantine qa/specs/features/ee/api/7_configure/kubernetes/kubernetes_agent_spec.rb
      ```
Matt Kasa's avatar
Matt Kasa committed
102

103
      You can also customize the `agentk` version to install with an environment variable: `GITLAB_AGENTK_VERSION=v13.7.1`