From ba8d491486da0820f73fbe8ecb8a4ee6b3ab0897 Mon Sep 17 00:00:00 2001 From: Raj Das Date: Tue, 15 Jun 2021 19:35:33 +0530 Subject: [PATCH 1/6] Refactoring installation mode in the docs Signed-off-by: Raj Das --- website/docs/admin-mode.md | 193 -------------- website/docs/agent-installation.md | 40 +-- ...tion.md => litmus-installation-cluster.md} | 17 +- website/docs/litmus-installation-namespace.md | 242 ++++++++++++++++++ website/docs/litmus-uninstallation.md | 12 +- website/docs/namespaced-mode.md | 219 ---------------- website/sidebars.js | 4 +- 7 files changed, 281 insertions(+), 446 deletions(-) delete mode 100644 website/docs/admin-mode.md rename website/docs/{litmus-installation.md => litmus-installation-cluster.md} (93%) create mode 100644 website/docs/litmus-installation-namespace.md delete mode 100644 website/docs/namespaced-mode.md diff --git a/website/docs/admin-mode.md b/website/docs/admin-mode.md deleted file mode 100644 index e7b8aff9..00000000 --- a/website/docs/admin-mode.md +++ /dev/null @@ -1,193 +0,0 @@ ---- -id: admin-mode -title: Administrator Mode -sidebar_label: Administrator Mode -original_id: admin-mode ---- - ---- - -### What is Adminstator Mode? - -Admin mode is one of the ways the chaos orchestration is set up in Litmus, wherein all chaos resources (i.e., install time resources like the operator, chaosexperiment CRs, chaosServiceAccount/rbac and runtime resources like chaosengine, chaos-runner, experiment jobs & chaosresults) are set up in a single admin namespace (typically, litmus). In other words, centralized administration of chaos. This feature is aimed at making the SRE/Cluster Admins' life easier by doing away with setting up chaos pre-requisites on a per namespace basis (which may be more relevant in an autonomous/self-service cluster sharing model in dev environments). This mode typically needs a "wider" & "stronger" ClusterRole, albeit one that is still just a superset of the individual experiment permissions. In this mode, the applications in their respective namespaces are subjected to chaos while the chaos job runs elsewhere, i.e., admin namespace. - -### How to use Adminstator Mode? - -In order to use Admin Mode, you just have to create a ServiceAccount in the _admin_ or so-called _chaos_ namespace (`litmus` itself can be used), which is tied to a ClusterRole that has the permissions to perform operations on Kubernetes resources involved in the selected experiments across namespaces. Provide this ServiceAccount in ChaosEngine's .spec.chaosServiceAccount. - -### Supported Experiments in Namespaced Mode - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - - -
ExperimentScope of the experiment
Pod DeletePod Level
Container KillPod Level
- Pod Network Loss - Pod Level
- Pod Network Latency - Pod Level
- Pod Network Duplication - Pod Level
- Pod Network Corruption - Pod Level
Pod CPU HogPod Level
Pod Memory HogPod Level
Disk FillPod Level
Pod AutoscalerPod Level
Node CPU HogInfra Level
- Node Memory Hog - Infra Level
Node IO StressInfra Level
Node DrainInfra Level
Node TaintInfra Level
Node RestartInfra Level
- Kubelet Service Kill - Infra Level
- Docker Service Kill - Infra Level
- EC2 instance Terminate - Infra Level
EBS LossInfra Level
- -### Role Based Access Control (RBAC) Permission in Namespaced Mode - -In Admin mode the RBAC for different [litmus components](https://github.com/litmuschaos/litmus/tree/master/litmus-portal/graphql-server/manifests/cluster) are as follows, - -- [Argo](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/cluster/1b_argo_rbac.yaml) -- [Litmus Cluster Scope](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/cluster/2b_litmus_rbac.yaml) -- [Litmus Admin](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/cluster/3a_agents_rbac.yaml)(for running experiments) -- [Subscriber](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/cluster/3a_agents_rbac.yaml) -- [Litmus Event Tracker](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/cluster/3a_agents_rbac.yaml) - -### Install Litmus Portal in Admin Mode - -To install Litmus portal on admin mode refer to our [installation steps](./litmus-installation.md)! - -#### Deploy sample Application Hello World under Chaos (Optional) - -We can now deploy a sample hello world application under chaos (AUT) in any namespace. - -```bash -kubectl apply -f https://raw.githubusercontent.com/litmuschaos/litmus/master/litmus-portal/platforms/okteto/hello-world-AUT.yml -n -``` - -Output: - -```bash -deployment.apps/hello-world created -service/hello-world created -``` - -#### Create project from portal and check service accounts - -After logging in to the portal by following the installation steps, the next page will ask you to create a project. You can give a name of your project and click on Continue. In the next step you will be asked to change the password. You can keep the same password for the sake of simplicity, i.e litmus. - -With this, you’re done with the initial setup and you’ll arrive at the Welcome page. -Here, you can check the Targets option from the side bar if it changes to Active state from Pending state or not. - -Now, you can again go back to the cluster and check the pods in the target namespace (here litmus). - -```bash -$ kubectl get pods -n litmus -NAME READY STATUS RESTARTS AGE -argo-server-8497bdfd84-kk2vw 1/1 Running 0 3m28s -chaos-exporter-5fbd968db-z4n4f 1/1 Running 0 3m36s -chaos-operator-ce-c749c49cd-w8t4k 1/1 Running 0 3m36s -event-tracker-647db5959d-gshql 1/1 Running 0 3m29s -hello-world-867646c44b-f985x 1/1 Running 0 75m -hello-world-867646c44b-kqkbz 1/1 Running 0 75m -litmusportal-frontend-97c8bf86b-mx89w 1/1 Running 2 75m -litmusportal-server-5cfbfc88cc-m6c5j 2/2 Running 2 75m -mongo-0 1/1 Running 0 75m -subscriber-676fd59f59-xcvc2 1/1 Running 0 3m30s -workflow-controller-7dbc97dc75-7c6b9 1/1 Running 0 3m27s -``` - -You’ll find that some new deployment is shown which includes litmus infra components like ChaosOperator and monitoring component ChaosExporter to generate chaos metrics. Also, some new service accounts have been created to run chaos. - -```bash -$ kubectl get sa -n litmus -NAME SECRETS AGE -argo 1 6m19s -argo-chaos 1 6m24s -argo-server 1 6m18s -default 1 78m -litmus 1 6m29s -litmus-admin 1 6m25s -litmus-event-tracker-sa 1 6m22s -litmus-namespace-scope 1 6m27s -litmus-server-account 1 78m -``` - -With this, we are done setting up litmus in admin mode! diff --git a/website/docs/agent-installation.md b/website/docs/agent-installation.md index 870ffff4..42276774 100644 --- a/website/docs/agent-installation.md +++ b/website/docs/agent-installation.md @@ -27,22 +27,6 @@ The litmusctl CLI requires the following things: To install the latest version of litmusctl follow the below steps: -- Download the stable litmusctl(v0.1.0) binary from: - -| Platforms | Download Link | -| ------------------------------ | ------------------------------------------------------------------------------------------------------- | -| litmusctl-darwin-386 (MacOS) | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-darwin-386-v0.1.0.tar.gz) | -| litmusctl-darwin-amd64 (MacOS) | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-darwin-amd64-v0.1.0.tar.gz) | -| litmusctl-linux-386 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-386-v0.1.0.tar.gz) | -| litmusctl-linux-amd64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-amd64-v0.1.0.tar.gz) | -| litmusctl-linux-arm | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-arm-v0.1.0.tar.gz) | -| litmusctl-linux-arm64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-arm64-v0.1.0.tar.gz) | -| litmusctl-windows-386 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-386-v0.1.0.tar.gz) | -| litmusctl-windows-amd64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-amd64-v0.1.0.tar.gz) | -| litmusctl-windows-arm | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-arm-v0.1.0.tar.gz) | - -
- - Download the latest litmusctl(master) binary from: | Platforms | Download Link | @@ -57,7 +41,23 @@ To install the latest version of litmusctl follow the below steps: | litmusctl-windows-amd64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-amd64-master.tar.gz) | | litmusctl-windows-arm | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-arm-master.tar.gz) | -
+
+ +- Download the litmusctl(v0.2.0) binary from: + +| Platforms | Download Link | +| ------------------------------ | ------------------------------------------------------------------------------------------------------- | +| litmusctl-darwin-386 (MacOS) | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-darwin-386-v0.2.0.tar.gz) | +| litmusctl-darwin-amd64 (MacOS) | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-darwin-amd64-v0.2.0.tar.gz) | +| litmusctl-linux-386 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-386-v0.2.0.tar.gz) | +| litmusctl-linux-amd64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-amd64-v0.2.0.tar.gz) | +| litmusctl-linux-arm | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-arm-v0.2.0.tar.gz) | +| litmusctl-linux-arm64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-linux-arm64-v0.2.0.tar.gz) | +| litmusctl-windows-386 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-386-v0.2.0.tar.gz) | +| litmusctl-windows-amd64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-amd64-v0.2.0.tar.gz) | +| litmusctl-windows-arm | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-arm-v0.2.0.tar.gz) | + +
- Extract the binary @@ -101,7 +101,7 @@ $ litmusctl agent connect Next, you need to enter LitmusPortal details to login into your LitmusPortal account. Fields to be filled in: -**LitmusPortal UI URL:** Enter the URL used to access the Litmus Portal UI. +**LimtusPortal UI URL:** Enter the URL used to access the Litmus Portal UI. Example, http://172.17.0.2:31696/ **Username:** Enter your LitmusPortal username. @@ -151,7 +151,7 @@ Fields to filled in: **Platform Name:** Enter the platform name on which this agent is hosted. For example, AWS, GCP, Rancher etc. -**Enter the namespace:** You can either enter an existing namespace or enter a new namespace. In cases where the namespace does not exist, LitmusPortal creates it for you. +**Enter the namespace:** You can either enter an existing namespace or enter a new namespace. In cases where the namespace does not exist, LimtusPortal creates it for you. **Enter service account:** Enter a name for your service account. @@ -193,4 +193,4 @@ Installation Mode: cluster 👉 Litmus agents can be accessed here: http://172.17.0.2:31696/targets ``` -To verify, if the connection process was successful you can view the list of connected agents from the Targets section on your LitmusPortal and ensure that the connected agent is in Active State. +To verify, if the connection process was successful you can view the list of connected agents from the Targets section on your LitmusPortal and ensure that the connected agent is in Active State. \ No newline at end of file diff --git a/website/docs/litmus-installation.md b/website/docs/litmus-installation-cluster.md similarity index 93% rename from website/docs/litmus-installation.md rename to website/docs/litmus-installation-cluster.md index 60b7c37b..e43c4ced 100644 --- a/website/docs/litmus-installation.md +++ b/website/docs/litmus-installation-cluster.md @@ -1,7 +1,7 @@ --- id: litmus-install -title: Litmus Chaos Control Plane -sidebar_label: Control Plane +title: Litmus Chaos Control Plane (Cluster Mode) +sidebar_label: Control Plane (Namespace Mode) --- --- @@ -58,19 +58,12 @@ namespace/litmus created ```bash root@demo:~# helm install chaos litmuschaos/litmus-2-0-0-beta --namespace=litmus --devel -NAME: chaos -LAST DEPLOYED: Fri Sep 29 06:19:50 2020 -NAMESPACE: litmus -STATUS: deployed -REVISION: 1 -TEST SUITE: None -``` Expected Output ``` NAME: chaos -LAST DEPLOYED: Mon Mar 15 18:27:42 2021 +LAST DEPLOYED: Tue Jun 15 19:20:09 2021 NAMESPACE: litmus STATUS: deployed REVISION: 1 @@ -87,6 +80,8 @@ Visit https://docs.litmuschaos.io/docs/getstarted/ to find more info. ### **Install Litmus using kubectl ** + --- + #### **Create a Litmus namespace in Kubernetes** ```bash @@ -101,7 +96,7 @@ kubectl apply -f https://litmuschaos.github.io/litmus/2.0.0-Beta/litmus-2.0.0-Be ## **Verify your installation** -**Verify if the frontend, backend, and database Pods are running** +**Verify if the frontend, server, and database pod are running** ```bash kubectl get pods -n litmus diff --git a/website/docs/litmus-installation-namespace.md b/website/docs/litmus-installation-namespace.md new file mode 100644 index 00000000..1552ec62 --- /dev/null +++ b/website/docs/litmus-installation-namespace.md @@ -0,0 +1,242 @@ +--- +id: litmus-install-namespace-mode +title: Litmus Chaos Control Plane (Namespace Mode) +sidebar_label: Control Plane (Namespace Mode) +--- + +--- + + + +## Pre-requisites + +- Kubernetes 1.15 or later. + ​ +- Persistent volume of 20GB + ​ + Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus install would use the default storage class to allocate the PV. Provide this value + +- Helm3 or Kubectl + +## Installation + +Installation of Litmus can be done using either of the below methods +- [Helm3](#helm_install) chart or +- [Kubectl](#kubectl_install) yaml spec file + +### **Install Litmus using Helm ** + +The helm chart will install all the required service account configuration and chaos control plane. + +The following steps will help you install litmus via helm. + +#### Step-1: Add the litmus helm repository + +```bash +root@demo:~# helm repo add litmuschaos https://litmuschaos.github.io/litmus-helm/ +"litmuschaos" has been added to your repositories +``` + +```bash +root@demo:~# helm repo list +NAME URL +litmuschaos https://litmuschaos.github.io/litmus-helm/ +``` + +#### Step-2: Create the litmus namespace + +- The litmus infra components will be placed in this namespace. + +**Note**: The chaos control plane can be placed in any namespace, though it is typically placed in "litmus". + +```bash +root@demo:~# kubectl create ns litmus +namespace/litmus created +``` + +#### Step-3: Install the litmus chaos control plane + +```bash +root@demo:~# helm install chaos litmuschaos/litmus-2-0-0-beta --namespace=litmus --devel --set portalScope=namespace + +Expected Output + +``` +NAME: chaos +LAST DEPLOYED: Tue Jun 15 19:20:09 2021 +NAMESPACE: litmus +STATUS: deployed +REVISION: 1 +TEST SUITE: None +NOTES: +Thank you for installing litmus-2-0-0-beta 😀 + +Your release is named chaos and its installed to namespace: litmus. + +Visit https://docs.litmuschaos.io/docs/getstarted/ to find more info. +``` + +> **Note:** Litmus uses Kubernetes CRDs to define chaos intent. Helm3 handles CRDs better than Helm2. Before you start running a chaos experiment, verify if Litmus is installed correctly. + +- The cluster-admin or an equivalent user with the right permissions are required to install them CRDs upfront. To apply LitmusCRDs: + +```bash +kubectl apply -f https://raw.githubusercontent.com/litmuschaos/litmus/master/litmus-portal/litmus-portal-crds.yml +``` + +Output: + +```bash +customresourcedefinition.apiextensions.k8s.io/clusterworkflowtemplates.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/cronworkflows.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/workflows.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/workflowtemplates.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/chaosengines.litmuschaos.io created +customresourcedefinition.apiextensions.k8s.io/chaosexperiments.litmuschaos.io created +customresourcedefinition.apiextensions.k8s.io/chaosresults.litmuschaos.io created +customresourcedefinition.apiextensions.k8s.io/eventtrackerpolicies.eventtracker.litmuschaos.io created +``` + + --- + +### **Install Litmus using kubectl ** + +#### **Install Litmus** + +- Set the namespace on which you want to install litmus. +```bash +export LITMUS_PORTAL_NAMESPACE="" +kubectl get ns ${LITMUS_PORTAL_NAMESPACE} +# If the namespace is not already present +# then create the target namespace +kubectl create ns ${LITMUS_PORTAL_NAMESPACE} +``` + +- The cluster-admin or an equivalent user with the right permissions are required to install them CRDs upfront. To apply LitmusCRDs: + +```bash +kubectl apply -f https://raw.githubusercontent.com/litmuschaos/litmus/master/litmus-portal/litmus-portal-crds.yml +``` + +Output: + +```bash +customresourcedefinition.apiextensions.k8s.io/clusterworkflowtemplates.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/cronworkflows.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/workflows.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/workflowtemplates.argoproj.io created +customresourcedefinition.apiextensions.k8s.io/chaosengines.litmuschaos.io created +customresourcedefinition.apiextensions.k8s.io/chaosexperiments.litmuschaos.io created +customresourcedefinition.apiextensions.k8s.io/chaosresults.litmuschaos.io created +customresourcedefinition.apiextensions.k8s.io/eventtrackerpolicies.eventtracker.litmuschaos.io created +``` + +- Replace namespace with the target namespace. + +```bash +export LITMUS_PORTAL_NAMESPACE="" +curl +https://raw.githubusercontent.com/litmuschaos/litmus/master/docs/2 +.0.0-Beta/litmus-namespaced-2.0.0-Beta.yaml --output +litmus-portal-namespaced-K8s-template.yml +envsubst < litmus-portal-namespaced-K8s-template.yml > +${LITMUS_PORTAL_NAMESPACE}-ns-scoped-litmus-portal-manifest.yml +kubectl apply -f +${LITMUS_PORTAL_NAMESPACE}-ns-scoped-litmus-portal-manifest.yml -n +${LITMUS_PORTAL_NAMESPACE} +``` + +Output: + +```bash +configmap/litmus-portal-admin-config created +deployment.apps/litmusportal-frontend created +service/litmusportal-frontend-service created +serviceaccount/litmus-server-account created +role.rbac.authorization.k8s.io/litmus-server created +rolebinding.rbac.authorization.k8s.io/litmus-server-rb created +deployment.apps/litmusportal-server created +service/litmusportal-server-service created +statefulset.apps/mongo created +service/mongo-service created +``` + +## **Verify your installation** + +**Verify if the frontend, server, and database pods are running** + +- Check the litmus CRDs: + + ```bash + $ kubectl get crds | grep litmus + chaosengines.litmuschaos.io 2021-03-24T06:52:54Z + chaosexperiments.litmuschaos.io 2021-03-24T06:52:54Z + chaosresults.litmuschaos.io 2021-03-24T06:52:55Z + eventtrackerpolicies.eventtracker.litmuschaos.io 2021-03-24T06:52:55Z + + ``` + +- Check the pods in litmus namespace: + + ```bash + $ kubectl get pods -n litmus + + NAME READY STATUS RESTARTS AGE + litmusportal-frontend-97c8bf86b-mx89w 1/1 Running 2 6m24s + litmusportal-server-5cfbfc88cc-m6c5j 2/2 Running 2 6m19s + mongo-0 1/1 Running 0 6m16s + ``` + +- Check the services running in litmus namespace: + + ```bash + $ kubectl get svc -n litmus + + NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE + litmusportal-frontend-service NodePort 10.100.105.154 9091:30229/TCP 7m14s + litmusportal-server-service NodePort 10.100.150.175 9002:30479/TCP,9003:31949/TCP 7m8s + mongo-service ClusterIP 10.100.226.179 27017/TCP 7m6s + ``` + + +
+ +## **Setup the Portal** + +To setup and login to Litmus Portal expand the available services just created and copy the `PORT` of the `litmusportal-frontend-service` service + +```bash +kubectl get svc -n litmus +``` + +Expected Output + +```bash +NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE +chaos-litmus-portal-mongo ClusterIP 10.104.107.117 27017/TCP 2m +litmusportal-frontend-service NodePort 10.101.81.70 9091:30385/TCP 2m +litmusportal-server-service NodePort 10.108.151.79 9002:32456/TCP,9003:31160/TCP 2m +``` + +> **Note**: In this case, the PORT for `litmusportal-frontend-service` is `30385`. Yours will be different. + +### **Accessing the Portal** + +Once you have the PORT copied in your clipboard, simply use your NodeIP and PORT in this manner `:` to access the portal. + +For example: + +```yaml +http://172.17.0.3:30385/ +``` + +> Where `172.17.0.3` is my NodeIP and `30385` is the frontend service PORT. You can also use a LoadBalancer if not NodePort, the only change would be to provide a `:` + +You should be able to see the Login Page of Litmus. The **default credentials** are + +```yaml +Username: admin +Password: litmus +``` + + diff --git a/website/docs/litmus-uninstallation.md b/website/docs/litmus-uninstallation.md index 13a0286a..4684a436 100644 --- a/website/docs/litmus-uninstallation.md +++ b/website/docs/litmus-uninstallation.md @@ -6,10 +6,20 @@ sidebar_label: Control Plane --- -### **Uninstallation of Litmus Control Plane** +### **Uninstallation of Litmus Control Plane uning Helm** The helm chart uninstall installs the control plane components ```bash helm uninstall litmuschaos --namespace litmus +kubectl delete ns litmus ``` + +### **Uninstallation of Litmus Control Plane using kubectl** + +The helm chart uninstall installs the control plane components + +```bash +kubectl delete ns litmus +``` + \ No newline at end of file diff --git a/website/docs/namespaced-mode.md b/website/docs/namespaced-mode.md deleted file mode 100644 index 55f7f72d..00000000 --- a/website/docs/namespaced-mode.md +++ /dev/null @@ -1,219 +0,0 @@ ---- -id: namespaced-mode -title: Namespaced Mode -sidebar_label: Namespaced Mode -original_id: namespaced-mode ---- - ---- - -### What is Namespaced Mode? - -Namespaced mode is the other end of the orchestration spectrum & is an antithesis of the admin-mode of operation. Here, the ChaosOperator as well as the chaos resources (chaosexperiment, chaosengine, chaosresult CRs, the experiment pods and chaos workflows) are run in the same namespace where the application under test (AUT) resides. This mode serves the use-cases where the developers/users don't typically have much autonomy over cluster usage and operate strictly within a specific allotted namespace. However, in this case, too, the cluster-admin or an equivalent user with the right permissions are required to install them CRDs upfront. - -Note that this mode of operation restricts the scope of chaos experiments to those at the pod-level, as the node/infra level experiments need cluster-wide access. - -### How to use Namespaced Mode? - -In order to use Namespaced Mode, you just have to install the namespace-scoped litmus operator manifest in the desired (app) namespace. This installs the ChaosOperator, configured to watch for ChaosEngine resources in the same namespace while also setting up the RBAC that can be used for the execution of the standard (generic suite) of chaos experiments. - -### Supported Experiments in Namespaced Mode - -- [Pod Delete](https://docs.litmuschaos.io/docs/pod-delete/) -- [Container Kill](https://docs.litmuschaos.io/docs/container-kill/) -- [Pod Network Loss](https://docs.litmuschaos.io/docs/pod-network-loss/) -- [Pod Network Latency](https://docs.litmuschaos.io/docs/pod-network-latency/) -- [Pod Network Duplication](https://docs.litmuschaos.io/docs/pod-network-duplication/) -- [Pod Network Corruption](https://docs.litmuschaos.io/docs/pod-network-corruption/) -- [Pod CPU Hog](https://docs.litmuschaos.io/docs/pod-cpu-hog/) -- [Pod Memory Hog](https://docs.litmuschaos.io/docs/pod-memory-hog/) -- [Disk Fill](https://docs.litmuschaos.io/docs/disk-fill/) -- [Pod Autoscaler](https://docs.litmuschaos.io/docs/pod-autoscaler/) - -### Role Based Access Control (RBAC) Permission in Namespaced Mode - -In Namespace mode the RBAC for different [litmus components](https://github.com/litmuschaos/litmus/tree/master/litmus-portal/graphql-server/manifests/namespace) are as follows, - -- [Argo](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/namespace/1a_argo_rbac.yaml) -- [Litmus Cluster Scope](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/namespace/2a_litmus_rbac.yaml) -- [Litmus Admin](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/namespace/3a_agents_rbac.yaml)(for running experiments) -- [Subscriber](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/namespace/3a_agents_rbac.yaml) -- [Litmus Event Tracker](https://github.com/litmuschaos/litmus/blob/master/litmus-portal/graphql-server/manifests/namespace/3a_agents_rbac.yaml) - -### Install Litmus Portal in Namespaced Mode - -To install Litmus portal on namespaced mode we need to run the following steps: - -#### Checkout the namespace - -Check the namespace on which you want to install litmus. - -```bash -export LITMUS_PORTAL_NAMESPACE="" -kubectl get ns ${LITMUS_PORTAL_NAMESPACE} -# If the namespace is not already present -# then create the target namespace -kubectl create ns ${LITMUS_PORTAL_NAMESPACE} -``` - -Output: - -```bash -namespace/litmus created -``` - -#### Install Litmus CRDs - -The cluster-admin or an equivalent user with the right permissions are required to install them CRDs upfront. - -```bash -kubectl apply -f https://raw.githubusercontent.com/litmuschaos/litmus/master/litmus-portal/litmus-portal-crds.yml -``` - -Output: - -```bash -customresourcedefinition.apiextensions.k8s.io/clusterworkflowtemplates.argoproj.io created -customresourcedefinition.apiextensions.k8s.io/cronworkflows.argoproj.io created -customresourcedefinition.apiextensions.k8s.io/workflows.argoproj.io created -customresourcedefinition.apiextensions.k8s.io/workflowtemplates.argoproj.io created -customresourcedefinition.apiextensions.k8s.io/chaosengines.litmuschaos.io created -customresourcedefinition.apiextensions.k8s.io/chaosexperiments.litmuschaos.io created -customresourcedefinition.apiextensions.k8s.io/chaosresults.litmuschaos.io created -``` - -#### Install Litmus Portal namespaced mode - -Replace namespace with the target namespace (here litmus). - -```bash -export LITMUS_PORTAL_NAMESPACE="" -curl -https://raw.githubusercontent.com/litmuschaos/litmus/master/docs/2 -.0.0-Beta/litmus-namespaced-2.0.0-Beta.yaml --output -litmus-portal-namespaced-K8s-template.yml -envsubst < litmus-portal-namespaced-K8s-template.yml > -${LITMUS_PORTAL_NAMESPACE}-ns-scoped-litmus-portal-manifest.yml -kubectl apply -f -${LITMUS_PORTAL_NAMESPACE}-ns-scoped-litmus-portal-manifest.yml -n -${LITMUS_PORTAL_NAMESPACE} -``` - -Output: - -```bash -configmap/litmus-portal-admin-config created -deployment.apps/litmusportal-frontend created -service/litmusportal-frontend-service created -serviceaccount/litmus-server-account created -role.rbac.authorization.k8s.io/litmus-server created -rolebinding.rbac.authorization.k8s.io/litmus-server-rb created -deployment.apps/litmusportal-server created -service/litmusportal-server-service created -statefulset.apps/mongo created -service/mongo-service created -``` - -#### Deploy sample Application Hello World under Chaos (Optional) - -We can now deploy a sample hello world application under chaos (AUT) in the target namespace. - -```bash -kubectl apply -f https://raw.githubusercontent.com/litmuschaos/litmus/master/litmus-portal/platforms/okteto/hello-world-AUT.yml -n ${LITMUS_PORTAL_NAMESPACE} -``` - -Output: - -```bash -deployment.apps/hello-world created -service/hello-world created -``` - -#### Verify the installation - -- Check the litmus CRDs: - - ```bash - $ kubectl get crds | grep litmus - - chaosengines.litmuschaos.io 2021-03-24T06:52:54Z - chaosexperiments.litmuschaos.io 2021-03-24T06:52:54Z - chaosresults.litmuschaos.io 2021-03-24T06:52:55Z - ``` - -- Check the pods in litmus namespace: - - ```bash - $ kubectl get pods -n litmus - - NAME READY STATUS RESTARTS AGE - hello-world-867646c44b-f985x 1/1 Running 0 6m11s - hello-world-867646c44b-kqkbz 1/1 Running 0 6m11s - litmusportal-frontend-97c8bf86b-mx89w 1/1 Running 2 6m24s - litmusportal-server-5cfbfc88cc-m6c5j 2/2 Running 2 6m19s - mongo-0 1/1 Running 0 6m16s - ``` - -- Check the services running in litmus namespace: - - ```bash - $ kubectl get svc -n litmus - - NAME TYPE CLUSTER-IP EXTERNAL-IP PORT(S) AGE - hello-world ClusterIP 10.100.46.148 8080/TCP 7m1s - litmusportal-frontend-service NodePort 10.100.105.154 9091:30229/TCP 7m14s - litmusportal-server-service NodePort 10.100.150.175 9002:30479/TCP,9003:31949/TCP 7m8s - mongo-service ClusterIP 10.100.226.179 27017/TCP 7m6s - ``` - -#### Access the Litmus portal frontend service. - -To access the frontend we need to access the `litmusportal-frontend-service` mentioned above. We can either access the frontend using `NodePort` service (by Default) or change the service to `LoadBalancer` and use it. We access the frontend using `NodePort` service (Node IP and port from frontend service) - -Now, for creating a project, we need to login using Default username and password which is: - -- username: admin -- password: litmus - -After logging in, the next page will ask you to create a project. You can give a name of your project and click on Continue. In the next step you will be asked to change the password. You can keep the same password for the sake of simplicity, i.e litmus. - -With this, you’re done with the initial setup and you’ll arrive at the Welcome page. -Here, you can check the Targets option from the side bar if it changes to Active state from Pending state or not. - -Now, you can again go back to the cluster and check the pods in the target namespace (here litmus). - -```bash -$ kubectl get pods -n litmus - -NAME READY STATUS RESTARTS AGE -argo-server-8497bdfd84-kk2vw 1/1 Running 0 3m28s -chaos-exporter-5fbd968db-z4n4f 1/1 Running 0 3m36s -chaos-operator-ce-c749c49cd-w8t4k 1/1 Running 0 3m36s -event-tracker-647db5959d-gshql 1/1 Running 0 3m29s -hello-world-867646c44b-f985x 1/1 Running 0 75m -hello-world-867646c44b-kqkbz 1/1 Running 0 75m -litmusportal-frontend-97c8bf86b-mx89w 1/1 Running 2 75m -litmusportal-server-5cfbfc88cc-m6c5j 2/2 Running 2 75m -mongo-0 1/1 Running 0 75m -subscriber-676fd59f59-xcvc2 1/1 Running 0 3m30s -workflow-controller-7dbc97dc75-7c6b9 1/1 Running 0 3m27s -``` - -You’ll find that some new deployment is shown which includes litmus infra components like ChaosOperator and monitoring component ChaosExporter to generate chaos metrics. Also, some new service accounts have been created to run chaos. - -```bash -$ kubectl get sa -n litmus - -NAME SECRETS AGE -argo 1 6m19s -argo-chaos 1 6m24s -argo-server 1 6m18s -default 1 78m -litmus 1 6m29s -litmus-admin 1 6m25s -litmus-event-tracker-sa 1 6m22s -litmus-namespace-scope 1 6m27s -litmus-server-account 1 78m -``` - -With this, we are done setting up litmus in namespaced mode! diff --git a/website/sidebars.js b/website/sidebars.js index 434c87d0..959c92f8 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -8,7 +8,7 @@ module.exports = { "Getting Started": [ "getstarted", { - "Installation" : [ "litmus-install", "agent-install", "litmus-with-ingress"], + "Installation" : [ "litmus-install-cluster-mode", "litmus-install-namespace-mode", "agent-install", "litmus-with-ingress"], }, "create-workflow", "observe-workflow", @@ -44,6 +44,6 @@ module.exports = { // "rbac", // "service-acounts", // ], - Advanced: ["admin-mode", "namespaced-mode", "litmus-psp"], + Advanced: ["litmus-psp"], }, }; From a844e7374997467aa53013a603547ea6a69de957 Mon Sep 17 00:00:00 2001 From: Raj Das Date: Tue, 15 Jun 2021 22:51:17 +0530 Subject: [PATCH 2/6] sidebar fix Signed-off-by: Raj Das --- website/docs/agent-installation.md | 4 ++-- website/docs/litmus-installation-cluster.md | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/website/docs/agent-installation.md b/website/docs/agent-installation.md index 42276774..1da18260 100644 --- a/website/docs/agent-installation.md +++ b/website/docs/agent-installation.md @@ -101,7 +101,7 @@ $ litmusctl agent connect Next, you need to enter LitmusPortal details to login into your LitmusPortal account. Fields to be filled in: -**LimtusPortal UI URL:** Enter the URL used to access the Litmus Portal UI. +**LitmusPortal UI URL:** Enter the URL used to access the Litmus Portal UI. Example, http://172.17.0.2:31696/ **Username:** Enter your LitmusPortal username. @@ -151,7 +151,7 @@ Fields to filled in: **Platform Name:** Enter the platform name on which this agent is hosted. For example, AWS, GCP, Rancher etc. -**Enter the namespace:** You can either enter an existing namespace or enter a new namespace. In cases where the namespace does not exist, LimtusPortal creates it for you. +**Enter the namespace:** You can either enter an existing namespace or enter a new namespace. In cases where the namespace does not exist, LitmusPortal creates it for you. **Enter service account:** Enter a name for your service account. diff --git a/website/docs/litmus-installation-cluster.md b/website/docs/litmus-installation-cluster.md index e43c4ced..0d9cd7a2 100644 --- a/website/docs/litmus-installation-cluster.md +++ b/website/docs/litmus-installation-cluster.md @@ -1,5 +1,5 @@ --- -id: litmus-install +id: litmus-install-cluster-mode title: Litmus Chaos Control Plane (Cluster Mode) sidebar_label: Control Plane (Namespace Mode) --- From 2a8bd3341f83b7dbac43f376b1fe53cf6654d6ee Mon Sep 17 00:00:00 2001 From: Raj Das Date: Tue, 15 Jun 2021 22:52:28 +0530 Subject: [PATCH 3/6] embedmd fix Signed-off-by: Raj Das --- website/docs/agent-installation.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/website/docs/agent-installation.md b/website/docs/agent-installation.md index 1da18260..1ec815ca 100644 --- a/website/docs/agent-installation.md +++ b/website/docs/agent-installation.md @@ -193,4 +193,4 @@ Installation Mode: cluster 👉 Litmus agents can be accessed here: http://172.17.0.2:31696/targets ``` -To verify, if the connection process was successful you can view the list of connected agents from the Targets section on your LitmusPortal and ensure that the connected agent is in Active State. \ No newline at end of file +To verify, if the connection process was successful you can view the list of connected agents from the Targets section on your LitmusPortal and ensure that the connected agent is in Active State. From a35a9a13a16ce4fb2a575b4dc7a6ab5669dbc789 Mon Sep 17 00:00:00 2001 From: Jonsy13 Date: Tue, 15 Jun 2021 23:14:46 +0530 Subject: [PATCH 4/6] Added Minor changes. Signed-off-by: Jonsy13 --- website/docs/agent-installation.md | 4 +-- website/docs/litmus-installation-cluster.md | 23 ++++++++------- website/docs/litmus-installation-namespace.md | 28 ++++++++----------- 3 files changed, 24 insertions(+), 31 deletions(-) diff --git a/website/docs/agent-installation.md b/website/docs/agent-installation.md index 1ec815ca..d1f8b0ae 100644 --- a/website/docs/agent-installation.md +++ b/website/docs/agent-installation.md @@ -41,7 +41,7 @@ To install the latest version of litmusctl follow the below steps: | litmusctl-windows-amd64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-amd64-master.tar.gz) | | litmusctl-windows-arm | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-arm-master.tar.gz) | -
+
- Download the litmusctl(v0.2.0) binary from: @@ -57,7 +57,7 @@ To install the latest version of litmusctl follow the below steps: | litmusctl-windows-amd64 | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-amd64-v0.2.0.tar.gz) | | litmusctl-windows-arm | [Click here](https://litmusctl-bucket.s3-eu-west-1.amazonaws.com/litmusctl-windows-arm-v0.2.0.tar.gz) | -
+
- Extract the binary diff --git a/website/docs/litmus-installation-cluster.md b/website/docs/litmus-installation-cluster.md index 0d9cd7a2..9a87d653 100644 --- a/website/docs/litmus-installation-cluster.md +++ b/website/docs/litmus-installation-cluster.md @@ -1,7 +1,7 @@ --- id: litmus-install-cluster-mode title: Litmus Chaos Control Plane (Cluster Mode) -sidebar_label: Control Plane (Namespace Mode) +sidebar_label: Control Plane (Cluster Mode) --- --- @@ -12,17 +12,16 @@ sidebar_label: Control Plane (Namespace Mode) - Kubernetes 1.15 or later. ​ -- Persistent volume of 20GB - ​ - Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus install would use the default storage class to allocate the PV. Provide this value +- Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus would use the default storage class to allocate the PV. - Helm3 or Kubectl -## Installation +## Installation Installation of Litmus can be done using either of the below methods -- [Helm3](#helm_install) chart or -- [Kubectl](#kubectl_install) yaml spec file + +- [Helm3](#helm_install) chart or +- [Kubectl](#kubectl_install) yaml spec file ### Installation Steps @@ -58,6 +57,7 @@ namespace/litmus created ```bash root@demo:~# helm install chaos litmuschaos/litmus-2-0-0-beta --namespace=litmus --devel +``` Expected Output @@ -74,22 +74,23 @@ Thank you for installing litmus-2-0-0-beta 😀 Your release is named chaos and its installed to namespace: litmus. Visit https://docs.litmuschaos.io/docs/getstarted/ to find more info. + ``` > **Note:** Litmus uses Kubernetes CRDs to define chaos intent. Helm3 handles CRDs better than Helm2. Before you start running a chaos experiment, verify if Litmus is installed correctly. ### **Install Litmus using kubectl ** - --- - -#### **Create a Litmus namespace in Kubernetes** +#### **Create a Litmus namespace in Kubernetes** ```bash kubectl create ns litmus ``` + #### **Install Litmus** Applying the manifest file will install all the required service account configuration and chaos control plane. + ```bash kubectl apply -f https://litmuschaos.github.io/litmus/2.0.0-Beta/litmus-2.0.0-Beta.yaml ``` @@ -110,8 +111,6 @@ chaos-litmus-portal-mongo-6764cfdd59-c9r56 1/1 Running 0 2m6s chaos-litmus-portal-server-5ffbccbfff-dknv8 2/2 Running 0 2m6s ``` -
- ## **Setup the Portal** To setup and login to Litmus Portal expand the available services just created and copy the `PORT` of the `litmusportal-frontend-service` service diff --git a/website/docs/litmus-installation-namespace.md b/website/docs/litmus-installation-namespace.md index 1552ec62..08383533 100644 --- a/website/docs/litmus-installation-namespace.md +++ b/website/docs/litmus-installation-namespace.md @@ -12,17 +12,16 @@ sidebar_label: Control Plane (Namespace Mode) - Kubernetes 1.15 or later. ​ -- Persistent volume of 20GB - ​ - Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus install would use the default storage class to allocate the PV. Provide this value +- Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus would use the default storage class to allocate the PV. - Helm3 or Kubectl -## Installation +## Installation Installation of Litmus can be done using either of the below methods -- [Helm3](#helm_install) chart or -- [Kubectl](#kubectl_install) yaml spec file + +- [Helm3](#helm_install) chart or +- [Kubectl](#kubectl_install) yaml spec file ### **Install Litmus using Helm ** @@ -58,10 +57,11 @@ namespace/litmus created ```bash root@demo:~# helm install chaos litmuschaos/litmus-2-0-0-beta --namespace=litmus --devel --set portalScope=namespace +``` Expected Output -``` +```bash NAME: chaos LAST DEPLOYED: Tue Jun 15 19:20:09 2021 NAMESPACE: litmus @@ -74,6 +74,7 @@ Thank you for installing litmus-2-0-0-beta 😀 Your release is named chaos and its installed to namespace: litmus. Visit https://docs.litmuschaos.io/docs/getstarted/ to find more info. + ``` > **Note:** Litmus uses Kubernetes CRDs to define chaos intent. Helm3 handles CRDs better than Helm2. Before you start running a chaos experiment, verify if Litmus is installed correctly. @@ -97,13 +98,12 @@ customresourcedefinition.apiextensions.k8s.io/chaosresults.litmuschaos.io create customresourcedefinition.apiextensions.k8s.io/eventtrackerpolicies.eventtracker.litmuschaos.io created ``` - --- - ### **Install Litmus using kubectl ** #### **Install Litmus** - Set the namespace on which you want to install litmus. + ```bash export LITMUS_PORTAL_NAMESPACE="" kubectl get ns ${LITMUS_PORTAL_NAMESPACE} @@ -135,15 +135,10 @@ customresourcedefinition.apiextensions.k8s.io/eventtrackerpolicies.eventtracker. ```bash export LITMUS_PORTAL_NAMESPACE="" -curl -https://raw.githubusercontent.com/litmuschaos/litmus/master/docs/2 -.0.0-Beta/litmus-namespaced-2.0.0-Beta.yaml --output -litmus-portal-namespaced-K8s-template.yml +curl https://raw.githubusercontent.com/litmuschaos/litmus/master/docs/2.0.0-Beta/litmus-namespaced-2.0.0-Beta.yaml --output litmus-portal-namespaced-K8s-template.yml envsubst < litmus-portal-namespaced-K8s-template.yml > ${LITMUS_PORTAL_NAMESPACE}-ns-scoped-litmus-portal-manifest.yml -kubectl apply -f -${LITMUS_PORTAL_NAMESPACE}-ns-scoped-litmus-portal-manifest.yml -n -${LITMUS_PORTAL_NAMESPACE} +kubectl apply -f ${LITMUS_PORTAL_NAMESPACE}-ns-scoped-litmus-portal-manifest.yml -n ${LITMUS_PORTAL_NAMESPACE} ``` Output: @@ -198,7 +193,6 @@ service/mongo-service created mongo-service ClusterIP 10.100.226.179 27017/TCP 7m6s ``` -
## **Setup the Portal** From f1f3d6c292fee0db848ae378fc2b128e58c1b239 Mon Sep 17 00:00:00 2001 From: Jonsy13 Date: Tue, 15 Jun 2021 23:17:12 +0530 Subject: [PATCH 5/6] Fixed the spellcheck issues. Signed-off-by: Jonsy13 --- .wordlist.txt | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/.wordlist.txt b/.wordlist.txt index e549e442..bff8d063 100644 --- a/.wordlist.txt +++ b/.wordlist.txt @@ -1,4 +1,8 @@ mongodb +eventtracker +eventtrackerpolicies +portalScope +LitmusCRDs graphql accomodate accomodated From 3c8c0958d99bfe45f9b9b789f5d221d880e18611 Mon Sep 17 00:00:00 2001 From: Jonsy13 Date: Tue, 15 Jun 2021 23:23:24 +0530 Subject: [PATCH 6/6] Fixed the CI id issue. Signed-off-by: Jonsy13 --- website/docs/getstarted.md | 5 ++--- website/docs/litmus-uninstallation.md | 2 +- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/website/docs/getstarted.md b/website/docs/getstarted.md index 37b1627e..68e21b4a 100644 --- a/website/docs/getstarted.md +++ b/website/docs/getstarted.md @@ -12,16 +12,15 @@ sidebar_label: Pre-requisites - Persistent volume of 20GB - Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus install would use the default storage class to allocate the PV. Provide this value + Recommend to have a Persistent volume(PV) of 20GB, You can start with 1GB for test purposes as well. This PV is used as persistent storage to store the chaos config and chaos-metrics in the Portal. By default, litmus install would use the default storage class to allocate the PV. Provide this value - Helm3 or Kubectl - ## Getting Started Running chaos on your application involves the following steps: -[Install Litmus](litmus-install) +[Install Litmus](litmus-install-cluster-mode) [How to Create and Run a Workflow](create-workflow) diff --git a/website/docs/litmus-uninstallation.md b/website/docs/litmus-uninstallation.md index 7d690d20..2f959f2d 100644 --- a/website/docs/litmus-uninstallation.md +++ b/website/docs/litmus-uninstallation.md @@ -22,4 +22,4 @@ kubectl delete ns litmus ```bash kubectl delete ns litmus ``` - \ No newline at end of file +