Merge "Doc: minor fixes, CRD link to GH, add backing services page"

doc/deployment/backing_services.md

@@ -0,0 +1,39 @@
+# Backing services
+
+Here you will find information about the backing services used by Zuul and Nodepool.
+
+## Table of Contents
+
+1. Philosophy
+1. MariaDB
+1. ZooKeeper
+
+## Philosophy
+
+The goal of SF-Operator is to provide a Zuul-based CI infrastructure on OpenShift with the least
+friction possible. With that in mind, we decided to minimize the prerequisites to deployment, and
+thus decided to integrate "barebones" deployments of the backing services required by Zuul and Nodepool.
+
+The pros are:
+
+* A deployer does not need to worry about provisioning a database or setting up a Zookeeper cluster
+prior to deploying SF.
+
+The cons are:
+
+* Lifecycle support for these backing services is minimal (deployment, updates) compared to what a
+proper operator-backed deployment could offer (see for example [what the mariadb-operator can do](https://mariadb.org/mariadb-in-kubernetes-with-mariadb-operator/)).
+
+In other words, for backing services deployed as statefulsets, it is always possible to modify the replicas amount directly in their manifests, but SF-Operator will not act upon it - for example increasing mariadb's replicas will not set up a primary node and replica nodes like a dedicated mariadb operator would. You will only end up with one node being used by Zuul, and the rest using up resources for nothing.
+
+## MariaDB
+
+MariaDB provides a backend for Zuul's builds and buildsets results. It can be queried via zuul-web.
+
+MariaDB is deployed as a single-pod statefulset.
+
+## ZooKeeper
+
+ZooKeeper coordinates data and configurations between all the Zuul and Nodepool microservices.
+
+ZooKeeper is deployed as a single-pod statefulset.

doc/deployment/crds.md

@@ -10,8 +10,8 @@ This document gives details about the Custom Resource Definitions (CRDs) that th
 
 The Custom Resources installed by the SF-Operator are described in the following OpenAPI specs:
 
-* [SoftwareFactory](./../../config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml)
-* [LogServer](./../../config/crd/bases/sf.softwarefactory-project.io_logservers.yaml)
+* [SoftwareFactory](https://github.com/softwarefactory-project/sf-operator/blob/master/config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml)
+* [LogServer](https://github.com/softwarefactory-project/sf-operator/blob/master/config/crd/bases/sf.softwarefactory-project.io_logservers.yaml)
 
 The spec is constantly evolving during alpha development, and should be considered
 unstable but the ultimate source of truth for documentation about its properties.

doc/deployment/index.md

@@ -11,6 +11,7 @@ and managing a Software Factory Custom Resource through SF-Operator.
     1. [Nodepool](./nodepool.md)
     1. [Zuul](./zuul.md)
     1. Logserver
+    1. [Backing services](./backing_services.md)
 1. [Setting up certificates](./certificates.md)
 1. [Monitoring](./monitoring.md)
 1. [Deleting a deployment](./delete.md)

doc/deployment/nodepool.md

@@ -30,23 +30,14 @@ it is impossible (or at least very hard) to build Nodepool images on a pod, whic
 
 > There is no assumption about the processes and toolings used to build images on the `image-builder`, except that the workflow must be driven by an Ansible playbook from the `nodepool-builder`.
 
-The operator also includes backing services with bare bones support:
-
-| Service | Kubernetes resource type | Scalable Y/N |
-|---------|--------------------------|-------------|
-| zookeeper | statefulset | N |
-
-> Although Zookeeper is deployed as a statefulset, modifying its replica count directly in its manifest
-will have no effect on the service itself - besides eventually creating unused pods.
-
 ## Services configuration
 
 Configuring the Nodepool micro-services is done through the SoftwareFactory deployment's manifest. Many configuration parameters are exposed by The [SoftwareFactory Custom Resource spec](./../../config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml).
 
 The spec is constantly evolving during alpha development, and should be considered
 unstable but the ultimate source of truth for documentation about its properties.
 
-## Setting up provider secrets
+## Setting up providers secrets
 
 Currently the SF Operator supports OpenStack (`clouds.yaml`) and Kubernetes (`kube.config`) configuration files. These files are used by Nodepool to manage resources on its providers.
 They are managed by the SF Operator in a secret called `nodepool-providers-secrets`.

doc/deployment/zuul.md

@@ -23,15 +23,6 @@ Zuul is deployed by SF-Operator as micro-services:
 | zuul-executor | statefulset | Y |
 | zuul-web | deployment | N |
 
-The operator also includes backing services with bare bones support:
-
-| Service | Kubernetes resource type | Scalable Y/N |
-|---------|--------------------------|-------------|
-| zookeeper | statefulset | N |
-| mariadb | statefulset | N |
-
-> For services deployed as statefulsets, it is always possible to modify the replicas amount directly in their manifests, but SF-Operator will not act upon it - for example increasing mariadb's replicas will not set up a primary node and replica nodes like a dedicated mariadb operator would. You will only end up with one node being used by Zuul, and the rest using up resources for nothing.
-
 ## Services configuration
 
 Configuring the Zuul micro-services is done through the SoftwareFactory deployment's manifest. Many configuration parameters are exposed by The [SoftwareFactory Custom Resource spec](./../../config/crd/bases/sf.softwarefactory-project.io_softwarefactories.yaml).