# Gerrit slave on Kubernetes

Gerrit is a web-based code review tool, which acts as a Git server. On large setups
Gerrit servers can see a sizable amount of traffic from git operations performed by
developers and build servers. The major part of requests are read-only requests
(e.g. by `git fetch` operations). To take some load of the Gerrit master server,
Gerrit slaves can be deployed to serve read-only requests.

This helm chart provides a Gerrit slave setup that can be deployed on Kubernetes.
The Gerrit slave is capable of receiving replicated git repositories from a
Gerrit master. The Gerrit slave can then serve authenticated read-only requests.

## Prerequisites

- Helm and Tiller (of course)

    (Check out [this guide](https://docs.helm.sh/using_helm/#quickstart-guide)
    how to install and use helm.)

- Access to a provisioner for persistent volumes with `Read Write Many (RWM)`-
  capability.

    A list of applicaple volume types can be found
    [here](https://kubernetes.io/docs/concepts/storage/persistent-volumes/#access-modes).
    This project was developed using the
    [NFS-server-provisioner helm chart](https://github.com/helm/charts/tree/master/stable/nfs-server-provisioner),
    a NFS-provisioner deployed in the Kubernetes cluster itself. Refer to
    [this guide](/helm-charts/gerrit-slave/docs/nfs-provisioner.md) of how to
    deploy it in context of this project.

- A domain name that is configured to point to the IP address of the node running
  the Ingress controller on the kubernetes cluster (as described
  [here](http://alesnosek.com/blog/2017/02/14/accessing-kubernetes-pods-from-outside-of-the-cluster/)).

- (Optional: Required, if SSL is configured)
  A [Java keystore](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html#httpd.sslKeyStore)
  to be used by Gerrit.

- (Optional: Required, for Gerrit versions lower than 2.16)
  A relational database to contain the ReviewDB, e.g. as provided by the
  [reviewdb chart](/helm-charts/reviewdb). With Gerrit 2.16 an embedded H2-
  database is usually enough, since the data is not changed during runtime.

## Installing the Chart

***note
**ATTENTION:** The value for `gerritSlave.ingress.host` is required for rendering
the chart's templates. The nature of the value does not allow defaults.
Thus a custom `values.yaml`-file setting this value is required!
***

To install the chart with the release name `gerrit-slave`, execute:

```sh
cd $(git rev-parse --show-toplevel)/helm-charts
helm install ./gerrit-slave \
  -n gerrit-slave \
  -f <path-to-custom-values>.yaml
```

The command deploys the Gerrit slave on the current Kubernetes cluster. The
[configuration section](#Configuration) lists the parameters that can be
configured during installation.

## Configuration

The following sections list the configurable values in `values.yaml`. To configure
a Gerrit slave setup, make a copy of the `values.yaml`-file and change the
parameters as needed. The configuration can be applied by installing the chart as
described [above](#Installing-the-chart).

In addition, single options can be set without creating a custom `values.yaml`:

```sh
cd $(git rev-parse --show-toplevel)/helm-charts
helm install ./gerrit-slave \
  -n gerrit-slave \
  --set=gitRepositoryStorage.size=100Gi,gitBackend.replicas=2
```

### Container images

| Parameter                                  | Description                                          | Default                                                              |
|--------------------------------------------|------------------------------------------------------|----------------------------------------------------------------------|
| `images.registry.name`                     | The image registry to pull the container images from | ``                                                                   |
| `images.registry.ImagePullSecret.name`     | Name of the ImagePullSecret                          | `image-pull-secret` (if empty no image pull secret will be deployed) |
| `images.registry.ImagePullSecret.create`   | Whether to create an ImagePullSecret                 | `false`                                                              |
| `images.registry.ImagePullSecret.username` | The image registry username                          | `nil`                                                                |
| `images.registry.ImagePullSecret.password` | The image registry password                          | `nil`                                                                |
| `images.version`                           | The image version (image tag) to use                 | `latest`                                                             |
| `images.imagePullPolicy`                   | Image pull policy                                    | `Always`                                                             |

### Storage classes

For information of how a `StorageClass` is configured in Kubernetes, read the
[official Documentation](https://kubernetes.io/docs/concepts/storage/storage-classes/#introduction).

| Parameter                              | Description                                                       | Default                                           |
|----------------------------------------|-------------------------------------------------------------------|---------------------------------------------------|
| `storageClasses.default.name`          | The name of the default StorageClass (RWO)                        | `default`                                         |
| `storageClasses.default.create`        | Whether to create the StorageClass                                | `false`                                           |
| `storageClasses.default.provisioner`   | Provisioner of the StorageClass                                   | `kubernetes.io/aws-ebs`                           |
| `storageClasses.default.reclaimPolicy` | Whether to `Retain` or `Delete` volumes, when they become unbound | `Delete`                                          |
| `storageClasses.default.parameters`    | Parameters for the provisioner                                    | `parameters.type: gp2`, `parameters.fsType: ext4` |
| `storageClasses.shared.name`           | The name of the shared StorageClass (RWM)                         | `shared-storage`                                  |
| `storageClasses.shared.create`         | Whether to create the StorageClass                                | `false`                                           |
| `storageClasses.shared.provisioner`    | Provisioner of the StorageClass                                   | `nfs`                                             |
| `storageClasses.shared.reclaimPolicy`  | Whether to `Retain` or `Delete` volumes, when they become unbound | `Delete`                                          |
| `storageClasses.shared.parameters`     | Parameters for the provisioner                                    | `parameters.mountOptions: vers=4.1`               |

### Storage for Git repositories

| Parameter                   | Description                                     | Default |
|-----------------------------|-------------------------------------------------|---------|
| `gitRepositoryStorage.size` | Size of the volume storing the Git repositories | `5Gi`   |

### Apache-Git-HTTP-Backend (Git-Backend)

| Parameter                                | Description                                                                 | Default                                                                   |
|------------------------------------------|-----------------------------------------------------------------------------|---------------------------------------------------------------------------|
| `gitBackend.image`                       | Image name of the Apache-git-http-backend container image                   | `k8s-gerrit/apache-git-http-backend`                                      |
| `gitBackend.replicas`                    | Number of pod replicas to deploy                                            | `1`                                                                       |
| `gitBackend.resources`                   | Configure the amount of resources the pod requests/is allowed               | `requests.cpu: 100m`                                                      |
|                                          |                                                                             | `requests.memory: 256Mi`                                                  |
|                                          |                                                                             | `limits.cpu: 100m`                                                        |
|                                          |                                                                             | `limits.memory: 256Mi`                                                    |
| `gitBackend.credentials.htpasswd`        | `.htpasswd`-file containing username/password-credentials for accessing git | `git:$apr1$O/LbLKC7$Q60GWE7OcqSEMSfe/K8xU.` (user: git, password: secret) |
| `gitBackend.logging.persistence.enabled` | Whether to persist logs                                                     | `true`                                                                    |
| `gitBackend.logging.persistence.size`    | Storage size for persisted logs                                             | `1Gi`                                                                     |
| `gitBackend.service.type`                | Which kind of Service to deploy                                             | `LoadBalancer`                                                            |
| `gitBackend.service.http.enabled`        | Whether to serve HTTP-requests (needed for Ingress)                         | `true`                                                                    |
| `gitBackend.service.http.port`           | Port over which to expose HTTP                                              | `80`                                                                      |
| `gitBackend.service.https.enabled`       | Whether to serve HTTPS-requests                                             | `false`                                                                   |
| `gitBackend.service.https.port`          | Port over which to expose HTTPS                                             | `443`                                                                     |
| `gitBackend.service.https.cert`          | Public SSL server certificate                                               | `-----BEGIN CERTIFICATE-----`                                             |
| `gitBackend.service.https.key`           | Private SSL server certificate                                              | `-----BEGIN RSA PRIVATE KEY-----`                                         |
| `gitBackend.ingress.enabled`             | Whether to deploy an Ingress                                                | `false`                                                                   |
| `gitBackend.ingress.host`                | Host name to use for the Ingress (required for Ingress)                     | `nil`                                                                     |
| `gitBackend.ingress.alias`               | Optional: ALias host name for the Ingress                                   | `nil`                                                                     |
| `gitBackend.ingress.tls.enabled`         | Whether to enable TLS termination in the Ingress                            | `false`                                                                   |
| `gitBackend.ingress.tls.cert`            | Public SSL server certificate                                               | `-----BEGIN CERTIFICATE-----`                                             |
| `gitBackend.ingress.tls.key`             | Private SSL server certificate                                              | `-----BEGIN RSA PRIVATE KEY-----`                                         |

***note
At least one endpoint (HTTP and/or HTTPS) has to be enabled in the service!
***

### Git garbage collection

| Parameter                           | Description                                                      | Default                  |
|-------------------------------------|------------------------------------------------------------------|--------------------------|
| `gitGC.image`                       | Image name of the Git-GC container image                         | `k8s-gerrit/git-gc`      |
| `gitGC.schedule`                    | Cron-formatted schedule with which to run Git garbage collection | `0 6,18 * * *`           |
| `gitGC.resources`                   | Configure the amount of resources the pod requests/is allowed    | `requests.cpu: 100m`     |
|                                     |                                                                  | `requests.memory: 256Mi` |
|                                     |                                                                  | `limits.cpu: 100m`       |
|                                     |                                                                  | `limits.memory: 256Mi`   |
| `gitGC.logging.persistence.enabled` | Whether to persist logs                                          | `true`                   |
| `gitGC.logging.persistence.size`    | Storage size for persisted logs                                  | `1Gi`                    |

### Gerrit slave

***note
The way the Jetty servlet used by Gerrit works, the Gerrit slave component of the
gerrit-slave chart actually requires the URL to be known, when the chart is installed.
The suggested way to do that is to use the provided Ingress resource. This requires
that a URL is available and that the DNS is configured to point the URL to the
IP of the node the Ingress controller is running on!
***

***note
Setting the canonical web URL in the gerrit.config to the host used for the Ingress
is mandatory, if access to the Gerrit slave is required!
***

| Parameter                                    | Description                                                                                                              | Default                           |
|----------------------------------------------|--------------------------------------------------------------------------------------------------------------------------|-----------------------------------|
| `gerritMaster.images.gerritInit`             | Image name of the Gerrit init container image                                                                            | `k8s-gerrit/gerrit-init`          |
| `gerritMaster.images.gerritSlave`            | Image name of the Gerrit slave container image                                                                           | `k8s-gerrit/gerrit-slave`         |
| `gerritSlave.initializeTestSite.enabled`     | Enable the initialization of a site. USE ONLY for testing, if you do not plan to replicate repositories or the database. | `true`                            |
| `gerritSlave.resources`                      | Configure the amount of resources the pod requests/is allowed                                                            | `requests.cpu: 1`                 |
|                                              |                                                                                                                          | `requests.memory: 5Gi`            |
|                                              |                                                                                                                          | `limits.cpu: 1`                   |
|                                              |                                                                                                                          | `limits.memory: 6Gi`              |
| `gerritSlave.logging.persistence.enabled`    | Whether to persist logs                                                                                                  | `true`                            |
| `gerritSlave.logging.persistence.size`       | Storage size for persisted logs                                                                                          | `1Gi`                             |
| `gerritSlave.h2Database.persistence.enabled` | Whether to persist h2 databases                                                                                          | `true`                            |
| `gerritSlave.h2Database.persistence.size`    | Storage size for persisted h2 databases                                                                                  | `1Gi`                             |
| `gerritSlave.service.type`                   | Which kind of Service to deploy                                                                                          | `NodePort`                        |
| `gerritSlave.service.http.port`              | Port over which to expose HTTP                                                                                           | `80`                              |
| `gerritSlave.ingress.host`                   | REQUIRED: Host name to use for the Ingress (required for Ingress)                                                        | `nil`                             |
| `gerritSlave.ingress.alias`                  | Optional: Alias host name for the Ingress                                                                                | `nil`                             |
| `gerritSlave.ingress.tls.enabled`            | Whether to enable TLS termination in the Ingress                                                                         | `false`                           |
| `gerritSlave.ingress.tls.cert`               | Public SSL server certificate                                                                                            | `-----BEGIN CERTIFICATE-----`     |
| `gerritSlave.ingress.tls.key`                | Private SSL server certificate                                                                                           | `-----BEGIN RSA PRIVATE KEY-----` |
| `gerritSlave.keystore`                       | base64-encoded Java keystore (`cat keystore.jks | base64`) to be used by Gerrit, when using SSL                          | `nil`                             |
| `gerritSlave.config.gerrit`                  | The contents of the gerrit.config                                                                                        | [see here](#Gerrit-config-files)  |
| `gerritSlave.config.secure`                  | The contents of the secure.config                                                                                        | [see here](#Gerrit-config-files)  |

### Gerrit config files

The gerrit-slave chart provides a ConfigMap containing the `gerrit.config` and a
Secret containing the `secure.config` to configure the Gerrit installation in the
Gerrit slave component. The content of the `gerrit.config` and `secure.config`
can be set in the `values.yaml` under the keys `gerritSlave.config.gerrit` and
`gerritSlave.config.secure` respectively. All configuration options are described
in detail in the [official documentation of Gerrit](https://gerrit-review.googlesource.com/Documentation/config-gerrit.html).
Some options however have to be set in a specified way for the Gerrit slave to
work as intended:

- `gerrit.basePath`

    Path to the directory containing the repositories. The chart mounts this
    directory from a persistent volume to `/var/gerrit/git` in the container. For
    Gerrit to find the correct directory, this has to be set to `git`.

- `gerrit.serverId`

    In Gerrit-version higher than 2.14 Gerrit needs a server ID, which is used by
    NoteDB. Gerrit would usually generate a random ID on startup, but since the
    gerrit.config file is read only, when mounted as a ConfigMap this fails.
    Thus the server ID has to be set manually!

- `gerrit.canonicalWebUrl`

    The canonical web URL has to be set to the Ingress host.

- `database.*`

    If the database is installed in the same Kubernetes cluster, the name of the
    service exposing the database deployment may be used as a hostname.

    With newer versions of the MySQL-driver used by Gerrit, using SSL-encrypted
    communication with the database is enforced by default. This can be deactivated
    by setting the `useSSL=false`-option. To do that in Gerrit, the database-URL
    has to be provided manually:
    `url = jdbc:mysql://<db-host>:<db-port>/<db-name>?nullNamePatternMatchesAll=true&useSSL=false`

- `httpd.listenURL`

    This has to be set to `proxy-http://*:8080/` or `proxy-https://*:8080`,
    depending of TLS is enabled in the Ingress or not, otherwise the Jetty
    servlet will run into an endless redirect loop.

- `container.user`

    The technical user in the Gerrit slave container is called `gerrit`. Thus, this
    value is required to be `gerrit`.

- `container.slave`

    Since this chart is meant to install a Gerrit slave, this naturally has to be
    `true`.

- `container.javaHome`

    This has to be set to `/usr/lib/jvm/java-8-openjdk-amd64`, since this is
    the path of the Java installation in the container.

- `container.javaOptions`

    The maximum heap size has to be set. And its value has to be lower than the
    memory resource limit set for the container (e.g. `-Xmx4g`). In your calculation
    allow memory for other components running in the container.

## Upgrading the Chart

To upgrade an existing installation of the gerrit-slave chart, e.g. to install
a newer chart version or to use an updated custom `values.yaml`-file, execute
the following command:

```sh
cd $(git rev-parse --show-toplevel)/helm-charts
helm upgrade <release-name> \
  -f <path-to-custom-values>.yaml \
  ./gerrit-slave
```

## Uninstalling the Chart

To delete the chart from the cluster, use:

```sh
helm delete <release-name> \
  --purge
```