Ramen developer quick start guide

Contribution Flow

Fork the repository on GitHub
Create a branch from where you want to base your work (usually main).
Make your changes and arrange them in readable commits.
Make sure your commit messages are in the proper format.
Make sure all tests pass, and add any new tests
Push your changes to the branch in your fork of the repository. as appropriate.
Submit a pull request to the original repository.

Getting the source

Fork the Ramen repository on github

Clone the source locally

git clone git@github.com:my-github-user/ramen.git

Add an upstream remote, to make it easy to sync your repo from upstream.
```
git remote add upstream https://github.com/RamenDR/ramen.git
```
Add the commit-msg hook to sign off your commits
Ramen requires a Signed-off-by: My Name <myemail@example.com> footer in the commit message. To add it automatically to all commits, add this hook:
```
cp hack/commit-msg .git/hooks/
```

Setting up the environment for development and testing

To set up a Ramen development environment you will need to run 3 Kubernetes clusters. Ramen makes this easy using minikube, but you need enough resources:

Bare metal or virtual machine with nested virtualization enabled
8 CPUs or more
16 GiB of free memory
20 GiB of free disk space
Internet connection
Linux - tested on RHEL 8.6 and Fedora 37.

Create and activate python virtual environment

The Ramen project uses python tools to create and provision test environment and run tests. To create a virtual environment including the tools run:

make venv

This creates a virtual environment in ~/.venv/ramen and a symbolic link venv for activating the environment.

Activate the python virtual environment:

source venv

Create the environment

You can run the make target create-rdr-env to create a 3 cluster environment for suitable for Regional DR. This will create 3 minikube clusters, and install the necessary components for the Ramen operator to run.

This uses drenv tool to setup the environment. Refer to drenv readme for more details.

make create-rdr-env

Building the ramen operator image

Build the Ramen operator container image:

make docker-build

This builds the image quay.io/ramendr/ramen-operator:latest

Deploying the ramen operator

You can either deploy the Ramen operator using the make targets or use the ramendev tool. For more info on the ramendev tool see ramendev/README.md .

Using ramendev
Ensure python virtual environment is active as ramendev is a python tool.
- Deploy the Ramen operator in the environment using ramendev.
```
ramendev deploy test/envs/regional-dr.yaml
```
- Ramen needs to be configured to know about the managed clusters and the s3 endpoints. Configure the ramen operator for environment.
```
ramendev config test/envs/regional-dr.yaml
```

Updating ramen after code changes

After making code changes, rebuild the image and deploy again. This will update the Ramen operator on all clusters without affecting existing DR-protected workloads or configuration.

make docker-build
ramendev deploy test/envs/regional-dr.yaml

Testing Ramen

Read the testing guide for test instructions.

Undeploying the ramen operator

If you want to clean up your environment, you can unconfigure Ramen and undeploy it.

ramendev unconfig test/envs/regional-dr.yaml
ramendev undeploy test/envs/regional-dr.yaml

Handling CI failures after a PR is created

After submitting a pull request, check the CI results in the Checks tab and address any failures.

If the failure requires a code change, make the fix locally and push again:

git push <your-fork> <your-branch>

This re-triggers the applicable CI jobs automatically.

Otherwise, if the failure is due to a timeout or a transient issue and a restart is needed, amend your last commit without changes and force-push to re-trigger the CI jobs:

git commit --no-edit --amend
git push <your-fork> <your-branch> --force