Initial documentation for Ramen (RamenDR#40)

* Initial documentation for Ramen

- Updated README
- Added DCO and CONTRIBUTING guide
- Added a docs directory
- Added some initial docs, which can be updated as
  we progress

Signed-off-by: Shyamsundar Ranganathan <[email protected]>

* Addressed review comments

Also, restructured the 2 lists at the beginning
to a single list about Ramen.

Signed-off-by: Shyamsundar Ranganathan <[email protected]>

* Updated README based on review comments

Signed-off-by: Shyamsundar Ranganathan <[email protected]>

CONTRIBUTING.md

@@ -0,0 +1,84 @@
+# How to Contribute
+
+The Ramen project in under [Apache 2.0 license](LICENSE). We accept
+contributions via GitHub pull requests. This document outlines some of the
+conventions related to development workflow to make it easier to get your
+contribution accepted.
+
+## Certificate of Origin
+
+By contributing to this project you agree to the Developer Certificate of
+Origin (DCO). This document was created by the Linux Kernel community and is a
+simple statement that you, as a contributor, have the legal right to make the
+contribution. See the [DCO](DCO) file for details.
+
+Contributors sign-off that they adhere to these requirements by adding a
+Signed-off-by line to commit messages. For example:
+
+```
+This is my commit message
+
+Signed-off-by: Random J Developer <[email protected]>
+```
+
+Git even has a -s command line option to append this automatically to your
+commit message:
+
+```
+git commit -s -m 'This is my commit message'
+```
+
+If you have already made a commit and forgot to include the sign-off, you can
+amend your last commit to add the sign-off with the following command, which
+can then be force pushed.
+
+```
+git commit --amend -s
+```
+
+## Getting Started
+
+1. Fork the repository on GitHub
+1. Read the [install](docs/install.md) guide for build and deploy instructions
+1. Play with the project, submit bugs, submit patches!
+
+## Contribution Flow
+
+This is a rough outline of what a contributor's workflow looks like:
+
+1. Create a branch from where you want to base your work (usually main).
+1. Make your changes and arrange them in readable commits.
+1. Make sure your commit messages are in the proper format (see below).
+1. Push your changes to the branch in your fork of the repository.
+1. Make sure all [tests](docs/testing.md) pass, and add any new [tests](docs/testing.md)
+   as appropriate.
+1. Submit a pull request to the original repository.
+
+## Coding Style
+
+Ramen project is written in golang and follows the style guidelines dictated
+by the go fmt as well as go vet tools.
+
+Additionally various golang linters are enforced to ensure consistent coding
+style, these can be run using, `make lint` and in turn uses [golangci](https://golangci-lint.run/)
+with [this](.golangci.yaml) configuration.
+
+Several other linters are run on the pull request using the
+[pre-commit.sh](hack/pre-commit.sh) script.
+
+### Pull Request Flow
+
+The general flow for a pull request approval process is as follows:
+
+1. Author submits the pull request
+1. Reviewers and maintainers for the applicable code areas review the pull
+   request and provide feedback that the author integrates
+1. Reviewers and/or maintainers signify their LGTM on the pull request
+1. A maintainer approves the pull request based on at least one LGTM from the
+   previous step
+    1. Note that the maintainer can heavily lean on the reviewer for examining
+       the pull request at a finely grained detailed level. The reviewers are
+       trusted members and maintainers can leverage their efforts to reduce
+       their own review burden.
+1. A maintainer merges the pull request into the target branch (main, release,
+   etc.)

DCO

@@ -0,0 +1,36 @@
+Developer Certificate of Origin
+Version 1.1
+
+Copyright (C) 2004, 2006 The Linux Foundation and its contributors.
+660 York Street, Suite 102,
+San Francisco, CA 94110 USA
+
+Everyone is permitted to copy and distribute verbatim copies of this
+license document, but changing it is not allowed.
+
+
+Developer's Certificate of Origin 1.1
+
+By making a contribution to this project, I certify that:
+
+(a) The contribution was created in whole or in part by me and I
+    have the right to submit it under the open source license
+    indicated in the file; or
+
+(b) The contribution is based upon previous work that, to the best
+    of my knowledge, is covered under an appropriate open source
+    license and I have the right under that license to submit that
+    work with modifications, whether created in whole or in part
+    by me, under the same open source license (unless I am
+    permitted to submit under a different license), as indicated
+    in the file; or
+
+(c) The contribution was provided directly to me by some other
+    person who certified (a), (b) or (c) and I have not modified
+    it.
+
+(d) I understand and agree that this project and the contribution
+    are public and that a record of the contribution (including all
+    personal information I submit with it, including my sign-off) is
+    maintained indefinitely and may be redistributed consistent with
+    this project or the open source license(s) involved.

README.md

@@ -1 +1,48 @@
-# ramen
+# Ramen
+
+Ramen is a **disaster-recovery orchestrator** for stateful applications across
+a set of peer kubernetes clusters which are deployed and managed using
+[open-cluster-management](https://open-cluster-management.io/concepts/architecture/)
+(**OCM**) and provides **cloud-native interfaces** to orchestrate the
+life-cycle of an application's state on PersistentVolumes. These include:
+
+- Failing over an application's state to a peer cluster on unavailability of
+  the currently deployed cluster
+- Failing back an application's state to the previously deployed cluster
+- Migration of an application's state to a peer cluster
+
+Ramen relies on storage plugins providing support for the CSI addon
+[storage replication extensions](https://github.com/csi-addons/volume-replication-operator)
+, of which [ceph-csi](https://github.com/ceph/ceph-csi/) is a sample
+implementation.
+
+For details regarding use-cases for Ramen see the [motivation](docs/motivation.md)
+guide.
+
+## Getting Started and Documentation
+
+For installation, deployment, and administration, see the [install](docs/install.md)
+guide.
+
+## Contributing
+
+We welcome contributions. See [contributing](CONTRIBUTING.md) guide to get
+started.
+
+## Report a Bug
+
+For filing bugs, suggesting improvements, or requesting new features, please
+open an [issue](https://github.com/ramendr/ramen/issues).
+
+## Project Status
+
+The entire project is under development, and hence all APIs supported by Ramen
+are currently **alpha**. There are no releases as yet.
+
+- **Alpha:** The API may change in incompatible ways in a later software
+  release without notice, recommended for use only in short-lived testing
+  clusters, due to increased risk of bugs and lack of long-term support.
+
+## Licensing
+
+Ramen is under the Apache 2.0 license.

docs/avr-crd.md

@@ -0,0 +1,3 @@
+# ApplicationVolumeReplication(AVR) CRD
+
+## **Under construction**

docs/install.md

@@ -0,0 +1,52 @@
+# Install
+
+## **Under construction**
+
+## Prerequisites
+
+### OCM based multi-cluster setup
+
+Ramen works as part of the [OCM hub] to orchestrate disaster-recovery, of
+application state, for applications deployed to [OCM managed clusters].
+
+As a result Ramen requires that multiple kubernetes clusters, that form the
+set of peer clusters, across which application deployment and state needs to
+be managed for disaster recovery are, managed clusters of an OCM hub.
+
+The OCM hub orchestration is provided by Ramen using the
+[ApplicationVolumeReplication(AVR) CRD](docs/avr-crd.md).
+
+### Ceph-CSI as the volume provisioner
+
+Ramen also works as part of the [OCM managed clusters] to orchestrate,
+
+- [VolumeReplication](https://github.com/csi-addons/volume-replication-operator/blob/main/api/v1alpha1/volumereplication_types.go)
+  resources for all PVCs of an application
+- Preserving metadata regarding each PVC that is replicated
+
+VolumeReplication resources require storage providers to support
+[CSI extensions](https://github.com/csi-addons/spec) that enable managing
+volume replication features for volumes provisioned by the storage provider.
+[ceph-CSI](https://github.com/ceph/ceph-csi/) is one such storage provider
+that supports the required extensions.
+
+The managed cluster orchestration is provided by Ramen using the
+[VolumeReplicationGroup(VRG) CRD](docs/vrg-crd.md).
+
+**NOTE:** Ramen on OCM managed clusters and its orchestration of VRG CRD can
+be accomplished independent of an OCM setup, and only requires a native
+kubernetes cluster to manage VRG resources.
+
+### S3 store
+
+Ramen preserves metadata related to VolumeReplication resources in an S3
+compatible object store. An S3 store endpoint is hence required as part of the
+setup.
+
+Ramen specifically stores PV metadata for a replicated PVC, to restore the same
+across peer cluster prior to deploying the PVCs of the application, to ensure
+proper binding of the PVC resources to the replicated storage end points.
+
+## Installing Ramen on OCM hub
+
+## Installing Ramen on managed kubernetes clusters

docs/motivation.md

@@ -0,0 +1,3 @@
+# Motivation
+
+## **Under Construction**

docs/testing.md

@@ -0,0 +1,3 @@
+# Testing
+
+## **Under construction**

docs/vrg-crd.md

@@ -0,0 +1,3 @@
+# VolumeReplicationGroup(VRG) CRD
+
+## **Under construction**