my-rook-config/Documentation/Contributing/development-environment.md at 4eed2a644f9bf2eaffceff85a68fbe86471c2b77

Files

T

Blaine Gardner c9d99e01a0 ci: use markdownlint to enforce mkdocs compatibility

mkdocs uses a markdown renderer that is hardcoded to 4 spaces per tab
for detecting indentation levels, including ordered- and
unordered-lists. Since we cannot easily change the renderer, begin using
a markdown linter in CI that will fail if official docs do not adhere to
the spacing rules.

As a starting point, the markdownlint config does not begin with the
default set of checks, which might overwhelm attempts to fix them.
Instead, focus on list-tab-spacing rules and a few other highly useful
checks.

markdownlint also has some gaps in its abilities that allow common Rook
doc issues to pass acceptance. However, it allows creating custom
linting plugins. Create 2 such linting plugins to check 2 things:

- all doc lines (except code blocks) must be aligned to a 4-space
  boundary, without exception. This ensures that markdown will render
  correctly with mkdocs. This unfortunately makes it possible to create
  lists that are internally aligned strangely.
- admonitions must all follow the same format of
  ```
  !!! header
      body
  ```

For the strange lists, this is allowed and renders correctly, but it
looks strange:

```md
- first bullet
- second bullet
    still second bullet
- third bullet

    has a paragraph
    of text inside

- last bullet

Signed-off-by: Blaine Gardner <blaine.gardner@ibm.com>

2024-04-29 17:25:11 -06:00

3.8 KiB

Raw Blame History

title

title
Developer Environment

Install Kubernetes

You can choose any Kubernetes install of your choice. The test framework only depends on kubectl being configured. To install kubectl, please see the official guide.

Minikube

The developers of Rook are working on Minikube and thus it is the recommended way to quickly get Rook up and running. Minikube should not be used for production but the Rook authors consider it great for development. While other tools such as k3d/kind are great, users have faced issues deploying Rook.

Always use a virtual machine when testing Rook. Never use your host system where local devices may mistakenly be consumed.

To install Minikube follow the official guide. It is recommended to use the kvm2 driver when running on a Linux machine and the hyperkit driver when running on a MacOS. Both allow to create and attach additional disks to the virtual machine. This is required for the Ceph OSD to consume one drive. We don't recommend any other drivers for Rook. You will need a Minikube version 1.23 or higher.

Starting the cluster on Minikube is as simple as running:

# On Linux
minikube start --disk-size=40g --extra-disks=1 --driver kvm2

# On MacOS with Intel processor
minikube start --disk-size=40g --extra-disks=1 --driver hyperkit

# On MacOS with Apple silicon
minikube start --disk-size=40g --extra-disks 1 --driver qemu

It is recommended to install a Docker client on your host system too. Depending on your operating system follow the official guide.

Stopping the cluster and destroying the Minikube virtual machine can be done with:

minikube delete

Install Helm

Use helm.sh to install Helm and set up Rook charts defined under _output/charts (generated by build):

To install and set up Helm charts for Rook run tests/scripts/helm.sh up.
To clean up tests/scripts/helm.sh clean.

!!! note These helper scripts depend on some artifacts under the _output/ directory generated during build time. These scripts should be run from the project root.

!!! note If Helm is not available in your PATH, Helm will be downloaded to a temporary directory (/tmp/rook-tests-scripts-helm) and used from that directory.

Using local Rook image on minikube cluster

Developers can test quickly their changes by building and using the local Rook image on their minikube cluster.

Set the local Docker environment to use minikube:
```
eval $(minikube docker-env -p minikube)
```
Build your local Rook image. The following command will generate a Rook image labeled in the format local/ceph-<arch>.
```
cd <your_rook_src_directory>
make BUILD_REGISTRY=local
```
Tag the generated image as rook/ceph:master so operator will pick it.
```
docker tag "local/ceph-$(go env GOARCH)" 'rook/ceph:master'
```
Create a Rook cluster in minikube, or if the Rook cluster is already configured, apply the new operator image by restarting the operator.

Creating a dev cluster

To accelerate the development process, users have the option to employ the script located at tests/scripts/create-dev-cluster.sh. This script is designed to rapidly set up a new minikube environment, apply the CRDs and the common file, and then utilize the cluster-test.yaml script to create the Rook cluster. Once setup, users can use the different *-test.yaml files from the deploy/examples/ directory to configure their clusters. This script supports the possibility of creating multiple rook clusters running on the same machine by using the option -p <profile-name>.

3.8 KiB Raw Blame History