diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index a5a1405a..b1e6538a 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1 +1,3 @@ # Contribute to the test-operator + +We accept changes proposed as pull requests. diff --git a/README.md b/README.md index 397340b5..72ae7b5b 100644 --- a/README.md +++ b/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=/test-operator:tag -``` - -3. Deploy the controller to the cluster with the image specified by `IMG`: - -```sh -make deploy IMG=/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 diff --git a/docs/source/conf.py b/docs/source/conf.py index 28d9ac4a..31ef9f61 100644 --- a/docs/source/conf.py +++ b/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. diff --git a/docs/source/guide.rst b/docs/source/guide.rst new file mode 100644 index 00000000..64b957a0 --- /dev/null +++ b/docs/source/guide.rst @@ -0,0 +1,54 @@ +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 with the installation one at once by: ``make install run`` + +Then apply a tempest resource definition, e.g. the default one: + +.. literalinclude:: ../../config/samples/test_v1beta1_tempest.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 + +Custom Tempest Configuration +---------------------------- +This is TBA. + +Getting logs +------------ +This is TBA. diff --git a/docs/source/images.rst b/docs/source/images.rst new file mode 100644 index 00000000..02f3663e --- /dev/null +++ b/docs/source/images.rst @@ -0,0 +1,10 @@ +Test Images +=========== + +The `test-operator` uses images that are built and defined in +`TCIB (The Container Image Build) `_. +The built images are published to `quay.io `_. + +Currently, `test-operator` runs the following images: + +* `openstack-tempest `_ diff --git a/docs/source/index.rst b/docs/source/index.rst index b2eccdba..28f3635c 100644 --- a/docs/source/index.rst +++ b/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 diff --git a/docs/source/samples/tempest-config.yaml b/docs/source/samples/tempest-config.yaml new file mode 100644 index 00000000..027c3e04 --- /dev/null +++ b/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 diff --git a/docs/source/samples/tempest-deployment.yaml b/docs/source/samples/tempest-deployment.yaml new file mode 100644 index 00000000..ac12f530 --- /dev/null +++ b/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 diff --git a/docs/source/tempest_pod.rst b/docs/source/tempest_pod.rst new file mode 100644 index 00000000..ad9dafbc --- /dev/null +++ b/docs/source/tempest_pod.rst @@ -0,0 +1,133 @@ +Run Tempest in a Pod +==================== +Sometimes, you may want to avoid running the whole operator, e.g. for +debugging or development purposes. In that case, you can run Tempest in a +`pod `_. + +Write Object Definitions +-------------------------- + +Create a file named ``tempest-config.yaml`` with the following content: + +.. literalinclude:: samples/tempest-config.yaml + :language: yaml + +The file contains tempest configuration and will be used to pass any tempest +options to the container running Tempest. + +Then create a file named ``tempest-deployment.yaml`` with the following content: + +.. literalinclude:: samples/tempest-deployment.yaml + :language: yaml + +The file contains a pod definition - it tells OpenShift to create a Pod running +one container that will run Tempest from the openstack-tempest image. More about +images can be found `here <./images.html>`_. + +Create Resources +---------------- + +Run the `oc apply` command to create the resources: + +.. code-block:: bash + + oc apply -f tempest-config.yaml + oc apply -f tempest-deployment.yaml + +You can verify that the resources were created with: + +.. code-block:: bash + + oc get configmap my-tempest-data + oc get pods tempest-worker + +Add ``-o yaml`` to the above commands to see the details of the resources. + +Debug Tempest Container +----------------------- + +Use `oc describe` command to see the full definition of the pod including +latest events, such as pulling of the tempest image, creating and starting +a container. + +.. code-block:: bash + + oc describe pod tempest-worker + +To see the console output from the tempest run execute: + +.. code-block:: bash + + oc logs tempest-worker + +SSH to the Tempest Container +```````````````````````````` +In case you want to SSH the container to run Tempest manually, you may want to +run the pod as a `sleepy` pod. Uncomment the ``command`` option in the +``tempest-deployment.yaml`` file shared above to create such pod. + +Then SSH to the container: + +.. code-block:: bash + + oc rsh --container tempest-container tempest-worker + +.. note:: + If a pod runs only one container you can omit ``--container`` argument. + +Once inside the container, change directory to ``/var/lib/tempest`` to find +tempest configuration together with the ``run_tempest.sh`` script. + +While inside the container, you can run Tempest commands according to the +`Tempest documentation `_. + +The container has also installed +`python-tempestconf `_ project +(``discover-tempest-config`` command). If you run the pod as a `sleepy` one, +``run_tempest.sh`` defined in the image wasn't executed. In that case, you have +to generate ``tempest.conf`` manually - either run ``run_tempest.sh`` or +``discover-tempest-config`` command based on +`its documentation `_. + +Custom Tempest Configuration +---------------------------- +In order to pass custom configuration to `tempest` and `python-tempestconf`, you +can either SSH to the running tempest container where you can interact with +``tempest`` and ``discover-tempest-config`` commands directly according to their +documentations, see `SSH to the Tempest Container`_, or follow the steps +described below. + +python-tempestconf configuration +````````````````````````````````` +The only, currently, supported way for passing custom arguments to +``discover-tempest-config`` command is via a file called ``profile.yaml``. See +the python-tempestconf's official documentation for +`more details about the file `_. + +Add the content of the ``profile.yaml`` file to the ``tempest-config.yaml`` file +under **data** section like this: + +.. code-block:: yaml + + data: + + profile.yaml: | + + +And then add the following to the ``tempest-deployment.yaml`` under +**volumeMounts** section of the tempest-container: + +.. code-block:: yaml + + - mountPath: "/var/lib/tempest/external_files/profile.yaml" + name: tempest-config + subPath: profile.yaml + +Tempest configuration +````````````````````` +Change the ``tempest-config.yaml`` file accordingly to pass any custom +configuration to Tempest. Please mind the content of the ``run_tempest.sh`` +script defined inside the tempest image as that is the limitation of what +can be recognized, parsed and taken into account during the tempest run. + +The content of the ``run_tempest.sh`` `can be found here `_. diff --git a/docs/source/tempest_podman.rst b/docs/source/tempest_podman.rst new file mode 100644 index 00000000..32bd132c --- /dev/null +++ b/docs/source/tempest_podman.rst @@ -0,0 +1,46 @@ +Run Tempest via Podman +====================== +Sometimes, you may want to avoid running the whole operator, e.g. for +debugging or development purposes. In that case, you can run Tempest locally +via Podman. + +This is probably the fastest way to run tempest, but it's the least +user-friendly one. + +Create a tempest directory where you will put your config files and where +tempest will save the logs from the test run: + +.. code-block:: bash + + mkdir -p /tmp/tempest/logs + +Find/generate clouds.yaml file. `ci-framework` has a Jinja template for +generating the file, `see `_. +Once you have ``clouds.yaml`` copy it to ``/tmp/tempest/logs``: + +.. code-block:: bash + + cp ~/clouds.yaml /tmp/tempest/logs + +Create ``exclude.txt`` and ``include.txt`` files + +.. code-block:: bash + + touch /tmp/tempest/logs/exclude.txt + touch /tmp/tempest/logs/include.txt + +Include the tempest test(s) you want to run in ``include.txt`` file. + +Set directory permissions: + +.. code-block:: bash + + podman unshare chown 42480:42480 -R /tmp/tempest/logs + +Run tempest: + +.. code-block:: bash + + podman run -e CONCURRENCY=4 -v /tmp/tempest/logs/:/var/lib/tempest/external_files:Z quay.io/podified-antelope-centos9/openstack-tempest:current-podified + +Profit! Logs will be in ``/tmp/tempest/logs`` (subunit, html files, tempest logs, etc)