| # A ReviewDB for Gerrit on Kubernetes |
| |
| Gerrit requires a database to store user and change data. The database is commonly |
| called ReviewDB. Gerrit provides a set of options, which database technology to |
| use. This chart is meant to install a database and initialize it, so it can be |
| used as a ReviewDB for Gerrit-master and -slave setups installed with the |
| respective charts. Currently, the following databases sre supported by this chart: |
| |
| - MySQL |
| |
| ***note |
| The gerrit-master and gerrit-slave charts also support H2, but since H2-databases |
| do not require a separate server, this chart is not required in that case. |
| *** |
| |
| ***note |
| With upcoming versions of Gerrit, the ReviewDB will be completely migrated to |
| NoteDB, removing the dependency on a external relational database. |
| *** |
| |
| ## Installation |
| |
| To install a MySQL database with the reviewdb chart, set `mysql.enabled`to |
| true in the `values.yaml`. This will then install the |
| [mysql chart](https://github.com/helm/charts/tree/master/stable/mysql) |
| onto the Kubernetes cluster as a dependency. |
| |
| To install the chart with the release name `reviewdb`, execute: |
| |
| ```sh |
| cd $(git rev-parse --show-toplevel)/helm-charts |
| helm install ./reviewdb \ |
| --dep-up \ |
| -n reviewdb \ |
| -f <path-to-custom-values>.yaml |
| ``` |
| |
| ## Configuration |
| |
| ### Common |
| |
| #### 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` | |
| |
| #### Replication |
| |
| ***note |
| Currently, only master-slave replication is possible. Thus, enabling replication |
| always means to use the database as slave. |
| *** |
| |
| | Parameter | Description | Default | |
| |-----------|--------------------------------------------------------|---------| |
| | `isSlave` | Whether to switch on replication from another database | `false` | |
| |
| |
| #### MySQL |
| |
| ***note |
| Not all options available in the mysql-chart that is used as a dependency are |
| listed in the `values.yaml`-file of this chart. The complete list of options for |
| the mysql-chart can be viewed in the chart's |
| [documentation](https://github.com/helm/charts/blob/master/stable/mysql/README.md). |
| *** |
| |
| | Parameter | Description | Default | |
| |--------------------------------------------|-------------------------------------------------------------------------------------------------------------------------------------------------|------------------------------------------------------------------------------------------------| |
| | `mysql.enabled` | Whether to install the MySQL database | `true` | |
| | `mysql.replication` | Only used, if `isSlave` is `true` | `{}` | |
| | `mysql.replication.config.masterHost` | Hostname of the Mysql database master | `mysql.example.com` | |
| | `mysql.replication.config.masterPort` | Port of the Mysql database master | `3306` | |
| | `mysql.replication.config.masterUser` | Username of technical user created for replication | `repl` | |
| | `mysql.replication.config.masterPassword` | Password of technical user created for replication | `password` | |
| | `mysql.replication.config.masterLogFile` | Transaction log file at timepoint of dump as retrieved [here](#Create-database-dump-and-note-database-state) | `mysql-bin.000001` | |
| | `mysql.replication.config.masterLogPos` | Transaction log position at timepoint of dump as retrieved [here](#Create-database-dump-and-note-database-state) | `111` | |
| | `mysql.replication.dbDumpAcceptPath` | Path, where the replication init script will expect the database dump file to appear | `/var/data/db/master_dump.sql` | |
| | `mysql.image` | Which container image containing MySQL to use | `mysql` | |
| | `mysql.imageTag` | Tag of container image (usually the database version) | `5.5.61` | |
| | `mysql.mysqlRootPassword` | Password of the database `root` user | `big_secret` | |
| | `mysql.mysqlUser` | Database user (The technical user used by Gerrit) | `gerrit` | |
| | `mysql.mysqlPassword` | Password of the database user | `secret` | |
| | `mysql.livenessProbe.initialDelaySeconds` | Delay before liveness probe is initiated | `30` | |
| | `mysql.livenessProbe.periodSeconds` | How often to perform the probe | `10` | |
| | `mysql.livenessProbe.timeoutSeconds` | When the probe times out | `5` | |
| | `mysql.livenessProbe.successThreshold` | Minimum consecutive successes for the probe to be considered successful after having failed. | `1` | |
| | `mysql.livenessProbe.failureThreshold` | Minimum consecutive failures for the probe to be considered failed after having succeeded. | `3` | |
| | `mysql.readinessProbe.initialDelaySeconds` | Delay before readiness probe is initiated | `5` | |
| | `mysql.readinessProbe.periodSeconds` | How often to perform the probe | `10` | |
| | `mysql.readinessProbe.timeoutSeconds` | When the probe times out | `1` | |
| | `mysql.readinessProbe.successThreshold` | Minimum consecutive successes for the probe to be considered successful after having failed. | `1` | |
| | `mysql.readinessProbe.failureThreshold` | Minimum consecutive failures for the probe to be considered failed after having succeeded. | `3` | |
| | `mysql.persistence.enabled` | Create a volume to store data | `true` | |
| | `mysql.persistence.size` | Size of persistent volume claim | `8Gi` | |
| | `mysql.persistence.storageClass` | Type of persistent volume claim | `default` | |
| | `mysql.persistence.accessMode` | ReadWriteOnce or ReadOnly | `ReadWriteOnce` | |
| | `mysql.resources` | Configure the amount of resources the pod requests/is allowed | `requests.cpu: 250m` | |
| | | | `requests.memory: 1Gi` | |
| | | | `limits.cpu: 250m` | |
| | | | `limits.memory: 1Gi` | |
| | `mysql.configurationFiles` | Add configuration files for MySQL | `{}` (check the [Configuration files-section](#Configuration-files) for configuration options) | |
| | `mysql.initializationFiles` | Add scripts that are executed, when the database is started the first time | `{}` (check the [Initialization files-section](#Initialization-files) for details) | |
| | `mysql.service.type` | Type of the Service used to expose the database | `NodePort` | |
| | `mysql.service.port` | The port used to expose the database | `3306` | |
| | `mysql.ssl.enabled` | Setup and use SSL for MySQL connections | `false` | |
| | `mysql.ssl.secret` | Name of the secret containing the SSL certificates (Has to be different between multiple instances running in the same cluster) | `ssl-certs` | |
| | `mysql.ssl.certificates[0].name` | Name of the secret containing the SSL certificates (Has to be different between multiple instances running in the same cluster) | `ssl-certs` | |
| | `mysql.ssl.certificates[0].ca` | CA certificate (if using replication use the CA created [here](#create-certificates-for-ssl_encrypted-communication)) | `-----BEGIN CERTIFICATE-----` | |
| | `mysql.ssl.certificates[0].cert` | Server certificate (public key) (if using replication use the certificate created [here](#create-certificates-for-ssl_encrypted-communication)) | `-----BEGIN CERTIFICATE-----` | |
| | `mysql.ssl.certificates[0].key` | Server key (private key) (if using replication use the key created [here](#create-certificates-for-ssl_encrypted-communication)) | `-----BEGIN RSA PRIVATE KEY-----` | |
| |
| ##### Configuration files |
| |
| The configuration file for the MySQL-server is provided under the keys |
| `mysql.configurationsFiles.*.cnf`. There are three different config-files provided: |
| |
| - `common.cnf`: Contains configuration, which is the same for master- and slave- |
| databases: |
| |
| | Parameter | Description | Default | |
| |-----------------|----------------------------------------------------------|-------------------| |
| | `log-bin` | Name of transaction logs (used for database replication) | `mysql-bin` | |
| | `log-bin-index` | Name of transaction log indices | `mysql-bin.index` | |
| | `log-error` | Error log file | `error.log` | |
| | `binlog_format` | Format of the binlogs (Has to be the same as on master) | `row` | |
| |
| In addition, if using SSL for MySQL-requests the following options have to be made |
| available by uncommenting them. The values must not be changed, when using the chart: |
| |
| ```sh |
| ssl-ca=/ssl/ca.pem |
| ssl-cert=/ssl/server-cert.pem |
| ssl-key=/ssl/server-key.pem |
| ``` |
| |
| - `mysql-master.cnf`: Contains configuration specific for the master database: |
| |
| | Parameter | Description | Default | |
| |-------------|------------------------------|---------| |
| | `server-id` | ID unique in the MySQL setup | `1` | |
| |
| - `mysql-slave.cnf`: Contains configuration specific for the slave database: |
| |
| | Parameter | Description | Default | |
| |-----------------------|-----------------------------------------------------------------------------------------------------------------------------|---------------------------------------------------------------------------| |
| | `relay-log` | The slave's relay log location | `/var/lib/mysql/relay.log` | |
| | `relay-log-info-file` | The slave's relay log info file location | `/var/lib/mysql/relay-log.info` | |
| | `relay-log-index` | The slave's relay log index location | `/var/lib/mysql/relay-log.index` | |
| | `log_slave_updates` | Whether to log slave update | `1` | |
| | `sql_mode` | Configure SQL-mode | `"ERROR_FOR_DIVISION_BY_ZERO,NO_AUTO_CREATE_USER,NO_ENGINE_SUBSTITUTION"` | |
| | `read_only` | Toggle read only mode. In production this should be on (`1`). The test mode of the Gerrit slave expects it to be off (`0`). | `0` | |
| | `replicate-ignore-db` | Databases not to replicate (replicating the `mysql`-DB for example would overwrite database users) | `mysql` | |
| | `server-id` | ID unique in the MySQL setup | `42` | |
| |
| The `mysql-master.cnf`- and `mysql-slave.cnf`-files are mutually exclusive. |
| Comment out the contents of the file, that is not needed, depending on installing |
| a master or slave database. |
| |
| ##### Initialization files |
| |
| - `initialize_reviewdb.sql` |
| |
| Creates a database called 'reviewdb', that can be used by Gerrit for the ReviewDB. |
| Leave this file unchanged. |
| |
| - `create_repl_user.sql` |
| |
| Creates a user, that can be used for database replication. This user is only needed |
| on the master database and only, when the data is supposed to be replicated to |
| slaves. To use it, uncomment the code and change the username, password and |
| certificate subject as needed. |
| |
| ## Aditional configuration steps |
| |
| ### Create certificates for SSL-encrypted communication |
| |
| For SSL-encrypted communication, a set of certificates is needed. Use the |
| following commands to create them after adjusting the subject strings: |
| |
| ```sh |
| openssl genrsa -out ./ca.key.pem 4096 |
| |
| openssl req \ |
| -key ./ca.key.pem \ |
| -new \ |
| -x509 \ |
| -days 7300 \ |
| -sha256 \ |
| -out ./ca.cert.pem \ |
| -subj "/C=DE/O=Gerrit/CN=gerrit-db-master" \ |
| -nodes |
| |
| openssl genrsa -out ./master.key.pem 4096 |
| |
| openssl req \ |
| -key ./master.key.pem \ |
| -new \ |
| -sha256 \ |
| -out ./master.csr.pem \ |
| -subj "/C=DE/O=Gerrit/CN=gerrit-db-master" \ |
| -nodes |
| |
| openssl x509 \ |
| -req \ |
| -CA ./ca.cert.pem \ |
| -CAkey ./ca.key.pem \ |
| -CAcreateserial \ |
| -in ./master.csr.pem \ |
| -out ./master.cert.pem |
| |
| openssl genrsa -out ./slave.key.pem 4096 |
| |
| openssl req \ |
| -key ./slave.key.pem \ |
| -new \ |
| -sha256 \ |
| -out ./slave.csr.pem \ |
| -subj "/C=DE/O=Gerrit/CN=gerrit-db-slave" \ |
| -nodes |
| |
| openssl x509 \ |
| -req \ |
| -CA ./ca.cert.pem \ |
| -CAkey ./ca.key.pem \ |
| -CAcreateserial \ |
| -in ./slave.csr.pem \ |
| -out ./slave.cert.pem |
| ``` |
| |
| ***note |
| The `CN` has to be the hostname of the database instances. In case the database |
| is running on Kubernetes it can be the service name. |
| *** |
| |
| ### Configuring a master DB instance for replication |
| |
| For the replication to work, the MySQL database master has to be configured |
| accordingly and some data about the database state has to be collected. The |
| necessary steps are detailed in this section. If it is not planned to replicate |
| the master database, skip this section. |
| |
| #### Create database dump and note database state |
| |
| In the next steps the content of the database has to be retrieved and the corresponding |
| status of the transaction logs has to be retrieved. Depending on the traffic the |
| database receives, the master DB should be stopped for these steps, since the |
| information could get out off sync, if the data is changed inbetween the steps: |
| |
| ```sql |
| STOP MASTER; |
| ``` |
| |
| Retrieve the status of the master: |
| |
| ```sql |
| SHOW MASTER STATUS; |
| |
| +------------------+----------+--------------+------------------+-------------------+ |
| | File | Position | Binlog_Do_DB | Binlog_Ignore_DB | Executed_Gtid_Set | |
| +------------------+----------+--------------+------------------+-------------------+ |
| | mysql-bin.000004 | 69444891 | | | | |
| +------------------+----------+--------------+------------------+-------------------+ |
| ``` |
| |
| The filename and position have to be entered in the database slave's `values.yaml` |
| under `mysql.replication.config.masterLogFile` and |
| `mysql.replication.config.masterLogPos`. |
| |
| Dump the content of the database: |
| |
| ```sh |
| mysqldump --user=root -p --databases reviewdb > ./master_dump.sql |
| ``` |
| |
| Afterwards, the master can be started again: |
| |
| ```sql |
| START MASTER; |
| ``` |
| |
| ## Initialize replication |
| |
| ### MySQL |
| |
| Deploying the reviewdb chart with replication enabled, will create a MySQL |
| database with a technical user to be used by the Gerrit slave and an empty |
| ReviewDB database. In addition a Job will be deployed that waits for a database |
| dump to be copied into the container to the location specified in |
| `mysql.replication.dbDumpAcceptPath`. The dump file can be copied into the |
| container using kubectl: |
| |
| ```sh |
| JOB_POD=$(kubectl get pod -l app=mysql-replication-init -o jsonpath="{.items[0].metadata.name}") |
| kubectl cp <PATH_TO_DUMP> ${JOB_POD}:<DB_DUMP_ACCEPT_PATH> |
| ``` |
| |
| As soon as the file is fully copied into the container, the script will load |
| the dump into the database and initialize the replication in the slave. The |
| database is then fully configured. |
