Contributing

Getting Started

You’ll need a Kubernetes cluster to run against. You can use 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).

Running on the cluster

Install Instances of Custom Resources:
```
 kubectl apply -f config/samples/
```

Build and push your image to the location specified by IMG:

 make docker-build docker-push IMG=<some-registry>/dataplane-operator:tag

Deploy the controller to the cluster with the image specified by IMG:
```
 make deploy IMG=<some-registry>/dataplane-operator:tag
```

Uninstall CRDs

To delete the CRDs from the cluster:

make uninstall

Undeploy controller

UnDeploy the controller to the cluster:

make undeploy

How it works

This project aims to follow the Kubernetes Operator pattern

It uses Controllers which provide a reconcile function responsible for synchronizing resources until the desired state is reached on the cluster

Test It Out

Install the CRDs into the cluster:
```
 make install
```
Run your controller (this will run in the foreground, so switch to a new terminal if you want to leave it running):
```
 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:

make manifests

NOTE: Run make --help for more information on all potential make targets

More information can be found via the Kubebuilder Documentation

Testing

The tests can be run with the following command:

make test

The test target runs the EnvTest tests with Ginkgo. These tools will be installed by the test if needed.

EnvTest tests are under the tests/functional directory in dataplane-operator.

Running kuttl tests

kuttl tests are under the tests/kuttl/tests in dataplane-operator and can be executed either directly from dataplane operator repository, or from install_yamls

Requirements

The kuttl tests require a running cluster with openstack-ansibleee-operator, openstack-baremetal-operator, infra-operator and rabbitmq-cluster-operator running in the cluster. The easiest way to ensure presence of these operators is to use install_yamls. However, it is possible to deploy them manually as well.

From install_yamls

First clone both the dataplane-operator and the install-yamls repos and make sure that they are in a state (commit) you want to test. For the purposes of this guide, we will assume following directory layout:

~
├── dataplane-operator
└── install_yamls

The kuttl tests are also run from the install_yamls repository by the CI jobs.

We will also assume that there is no cluster already running. If you already have a cluster, skip the following step.

Initialize your CRC with install_yamls utilities. Make sure to have your pull secret ready and to fulfill all HW requirements. CRC can be initialized without install_yamls utilities. However, using existing scripts will simplify debugging and issue reporting.

Ensure presence of dataplane operator requirements and cleanup all remains of possible previous kuttl test run.

cd ..
make dataplane_kuttl_prep
make dataplane_cleanup

Moving to the dataplane-operator repo, we can start the dataplane operator itself.

Ports 8080 and 8081 are used for collection of metrics and health information. Make sure that they are not in use. You can override them using METRICS_PORT and HEALTH_PORT vars.

This will start dataplane operator in your shell. Either redirect the output or have another ready for next step.

cd ../dataplane-operator
make run

If your patch introduces any changes to resources, such as OpenStackDataPlaneDeployment, you have to apply them manually. Otherwise the test suite will run without them. Changes to existing resources can be introduced with oc patch, new resoruces require oc apply.

oc apply -f ./path/to/my/file.yaml

Finally, you can launch kuttl tests themselves. You can also apply configurations from your tests manually.

make kuttl-test

From dataplane-operator

The kuttl tests can also be run directly from the dataplane-operator checkout but you need the operators listed under Requirements When running from a dataplane-operator checkout, kubectl-kuttl must be installed. The kubectl-kuttl command can be installed from kuttl releases, or using the Makefile target kuttl:

make kuttl

Then, run the operator from a checkout:

make run

Execute the kuttl tests:

make kuttl-test

Using KUTTL_ARGS

Kuttl tests can be supplied with any arguments compatible with the installed version of kuttl CLI, using the KUTTL_ARGS var.

For example to run a single test:

make kuttl-test KUTTL_ARGS="--test dataplane-deploy-no-nodes"

Skip the test resource delete, which will leave the test resources created in the cluster, and can be useful for debugging failed tests:

make kuttl-test KUTTL_ARGS="--test dataplane-deploy-no-nodes --skip-delete"

Contributing to documentation

Rendering documentation locally

Install docs build requirements:

make docs-dependencies

To render the user-facing documentation site locally:

make docs

The built HTML files are in docs_build/dataplane directory.

There are some additional make targets for convenience. The following targets, in addition to rendering the docs, will also open the resulting HTML in your browser so that you don’t have to look for it:

make docs-preview

The following targets set up an inotify watch on the documentation sources, and when it detects modification, the HTML is re-rendered. This is so that you can use "edit source - save source - refresh browser page" loop when working on the docs, without having to run make docs-* repeatedly.

make docs-watch