doc: Add nodepool-builder documentation

This change:

- Add the nodepool-builder documentation
- Populate the User documentation by focusing on the config repo
  usage for zuul, nodepool-launcher, nodepool-builder.

Change-Id: I123345835438b5153d7c7f85b7864140ed4283f8

README.md

@@ -8,13 +8,13 @@
 
 ## About
 
-SF-Operator is an Operator that simplifies the deployment and operation of [Zuul](https://zuul-ci.org) and its dependencies (NodePool, Zookeeper, MariaDB, Log Server) on the OpenShift Container Platform.
+SF-Operator is an Operator that simplifies the deployment and operation of Software Factory instances on the OpenShift Container Platform. An instance of Software Factory is composed of [Zuul](https://zuul-ci.org) and its dependencies ([NodePool](https://zuul-ci.org/docs/nodepool/latest/), Zookeeper, MariaDB, Log Server).
 
 It is the natural evolution of the [Software Factory project](https://softwarefactory-project.io): the 3.8.x release of Software Factory saw the containerization of every major service, but was still delivered as RPM packages, in the form of a custom CentOS 7 distribution.
 SF-Operator builds upon this containerization effort to move from a distro-centric approach to a cloud-native deployment.
 This is also an opportunity to focus on the leanest service suite needed to provide a working gated CI infrastructure; hence a scope reduced to Zuul and its dependencies only.
 
-SF-Operator is built mostly in Go upon the [Operator Framework](https://operatorframework.io), with the aim of reaching the highest capability level that can be achieved, in order to bring a modern, scalable gated CI alternative to OpenShift users, with the least friction from operation as possible. 
+SF-Operator is built mostly in Go upon the [Operator Framework](https://operatorframework.io), with the aim of reaching the highest capability level that can be achieved, in order to bring a modern, scalable gated CI alternative to OpenShift users, with the least friction from operation as possible.
 
 Furthermore, SF-Operator takes advantage of some of the specificities of OpenShift as a container orchestration platform:
 
@@ -37,7 +37,7 @@ The current project status is: **Alpha - NOT PRODUCTION READY**
     - Zuul Web: ✅
     - Zuul Merger: ❌
     - Nodepool Launcher: ✅
-    - Nodepool Builder: ❌
+    - Nodepool Builder: ✅
     - Zookeeper: ✅
     - MariaDB: ✅
     - Log Server: ✅
@@ -70,7 +70,9 @@ The current project status is: **Alpha - NOT PRODUCTION READY**
 * [Operator documentation](https://softwarefactory-project.github.io/sf-operator/operator/): for OpenShift cluster administrators, this documentation covers installing SF-Operator and managing the operator's lifecycle.
 * [Deployment documentation](https://softwarefactory-project.github.io/sf-operator/deployment/): this documentation covers the essentials for people or teams who intend to deploy and manage Zuul and its dependencies through the SF-Operator.
 * [Developer documentation](https://softwarefactory-project.github.io/sf-operator/developer/): this documentation describes how to set up a development and testing environment to develop the SF-Operator.
+* [End User documentation](https://softwarefactory-project.github.io/sf-operator/user/): for users of a Software Factory instance. This documentation mostly describes the `Software Factory's config repository` usage (configuration-as-code).
 * [CLI refererence](https://softwarefactory-project.github.io/sf-operator/cli/)
+
 ## Getting Help
 
 Should you have any questions or feedback concerning the SF-Operator, you can:

doc/deployment/config_repository.md

@@ -3,7 +3,7 @@
 ## Table of Contents
 
 1. [Concept](#concept)
-1. [Repository Structure](#repository-structure)
+1. [Repository content](#repository-content)
 1. [Setting up the repository](#setting-up-the-repository)
     1. [Gerrit](#gerrit)
         1. [Prerequisites](#prerequisites-on-gerrit)
@@ -33,22 +33,8 @@ Below you can find more details about the default jobs running against the confi
 
 This setup enables GitOps workflows on the configuration of your Zuul-based CI infrastructure.
 
-## Repository structure
-
-For the config-check and config-update to work as intended, a specific file structure is expected in the config repository:
-
-```
-/
-|_ zuul/
-|     |_ main.yaml
-|
-|_nodepool/
-      |_ nodepool.yaml
-```
-
-The file `zuul/main.yaml` holds the [tenants configuration](https://zuul-ci.org/docs/zuul/latest/tenants.html) that will be applied on the deployment.
-
-The file `nodepool.yaml` holds [the diskimages, labels and node providers configuration](https://zuul-ci.org/docs/nodepool/latest/configuration.html).
+The config repository is expected to follow a specific file structure for the automation to work properly. Please refer to the [user documentation](../user/index.md)
+to learn more about the expected repository file structure and its usage.
 
 Any other file or folder will be ignored.
 
@@ -87,11 +73,11 @@ ssh -p29418 <gerrit_host> gerrit set-members --add [email protected] "Service Use
 ##### Repository ACLs and Labels
 
 > Access controls and labels management with Gerrit is out of the scope of this documentation. Please refer to
-Gerrit's documentation for further details, for example 
+Gerrit's documentation for further details, for example
 [here](https://gerrit-review.googlesource.com/Documentation/access-control.html) for ACLs
 or [here](https://gerrit-review.googlesource.com/Documentation/config-labels.html) for labels.
 
-The config repository must be set with specific ACLs to allow Zuul to interact with it:
+The repository must be set with specific ACLs to allow Zuul to interact with it:
 
 ```INI
 [access "refs/heads/*"]
@@ -101,7 +87,7 @@ submit = group Service Users
 
 Zuul triggers events based on specific labels, so these must be configured as well.
 
-Here are the required labels to define in the config repository's *Access* settings (*meta/config*) on Gerrit:
+Here are the required labels to define in the repository's *Access* settings (*meta/config*) on Gerrit:
 
 ```INI
 [label "Code-Review"]

doc/deployment/nodepool.md

@@ -9,9 +9,10 @@ but addresses specificities and idiosyncrasies induced by deploying Nodepool wit
 1. [Architecture](#architecture)
 1. [Services configuration](#services-configuration)
 1. [Setting up providers secrets](#setting-up-providers-secrets)
-1. [Using a cloud image in an OpenStack cloud](#using-a-cloud-image-in-an-openstack-cloud)
+1. [Get the builder's SSH public key](#get-the-builders-ssh-public-key)
 1. [Using the openshifpods driver with your cluster](#using-the-openshiftpods-driver-with-your-cluster)
 1. [Using the Nodepool CLI](#using-the-nodepool-cli)
+1. [Troubleshooting](#troubleshooting)
 
 ## Architecture
 
@@ -20,6 +21,14 @@ Nodepool is deployed by SF-Operator as micro-services:
 | Service | Kubernetes resource type | Scalable Y/N |
 |---------|--------------------------|-------------|
 | nodepool-launcher | deployment | N |
+| nodepool-builder | statefulset | N |
+
+`nodepool-builder` requires access to at least one `image-builder` machine that is to be deployed out-of-band. Due to security limitations,
+it is impossible (or at least very hard) to build Nodepool images on a pod, which is why this process must be delegated remotely to an `image-builder` machine.
+
+> The only requirement for the `image-builder` machine is that the `nodepool-builder` is able to run Ansible tasks via SSH. Please refer to sections [Get the builder's SSH public key](#get-the-builders-ssh-public-key) and [Configuring Nodepool builder](../user/nodepool_config_repository#configuring-nodepool-builder).
+
+> 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:
 
@@ -75,60 +84,15 @@ When your deployment is ready, the provider secrets have been updated in Nodepoo
 which will copy the configuration files from Nodepool into the files defined in sfconfig.yaml. Be careful not to erase
 important data!
 
-## Using a cloud image in an OpenStack cloud
-
-There is a simple way to provision a cloud image with Zuul's SSH key, so that Zuul can run jobs on images in an OpenStack cloud.
-
-1. If not done already, clone the [config repository for your deployment](./config_repository.md).
-2. Edit `nodepool/nodepool.yaml` to add labels and providers:
-
-```yaml
-labels:
--   name: my-cloud-image-label
-    # min-ready: 1
-providers:
-- name: default
-  cloud: default
-  clean-floating-ips: true
-  image-name-format: '{image_name}-{timestamp}'
-  boot-timeout: 120 # default 60
-  cloud-images:
-    - name: my-cloud-image
-      username: cloud-user
-  pools:
-    - name: main
-      max-servers: 10
-      networks:
-        - $public_network_name
-      labels:
-        - cloud-image: cloud-centos-9-stream
-          name: cloud-centos-9-stream
-          flavor-name: $flavor
-          userdata: |
-            #cloud-config
-            package_update: true
-            users:
-              - name: cloud-user
-                ssh_authorized_keys:
-                  - $zuul-ssh-key
-```
-
-3. Save, commit, propose a review and merge the change.
-4. Wait for the **config-update** job to complete.
-5. If the `min-ready` property is over 0, you can validate that an instance is available with:
-
-```sh
-$ kubectl exec -ti nodepool-launcher-$uuid -c launcher -- nodepool list
-```
+## Get the builder's SSH public key
 
-An instance with your new image label should appear in the list. You can take note of its public IP for the next step.
+The Nodepool builder component should be used with at least one `image-builder` companion machine.
+It must have the capablility to connect via SSH to the builder machine.
 
-6. You can also make sure a Zuul Executor pod can connect to the instance:
+Here is the command to fetch the builder SSH public key:
 
 ```sh
-$kubectl exec -ti zuul-executor-0 -- ssh -o "StrictHostKeyChecking no" -i /var/lib/zuul-ssh/..data/priv cloud-user@$public_ip hostname
-Warning: Permanently added '$public_ip' (ED25519) to the list of known hosts.
-np0000000001
+kubectl get secret nodepool-builder-ssh-key -n sf -o jsonpath={.data.pub} | base64 -d
 ```
 
 ## Using the Openshiftpods driver with your cluster
@@ -178,3 +142,28 @@ kubectl exec --stdin --tty nodepool-launcher-XYZ -- /bin/sh
 ```
 
 Then from that shell, run the `nodepool` command.
+
+## Troubleshooting
+
+### How to connect on a ready node from the launcher pod
+
+`nodepool list` is used to list all node managed by the launcher and their current status.
+
+```sh
+$ kubectl exec -ti nodepool-launcher-$uuid -c launcher -- nodepool list
+```
+
+Look for the node's IP address then from the Zuul executor pod, run:
+
+```sh
+$kubectl exec -ti zuul-executor-0 -- ssh -o "StrictHostKeyChecking no" -i /var/lib/zuul-ssh/..data/priv <user>@<ip>
+Warning: Permanently added '$public_ip' (ED25519) to the list of known hosts.
+$ hostname
+np0000000001
+```
+
+### Accessing the Nodepool API
+
+Nodepool exposes some [API endpoints](https://zuul-ci.org/docs/nodepool/latest/operation.html#web-interface).
+
+For instance, to reach the `image-list` endpoint a user can access the following URL: `https://nodepool.<fqdn>/image-list`.

doc/user/index.md

@@ -4,4 +4,5 @@ Welcome to the User documentation. This section is aimed at the users of a Zuul-
 
 ## Table of Contents
 
-1. [Getting started](./getting_started.md)
+1. [Using the config repository to setup Zuul tenants](./zuul_config_repository.md)
+1. [Using the config repository to setup Nodepool configuration](./nodepool_config_repository.md)