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

* refactor(contributor-guide): Updating contributor guidelines

Signed-off-by: shubhamchaudhary <shubham.chaudhary@mayadata.io>
This commit is contained in:
Shubham Chaudhary 2020-03-25 16:18:30 +05:30 committed by GitHub
parent f280387356
commit 5dcbe9e48b
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
8 changed files with 225 additions and 80 deletions

View File

@ -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 Kubernetes job (executes the business logic, also called litmusbook)
- 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 (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
hello-world service. The attributes.yaml can be constructed like this:
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:
```
$ cat attributes.yaml
---
name: kill-hello-replicas
version: 0.1.0
category: hello-world
repository: https://github.com/litmuschaos/demo-app/tree/master/sample_apps/hellonode
community: https://kubernetes.slack.com/messages/CNXNB0ZTN
description: "kills hello-world pods in a random manner"
keywords:
- pods
- kubernetes
- hello-world
- nodejs
maturity: alpha
maintainers:
- ksatchit@mayadata.io
contributors:
- ksatchit@mayadata.io
min_kubernetes_version: 1.12.0
references:
- https://docs.litmuschaos.io/docs/getstarted/
name: pod-delete
version: 0.1.0
category: sample-category
repository: https://github.com/litmuschaos/litmus/tree/master/experiments/sample-category/pod-delete
community: https://kubernetes.slack.com/messages/CNXNB0ZTN
description: "kills nginx pods in a random manner"
keywords:
- pods
- kubernetes
- sample-category
- nginx
scope: "Namespaced"
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:
- ksatchit@mayadata.io
provider:
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
`kill-hello-replicas` experiment.
- Run the following command to generate the necessary artefacts for submitting the `sample-category` chaos chart with
`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,
**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)
@ -136,4 +168,4 @@ The experiment created using the above steps, can be tested in the following man
- Send a PR to the [litmus](https://github.com/litmuschaos/litmus) repo with the modified litmusbook files
- Send a PR to the [chaos-charts](https://github.com/litmuschaos/chaos-charts) repo with the modified experiment CR,
experiment chartserviceversion, chaos chart (category-level) chartserviceversion & package (if applicable) YAMLs
experiment chartserviceversion, chaos chart (category-level) chartserviceversion & package (if applicable) YAMLs

View File

@ -1,15 +1,15 @@
---
name: kill-hello-replicas
name: pod-delete
version: 0.1.0
category: hello-world
repository: https://github.com/litmuschaos/demo-app/tree/master/sample_apps/hellonode
category: sample-category
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
- nodejs
- sample-category
- nginx
scope: "Namespaced"
permissions:
- apiGroups:

View File

@ -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)

View File

@ -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:
@ -17,14 +20,11 @@
- include: {{ name }}-ansible-prerequisites.yml
## GENERATE EXP RESULT NAME
- block:
- name: Construct chaos result name (experiment_name)
set_fact:
c_experiment: "{{ '{{' }} lookup('env','CHAOSENGINE') {{ '}}' }}-{{ '{{' }} c_experiment {{ '}}' }}"
when: lookup('env','CHAOSENGINE')
## GENERATE EXP RESULT NAME
- name: Construct chaos result name
set_fact:
c_result: "{{ '{{' }} c_engine {{ '}}' }}-{{ '{{' }} c_experiment {{ '}}' }}"
when: "c_engine is defined and c_engine != ''
## 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 {{ '}}' }}"
@ -93,6 +102,15 @@
- "{{ '{{' }} auxiliary_appinfo.split(',') {{ '}}' }}"
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"
@ -102,6 +120,9 @@
flag: "Fail"
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

View File

@ -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:

View File

@ -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'

View File

@ -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"]

View File

@ -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