Chaos Scenarios cannot only be scheduled on your default cluster, Litmus allows you to schedule chaos scenario on a remote cluster.

In this tutorial, you will learn how to create Chaos Scenarios on a remote cluster.

First, you will learn to deploy a remote cluster on GKE(Google Kubernetes Engine), then you will install a CLI tool called litmusctl. Next, you will use litmusctl to register this cluster as a target chaos delegate in ChaosCenter. Finally, you will schedule a predefined chaos scenario on this remote cluster.

What you will learn


Google Kubernetes Engine(GKE) is a managed production-ready environment for running containerized applications.

In this section, we will deploy a Kubernetes cluster on GKE. After that, you will install Litmus on this cluster and expose it to the public using an external IP.

Enable the Kubernetes Engine API

Once you have a GCP account setup, head on to to enable the Kubernetes Engine API.

If you haven't already, you will be prompted to enable billing to proceed.

Once the Kubernetes Engine API is enabled, you can create a cluster on GKE.

Create the cluster

Click the Create button at the top navigation bar.

Next, choose the Standard Cluster by clicking the Configure button next to that option.

Here, you will see all the options you need to configure your Kubernetes cluster. You can choose to configure your cluster if you're familiar with it or select the My first cluster option by the rightmost navigation.

The cluster might take a while to create as it is trying to create the necessary resources for your cluster while undergoing a health check.

Now that your cluster has been created, you can proceed to install litmus.

First, you need to connect to your cluster and access its shell. Click on the name of the cluster to proceed.

Click on the connect shell button at the top, then click on the RUN IN CLOUD SHELL button.

This will open a cloud shell terminal in your console and, a cloud SDK command will run in your terminal. This command will configure the Kubectl to configure itself for the cluster you just created. If prompted to Authorize, you should accept.

Install Litmus

Here, we will be following the steps given in this tutorial. Specifically, we would be installing Litmus using kubectl.

Create a namespace

kubectl create ns litmus

Install Litmus

kubectl apply -f

Check if the Litmus control plane components comprising the Web-UI (frontend), GraphQL server & MongoDB pods are created and running successfully.

Verify Installation

kubectl get pods -n litmus
NAME                                        READY   STATUS    RESTARTS   AGE
litmusportal-auth-server-7594bf7c46-td8jv   1/1     Running   0          47m
litmusportal-frontend-5fb5bb84f7-tcf95      1/1     Running   0          47m
litmusportal-server-858584d5b9-r8kkn        1/1     Running   0          47m
mongo-0                                     1/1     Running   0          47m

It might take a few minutes for all the pods to have a running state. Give it some time.

Access the ChaosCenter

To access the litmus frontend, we need to know what service exposes this frontend. To get a list of running services in the litmus namespace, run the below command.

kubectl get svc -n litmus
NAME                               TYPE           CLUSTER-IP     EXTERNAL-IP      PORT(S)                         AGE
litmusportal-auth-server-service   NodePort   <none>           9003:31241/TCP,3030:31248/TCP   49m
litmusportal-frontend-service      LoadBalancer   9091:32733/TCP                  49m
litmusportal-server-service        NodePort    <none>           9002:30707/TCP,8000:30327/TCP   49m
mongo-headless-service             ClusterIP      None           <none>           27017/TCP                       49m
mongo-service                      ClusterIP    <none>           27017/TCP                       49m

From the above, we can see that the frontend is exposed via a NodePort service and it has the name of litmusportal-frontend-service. It exposes this service on a TCP port that looks something like 9091:xxxxx/TCP where xxxxx is the corresponding node port of the service.

To access the ChaosCenter, we need to expose this port by using a firewall rule. We can do this by running this command:

Expose the node port

gcloud compute firewall-rules create frontend-service-rule --allow tcp:<NODE_PORT>

Replace the NODE_PORT in the command above with your service's node port. You should expose the firewall for both the litmusportal-frontend-service and the litmusportal-server-service.

You can now access the ChaosCenter, but first, you need to get the external IPs of your node.

Get node external IPs

kubectl get nodes -o wide
gke-litmus-cluster-default-pool-12e7a198-19wl   Ready    <none>   8h    v1.19.9-gke.1900     Container-Optimized OS from Google   5.4.89+          containerd://1.4.3
gke-litmus-cluster-default-pool-12e7a198-b53p   Ready    <none>   8h    v1.19.9-gke.1900   Container-Optimized OS from Google   5.4.89+          containerd://1.4.3
gke-litmus-cluster-default-pool-12e7a198-s13l   Ready    <none>   8h    v1.19.9-gke.1900   Container-Optimized OS from Google   5.4.89+          containerd://1.4.3

Copy the external IP of any of the above nodes and paste it into your browser's URL, followed by a :xxxxx where xxxxx corresponds to your node port. You will be presented with a screen showing the ChaosCenter's homepage.

What is litmusctl?

Litmusctl is a LitmusChaos command-line tool that allows you to manage litmuschaos's chaos delegate plane. Litmusctl can be used to create chaos delegates, project, and manage multiple litmuschaos accounts.

Litmusctl has the following requirements:

Note that the above are corresponding to the target cluster and not the GKE cluster where the control plane is situated.

Download the litmusctl binary corresponding to your OS from the table below:

