doc: Rework install doc to cover both template and helm install

The installation description is changed as follows

* break out the different operator installation methods
  into preamble sections that explain the how and why.

* add references to the Helm chart with respect to the
  PXC operator and cert-manager management.

Change-Id: I862afaa7f60992c55f187246d2513df4d3e7bf23

doc/source/index.rst

@@ -13,6 +13,61 @@ installing other operators upon which it relies.  Be sure to read
 about deployment options if you want to perform some of these tasks
 yourself.
 
+Managing the Operator
+---------------------
+
+There are two ways that you can manage the Zuul operator:
+
+* Install the Helm chart
+* Install the Kubernetes templates
+
+Kubernetes Templates
+--------------------
+
+Using the Kubernetes templates allows for a simple out of the box
+experience with minimal user intervention.
+
+.. note::
+
+   When using the `Simple Example`, if cert-manager and the Percona XtraDB
+   operator are not already installed, the Zuul Operator will attempt to
+   install them.  This requires that the operator be installed with the
+   service account bound to the cluster-admin role.
+
+To install with cluster-admin permissions, from the root of the
+zuul-operator repo, run:
+
+.. code-block:: bash
+
+   kubectl apply -f deploy/crds/zuul-ci_v1alpha1_zuul_crd.yaml
+   kubectl apply -f deploy/operator-cluster-admin.yaml
+
+Otherwise, run:
+
+.. code-block:: bash
+
+   kubectl apply -f deploy/crds/zuul-ci_v1alpha1_zuul_crd.yaml
+   kubectl apply -f deploy/operator.yaml
+
+Helm Chart
+----------
+
+Using the Helm chart allows a level of customization of the operator
+installation.  The chart also contains two sub-charts:
+
+#. cert-manager
+#. Percona XtraDB
+
+These allow the user to install these components with the operator Helm
+installation if so desired.
+
+To install the chart, from the root of the zuul-operator repo, run:
+
+.. code-block:: bash
+
+   helm install my-zuul helm/zuul
+
+
 Simple Example
 --------------
 
@@ -20,27 +75,12 @@ The quickest way to get a running Zuul is to allow the operator to
 manage all of the dependencies for you.  In this case, the operator
 will:
 
-* Install cert-manager and set up a self-signed cluster issuer
-* Install the Percona XtraDB operator and create a three-node PXC
-  database cluster
+* Set up a self-signed cluster issuer
+* Create a three-node PXC database cluster
 * Create a three-node ZooKeeper cluster
 * And of course, create a Zuul system
 
-.. note::
-
-   Installing other operators requires a high level of access, so when
-   used in this manner, zuul-operator runs with cluster admin
-   privileges.  If you would like the operator to run with reduced
-   privileges, see Managing Operator Dependencies.
-
-From the root of the zuul-operator repo, run:
-
-.. code-block:: bash
-
-   kubectl apply -f deploy/crds/zuul-ci_v1alpha1_zuul_crd.yaml
-   kubectl apply -f deploy/operator-cluster-admin.yaml
-
-You probably want a namespace, so go ahead and create one with:
+To start, you probably want a namespace, so go ahead and create one with:
 
 .. code-block:: bash
 
@@ -64,7 +104,7 @@ Then create a file called ``zuul.yaml`` which looks like:
    apiVersion: operator.zuul-ci.org/v1alpha2
    kind: Zuul
    metadata:
-     name: zuul
+     name: my
    spec:
      executor:
        count: 1
@@ -84,7 +124,7 @@ Then create a file called ``zuul.yaml`` which looks like:
          baseurl: https://opendev.org
 
 This will create the most basic of Zuul installations, with one each
-of the `zuul-executor`, `zuul-scheduler`, and `zuul-web` processes.
+of the `zuul-executor`, `zuul-scheduler`, and `zuul-web` pods.
 It will also create a Nodepool launcher for each of the providers
 listed in your ``nodepool.yaml``.  If your Zuul tenant config file
 requires more connections, be sure to add them here.
@@ -92,14 +132,12 @@ requires more connections, be sure to add them here.
 Managing Operator Dependencies
 ------------------------------
 
-You may not want zuul-operator to install other operators (for
-example, if your cluster has other users and you don't want
-cert-manager or pxc-operator to be tied to a Zuul installation, or if
-you would prefer to avoid granting zuul-operator cluster admin
-privileges).  In that case, you may install the other operators
-yourself and still allow zuul-operator to use those other operators.
-It can still create a PXC cluster for you as long as the pxc-operator
-is present.
+You may not want zuul-operator Helm chart to install other operators
+(for example, if your cluster has other users and you don't want
+cert-manager or pxc-operator to be tied to a Zuul Operator installation)
+In that case, you may install the other operators yourself and still
+allow zuul-operator to use those other operators.  It can still create
+a PXC cluster for you as long as the pxc-operator is present.
 
 To use this mode of operation, make sure the following dependencies
 are installed before using zuul-operator:
@@ -107,13 +145,22 @@ are installed before using zuul-operator:
 * Cert-manager (at least version 1.2.0)
 * Percona-xtradb-cluster-operator (at least version 1.7.0)
 
-With these installed, you may install zuul-operator with reduced
-privileges:
+If you'd prefer to install these with the Zuul Operator Helm chart, in
+your values.yaml add:
+
+.. code-block:: yaml
+
+   cert-manager:
+     enabled: true
+
+   pxc-operator:
+     enabled: true
+
+With this, you can install the zuul-operator Helm chart as follows:
 
 .. code-block:: bash
 
-   kubectl apply -f deploy/crds/zuul-ci_v1alpha1_zuul_crd.yaml
-   kubectl apply -f deploy/operator.yaml
+   helm install -f values.yaml my-zuul helm/zuul-operator
 
 After this point, usage is the same as other methods.