openebs-archive / openebs-docs

OpenEBS Documentation

OpenEBS Documentation (Deprecated)

The content in this repository has been migrated to https://github.com/openebs/website

---

openebs-docs is the repository for the official OpenEBS documentation. This is using Docusaurus as a documentation framework. It's easy to use and write documentation using Docusaurus, which uses markdown markup language. Additional details on the Docusaurus project can be found here.

For Developers

Instead of performing the following steps, you might just want to edit the docs in a fully pre-configured development environment in the browser: .

Install Node.js

sudo apt-get install software-properties-common
curl -sL https://deb.nodesource.com/setup_13.x | sudo -E bash -

Get the latest Node.js package

sudo apt-get install -y nodejs

Install Yarn

npm install -g yarn

Clone openebs-docs repository

git clone https://github.com/openebs/openebs-docs.git
cd openebs-docs

Start the server

cd website
npm start

The above step will start a server on the localhost:3000

How OpenEBS-docs get published?

The following procedure lists the tasks from the time you select an issue to publish the document:

1. Go through the issues, and select an issue you want to work on.

2. Go to openebs-docs/website, and execute npm start. You can then preview the document at http://localhost:3000/docs/next/overview.html.

3. Work on your issue and create and submit your pull request(PR) for the members to review. Do perform the DCO signoff. DCO stands for Developer Certificate of Origin. It requires the commit message to have a Signed-off-by: statement along with the email address of the author of that commit. You can do this using the following command git commit -s -m 'Commit message related to the issue'. You can read more about it here.

4. Make changes to your pull request as suggested by the members. In order to keep the pull request clean, you can use git commit --amend -s -m 'Commit message related to the issue' along with git push -f. This will prevent multiple commits.

5. After you submit your pull request, and after it is approved by at least one member, it goes through Travis CI integration. Your pull request is checked, and if it exits with code 0 for all the cases, then it's considered as passed and good for merging. If it fails, identify and fix the errors and resubmit it. You can use the commands mentioned in point 4.

6. The maintainers can then merge your pull request. Congrats on your contribution to the OpenEBS-docs code-base.

License

The project is licensed under the Apache 2.0 License. See LICENSE for the full license text.

openebs-docs's Issues

Update website URL in siteconfig file

Tutorial for operator yaml

FEATURE REQUEST

What happened:

What you expected to happen:
Create the Tutorial for operator yaml

    * creating maya service account
    * defining role and privileges
    * deploying Maya API server
    * servicing maya-apiserver-service
    * deploying OpenEBS provisioner

How to reproduce it (as minimally and precisely as possible):

Anything else we need to know?:

Setup Ingress for docs.openebs.io

Change cursor pointer type for Sidebars

Update the openebs operator(s) to place maya based deployments into tainted K8s Nodes

Is this a BUG REPORT or FEATURE REQUEST?

FEATURE REQUEST

Why is this required?

• OpenEBS has a set of K8s Deployments which are typically control plane based services for OpenEBS
• It will be good to place these (optionally, depends on customer environments/requirements) on control plane specific K8s Nodes.
  • This will ensure non-interference with data plane & application plane K8s Nodes

How to do this ?

• Taint the K8s Nodes for controller plane services
• Ensure this is an optional feature for the deployments where this is not applicable
• Ensure this is an optional feature for the deployments where customer does not want this
• Might want to build a Tool / Daemon / CLI that looks into existing K8s deployment, accepts/assumes admin entries, generates these yaml based operators & runs them as well.
  • Might want to break this into a series of smaller tasks/issues

Related Issues

Update header links in siteconfig.js file

WHY ?

• Update header links in siteconfig.js file
• Remove API,Blog and help page links from header

[Doc] Add a Documentation procedure for deploying Kafka in OpenEBS read the docs

Integrate Openebs-docs with hotjar for user's feedback

WHY ?

• Integrate OpenEBS docs with hotjar in order to provide a functionality for user to provide feedback on
  documentation.

Add header for openebs-docs

WHY ?

• Add header for openebs-docs with openebs logo

Update nginx.custom file to change the index page

Update project name in siteconfig file

Demo around Cassandra

What is this all about ?

