From c2ffef7a9f814929f88873d8372b7a76b2e8ad46 Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Thu, 5 Oct 2023 08:57:19 +0200 Subject: [PATCH 1/2] Change documentation theme Change the theme to material theme --- docs/requirements.txt | 2 +- docs/source/Makefile | 96 ------------------------------------------- docs/source/conf.py | 17 +++++++- 3 files changed, 16 insertions(+), 99 deletions(-) delete mode 100644 docs/source/Makefile diff --git a/docs/requirements.txt b/docs/requirements.txt index ee3ed71d..5e175f15 100644 --- a/docs/requirements.txt +++ b/docs/requirements.txt @@ -1,7 +1,7 @@ ansible-core>=2.14.6 sphinx>=6.2.1 # BSD sphinx-autobuild>=2021.3.1 -sphinx_rtd_theme>=1.2.2 +sphinx-material doc8>=0.8.1 # Apache-2.0 sphinxemoji myst-parser diff --git a/docs/source/Makefile b/docs/source/Makefile deleted file mode 100644 index 3241a24d..00000000 --- a/docs/source/Makefile +++ /dev/null @@ -1,96 +0,0 @@ -# -*- coding: utf-8 -*- -# -# this documentation build configuration file can be -# created using sphinx-quickstart - -# If extensions (or modules to document with autodoc) are in another directory, -# add these directories to sys.path here. If the directory is relative to the -# documentation root, use os.path.abspath to make it absolute, like shown here. -# -# import os -# import sys -# sys.path.insert(0, os.path.abspath('.')) -import os -import re - -# -- General configuration ------------------------------------------------ - -# If your documentation needs a minimal Sphinx version, state it here. -# -# needs_sphinx = '1.0' - -# Add any Sphinx extension module names here, as strings. They can be -# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom -# ones. -extensions = ['myst_parser', - 'sphinx.ext.autodoc', - 'sphinx.ext.doctest', - 'sphinx.ext.intersphinx', - 'sphinx.ext.todo', - 'sphinx.ext.viewcode', - 'sphinxemoji.sphinxemoji', - 'reno.sphinxext'] - -# Add any paths that contain templates here, relative to this directory. -templates_path = ['_templates'] - -# The suffix(es) of source filenames. -# You can specify multiple suffix as a list of string: -# source_suffix = ['.rst', '.md'] -# source_suffix = '.rst' -source_suffix = { - '.rst': 'restructuredtext', - '.md': 'markdown', -} - -# The master toctree document. -master_doc = 'index' - -# General information about the project. -project = u'ci-framework' -copyright = u'2023, Red Hat' - -# Versions -# Get the latest release. Subject to be tagged as following: -# v1.0 -# v2.0 -# v2.1 -get_version_command = 'git tag --sort=committerdate -l v* | tail -1' -release = re.sub('^v', '', os.popen(get_version_command).read().strip()) -version = release - -# The language for content autogenerated by Sphinx. Refer to documentation -# for a list of supported languages. -# -# This is also used if you do content translation via gettext catalogs. -# Usually you set "language" from the command line for these cases. -language = 'en' - -# List of patterns, relative to source directory, that match files and -# directories to ignore when looking for source files. -# This patterns also effect to html_static_path and html_extra_path -exclude_patterns = [] - -# The name of the Pygments (syntax highlighting) style to use. -pygments_style = 'sphinx' - -# If true, `todo` and `todoList` produce output, else they produce nothing. -todo_include_todos = True - - -# -- Options for HTML output ---------------------------------------------- - -# The theme to use for HTML and HTML Help pages. See the documentation for -# a list of builtin themes. -html_theme = 'sphinx_rtd_theme' - -# 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. -# -# html_theme_options = {} - -# -- Options for HTMLHelp output ------------------------------------------ - -# Output file base name for HTML help builder. -# htmlhelp_basename = 'doc' diff --git a/docs/source/conf.py b/docs/source/conf.py index dfa257dc..28d9ac4a 100644 --- a/docs/source/conf.py +++ b/docs/source/conf.py @@ -83,14 +83,27 @@ # The theme to use for HTML and HTML Help pages. See the documentation for # a list of builtin themes. -# html_theme = "sphinx_rtd_theme" # html_logo = "images/logo_cifmw_200.png" +html_theme = "sphinx_material" # 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. # -# html_theme_options = {} +html_theme_options = { + "base_url": "https://github.com/openstack-k8s-operators/test-operator/", + "repo_url": "https://github.com/openstack-k8s-operators/test-operator/", + "nav_title": "test-operator", + "repo_name": "test-operator", + "repo_type": "github", + "globaltoc_depth": 2, + "color_primary": "blue-grey", + "color_accent": "cyan", + "touch_icon": "images/openstack-logo.png", + "theme_color": "#2196f3", + "master_doc": False, + "table_classes": ["plain"], +} # -- Options for HTMLHelp output ------------------------------------------ From c9d177e3cba63eddf8b42c761c0eae2d44c24875 Mon Sep 17 00:00:00 2001 From: Martin Kopec Date: Mon, 9 Oct 2023 11:38:52 +0200 Subject: [PATCH 2/2] Add documentation Document running of tempest via different ways. --- CONTRIBUTING.md | 2 + README.md | 79 ++---------- docs/source/conf.py | 5 + docs/source/guide.rst | 55 ++++++++ docs/source/images.rst | 24 ++++ docs/source/index.rst | 33 +++-- docs/source/prerequisites.rst | 21 ++++ docs/source/samples/tempest-config.yaml | 7 ++ docs/source/samples/tempest-deployment.yaml | 63 ++++++++++ docs/source/tempest_pod.rst | 133 ++++++++++++++++++++ docs/source/tempest_podman.rst | 46 +++++++ 11 files changed, 386 insertions(+), 82 deletions(-) create mode 100644 docs/source/guide.rst create mode 100644 docs/source/images.rst create mode 100644 docs/source/prerequisites.rst create mode 100644 docs/source/samples/tempest-config.yaml create mode 100644 docs/source/samples/tempest-deployment.yaml create mode 100644 docs/source/tempest_pod.rst create mode 100644 docs/source/tempest_podman.rst 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..66531aae --- /dev/null +++ b/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 + +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..4ffcdfa7 --- /dev/null +++ b/docs/source/images.rst @@ -0,0 +1,24 @@ +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 `_. + +.. note:: + You can use the images to run a container or a pod on your own, without + running the test-operator, see `Run Tempest in a Pod <./tempest_pod.html>`_ + or `Run Tempest via Podman <./tempest_podman.html>`_. + +To find all tempest images, go to +`podified-master-centos9 organization `_ +and filter for *tempest* results. + +Currently, there are the following tempest images: + +* `openstack-tempest `_ +* `openstack-tempest-extras `_ + +`test-operator` runs, for now, only the following test images: + +* openstack-tempest diff --git a/docs/source/index.rst b/docs/source/index.rst index b2eccdba..dea937db 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,27 +1,40 @@ .. 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 + prerequisites.rst + 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/prerequisites.rst b/docs/source/prerequisites.rst new file mode 100644 index 00000000..63edca50 --- /dev/null +++ b/docs/source/prerequisites.rst @@ -0,0 +1,21 @@ +Prerequisites +============= + +First, you will need an OpenStack Platform running on OpenShift. See, the +`ci-framework documentation `_ +to get you started. It will get you through the installation of such environment. + +E.g. if you want to install OpenStack Platform running on OpenShift on your +own hardware, follow `the steps in this doc `_. + +After the installations is completed, you can source the credentials to the +environment as follows: + +.. code-block:: bash + + eval $(${HOME}/ci-framework-data/bin/crc oc-env) + export KUBECONFIG="${HOME}/.crc/machines/crc/kubeconfig" + oc login -u kubeadmin -p 12345678 https://api.crc.testing:6443 + +.. note:: + 12345678 is a default password set by ci-framework 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..cfe96cdd --- /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 according to +`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)