Add documentation

Document running of tempest via different ways.

CONTRIBUTING.md

@@ -1 +1,3 @@
 # Contribute to the test-operator
+
+We accept changes proposed as pull requests.

README.md

@@ -1,80 +1,15 @@
 # test-operator
-// TODO(user): Add simple overview of use/purpose
+This is a test operator that automates testing of an OpenStack deployment
+running on a Kubernetes cluster. The operator runs
+[Tempest](https://opendev.org/openstack/tempest) tests.
 
-## Description
-// TODO(user): An in-depth paragraph about your project and overview of use
 
 ## Getting Started
-You’ll need a Kubernetes cluster to run against. You can use [KIND](https://sigs.k8s.io/kind) to get a local cluster for testing, or run against a remote cluster.
-**Note:** Your controller will automatically use the current context in your kubeconfig file (i.e. whatever cluster `kubectl cluster-info` shows).
+First, you will need an OpenStack Platform running on OpenShift. See, the
+[ci-framework documentation](https://ci-framework.readthedocs.io/en/latest/)
+to get you started. It will get you through the installation of such environment.
 
-### Running on the cluster
-1. Install Instances of Custom Resources:
-
-```sh
-kubectl apply -f config/samples/
-```
-
-2. Build and push your image to the location specified by `IMG`:
-
-```sh
-make docker-build docker-push IMG=<some-registry>/test-operator:tag
-```
-
-3. Deploy the controller to the cluster with the image specified by `IMG`:
-
-```sh
-make deploy IMG=<some-registry>/test-operator:tag
-```
-
-### Uninstall CRDs
-To delete the CRDs from the cluster:
-
-```sh
-make uninstall
-```
-
-### Undeploy controller
-UnDeploy the controller to the cluster:
-
-```sh
-make undeploy
-```
-
-## Contributing
-// TODO(user): Add detailed information on how you would like others to contribute to this project
-
-### How it works
-This project aims to follow the Kubernetes [Operator pattern](https://kubernetes.io/docs/concepts/extend-kubernetes/operator/)
-
-It uses [Controllers](https://kubernetes.io/docs/concepts/architecture/controller/)
-which provides a reconcile function responsible for synchronizing resources untile the desired state is reached on the cluster
-
-### Test It Out
-1. Install the CRDs into the cluster:
-
-```sh
-make install
-```
-
-2. Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
-
-```sh
-make run
-```
-
-**NOTE:** You can also run this in one step by running: `make install run`
-
-### Modifying the API definitions
-If you are editing the API definitions, generate the manifests such as CRs or CRDs using:
-
-```sh
-make manifests
-```
-
-**NOTE:** Run `make --help` for more information on all potential `make` targets
-
-More information can be found via the [Kubebuilder Documentation](https://book.kubebuilder.io/introduction.html)
+Then proceed to our [documentation](https://openstack-k8s-operators.github.io/test-operator/).
 
 ## License
 

docs/source/conf.py

@@ -86,6 +86,11 @@
 # html_logo = "images/logo_cifmw_200.png"
 html_theme = "sphinx_material"
 
+html_show_sourcelink = True
+html_sidebars = {
+    "**": ["globaltoc.html", "localtoc.html"]
+}
+
 # Theme options are theme-specific and customize the look and feel of a theme
 # further.  For a list of options available for each theme, see the
 # documentation.

docs/source/guide.rst

@@ -0,0 +1,55 @@
+User Guide
+==========
+
+This guide is a starting point for configuring and running the `test-operator`.
+
+Installation
+------------
+
+.. code-block:: bash
+
+    make install
+
+Execution
+---------
+Execute the following command to run the operator. Note, that after running the
+following command you will need to switch to another terminal unless you run it
+in the background.
+
+.. code-block:: bash
+
+    make run
+
+.. note::
+    You can run this step together with the installation at once by running: ``make install run``
+
+Then apply a tempest resource definition, e.g. the default one:
+
+.. literalinclude:: ../../config/samples/test_v1beta1_tempest.yaml
+   :language: yaml
+
+.. code-block:: bash
+
+    oc apply -f config/samples/test_v1beta1_tempest.yaml
+
+After that, verify that a pod was created with:
+
+.. code-block:: bash
+
+    oc get pods | grep tempest
+
+You should see a pod with a name like `tempest-tests-xxxxx`.
+
+To see the console output of the execution run the following:
+
+.. code-block:: bash
+
+    oc logs <name of the pod>
+
+Custom Tempest Configuration
+----------------------------
+This is TBA.
+
+Getting logs
+------------
+This is TBA.

docs/source/images.rst

@@ -0,0 +1,19 @@
+Test Images
+===========
+
+The `test-operator` uses images that are built and defined in
+`TCIB (The Container Image Build) <https://github.com/openstack-k8s-operators/tcib>`_.
+The built images are published to `quay.io <https://quay.io/>`_.
+
+To find all tempest images, go to
+`podified-master-centos9 organization <https://quay.io/organization/podified-master-centos9>`_
+and filter for *tempest* results.
+
+Currently, there are the following tempest images:
+
+* `openstack-tempest <https://quay.io/podified-antelope-centos9/openstack-tempest>`_
+* `openstack-tempest-extras <https://quay.io/podified-antelope-centos9/openstack-tempest-extras>`_
+
+`test-operator` run, for now, only the following test images:
+
+* openstack-tempest

docs/source/index.rst

@@ -1,27 +1,39 @@
 ..  documentation master file
 
-=============
-test-operator
-=============
+===============================
+Documentation for test-operator
+===============================
 
 Welcome to the documentation for test-operator. This documentation is designed
 to help you get up and running with our project as quickly and smoothly as
 possible.
 
+Overview
+========
 .. toctree::
    :maxdepth: 1
-   :caption: Overview
 
    readme.md
 
+Configuration Guide
+===================
 .. toctree::
    :maxdepth: 1
-   :caption: For Contributors
 
-   contributing.md
+   images.rst
+   guide.rst
+
+Debugging
+=========
+.. toctree::
+   :maxdepth: 1
 
-Indices and tables
-==================
+   tempest_pod.rst
+   tempest_podman.rst
 
-* :ref:`genindex`
-* :ref:`search`
+For Contributors
+================
+.. toctree::
+   :maxdepth: 1
+
+   contributing.md

docs/source/samples/tempest-config.yaml

@@ -0,0 +1,7 @@
+apiVersion: v1
+kind: ConfigMap
+metadata:
+  name: my-tempest-data
+data:
+  include.txt: |
+    tempest.api.identity.v3

docs/source/samples/tempest-deployment.yaml

@@ -0,0 +1,63 @@
+apiVersion: v1
+kind: PersistentVolumeClaim
+metadata:
+  name: tempest-home
+spec:
+  resources:
+    requests:
+        storage: 10G
+  accessModes:
+    - ReadWriteMany
+    - ReadWriteOnce
+---
+apiVersion: v1
+kind: Pod
+metadata:
+  name: tempest-worker
+spec:
+  securityContext:
+     fsGroup: 42480
+  volumes:
+    - name: tempest-workdir
+      persistentVolumeClaim:
+        claimName: tempest-home
+    - name: cloud-passwd
+      secret:
+         secretName: openstack-config-secret
+    - name: clouds-config
+      configMap:
+          name: openstack-config
+    - name: tempest-config
+      configMap:
+          name: my-tempest-data
+    - name: pre-install
+      emptyDir: {}
+  containers:
+    - name: tempest-container
+      image: quay.io/podified-antelope-centos9/openstack-tempest:current-podified
+      # Uncomment the following line to make the container sleep - that overrides
+      # any run commands defined in the tempest image - that will allow you to
+      # ssh to the container, install e.g. tempest plugins, change the tempest
+      # configuration and run tempest yourself.
+      # command: ["/usr/bin/dumb-init", "sleep", "infinity"]
+      restartPolicy: Never
+      volumeMounts:
+        - mountPath: "/var/lib/tempest/external_files/"
+          name: tempest-workdir
+        - mountPath: "/etc/openstack"
+          name: pre-install
+        - mountPath: "/etc/openstack/clouds.yaml"
+          name: clouds-config
+          subPath: clouds.yaml
+        - mountPath: "/var/lib/tempest/external_files/include.txt"
+          name: tempest-config
+          subPath: include.txt
+        - mountPath: "/etc/openstack/secure.yaml"
+          name: cloud-passwd
+          subPath: secure.yaml
+      env:
+        - name: OS_CLOUD
+          valueFrom:
+            configMapKeyRef:
+              name: openstack-config
+              key: OS_CLOUD