Describe minikube setup for evaluation
The documentation that far assumed that the user has a Kubernetes
cluster in the cloud available. For initial evaluation of the helm
charts, it would be practical to be able to test them on a local
machine. This change provides documentation and sample configuration
files to install a gerrit-master and gerrit-slave setup on a local
machine using Minikube.
Change-Id: I1eeb07401855910cca6c048e936e44c76ca6238a
diff --git a/Documentation/minikube.md b/Documentation/minikube.md
new file mode 100644
index 0000000..98d2242
--- /dev/null
+++ b/Documentation/minikube.md
@@ -0,0 +1,299 @@
+# Running Gerrit on Kubernetes using Minikube
+
+To test Gerrit on Kubernetes locally, a one-node cluster can be set up using
+Minikube. Minikube provides basic Kubernetes functionality and allows to quickly
+deploy and evaluate a Kubernetes deployment.
+This tutorial will guide through setting up Minikube to deploy the gerrit-
+master and gerrit-slave helm charts to it. Note, that due to limited compute
+resources on a single local machine and the restricted functionality of Minikube,
+the full functionality of the charts might not be usable.
+
+## Installing Kubectl and Minikube
+
+To use Minikube, a hypervisor is needed. A good non-commercial solution is HyperKit.
+The Minikube project provides binaries to install the driver:
+
+```sh
+curl -LO https://storage.googleapis.com/minikube/releases/latest/docker-machine-driver-hyperkit \
+ && sudo install -o root -g wheel -m 4755 docker-machine-driver-hyperkit /usr/local/bin/
+```
+
+To manage Kubernetes clusters, the Kubectl CLI tool will be needed. A detailed
+guide how to do that for all supported OSs can be found
+[here](https://kubernetes.io/docs/tasks/tools/install-kubectl/#install-with-homebrew-on-macos).
+On OSX hombrew can be used for installation:
+
+```sh
+brew install kubernetes-cli
+```
+
+Finally, Minikube can be installed. Download the latest binary
+[here](https://github.com/kubernetes/minikube/releases). To install it on OSX, run:
+
+```sh
+curl -Lo minikube https://storage.googleapis.com/minikube/releases/v0.30.0/minikube-darwin-amd64 && \
+ chmod +x minikube && \
+ sudo cp minikube /usr/local/bin/ && \
+ rm minikube
+```
+
+## Starting a Minikube cluster
+
+For a more detailed overview over the features of Minikube refer to the
+[official documentation](https://kubernetes.io/docs/setup/minikube/). If a
+hypervisor driver other than virtual box (e.g. hyperkit) is used, set the
+`--vm-driver` option accordingly:
+
+```sh
+minikube config set vm-driver hyperkit
+```
+
+The gerrit-master and gerrit-slave charts are configured to work with the default
+resource limits configured for minikube (2 cpus and 2Gi RAM). If more resources
+are desired (e.g. to speed up deployment startup or for more resource intensive
+tests), configure the resource limits using:
+
+```sh
+minikube config set memory 4096
+minikube config set cpus 4
+```
+
+To install a full Gerrit master and Gerrit slave setup with reasonable startup
+times, Minikube will need about 9.5 GB of RAM and 3-4 CPUs! But the more the
+better.
+
+To start a Minikube cluster simply run:
+
+```sh
+minikube start
+```
+
+Starting up the cluster will take a while. The installation should automatically
+configure kubectl to connect to the Minikube cluster. Run the following command
+to test whether the cluster is up:
+
+```sh
+kubectl get nodes
+
+NAME STATUS ROLES AGE VERSION
+minikube Ready master 1h v1.10.0
+```
+
+The helm-charts use ingresses, which can be used in Minikube by enabling the
+ingress addon:
+
+```sh
+minikube addons enable ingress
+```
+
+Since for testing there will probably no usable host names configured to point
+to the minikube installation, the traffic to the hostnames configured in the
+Ingress definition needs to be redirected to Minikube by editing the `/etc/hosts`-
+file, adding a line containing the Minikube IP and a whitespace-delimited list
+of all the hostnames:
+
+```sh
+echo "$(minikube ip) master.gerrit backend.gerrit slave.gerrit" | sudo tee -a /etc/hosts
+```
+
+The host names (e.g. `master.gerrit`) are the defaults, when using the values.yaml
+files provided as and example for minikube. Change them accordingly, if a different
+one is chosen.
+This will only redirect traffic from the computer running Minikube.
+
+To see whether all cluster components are ready, run:
+
+```sh
+kubectl get pos --all-namespaces
+```
+
+The status of all components should be `Ready`. The kubernetes dashboard giving
+an overview over all cluster components, can be opened by executing:
+
+```sh
+minikube dashboard
+```
+
+## Install helm
+
+Helm is needed to install and manage the helm charts. To install the helm client
+on your local machine (running OSX), run:
+
+```sh
+brew install kubernetes-helm
+```
+
+A guide for all suported OSs can be found [here](https://docs.helm.sh/using_helm/#installing-helm).
+
+For helm being able to install charts on a Kubernetes cluster, it needs Tiller
+installed. To do that, run:
+
+```sh
+helm init
+```
+
+## Start an NFS-server
+
+The helm-charts need a volume with ReadWriteMany access mode to store
+git-repositories. This guide will use the nfs-server-provisioner chart to provide
+NFS-volumes directly in the cluster. A basic configuration file for the nfs-server-
+provisioner-chart is provided in the supplements-directory. It can be installed
+by running:
+
+```sh
+helm install stable/nfs-server-provisioner \
+ --name nfs \
+ -f ./supplements/nfs.minikube.values.yaml
+```
+
+## Installing the gerrit-master helm chart
+
+A configuration file to configure the gerrit-master chart is provided at
+`./supplements/gerrit-master.minikube.values.yaml`. To install the gerrit-master
+chart on Minikube, run:
+
+```sh
+helm install ./helm-charts/gerrit-master \
+ -f ./supplements/gerrit-master.minikube.values.yaml \
+ --dep-up \
+ -n gerrit-master
+```
+
+Startup may take some time, especially when allowing only a small amount of
+resources to the containers. Check progress with `kubectl get pods -w` until
+it says that the pod `gerrit-master-gerrit-master-deployment-<id>` is `Running`.
+Then use `kubectl logs -f gerrit-master-gerrit-master-deployment-<id>` to follow
+the startup process of Gerrit until a line like this shows that Gerrit is ready:
+
+```sh
+[2018-11-27 09:58:52,066] [main] INFO com.google.gerrit.pgm.Daemon : Gerrit Code Review 2.16-18-ge42b76d4ba ready
+```
+
+***note
+The `gerrit.sh start` command may return `FAILED`. Nevertheless, when testing the
+setup, Gerrit started up anyway after some time. This happens, if due to low
+resources Gerrit needs too long to start up and the `gerrit.sh`-scripts runs into
+a timeout.
+***
+
+To open Gerrit's UI, run:
+
+```sh
+open http://master.gerrit
+```
+
+## Installing the gerrit-slave helm chart
+
+Before installing the gerrit-slave chart, some information and configuration is
+needed from the master's database. First find out the name of the pod running
+the mysql database of the master. It can be looked up by running:
+
+```sh
+kubectl get pods
+```
+
+It should have the format `gerrit-master-mysql-<id>`. Then exec the pod and log
+into the database by executing:
+
+```sh
+kubectl exec -it gerrit-master-mysql-<id> bash
+mysql -u root -pbig_secret
+```
+
+Create a user for the database replication:
+
+```sql
+CREATE USER 'repl' IDENTIFIED BY 'password';
+GRANT REPLICATION SLAVE, REPLICATION CLIENT ON *.* TO 'repl'
+ IDENTIFIED BY 'password';
+FLUSH PRIVILEGES;
+```
+
+Get the current position of the transaction logs by executing the following SQL
+statement:
+
+```sql
+SHOW MASTER STATUS;
+
+ +------------------+----------+--------------+------------------+-------------------+
+ | File | Position | Binlog_Do_DB | Binlog_Ignore_DB | Executed_Gtid_Set |
+ +------------------+----------+--------------+------------------+-------------------+
+ | mysql-bin.000004 | 4918 | | | |
+ +------------------+----------+--------------+------------------+-------------------+
+```
+
+Further, a dump of the reviewdb is needed. Exit mysql by typing `quit` and run:
+
+```sh
+mysqldump -u root -p --databases reviewdb > master_dump.sql
+```
+
+To get the dump to the host, exit the pod and run:
+
+```sh
+kubectl cp gerrit-master-mysql-<id>:/master_dump.sql master_dump.sql
+```
+
+A custom configuration file to configure the gerrit-slave chart is provided at
+`./supplements/gerrit-slave.minikube.values.yaml`. Change the values of
+`database.replication.mysql.config.masterLogFile` and
+`database.replication.mysql.config.masterLogPos` to the values retrieved beforehand.
+Then, the gerrit-slave chart can be started:
+
+```sh
+helm install ./helm-charts/gerrit-slave \
+ -f ./supplements/gerrit-slave.minikube.values.yaml \
+ --dep-up \
+ -n gerrit-slave
+```
+
+When the `gerrit-slave-mysql-<id>`-pod and the `gerrit-slave-mysql-replication-init-<id>`-
+pod are ready, provide the database dump to the database by executing:
+
+```sh
+kubectl cp master_dump.sql gerrit-slave-mysql-replication-init-<id>:/var/data/db/master_dump.sql
+```
+
+The status of database initialization can be followed by running:
+
+```sh
+kubectl logs -f gerrit-slave-mysql-replication-init-<id>
+```
+
+As soon as the status of the database slave is displayed, the database should be
+ready.
+
+As a next step the `All-Projects` and `All-Users` repositories have to be created
+on the slave by running:
+
+```sh
+curl -L -u git http://backend.gerrit/new/All-Projects.git
+curl -L -u git http://backend.gerrit/new/All-Users.git
+```
+
+Afterwards, the slave will start up, which can be followed by running:
+
+```sh
+kubectl logs -f gerrit-slave-gerrit-slave-deployment-<id>
+```
+
+Replication of repositories has to be started on the Gerrit master, e.g. by making
+a change in the respective repositories. Only then previous changes to the
+repositories will be available on the slave.
+
+## Cleanup
+
+Shut down minikube:
+
+```sh
+minikube stop
+```
+
+Delete the minikube cluster:
+
+```sh
+minikube delete
+```
+
+Remove the line added to `/etc/hosts`. If Minikube is restarted, the cluster will
+get a new IP and the `/etc/hosts`-entry has to be adjusted.
\ No newline at end of file
diff --git a/README.md b/README.md
index a0617ad..c22f560 100644
--- a/README.md
+++ b/README.md
@@ -120,6 +120,10 @@
These Helm charts can be used to install a Gerrit cluster consisting of a
Gerrit master and a Gerrit slave on a Kubernetes cluster.
+To evaluate and test the helm-charts, they can be installed on a local machine
+running Minikube. Follow this [guide](Documentation/minikube.md) to get a detailed
+description how to set up the Minikube cluster and install the charts.
+
## File System Storage
Currently this deployment uses NFS, some options:
diff --git a/supplements/gerrit-master.minikube.values.yaml b/supplements/gerrit-master.minikube.values.yaml
new file mode 100644
index 0000000..9445eef
--- /dev/null
+++ b/supplements/gerrit-master.minikube.values.yaml
@@ -0,0 +1,121 @@
+storageClasses:
+ default:
+ name: standard
+ shared:
+ name: shared-storage
+
+gitGC:
+ schedule: "*/15 * * * *"
+
+ resources:
+ requests:
+ cpu: 50m
+ memory: 100Mi
+ limits:
+ cpu: 50m
+ memory: 100Mi
+
+ logging:
+ persistence:
+ enabled: false
+
+gerritMaster:
+
+ resources:
+ requests:
+ cpu: 200m
+ memory: 400Mi
+ limits:
+ cpu: 500m
+ memory: 400Mi
+
+ logging:
+ persistence:
+ enabled: false
+
+ ingress:
+ host: master.gerrit
+
+ config:
+ gerrit: |-
+ [gerrit]
+ basePath = git
+ serverId = gerrit-master-1
+ canonicalWebUrl = http://master.gerrit
+ [database]
+ type = mysql
+ hostname = gerrit-master-mysql
+ port = 3306
+ database = reviewdb
+ url = jdbc:mysql://gerrit-master-mysql:3306/reviewdb?nullNamePatternMatchesAll=true&useSSL=false
+ [index]
+ type = LUCENE
+ [auth]
+ type = DEVELOPMENT_BECOME_ANY_ACCOUNT
+ [httpd]
+ listenUrl = proxy-http://*:8080/
+ [sshd]
+ listenAddress = off
+ [transfer]
+ timeout = 120 s
+ [user]
+ name = Gerrit Code Review
+ email = gerrit@example.com
+ anonymousCoward = Unnamed User
+ [cache]
+ directory = cache
+ [container]
+ user = gerrit
+ javaHome = /usr/lib/jvm/java-8-openjdk-amd64
+ javaOptions = -Djavax.net.ssl.trustStore=/var/gerrit/etc/keystore
+ javaOptions = -Xms300m
+ javaOptions = -Xmx300m
+
+ secure: |-
+ [database]
+ username = gerrit
+ password = secret
+
+ [httpd]
+ sslKeyPassword = gerrit
+
+ [remote "slave"]
+ username = git
+ password = secret
+
+ replication: |-
+ [gerrit]
+ autoReload = false
+ replicateOnStartup = true
+ defaultForceUpdate = true
+
+ [remote "slave"]
+ url = http://gerrit-slave-git-backend-service/git/${name}.git
+ replicationDelay = 0
+ timeout = 30
+
+
+mysql:
+ enabled: true
+
+ image: mysql
+ imageTag: 5.5.61
+
+ mysqlRootPassword: big_secret
+ mysqlUser: gerrit
+ mysqlPassword: secret
+
+ persistence:
+ enabled: false
+
+ resources:
+ requests:
+ cpu: 100m
+ memory: 200Mi
+ limits:
+ cpu: 100m
+ memory: 200Mi
+
+ service:
+ type: NodePort
+ port: 3306
\ No newline at end of file
diff --git a/supplements/gerrit-slave.minikube.values.yaml b/supplements/gerrit-slave.minikube.values.yaml
new file mode 100644
index 0000000..4ee283f
--- /dev/null
+++ b/supplements/gerrit-slave.minikube.values.yaml
@@ -0,0 +1,140 @@
+storageClasses:
+ default:
+ name: standard
+ shared:
+ name: shared-storage
+
+database:
+ provider: mysql
+ replication:
+ enabled: true
+ mysql:
+ config:
+ masterHost: gerrit-master-mysql
+ masterPort: 3306
+ masterUser: repl
+ masterPassword: password
+ masterLogFile: mysql-bin.000004
+ masterLogPos: 4918
+ dbDumpAcceptPath: /var/data/db/master_dump.sql
+
+gitBackend:
+ resources:
+ requests:
+ cpu: 50m
+ memory: 50Mi
+ limits:
+ cpu: 50m
+ memory: 100Mi
+
+ logging:
+ persistence:
+ enabled: false
+
+ service:
+ type: NodePort
+
+ ingress:
+ enabled: true
+ host: backend.gerrit
+
+gitGC:
+ schedule: "*/15 * * * *"
+
+ resources:
+ requests:
+ cpu: 50m
+ memory: 100Mi
+ limits:
+ cpu: 50m
+ memory: 100Mi
+
+ logging:
+ persistence:
+ enabled: false
+
+gerritSlave:
+ initializeTestSite:
+ enabled: false
+
+ resources:
+ requests:
+ cpu: 200m
+ memory: 400Mi
+ limits:
+ cpu: 500m
+ memory: 400Mi
+
+
+ logging:
+ persistence:
+ enabled: false
+
+ ingress:
+ host: slave.gerrit
+
+ config:
+ gerrit: |-
+ [gerrit]
+ basePath = git
+ serverId = gerrit-slave-1
+ canonicalWebUrl = http://slave.gerrit
+ [database]
+ type = mysql
+ hostname = gerrit-slave-mysql
+ port = 33306
+ database = reviewdb
+ url = jdbc:mysql://gerrit-slave-mysql:33306/reviewdb?nullNamePatternMatchesAll=true&useSSL=false
+ [index]
+ type = LUCENE
+ [auth]
+ type = DEVELOPMENT_BECOME_ANY_ACCOUNT
+ [httpd]
+ listenUrl = proxy-http://*:8080/
+ [sshd]
+ listenAddress = off
+ [transfer]
+ timeout = 120 s
+ [user]
+ name = Gerrit Code Review
+ email = gerrit@example.com
+ anonymousCoward = Unnamed User
+ [cache]
+ directory = cache
+ [container]
+ user = gerrit
+ slave = true
+ javaHome = /usr/lib/jvm/java-8-openjdk-amd64
+ javaOptions = -Djavax.net.ssl.trustStore=/var/gerrit/etc/keystore
+ javaOptions = -Xms300m
+ javaOptions = -Xmx300m
+
+ secure: |-
+ [database]
+ username = gerrit
+ password = secret
+
+ [httpd]
+ sslKeyPassword = gerrit
+
+
+mysql:
+ enabled: true
+
+ mysqlRootPassword: big_secret
+ mysqlUser: gerrit
+ mysqlPassword: secret
+
+ persistence:
+ enabled: false
+
+ resources:
+ requests:
+ cpu: 100m
+ memory: 200Mi
+ limits:
+ cpu: 100m
+ memory: 200Mi
+
+ service:
+ port: 33306
diff --git a/supplements/nfs.minikube.values.yaml b/supplements/nfs.minikube.values.yaml
new file mode 100644
index 0000000..87a2cbc
--- /dev/null
+++ b/supplements/nfs.minikube.values.yaml
@@ -0,0 +1,20 @@
+replicaCount: 1
+
+storageClass:
+ create: true
+ defaultClass: false
+ # The name of the StorageClass has to be the same as the one defined in the
+ # gerrit-master chart for `storageClasses.shared.name`
+ name: shared-storage
+ parameters:
+ # Required!
+ mountOptions: vers=4.1
+ reclaimPolicy: Delete
+
+resources:
+ requests:
+ cpu: 100m
+ memory: 256Mi
+ limits:
+ cpu: 100m
+ memory: 256Mi
\ No newline at end of file