• This image is a mindmap of various variables against Cassandra on K8s setup
• Modification of each variable should be accounted via Monitoring
• Cassandra based SLAs should be determined
• Cassandra based workloads should be determined
• Various infrastructure failures should be determined
• The thresholds should be determined so as to abide by the SLAs
• The entire mindmap should result in a reproducible setup
• The mindmap should be demo-able
• The mindmap should be portable across clouds

Assumptions

• Kubernetes Setup
• OpenEBS as the underlying persistent volume for Cassandra

Others

• Hardware & Software specifications used to determine these SLAs should be published
• Blogs should be written

Change search bar height in sync to header height

WHY ?

• Change search bar height in a way so that it is in sync with header height

User tutorial for installing OpenEBS on CoreOS + Kubernetes

The default Core-OS image doesn't enable iscsi which is required for OpenEBS volumes.
The tutorial should include the pre-requisites/steps to configure iscsi-initiator through kubelet-wrapper. details mentioned by @maikotz in #160

Change the primary colour of website in siteconfig.js file

[Doc] Add a Documentation procedure for deploying RabbitMQ in OpenEBS read the docs

Steps to destroy the demo apps is missing

The readme & guides available in various demo apps does not talk about destroying the app, volumes, cleanups, etc.

ref - https://github.com/openebs/openebs/tree/master/k8s/demo/

Add package-lock.json file

Add a new docusaurus project for hosting openebs documentation

WHY ?

• Host OpenEBS documentation using docusaurus project

Add a brain friendly guide to openEBS.

Our docs are becoming approachable day by day but nothing comes closer to a small video which can serve better than a paragraph of text.

Take a look at these websites in order

1. Kubernetes website
2. Kubernetes by example
3. Kubernetes for kids

What if you had seen them in the reverse order?
Fill the gaps which is with an awesome video/presentation, we'd be taking the link to that video.

Get more details on our slack 👍

[Doc] Add all images into new repository for docusaurus

Change index page in nginx custom file

Add sample sidebar label and introduction page

WHY ?

• Add some sample sidebar labels to openebs doc
• Add an introduction page

Doc Improvement: Getting Started / Deploying Stateful Workloads

