refactor(contributor-guide): Updating the contributor guidelines Readme (#1345)

* refactor(contributor-guide): Updating contributor guidelines

Signed-off-by: shubhamchaudhary <shubham.chaudhary@mayadata.io>

contribute/developer_guide/README.md

@@ -2,17 +2,19 @@
 
 The artefacts associated with a chaos-experiment are summarized below: 
 
-- Submitted in the litmuschaos/litmus repository, under the experiments/*chaos category* folder
+- Submitted in the litmuschaos/litmus repository, under the experiments/*chaos-category* folder i.e, `experiments/generic`
 
-  - Experiment business logic (either as ansible playbook, or other). May involve creation of new or reuse of existing chaoslib
+  - Experiment business logic (either as Ansible Playbook, Golang, Python or Bash script, or other). May involve creating new or reusing an existing chaoslib (e.g. pumba, chaostoolkit).
-  - Experiment Kubernetes job (executes the business logic, also called litmusbook)
+  - Experiment Kubernetes job (passes the experiment-specific chaos parameters, executes the business logic)
 
   Example: [pod delete experiment in litmus](/experiments/generic/pod_delete)
 
-- Submitted in litmuschaos/chaos-charts repository, under the *chaos category* folder
+- Submitted in litmuschaos/chaos-charts repository, under the *chaos-category* folder i.e, `generic`
 
   - Experiment custom resource (CR) (holds experiment-specific chaos parameters & playbook entrypoint)
   - Experiment ChartServiceVersion (holds experiment metadata that will be rendered on [charthub](hub.litmuschaos.io))
+  - Experiment RBAC ( holds experiment-specific ServiceAccount, Role and RoleBinding)
+  - Experiment Engine ( holds experiment-specific chaosengine)
 
   Example: [pod delete experiment in chaos-charts](https://github.com/litmuschaos/chaos-charts/tree/master/charts/generic/pod-delete)
 
@@ -36,79 +38,109 @@ scaffolded files consist of placeholders which can then be filled as desired.
 
 - Populate the `attributes.yaml` with details of the chaos experiment (or chart). Use the [attributes.yaml.sample](/contribute/developer_guide/attributes.yaml.sample) as reference. 
 
-  As an example, let us consider an experiment to kill one of the replicas of a nodejs-app that provides a simple 
+  As an example, let us consider an experiment to kill one of the replicas of a nginx deployment. The attributes.yaml can be constructed like this: 
-  hello-world service. The attributes.yaml can be constructed like this: 
   
   ```
   $ cat attributes.yaml 
   
   ---
-  name: kill-hello-replicas
+name: pod-delete
-  version: 0.1.0
+version: 0.1.0
-  category: hello-world
+category: sample-category
-  repository: https://github.com/litmuschaos/demo-app/tree/master/sample_apps/hellonode
+repository: https://github.com/litmuschaos/litmus/tree/master/experiments/sample-category/pod-delete
-  community: https://kubernetes.slack.com/messages/CNXNB0ZTN
+community: https://kubernetes.slack.com/messages/CNXNB0ZTN
-  description: "kills hello-world pods in a random manner"
+description: "kills nginx pods in a random manner"
-  keywords: 
+keywords:
   - pods
   - kubernetes
-    - hello-world
+  - sample-category
-    - nodejs
+  - nginx
-  maturity: alpha
+scope: "Namespaced"
-  maintainers: 
+permissions:
+  - apiGroups:
+      - ""
+      - "batch"
+      - "litmuschaos.io"
+    resources:
+      - "jobs"
+      - "pods"
+      - "chaosengines"
+      - "chaosexperiments"
+      - "chaosresults"
+    verbs:
+      - "create"
+      - "list"
+      - "get"
+      - "update"
+      - "patch"
+      - "delete"
+maturity: alpha
+maintainers:
   - ksatchit@mayadata.io
-  contributors: 
+contributors:
   - ksatchit@mayadata.io
-  min_kubernetes_version: 1.12.0
+provider:
-  references: 
+  name: Mayadata
+min_kubernetes_version: 1.12.0
+references:
   - https://docs.litmuschaos.io/docs/getstarted/
+
   ```
 
-- Run the following command to generate the necessary artefacts for submitting the `hello-world` chaos chart with 
+- Run the following command to generate the necessary artefacts for submitting the `sample-category` chaos chart with 
-  `kill-hello-replicas` experiment.
+  `pod-delete` experiment.
 
   ```
   $ python3 generate_chart.py --attributes_file=attributes.yaml --generate_type=experiment
   ```
-  View the generated files
-
-  ```
-  $ ls -ltr
-
-  total 12
-  drwxr-xr-x 2 ksatchit ksatchit 4096 Oct 17 12:54 mysql
-  drwxr-xr-x 6 ksatchit ksatchit 4096 Oct 21 09:28 generic
-  drwxr-xr-x 3 ksatchit ksatchit 4096 Oct 21 10:54 hello-world
-
-  $ ls -ltr hello-world/
-
-  total 8
-  -rw-r--r-- 1 ksatchit ksatchit  704 Oct 21 10:54 hello-world.chartserviceversion.yaml
-  drwxr-xr-x 2 ksatchit ksatchit 4096 Oct 21 10:54 kill-hello-replicas
-
-  $ ls -ltr hello-world/kill-hello-replicas
-
-  total 20
-  -rw-r--r-- 1 ksatchit ksatchit  704 Oct 21 10:54 kill-hello-replicas.chartserviceversion.yaml
-  -rw-r--r-- 1 ksatchit ksatchit 1405 Oct 21 10:54 kill-hello-replicas-k8s-job.yml
-  -rw-r--r-- 1 ksatchit ksatchit  590 Oct 21 10:54 kill-hello-replicas-experiment-cr.yml
-  -rw-r--r-- 1 ksatchit ksatchit   69 Oct 21 10:54 kill-hello-replicas-ansible-prerequisites.yml
-  -rw-r--r-- 1 ksatchit ksatchit 2167 Oct 21 10:54 kill-hello-replicas-ansible-logic.yml
-  
-  ```
- 
    **Note**: In the `--generate_type` attribute, select the appropriate type of manifests to be generated, where, 
   - `chart`: Just the chaos-chart metadata, i.e., chartserviceversion yaml 
   - `experiment`: Chaos experiment artefacts belonging to a an existing OR new chart. 
 
-- Proceed with construction of business logic inside the `kill-hello-replicas-ansible-logic.yml` file, by making
+  View the generated files in `/experiments/chaos-category` folder.
+
+  ```
+  $ cd /experiments
+
+  $ ls -ltr
+
+  total 28
+  drwxr-xr-x 2 ksatchit ksatchit 4096 Oct 17 12:54 mysql
+  drwxr-xr-x 6 ksatchit ksatchit 4096 Oct 21 09:28 generic
+  drwxr-xr-x 6 ksatchit ksatchit 4096 Oct 21 09:28 openebs
+  drwxr-xr-x 6 ksatchit ksatchit 4096 Oct 21 09:28 kafka
+  drwxr-xr-x 6 ksatchit ksatchit 4096 Oct 21 09:28 coredns
+  drwxr-xr-x 6 ksatchit ksatchit 4096 Oct 21 09:28 chaostoolkit
+  drwxr-xr-x 3 ksatchit ksatchit 4096 Oct 21 10:54 sample-category
+
+  $ ls -ltr sample-category/
+
+  total 12
+  -rw-r--r-- 1 ksatchit ksatchit  704 Oct 21 10:54 sample-category.package.yaml
+  -rw-r--r-- 1 ksatchit ksatchit  704 Oct 21 10:54 sample-category.chartserviceversion.yaml
+  drwxr-xr-x 2 ksatchit ksatchit 4096 Oct 21 10:54 pod-delete
+
+  $ ls -ltr sample-category/pod-delete
+
+  total 32
+  -rw-r--r-- 1 ksatchit ksatchit  704 Oct 21 10:54 pod-delete.chartserviceversion.yaml
+  -rw-r--r-- 1 ksatchit ksatchit 1405 Oct 21 10:54 rbac.yaml
+  -rw-r--r-- 1 ksatchit ksatchit 1405 Oct 21 10:54 experiment.yaml
+  -rw-r--r-- 1 ksatchit ksatchit 1405 Oct 21 10:54 engine.yaml
+  -rw-r--r-- 1 ksatchit ksatchit 1405 Oct 21 10:54 pod-delete-k8s-job.yml
+  -rw-r--r-- 1 ksatchit ksatchit   69 Oct 21 10:54 pod-delete-ansible-prerequisites.yml
+  -rw-r--r-- 1 ksatchit ksatchit 2167 Oct 21 10:54 pod-delete-ansible-logic.yml
+  
+  ```
+ 
+- Proceed with construction of business logic inside the `pod-delete-ansible-logic.yml` file, by making
   the appropriate modifications listed below to achieve the desired effect: 
 
   - variables 
   - entry & exit criteria checks for the experiment 
   - helper utils in either [utils](/utils/) or new [base chaos libraries](/chaoslib) 
 
-- Update the `kill-hello-replicas-experiment-cr.yml` with the right chaos params in the `spec.definition.env` with their
+- Update the `experiment.yaml` with the right chaos params in the `spec.definition.env` with their
   default values
 
 - Create an experiment README (example: [pod delete readme](experiments/generic/pod_delete/README.md)) explaining, briefly, 
@@ -118,12 +150,12 @@ scaffolded files consist of placeholders which can then be filled as desired.
 
 The experiment created using the above steps, can be tested in the following manner: 
 
-- Run the `kill-hello-replicas-k8s-job.yml` with the desired values in the ENV and appropriate `chaosServiceAccount` 
+- Run the `pod-delete-k8s-job.yml` with the desired values in the ENV and appropriate `chaosServiceAccount` 
   using a custom dev image instead of `litmuschaos/ansible-runner` (say, ksatchit/ansible-runner) that packages the 
   business logic.
 
 - (Optional) Once the experiment has been validated using the above step, it can also be tested against the standard chaos 
-  workflow using the `kill-hello-replicas-experiment-cr.yml`. This involves: 
+  workflow using the `experiment.yaml`. This involves: 
 
   - Launching the Chaos-Operator
   - Creating the ChaosExperiment CR on the cluster (use the same custom dev image used in the above step) 

contribute/developer_guide/attributes.yaml.sample

@@ -1,15 +1,15 @@
 ---
-name: kill-hello-replicas
+name: pod-delete
 version: 0.1.0
-category: hello-world
+category: sample-category
-repository: https://github.com/litmuschaos/demo-app/tree/master/sample_apps/hellonode
+repository: https://github.com/litmuschaos/litmus/tree/master/sample-category/pod-delete
 community: https://kubernetes.slack.com/messages/CNXNB0ZTN
-description: "kills hello-world pods in a random manner"
+description: "kills nginx pods in a random manner"
 keywords:
   - pods
   - kubernetes
-  - hello-world
+  - sample-category
-  - nodejs
+  - nginx
 scope: "Namespaced"
 permissions:
   - apiGroups:

contribute/developer_guide/generate_chart.py

@@ -43,9 +43,29 @@ def generate_chart(chart_parent_path, chart_config, litmus_env):
     with open(chart_filename, "w+") as f:
         f.write(output_from_parsed_template)
 
+# generate_rbac creates the rbac for the experiment
+def generate_rbac(chart_parent_path, chart_config, litmus_env):
+    rbac_filename = chart_parent_path + '/' + 'rbac.yaml'
+
+    # Load Jinja2 template
+    template = litmus_env.get_template('./templates/experiment_rbac.tmpl')
+    output_from_parsed_template = template.render(chart_config)
+    with open(rbac_filename, "w+") as f:
+        f.write(output_from_parsed_template)
+
+# generate_engine creates the chaos engine for the experiment
+def generate_engine(chart_parent_path, chart_config, litmus_env):
+    engine_filename = chart_parent_path + '/' + 'engine.yaml'
+
+    # Load Jinja2 template
+    template = litmus_env.get_template('./templates/experiment_engine.tmpl')
+    output_from_parsed_template = template.render(chart_config)
+    with open(engine_filename, "w+") as f:
+        f.write(output_from_parsed_template)
+
 # generate_job creates the experiment job manifest
 def generate_job(job_parent_path, job_name, job_config, litmus_env):
-    job_filename = job_parent_path + '/' + job_name + '.' + 'k8s_job.yml'
+    job_filename = job_parent_path + '/' + job_name + '_' + 'k8s_job.yml'
 
     # Load Jinja2 template
     template = litmus_env.get_template('./templates/experiment_k8s_job.tmpl')
@@ -55,7 +75,7 @@ def generate_job(job_parent_path, job_name, job_config, litmus_env):
 
 # generate_ansible_logic creates the ansible_logic manifest
 def generate_ansible_logic(ansible_logic_parent_path, ansible_logic_name, ansible_logic_config, litmus_env):
-    ansible_logic_filename = ansible_logic_parent_path + '/' + ansible_logic_name + '.' + 'ansible_logic.yml'
+    ansible_logic_filename = ansible_logic_parent_path + '/' + ansible_logic_name + '_' + 'ansible_logic.yml'
 
     # Load Jinja2 template
     template = litmus_env.get_template('./templates/experiment_ansible_logic.tmpl')
@@ -65,7 +85,7 @@ def generate_ansible_logic(ansible_logic_parent_path, ansible_logic_name, ansibl
 
 # generate_chaos_prerequisites creates the chaos_prerequisites manifest
 def generate_chaos_prerequisites(chaos_prerequisites_parent_path, chaos_prerequisites_name, chaos_prerequisites_config, litmus_env):
-    chaos_prerequisites_filename = chaos_prerequisites_parent_path + '/' + chaos_prerequisites_name + '.' + 'ansible_prerequisites.yml'
+    chaos_prerequisites_filename = chaos_prerequisites_parent_path + '/' + chaos_prerequisites_name + '_' + 'ansible_prerequisites.yml'
 
     # Load Jinja2 template
     template = litmus_env.get_template('./templates/experiment_ansible_prerequisites.tmpl')
@@ -142,6 +162,12 @@ def main():
         # generate experiment-custom-resource
         generate_chart(experiment_dir, config, env)
 
+        # generate experiment specific rbac
+        generate_rbac(experiment_dir, config, env)
+
+        # generate experiment specific chaos engine
+        generate_engine(experiment_dir, config, env)
+
         # generate experiment job
         generate_job(experiment_dir, entity_name, config, env)
 

contribute/developer_guide/templates/experiment_ansible_logic.tmpl

@@ -10,6 +10,9 @@
     c_duration: "{{ '{{' }} lookup('env','TOTAL_CHAOS_DURATION') {{ '}}' }}"
     c_experiment: {{ name }} 
     ramp_time: "{{ '{{' }} lookup('env','RAMP_TIME') {{ '}}' }}"
+    chaos_pod_name: "{{ '{{' }} lookup('env','POD_NAME') {{ '}}' }}"
+    chaos_uid: "{{ '{{' }} lookup('env','CHAOS_UID') {{ '}}' }}"
+    c_engine: "{{ '{{' }} lookup('env','CHAOSENGINE') {{ '}}' }}"
     c_util: ""
 
   tasks:
@@ -18,13 +21,10 @@
         - include: {{ name }}-ansible-prerequisites.yml
       
          ## GENERATE EXP RESULT NAME
-        - block:
+        - name: Construct chaos result name
-
-            - name: Construct chaos result name (experiment_name)
           set_fact:
-                c_experiment: "{{ '{{' }} lookup('env','CHAOSENGINE') {{ '}}' }}-{{ '{{' }} c_experiment {{ '}}' }}"
+            c_result: "{{ '{{' }} c_engine {{ '}}' }}-{{ '{{' }} c_experiment {{ '}}' }}"
-
+          when: "c_engine is defined and c_engine != ''
-          when: lookup('env','CHAOSENGINE')    
 
         ## RECORD START-OF-EXPERIMENT IN LITMUSCHAOS RESULT CR
         - include_tasks: /utils/runtime/update_chaos_result_resource.yml
@@ -60,6 +60,15 @@
                 
           when: auxiliary_appinfo is defined and auxiliary_appinfo != ''
 
+        ## RECORD EVENT FOR PRE-CHAOS CHECK
+        - include_tasks: /utils/common/generate-kubernetes-chaos-events.yml
+          vars:
+            stage: "PreChaosCheck"
+            exp_pod_name: "{{ '{{' }} chaos_pod_name {{ '}}' }}"
+            engine_ns: "{{ '{{' }} a_ns {{ '}}' }}"
+            message: "AUT is Running successfully"
+          when: "c_engine is defined and c_engine != ''"
+
         ## FAULT INJECTION 
 
         - include_tasks: "{{ '{{' }} c_util {{ '}}' }}"
@@ -94,6 +103,15 @@
                 
           when: auxiliary_appinfo is defined and auxiliary_appinfo != ''
 
+        ## RECORD EVENT FOR POST-CHAOS CHECK
+        - include_tasks: /utils/common/generate-kubernetes-chaos-events.yml
+          vars:
+            stage: "PostChaosCheck"
+            exp_pod_name: "{{ '{{' }} chaos_pod_name {{ '}}' }}"
+            engine_ns: "{{ '{{' }} a_ns {{ '}}' }}"
+            message: "AUT is Running successfully"
+          when: "c_engine is defined and c_engine != ''"
+        
         - set_fact:
             flag: "Pass"
 
@@ -103,6 +121,9 @@
 
       always: 
 
+        ## Getting failure step from experiment-pod
+        - include_tasks: /utils/runtime/getting_failure_step.yml  
+ 
         ## RECORD END-OF-TEST IN LITMUSCHAOS RESULT CR
         - include_tasks: /utils/runtime/update_chaos_result_resource.yml
           vars:

contribute/developer_guide/templates/experiment_custom_resource.tmpl

@@ -13,7 +13,7 @@ spec:
     image: "litmuschaos/ansible-runner:ci"
     args:
     - -c
-    - ansible-playbook ./experiments/{{ chart }}/{{ name }}/{{ name }}-ansible-logic.yml -i /etc/ansible/hosts -vv; exit 0
+    - ansible-playbook ./experiments/{{ category }}/{{ name }}/{{ name }}-ansible-logic.yml -i /etc/ansible/hosts -vv; exit 0
     command:
     - /bin/bash
     env:

contribute/developer_guide/templates/experiment_engine.tmpl

@@ -0,0 +1,33 @@
+apiVersion: litmuschaos.io/v1alpha1
+kind: ChaosEngine
+metadata:
+  name: nginx-chaos
+  namespace: default
+spec:
+  appinfo:
+    appns: 'default'
+    applabel: 'app=nginx'
+    appkind: 'deployment'
+  # It can be true/false
+  annotationCheck: 'true'
+  # It can be active/stop
+  engineState: 'active'
+  #ex. values: ns1:name=percona,ns2:run=nginx
+  auxiliaryAppInfo: ''
+  chaosServiceAccount: {{ name }}-sa
+  monitoring: false
+  # It can be delete/retain
+  jobCleanUpPolicy: 'delete'
+  experiments:
+    - name: {{ name }}
+      spec:
+        components:
+          env:
+            # set chaos duration (in sec) as desired
+            - name: TOTAL_CHAOS_DURATION
+              value: '30'
+
+            # set chaos interval (in sec) as desired
+            - name: CHAOS_INTERVAL
+              value: '10'
+              

contribute/developer_guide/templates/experiment_k8s_job.tmpl

@@ -56,4 +56,4 @@ spec:
                 fieldPath: spec.serviceAccountName
 
         command: ["/bin/bash"]
-        args: ["-c", "ansible-playbook ./experiments/{{ chart }}/{{ name }}/{{ name }}-ansible-logic.yml -i /etc/ansible/hosts; exit 0"]
+        args: ["-c", "ansible-playbook ./experiments/{{ category }}/{{ name }}/{{ name }}-ansible-logic.yml -i /etc/ansible/hosts; exit 0"]

contribute/developer_guide/templates/experiment_rbac.tmpl

@@ -0,0 +1,33 @@
+---
+apiVersion: v1
+kind: ServiceAccount
+metadata:
+  name: {{ name }}-sa
+  namespace: default
+  labels:
+    name: {{ name }}-sa
+---
+apiVersion: rbac.authorization.k8s.io/v1beta1
+kind: Role
+metadata:
+  name: {{ name }}-sa
+  namespace: default
+  labels:
+    name: {{ name }}-sa
+rules: {{ permissions }}
+---
+apiVersion: rbac.authorization.k8s.io/v1beta1
+kind: RoleBinding
+metadata:
+  name: {{ name }}-sa
+  namespace: default
+  labels:
+    name: {{ name }}-sa
+roleRef:
+  apiGroup: rbac.authorization.k8s.io
+  kind: Role
+  name: {{ name }}-sa
+subjects:
+- kind: ServiceAccount
+  name: {{ name }}-sa
+  namespace: default