Platforms 0.12.0 v0.11.0 v0.10.0 v0.9.0 v0.8.0 v0.7.0 master(Unreleased)
litmusctl-darwin-amd64 (MacOS) Click here Click here Click here Click here Click here Click here Click here
litmusctl-linux-386 Click here Click here Click here Click here Click here Click here Click here
litmusctl-linux-amd64 Click here Click here Click here Click here Click here Click here Click here
litmusctl-linux-arm Click here Click here Click here Click here Click here Click here Click here
litmusctl-linux-arm64 Click here Click here Click here Click here Click here Click here Click here
litmusctl-windows-386 Click here Click here Click here Click here Click here Click here Click here
litmusctl-windows-amd64 Click here Click here Click here Click here Click here Click here Click here
litmusctl-windows-arm Click here Click here Click here Click here Click here Click here Click here


Extract the binary

tar -zxvf litmusctl-<OS>-<ARCH>-<VERSION>.tar.gz

Provide necessary permissions

chmod +x litmusctl

Move the litmus binary to /usr/local/bin/litmusctl.

Note: Do this using root privileges

sudo mv litmusctl /usr/local/bin/litmusctl


Extract the binary

litmusctl.exe <command> <subcommand> <subcommand> [options and parameters]

Check the litmusctl version

litmusctl version

The external chaos delegate can be setup using either the interactive mode or the non-interactive mode. Here, we will be using the non-interactive mode of setup.

We can now use Litmusctl to create an external chaos delegate on the remote cluster. Open your terminal on your local Machine and run the following command. Give the ChaosCenter URL (including the port, if present) for endpoint, and your account username and password accordingly.

litmusctl config set-account --endpoint="" --username="" --password=""

Then, we can create an chaos delegate in a cluster mode.

Note: To get project-id, you can refer to your project in the ChaosCenter navbar and obtain its ID or use "litmusctl get projects" command.

litmusctl connect chaos-delegate --name="" --project-id="" --non-interactive

  🏃 Running prerequisites check....
  🔑 clusterrole ✅
  🔑 clusterrolebinding ✅
  🌟 Sufficient permissions. Installing the Chaos Delegate...
  📌 Summary 
  Agent Name: chaos-delegate-01
  Agent Description: ---
  Agent SSL/TLS Skip: false
  Platform Name: Others
  Namespace:  litmus (new)
  Service Account:  litmus (new)
  Installation Mode: cluster
  Applying YAML:
  namespace/litmus created
  serviceaccount/litmus created
  serviceaccount/litmus-admin created unchanged unchanged
  serviceaccount/argo-chaos created unchanged unchanged unchanged unchanged
  serviceaccount/event-tracker-sa created unchanged unchanged
  deployment.apps/chaos-operator-ce created
  deployment.apps/chaos-exporter created
  service/chaos-exporter created
  configmap/chaos delegate-config created
  secret/chaos delegate-secret created
  deployment.apps/subscriber created
  deployment.apps/event-tracker created
  service/chaos scenario-controller-metrics created
  deployment.apps/chaos scenario-controller created
  serviceaccount/litmus-cluster-scope created unchanged unchanged unchanged unchanged unchanged unchanged unchanged
  serviceaccount/argo created unchanged unchanged
  configmap/chaos scenario-controller-configmap created configured configured unchanged configured
  💡 Connecting chaos delegate to Litmus Portal.
  🏃 Agents are running!!
  🚀 Chaos Delegate Connection Successful!! 🎉
  👉 Litmus chaos delegates can be accessed here:

Navigate to the IP address printed in your terminal at the end, it should take you to the Chaos Delegates tab on your remote ChaosCenter. You should observe that your new Chaos Delegate has been added to your list of Chaos Delegates.

You can now proceed to schedule a scenario using the newly created Delegate on the remote cluster. Navigate to the scenarios tab on the sidebar, then click the Schedule a scenario button.

Select a target Delegate

You need to select a Target Delegate to proceed, you will see two options.

Select the latter, then click on the Next button.

Note: You may have to wait for the delegate to be up and ready, after which you can move forward by again clicking on "Next"

Select a scenario

Here, you will see four different options from which you can create a scenario. For this tutorial, you should select the first option which creates a scenario from a predefined chaos scenario template. Then select the podtato-head experiment, this experiment injects a pod-delete fault into a sample microservice application. Click the Next button when done.

Describe the scenario

Here, you can give this scenario a name and a description or leave the default ones. Click next when done.

Tune the scenario

This section consists of all the information related to the chaos scenario. It contains a pictorial visualization of the scenario and an option to edit the scenario yaml file.

Reliability Score

You can assign weights to the experiments present in the scenario. These weights will be then used for the calculation of the resilience score after the scenario completion. By default, 10 points are assigned to each experiment. This can be altered as per your use-case. After selecting weights click on the Next Button.


scenarios can be scheduled in two ways;

Select the Schedule now option and click next.

Verify and commit

Here, you can validate all the changes related to the chaos scenario like the chaos scenario name, the experiment weights, chaos scenario description, chaos scenario manifest, etc. Once you have verified all the changes, you can click the Finish button to start the schedule.

Click the Go to chaos scenario button to see the chaos scenario in action.

In this tutorial, you were introduced to how to create a remote cluster on Google Kubernetes Engine and deploy ChaosCenter on it. Them, you learned what litmusctl is and how to use it to create a new chaos delegate on a remote cluster. Lastly, you learned how you can schedule your own chaos on this remote cluster using the chaos delegate you created.

Please visit us in our LitmusSlack Channel (in Kubernetes workspace) and tell us how you like LitmusChaos and this tutorial! We are happy to hear your thoughts & suggestions!

Also, make sure to follow us on Twitter to get the latest news on LitmusChaos, our tutorials, and the newest releases!