In step 6 of the getting started section for on-premise deployments (http://openebs.readthedocs.io/en/latest/install/on_premise_solutions.html)
we need to add a step to check the state of the pods, to make sure they're all in the running state before deploying stateful apps. If an inexperienced user goes through these steps with cut and paste, they'll deploy a stateful workload before the cluster is ready, and things won't work out well.

Update .travis.yml to change image name for staging branch

Deploy OpenEBS-docs on GKE

Convert Usecases section rst files to md files.

Update readme file

WHY ?

• Update openebs-docs readme file

Add Side bar Content

Add footer for openebs-docs

WHY ?

• Add footer section for openebs docs

Display header logo in mobile view also

• Display openebs-logo for docs in mobile view also alongwith the desktop view
• Add custom css for enabling visibility of logo in openebs-docs

Add header and footer icon to siteconfig.js file

WHY ?

• Add header and footer icon to img folder and add it in siteconfig.js file to include it in header and footer

Add a search bar in header section of openebs-docs to enable doc search

WHY ?

• Add search bar in header on the right side in order to enable doc search for OpenEBS docs

Upgrade of OpenEBS volume controller from 0.4 to 0.5 creates orphaned replicaset

Is this a BUG REPORT or FEATURE REQUEST?

BUG REPORT

What happened:

The upgrade of the OpenEBS volume (jiva) controller deployment via recommended procedures (kubectl patch deployment) is seen to cause creation of a new replicaset without down-scaling the existing replicaset causing the upgraded volume replicas to continue accessing the older controller. This is caused due to addition of label selector in 0.5 for monitoring purposes. In the command output below, note that the older jiva replica replica-sets are downscaled while the older controller replica-set remains.

karthik@MayaMaster:~/0.4-0.5-upgrade$ kubectl get rs
NAME                                                      DESIRED   CURRENT   READY     AGE
maya-apiserver-6fc5b4d59c                                 0         0         0         8h
maya-apiserver-7b8f548dd8                                 1         1         1         5h
openebs-provisioner-6d9b78696d                            0         0         0         8h
openebs-provisioner-7958c6d44f                            1         1         1         5h
percona-5b9df94795                                        1         1         1         8h
pvc-cb0a1656-07c6-11e8-89bc-000c298ff5fc-ctrl-b779b6b5d   1         1         1         8h
pvc-cb0a1656-07c6-11e8-89bc-000c298ff5fc-ctrl-d9f4b469f   1         1         1         5h
pvc-cb0a1656-07c6-11e8-89bc-000c298ff5fc-rep-6bfdf45c99   2         2         2         5h
pvc-cb0a1656-07c6-11e8-89bc-000c298ff5fc-rep-7494f9dcf5   0         0         0         5h

Also, this causes the upgraded deployment to marked as the 1st revision thereby disallowing rollbacks via kubectl rollout undo deployment --to-revision

What you expected to happen:

Upgrades should be rollback friendly as much as possible. Use of labels may need to be re-looked once again.

How to reproduce it (as minimally and precisely as possible):
Perform patch deployment of OpenEBS volume controller from 0.4 to 0.5

Anything else we need to know?:

Here is the relevant info from kubernetes docs on the issue in question: https://kubernetes.io/docs/concepts/workloads/controllers/deployment/

Update repo name in .travis.yaml

Host docusaurus on staging-docs.openebs.io

OpenEBS deployment on Digital Ocean.

Create workflow documentation and automation script for deploying OpenEBS on Digital Ocean.

Change search bar bg color and text colour on focus

WHY ?

• Change search bar bg color to white
• Change search input text color to black

Integrate openebs-docs with algolia search

WHY ?

• Integrate Openebs-docs with algolia search in order to provide a smooth search functionality

Create new docker image for openebs-docs

Fix index page issue with nginx-custom

id of index page is changed, so nginx is not able to find doc1.html page.

Provide link (anchors) to sub-topics on the docs.openebs.io

We need to have a tree-view like structure on the sidebar OR have a menu in every major page - consisting of links to the sub-topics. A case in point is : the storage pool policy info can be reached by scrolling down in the policies page - we should ideally have a link to reach the intended section : https://docs.openebs.io/docs/storagepolicies.html

Update baseURL in siteconfig file

Add openebs logo in docs header

WHY ?

• Add OpenEBS logo in OpenEBS docs header section

Add the flow on how docs get published in the readme file.

Add Glossary section under Getting Started

Add a Glossary section where terms used in documentation are described and how they are used in the documentation.

Convert rst files under Setup section to md files.

Document the environment variables used in maya api service

Is this a BUG REPORT or FEATURE REQUEST?

FEATURE REQUEST

Details

maya api server defines the environment variables (referred as ENV) with an appropriate context.

e.g. the replica count of OpenEBS volume in default context one has to set the ENV variable

DEFAULT_REPLICA_COUNT=1 # or some non-negative value

e.g. similarly to fetch the replica count of OpenEBS volume in a context named XYZ one has to set the ENV variable

XYZ_REPLICA_COUNT=1

The ENV context can be set by passing XYZ as the value against the request option

env.mapi.openebs.io/env-var-ctx=XYZ

NOTE: Environment variables can sometimes be tricky if the user running the process (e.g. here maya api service) should have access to these variables.

Refer to below snippet for other ENV variables understood by maya api service

// EnvironmentVariableDefaults is a typed label that defines the environment variable
// defaults
type EnvironmentVariableDefaults string

const (
	// Default value for environment variable context
	EnvVariableContextDef EnvironmentVariableDefaults = "DEFAULT"
)

// EnvironmentVariableKey is a typed label that define the environment variables
type EnvironmentVariableKey string

const (
	// PVPProfileNameEnvVarKey is the environment variable key for persistent
	// volume provisioner's profile name
	//
	// Usage:
	// <CTX>_PVP_PROFILE_NAME = <some value>
	PVPProfileNameEnvVarKey EnvironmentVariableKey = "_PVP_PROFILE_NAME"
	// PVPNameEnvVarKey is the environment variable key for persistent volume
	// provisioner's name
	//
	// Usage:
	// <CTX>_PVP_NAME = <some value>
	PVPNameEnvVarKey EnvironmentVariableKey = "_PVP_NAME"
	// PVPControllerImageEnvVarKey is the environment variable key for persistent
	// volume provisioner's controller image
	//
	// Usage:
	// <CTX>_CONTROLLER_IMAGE = <some value>
	PVPControllerImageEnvVarKey EnvironmentVariableKey = "_CONTROLLER_IMAGE"
	// PVPPersistentPathEnvVarKey is the environment variable key for persistent
	// volume provisioner's replica persistent path
	//
	// Usage:
	// <CTX>_PERSISTENT_PATH = <some value>
	PVPPersistentPathEnvVarKey EnvironmentVariableKey = "_PERSISTENT_PATH"
	// PVPStorageSizeEnvVarKey is the environment variable key for persistent
	// volume provisioner's replica size
	//
	// Usage:
	// <CTX>_STORAGE_SIZE = <some value>
	PVPStorageSizeEnvVarKey EnvironmentVariableKey = "_STORAGE_SIZE"
	// PVPReplicaCountEnvVarKey is the environment variable key for persistent
	// volume provisioner's replica count
	//
	// Usage:
	// <CTX>_REPLICA_COUNT = <some value>
	PVPReplicaCountEnvVarKey EnvironmentVariableKey = "_REPLICA_COUNT"
	// PVPReplicaImageEnvVarKey is the environment variable key for persistent
	// volume provisioner's replica image
	//
	// Usage:
	// <CTX>_REPLICA_IMAGE = <some value>
	PVPReplicaImageEnvVarKey EnvironmentVariableKey = "_REPLICA_IMAGE"
	// PVPControllerCountEnvVarKey is the environment variable key for persistent
	// volume provisioner's controller count
	//
	// Usage:
	// <CTX>_CONTROLLER_COUNT = <some value>
	PVPControllerCountEnvVarKey EnvironmentVariableKey = "_CONTROLLER_COUNT"
	// PVPReplicaTopologyKeyEnvVarKey is the environment variable key for persistent
	// volume provisioner's replica topology key
	//
	// Usage:
	// <CTX>_REPLICA_TOPOLOGY_KEY = <some value>
	PVPReplicaTopologyKeyEnvVarKey EnvironmentVariableKey = "_REPLICA_TOPOLOGY_KEY"
	// OrchestratorNameEnvVarKey is the environment variable key for
	// orchestration provider's name
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_NAME = <some value>
	OrchestratorNameEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_NAME"
	// OrchestratorRegionEnvVarKey is the environment variable key for orchestration
	// provider's region
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_REGION = <some value>
	OrchestratorRegionEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_REGION"
	// OrchestratorDCEnvVarKey is the environment variable key for orchestration
	// provider's datacenter
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_DC = <some value>
	OrchestratorDCEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_DC"
	// OrchestratorAddressEnvVarKey is the environment variable key for orchestration
	// provider's address
	//
	// Usage:
	// <CTX>_<REGION>_<DC>_ORCHESTRATOR_ADDR = 10.20.1.1
	OrchestratorAddressEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_ADDR"
	// OrchestratorCNTypeEnvVarKey is the environment variable key for orchestration
	// provider's network type
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_CN_TYPE = <some value>
	OrchestratorCNTypeEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_CN_TYPE"
	// OrchestratorCNInterfaceEnvVarKey is the environment variable key for orchestration
	// provider's network interface
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_CN_INTERFACE = <some value>
	OrchestratorCNInterfaceEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_CN_INTERFACE"
	// OrchestratorCNAddrEnvVarKey is the environment variable key for orchestration
	// provider's network address
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_CN_ADDRESS = <some value>
	OrchestratorCNAddrEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_CN_ADDRESS"
	// OrchestratorNSEnvVarKey is the environment variable key for orchestration
	// provider's namespace
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_NS = <some value>
	OrchestratorNSEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_NS"
	// OrchestratorInClusterEnvVarKey is the environment variable key for orchestration
	// provider's in-cluster flag
	//
	// Usage:
	// <CTX>_ORCHESTRATOR_IN_CLUSTER = <some value>
	OrchestratorInClusterEnvVarKey EnvironmentVariableKey = "_ORCHESTRATOR_IN_CLUSTER"
)

Reduce favicon icon size

• Reduce favicon icon size in order to fit with the display

Update dockerfile to copy the build folder