diff --git a/.github/workflows/documentation.yaml b/.github/workflows/documentation.yaml index 55bc1ce7..8eaca9fe 100644 --- a/.github/workflows/documentation.yaml +++ b/.github/workflows/documentation.yaml @@ -3,8 +3,14 @@ on: push: branches: - main + paths: + - docs/** pull_request: + paths: + - docs/** workflow_dispatch: + paths: + - docs/** # Sets permissions of the GITHUB_TOKEN to allow deployment to GitHub Pages permissions: diff --git a/docs/source/guide.rst b/docs/source/guide.rst index 66531aae..05ac4dfd 100644 --- a/docs/source/guide.rst +++ b/docs/source/guide.rst @@ -3,27 +3,113 @@ User Guide This guide is a starting point for configuring and running the `test-operator`. -Installation ------------- + +Running Operator Locally +------------------------ +This is **quick and easy way** how to experiment with the operator during development of a +new feature. .. code-block:: bash - make install + make install run -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. +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 +Running Operator Using The Operator Lifecycle Manager (OLM) +----------------------------------------------------------- - make run +Another option is to start the operator by running the pre-build operator image +stored on +`quay.io `_ +using the OLM. .. 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: + Currently, the `test-operator `_ is not + part of the `openstack-operator-index `_ therefore a new catalog source which uses `test-operator-index + `_ image needs to be created + in advance. + +Follow these steps to install the operator in the openstack project. + +1. Create **OperatorGroup** + +.. code-block:: yaml + + cat operator-group.yaml + --- + apiVersion: operators.coreos.com/v1 + kind: OperatorGroup + metadata: + name: openstack-operatorgroup + namespace: openstack + spec: + targetNamespaces: + - openstack + +.. code-block:: bash + + oc apply -f operator-group.yaml + +2. Create **CatalogSource** + +.. code-block:: yaml + + cat catalog-source.yaml + --- + apiVersion: operators.coreos.com/v1alpha1 + kind: CatalogSource + metadata: + name: test-operator-index + namespace: openstack + spec: + sourceType: grpc + image: quay.io/openstack-k8s-operators/test-operator-index:latest + +.. code-block:: bash + + oc apply -f catalog-source.yaml + +3. Create **Subscription** + +.. code-block:: yaml + + cat subscription.yaml + --- + apiVersion: operators.coreos.com/v1alpha1 + kind: Subscription + metadata: + name: test-operator + namespace: openstack + spec: + name: test-operator + source: test-operator-index + sourceNamespace: openstack + +.. code-block:: bash + + oc apply -f subscription.yaml + +4. Wait for the **test-operator-controller-manager** pod to successfully spawn. Once you see + the pod running you can start to communicate with the operator using the **Tempest** resource + defined below. + +.. code-block:: bash + + oc get pods + ... + test-operator-controller-manager-6c9994847c-6jwn5 2/2 Running 0 20s + ... + + +Executing Tempest Tests +----------------------- +.. _Executing Tempest Tests: + +Once you have an operator running, then you can apply a tempest resource +definition, e.g. the default one: .. literalinclude:: ../../config/samples/test_v1beta1_tempest.yaml :language: yaml @@ -48,8 +134,43 @@ To see the console output of the execution run the following: Custom Tempest Configuration ---------------------------- -This is TBA. +To configure tempest via tempest.conf use the `tempestconfRun.overrides` +parameter. This parameter accepts a list of key value pairs that specify values +that should be written to tempest.conf generated inside the container. + +For example this definition of Tempest object: + +.. code-block:: yaml + + --- + apiVersion: test.openstack.org/v1beta1 + kind: Tempest + metadata: + name: tempest-tests + namespace: openstack + spec: + containerImage: quay.io/podified-antelope-centos9/openstack-tempest:current-podified + tempestRun: + includeList: | # <-- Use | to preserve \n + tempest.api.identity.v3.* + concurrency: 8 + tempestconfRun: + overrides: | + auth.admin_username admin + auth.admin_password 1234 + +will ensure that tempest will be executed with tempest.conf that looks like this: + + +.. code-block:: toml + + ... + [auth] + admin_username = admin + admin_password = 1234 + ... + -Getting logs +Getting Logs ------------ This is TBA. diff --git a/docs/source/images.rst b/docs/source/images.rst index 4ffcdfa7..1dab2800 100644 --- a/docs/source/images.rst +++ b/docs/source/images.rst @@ -17,8 +17,28 @@ and filter for *tempest* results. Currently, there are the following tempest images: * `openstack-tempest `_ + + An image that contains only tempest and no other plugins. The user can install any external + plugin during the container execution using the `tempestRun.externalPlugin*` parameters + (see :ref:`Executing Tempest Tests`) + +* `openstack-tempest-all `_ + + An image that contains tempest and all plugins that have an rpm: + + `neutron-tests-tempest, networking-l2gw, trove-tempest-plugin, ironic-tempest-plugin, + cinder-tempest-plugin, manila-tempest-plugin, designate-tempest-plugin, octavia-tempest-plugin, + barbican-tempest-plugin, keystone-tempest-plugin, novajoin-tempest-plugin, + kuryr-tempest-plugin, magnum-tempest-plugin, mistral-tempest-plugin, murano-tempest-plugin, + patrole, watcher-tempest-plugin, zaqar-tempest-plugin, heat-tempest-plugin, + telemetry-tempest-plugin, sahara-tempest-plugin, sahara-tests, vitrage-tempest-plugin.` + * `openstack-tempest-extras `_ + An image that contains `tempest-stress` and `whitebox-tempest-plugin` on top of the all plugins + that are part of the `openstack-tempest-all` image. + + `test-operator` runs, for now, only the following test images: -* openstack-tempest +* `openstack-tempest `_