From d228aef5d0c39a14980f98d943faf4014a7d48ce Mon Sep 17 00:00:00 2001 From: Pablo Chacin Date: Thu, 22 Jun 2023 20:31:29 +0200 Subject: [PATCH 01/11] Update xk6-disruptor welcome page Signed-off-by: Pablo Chacin --- .eslintignore | 1 + .../01 Get started/01 Welcome.md | 87 ++++++++++++++----- 2 files changed, 67 insertions(+), 21 deletions(-) diff --git a/.eslintignore b/.eslintignore index 5761dcfbf..934ba2711 100644 --- a/.eslintignore +++ b/.eslintignore @@ -4,6 +4,7 @@ node_modules/ docs/sources/get-started/run-cloud-tests-from-the-CLI.md docs/sources/get-started/run-your-first-tests.md CONTRIBUTING_FILE_FORMAT.md +src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md src/data/markdown/docs/40 xk6-disruptor/04 Examples/01 Inject Grpc faults into Service.md src/data/markdown/docs/40 xk6-disruptor/04 Examples/02 Inject HTTP faults into Pod.md src/data/markdown/docs/05 Examples/02 Tutorials/01 Get started with k6/100 Test-for-functional-behavior.md diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 3ed229397..ef1a477bb 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -5,46 +5,91 @@ head_title: 'xk6-disruptor Documentation' excerpt: 'xk6-disruptor is a k6 extension providing fault injection capabilities to test system reliability under turbulent conditions.' --- -xk6-disruptor is a k6 extension that can inject faults into a system to simulate turbulent conditions. +xk6-disruptor is an extension adds fault injection capabilities to [Grafana k6](https://github.com/grafana/k6). It implements the principles of Chaos Engineering discipline and enables Grafana k6 users to test their system's reliability under turbulent conditions. -xk6-disruptor intends to help testers approach the discipline of "Chaos Engineering" with k6 way—providing the best developer experience as a primary objective. +## Why xk6-disruptor? -The extension offers an [API](/javascript-api/xk6-disruptor/api/) to create disruptors that target one specific type of component (for example, Pods). -These disruptors can inject different types of [faults](/javascript-api/xk6-disruptor/api/faults), such as errors in HTTP requests, served by that component. -Currently, disruptors exist for [Pods](/javascript-api/xk6-disruptor/api/poddisruptor) and [Services](/javascript-api/xk6-disruptor/api/servicedisruptor), but others will be introduced in the future, along with other types of faults for existing disruptors. +xk6-disruptor is designed and built to provide the best experience for developers trying to make their systems more reliable: -
+- Everything as code. + - No need to learn a new DSL. + - Developers can use their usual development IDE + - Facilitate test reuse and sharing -xk6-disruptor is intended for systems running in Kubernetes. Other platforms are not supported at this time. +- Fast to adopt with no day-two surprises. No need to deploy and maintain a fleet of agents or operators. -
+- Easy to extend and integrate with other [types of tests](https://k6.io/docs/test-types/introduction/). No need to try to glue multiple tools together to get the job done. -## Use case for xk6-disruptor +Also, this project has been built to be a good citizen in the Grafana k6 ecosystem by: -The main use case for xk6-disruptor is to test how resilient an application is to diverse types of disruptions. xk6-disruptor can reproduce the effects of these disruptions, without having to reproduce their root causes. -For example, you can inject delays in the HTTP requests that an application makes to a service without having to stress or interfere with the infrastructure (network, nodes) on which the service runs. +- Working well with other extensions. +- Working well with k6's core concepts and features. -In this way, xk6-disruptor makes reliability tests repeatable, predictable, and with a limited blast radius. -These characteristics make it easier to incorporate such tests into the test suites of applications that deploy on shared infrastructures (such as staging environments). +You can check this out in the following example: +```js +export default function () { + // Create a new pod disruptor with a selector + // that matches pods from the "default" namespace with the label "app=my-app" + const disruptor = new PodDisruptor({ + namespace: "default", + select: { labels: { app: "my-app" } }, + }); -
+ // Check that there is at least one target + const targets = disruptor.targets(); + if (targets.length != 1) { + throw new Error("expected list to have one target"); + } -xk6-disruptor is in the alpha phase, undergoing active development. k6 doesn't guarantee API compatibility between releases. -Until this extension reaches v1.0 release, your k6 scripts may need to be updated on each release . + // Disrupt the targets by injecting HTTP faults into them for 30 seconds + const fault = { + averageDelay: 500, + errorRate: 0.1, + errorCode: 500 + } + disruptor.injectHTTPFaults(fault, "30s") +} +``` -
+## Features -## Try out xk6-disruptor on our demo environment +The project, at this time, is intended to test systems running in Kubernetes. Other platforms are not supported at this time. + +It offers an [API](/javascript-api/xk6-disruptor/api) for creating disruptors that target one specific type of the component (e.g., Pods) and is capable of injecting different kinds of [faults](/javascript-api/xk6-disruptor/api/faults), such as errors in HTTP requests served by that component. +Currently, disruptors exist for [Pods](/javascript-api/xk6-disruptor/api/poddisruptor) and [Services](/javascript-api/xk6-disruptor/api/servicedisruptor), but others will be introduced in the future as well as additional types of faults for the existing disruptors. + +## Use cases + +The main use case for xk6-disruptor is to test the resiliency of an application of diverse types of disruptions by reproducing their effects without reproducing their root causes. For example, inject delays in the HTTP requests an application makes to a service without having to stress or interfere with the infrastructure (network, nodes) on which the service runs or affect other workloads in unexpected ways. + +In this way, xk6-disruptor make reliability tests repeatable and predictable while limiting their blast radius. These are essential characteristics to incorporate these tests in the test suits of applications deployed on shared infrastructures such as staging environments. + +## Learn more + +Check the [get started guide](/javascript-api/xk6-disruptor/get-started) for instructions on how to install and use `xk6-disruptor`. + +The [examples](/javascript-api/xk6-disruptor/examples/) section in the documentation presents examples of using xk6-disruptor for injecting faults in different scenarios. + +The [Roadmap](https://github.com/grafana/xk6-disruptor/blob/main/ROADMAP.md) presents the project's goals for the coming months regarding new functionalities and enhancements. + + +## Try out xk6-disruptor + +### on our demo environment We provide an [interactive demo environment in Killercoda](https://killercoda.com/grafana-xk6-disruptor/scenario/killercoda) which you can use to try xk6-disruptor right away without having to install Kubernetes on your local machine. You can use this sandbox to try out xk6-disruptor and start writing fault injection on a microservices application right away. -## Install xk6-disruptor on your environment +### On your environment 1. Check the [requirements](/javascript-api/xk6-disruptor/get-started/requirements). -2. [Install](/javascript-api/xk6-disruptor/get-started/installation) the xk6-disrutor binary in your system. +2. [Install](/javascript-api/xk6-disruptor/get-started/installation) the xk6-disruptor binary in your system. + +## How to contribute + +If you encounter any bugs or unexpected behavior, please search the [currently open GitHub issues](https://github.com/grafana/xk6-disruptor/issues) first, and create a new one if it doesn't exist yet. -3. Run the [Injecting HTTP faults to a Pod](/javascript-api/xk6-disruptor/examples/inject-http-faults-into-pod) example. \ No newline at end of file +If you are interested in contributing with the development of this project, check the [contributing guide](https://github.com/grafana/xk6-disruptor/blob/main/docs/01-development/01-contributing.md) \ No newline at end of file From 599799d1e6202e937828dcba1073807c16c39d36 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 23 Jun 2023 12:55:27 +0200 Subject: [PATCH 02/11] intro change --- .../docs/40 xk6-disruptor/01 Get started/01 Welcome.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index ef1a477bb..0f6aec65d 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -5,7 +5,7 @@ head_title: 'xk6-disruptor Documentation' excerpt: 'xk6-disruptor is a k6 extension providing fault injection capabilities to test system reliability under turbulent conditions.' --- -xk6-disruptor is an extension adds fault injection capabilities to [Grafana k6](https://github.com/grafana/k6). It implements the principles of Chaos Engineering discipline and enables Grafana k6 users to test their system's reliability under turbulent conditions. +[xk6-disruptor](https://github.com/grafana/xk6-disruptor) is an extension that adds fault injection capabilities to k6. It implements the principles of the Chaos Engineering discipline to test the reliability of our applications under turbulent conditions such as latency delays and response errors. ## Why xk6-disruptor? @@ -27,7 +27,7 @@ Also, this project has been built to be a good citizen in the Grafana k6 ecosyst You can check this out in the following example: -```js +```javascript export default function () { // Create a new pod disruptor with a selector // that matches pods from the "default" namespace with the label "app=my-app" @@ -63,7 +63,7 @@ Currently, disruptors exist for [Pods](/javascript-api/xk6-disruptor/api/poddisr The main use case for xk6-disruptor is to test the resiliency of an application of diverse types of disruptions by reproducing their effects without reproducing their root causes. For example, inject delays in the HTTP requests an application makes to a service without having to stress or interfere with the infrastructure (network, nodes) on which the service runs or affect other workloads in unexpected ways. -In this way, xk6-disruptor make reliability tests repeatable and predictable while limiting their blast radius. These are essential characteristics to incorporate these tests in the test suits of applications deployed on shared infrastructures such as staging environments. +In this way, the disruptor makes reliability tests repeatable and predictable while limiting their blast radius. These are essential characteristics to incorporate these tests in the test suits of applications deployed on shared infrastructures such as staging environments. ## Learn more From 1afe035c91ffef1837d991ecaffbd0df02956509 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 23 Jun 2023 14:06:57 +0200 Subject: [PATCH 03/11] Merge contributing/demos in `Learn more` + Update Get started --- .../docs/40 xk6-disruptor/01 Get started.md | 12 +++++---- .../01 Get started/01 Welcome.md | 26 ++++--------------- 2 files changed, 12 insertions(+), 26 deletions(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started.md index 95a8cda1b..485e531c4 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started.md @@ -1,12 +1,14 @@ --- title: 'Get started' -excerpt: '' +excerpt: 'xk6-disruptor is an extension that adds fault injection capabilities to k6. Start here to learn the basics and how to use the disruptor' --- -[Welcome](/javascript-api/xk6-disruptor/) +Inject faults into kubernetes-based applications with `xk6-disruptor`. Start here to learn the basics to use the disruptor: -[Requirements](/javascript-api/xk6-disruptor/get-started/requirements) +- [About `xk6-disruptor`](/javascript-api/xk6-disruptor/) -[Installation](/javascript-api/xk6-disruptor/get-started/installation) +- [Requirements](/javascript-api/xk6-disruptor/get-started/requirements) -[Exposing Your Applications](/javascript-api/xk6-disruptor/get-started/expose-your-application/) +- [Installation](/javascript-api/xk6-disruptor/get-started/installation) + +- [Exposing your Kubernetes application](/javascript-api/xk6-disruptor/get-started/expose-your-application/) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 0f6aec65d..701eaf062 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -67,29 +67,13 @@ In this way, the disruptor makes reliability tests repeatable and predictable wh ## Learn more -Check the [get started guide](/javascript-api/xk6-disruptor/get-started) for instructions on how to install and use `xk6-disruptor`. +Check the [requirements](/javascript-api/xk6-disruptor/requirements/), [installation](/javascript-api/xk6-disruptor/installation/), and [how to expose your application](/javascript-api/xk6-disruptor/expose-your-application/) to get started with the disruptor. -The [examples](/javascript-api/xk6-disruptor/examples/) section in the documentation presents examples of using xk6-disruptor for injecting faults in different scenarios. +This documentation presents a few [examples of injecting faults in different scenarios](/javascript-api/xk6-disruptor/examples/). -The [Roadmap](https://github.com/grafana/xk6-disruptor/blob/main/ROADMAP.md) presents the project's goals for the coming months regarding new functionalities and enhancements. - - -## Try out xk6-disruptor - -### on our demo environment - -We provide an [interactive demo environment in Killercoda](https://killercoda.com/grafana-xk6-disruptor/scenario/killercoda) which you can use to try xk6-disruptor right away without having to install Kubernetes on your local machine. +Also, an [interactive demo environment in Killercoda](https://killercoda.com/grafana-xk6-disruptor/scenario/killercoda) is available to use the k6 disruptor right away. You can fail the services of a demo application without having to install Kubernetes on your local machine. -You can use this sandbox to try out xk6-disruptor and start writing fault injection on a microservices application right away. - -### On your environment - -1. Check the [requirements](/javascript-api/xk6-disruptor/get-started/requirements). - -2. [Install](/javascript-api/xk6-disruptor/get-started/installation) the xk6-disruptor binary in your system. - -## How to contribute +The [Roadmap](https://github.com/grafana/xk6-disruptor/blob/main/ROADMAP.md) presents the project's goals for the coming months regarding new functionalities and enhancements. -If you encounter any bugs or unexpected behavior, please search the [currently open GitHub issues](https://github.com/grafana/xk6-disruptor/issues) first, and create a new one if it doesn't exist yet. +And if you are interested in contributing to the development of this project, check the [contributing guide](https://github.com/grafana/xk6-disruptor/blob/main/docs/01-development/01-contributing.md). For any unexpected behavior, please search the [GitHub issues](https://github.com/grafana/xk6-disruptor/issues) first. -If you are interested in contributing with the development of this project, check the [contributing guide](https://github.com/grafana/xk6-disruptor/blob/main/docs/01-development/01-contributing.md) \ No newline at end of file From df1a6a799de1c7979899c636f1bef4d6e321def0 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 23 Jun 2023 16:22:53 +0200 Subject: [PATCH 04/11] Rewrite key features --- .../01 Get started/01 Welcome.md | 30 ++++++------------- 1 file changed, 9 insertions(+), 21 deletions(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 701eaf062..8fc05a4e5 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -5,27 +5,22 @@ head_title: 'xk6-disruptor Documentation' excerpt: 'xk6-disruptor is a k6 extension providing fault injection capabilities to test system reliability under turbulent conditions.' --- -[xk6-disruptor](https://github.com/grafana/xk6-disruptor) is an extension that adds fault injection capabilities to k6. It implements the principles of the Chaos Engineering discipline to test the reliability of our applications under turbulent conditions such as latency delays and response errors. +[xk6-disruptor](https://github.com/grafana/xk6-disruptor) is an extension that adds fault injection capabilities to k6. It implements the principles of the Chaos Engineering discipline to test the reliability of our applications under turbulent conditions such as latency delays and response errors. Key features include: -## Why xk6-disruptor? +- Everything as code. Facilitate test reuse without learning a new DSL. -xk6-disruptor is designed and built to provide the best experience for developers trying to make their systems more reliable: +- Fast to adopt with no day-two surprises. [No need to deploy and maintain](/javascript-api/xk6-disruptor/explanations/how-xk6-disruptor-works/) a fleet of agents or operators. -- Everything as code. - - No need to learn a new DSL. - - Developers can use their usual development IDE - - Facilitate test reuse and sharing +- Easy to extend and integrate with other [types of load tests](/test-types/load-test-types/). No need to try to glue multiple tools together to get the job done. -- Fast to adopt with no day-two surprises. No need to deploy and maintain a fleet of agents or operators. +## Capabilities -- Easy to extend and integrate with other [types of tests](https://k6.io/docs/test-types/introduction/). No need to try to glue multiple tools together to get the job done. +Currently, the disruptor is intended to test systems running in Kubernetes. Other platforms are not supported at this time. -Also, this project has been built to be a good citizen in the Grafana k6 ecosystem by: +It provides a Javascript API that can create [PodDisruptors](javascript-api/xk6-disruptor/api/poddisruptor) and [ServiceDisruptors](/javascript-api/xk6-disruptor/api/servicedisruptor) to inject different [faults](/javascript-api/xk6-disruptor/api/faults/) in HTTP and gRPC responses, such as errors and delays, into the selected Kubernetes Pods or Services. -- Working well with other extensions. -- Working well with k6's core concepts and features. - -You can check this out in the following example: +Other types of faults and disruptors will be introduced in the future. +The [Roadmap](https://github.com/grafana/xk6-disruptor/blob/main/ROADMAP.md) presents the project's goals for the coming months regarding new functionalities and enhancements. ```javascript export default function () { @@ -52,12 +47,6 @@ export default function () { } ``` -## Features - -The project, at this time, is intended to test systems running in Kubernetes. Other platforms are not supported at this time. - -It offers an [API](/javascript-api/xk6-disruptor/api) for creating disruptors that target one specific type of the component (e.g., Pods) and is capable of injecting different kinds of [faults](/javascript-api/xk6-disruptor/api/faults), such as errors in HTTP requests served by that component. -Currently, disruptors exist for [Pods](/javascript-api/xk6-disruptor/api/poddisruptor) and [Services](/javascript-api/xk6-disruptor/api/servicedisruptor), but others will be introduced in the future as well as additional types of faults for the existing disruptors. ## Use cases @@ -73,7 +62,6 @@ This documentation presents a few [examples of injecting faults in different sce Also, an [interactive demo environment in Killercoda](https://killercoda.com/grafana-xk6-disruptor/scenario/killercoda) is available to use the k6 disruptor right away. You can fail the services of a demo application without having to install Kubernetes on your local machine. -The [Roadmap](https://github.com/grafana/xk6-disruptor/blob/main/ROADMAP.md) presents the project's goals for the coming months regarding new functionalities and enhancements. And if you are interested in contributing to the development of this project, check the [contributing guide](https://github.com/grafana/xk6-disruptor/blob/main/docs/01-development/01-contributing.md). For any unexpected behavior, please search the [GitHub issues](https://github.com/grafana/xk6-disruptor/issues) first. From 0600de749cab517b31b0eaacc673dbe42b4dfd77 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 23 Jun 2023 16:43:12 +0200 Subject: [PATCH 05/11] vale accepts `Killercoda` --- .vale/Vocab/docs/accept.txt | 1 + .../markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md | 2 +- 2 files changed, 2 insertions(+), 1 deletion(-) diff --git a/.vale/Vocab/docs/accept.txt b/.vale/Vocab/docs/accept.txt index 5fd89900d..34658cd31 100644 --- a/.vale/Vocab/docs/accept.txt +++ b/.vale/Vocab/docs/accept.txt @@ -78,6 +78,7 @@ hostname htop kafka keyserver +Killercoda iftop iters initializer diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 8fc05a4e5..729dcdd56 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -11,7 +11,7 @@ excerpt: 'xk6-disruptor is a k6 extension providing fault injection capabilities - Fast to adopt with no day-two surprises. [No need to deploy and maintain](/javascript-api/xk6-disruptor/explanations/how-xk6-disruptor-works/) a fleet of agents or operators. -- Easy to extend and integrate with other [types of load tests](/test-types/load-test-types/). No need to try to glue multiple tools together to get the job done. +- Easy to extend and integrate with other types of k6 tests. No need to try to glue multiple tools together to get the job done. ## Capabilities From f05ff3966e235b6e9fa5fdbed936870bf04888a3 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 23 Jun 2023 17:57:59 +0200 Subject: [PATCH 06/11] update example --- .../markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 729dcdd56..f65c00b9c 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -33,7 +33,7 @@ export default function () { // Check that there is at least one target const targets = disruptor.targets(); - if (targets.length != 1) { + if (targets.length === 0) { throw new Error("expected list to have one target"); } From 70991f50d6c9d0b61cd0346d329b74d3919cca9b Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 23 Jun 2023 18:59:00 +0200 Subject: [PATCH 07/11] Disruptor use cases --- .../40 xk6-disruptor/01 Get started/01 Welcome.md | 15 +++++++++++++-- 1 file changed, 13 insertions(+), 2 deletions(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index f65c00b9c..2f7fef316 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -50,9 +50,20 @@ export default function () { ## Use cases -The main use case for xk6-disruptor is to test the resiliency of an application of diverse types of disruptions by reproducing their effects without reproducing their root causes. For example, inject delays in the HTTP requests an application makes to a service without having to stress or interfere with the infrastructure (network, nodes) on which the service runs or affect other workloads in unexpected ways. +The disruptor allows you to test the resiliency of applications and distributed systems by introducing service errors. -In this way, the disruptor makes reliability tests repeatable and predictable while limiting their blast radius. These are essential characteristics to incorporate these tests in the test suits of applications deployed on shared infrastructures such as staging environments. +The disruptor does not reproduce root causes, such as killing an instance or degrading the memory and CPU. +It focuses on the side effect, the propagation of errors to internal and public services, so you can focus on handling application errors and improving the resilience of the distributed system. + +This way, the disruptor makes reliability tests repeatable and predictable while limiting their blast radius. +These are essentials to test applications deployed on shared infrastructures such as pre-production and testing environments. + +Common use cases are: +- Test resilient policies such as backoff, timeouts, retries, etc. +- Test the fallback functionality when internal failures arise. +- Test SLOs under common internal failures. +- Test application performance when experiencing network delays. +- Add fault injection to existing performance tests. ## Learn more From 79de2a9b0b3f36bd52ae9ff502be7f452b0ce5cd Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Fri, 23 Jun 2023 19:15:22 +0200 Subject: [PATCH 08/11] fix vale error / rephrase use cases --- .../docs/40 xk6-disruptor/01 Get started/01 Welcome.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 2f7fef316..b96416298 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -50,10 +50,10 @@ export default function () { ## Use cases -The disruptor allows you to test the resiliency of applications and distributed systems by introducing service errors. +The disruptor lets you test the resiliency of applications and distributed systems by introducing service errors. The disruptor does not reproduce root causes, such as killing an instance or degrading the memory and CPU. -It focuses on the side effect, the propagation of errors to internal and public services, so you can focus on handling application errors and improving the resilience of the distributed system. +It focuses on the side effect, the propagation of errors to internal and public services, so you can work more easily on the error handling of the application and distributed systems. This way, the disruptor makes reliability tests repeatable and predictable while limiting their blast radius. These are essentials to test applications deployed on shared infrastructures such as pre-production and testing environments. From 838f9a6caf02d3e7923a894ca636be0657d60ea0 Mon Sep 17 00:00:00 2001 From: Pablo Chacin Date: Mon, 26 Jun 2023 11:37:31 +0200 Subject: [PATCH 09/11] Reword for clarity and accuracy Signed-off-by: Pablo Chacin --- .../01 Get started/01 Welcome.md | 26 ++++++++++--------- 1 file changed, 14 insertions(+), 12 deletions(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index b96416298..67664e8a3 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -5,9 +5,11 @@ head_title: 'xk6-disruptor Documentation' excerpt: 'xk6-disruptor is a k6 extension providing fault injection capabilities to test system reliability under turbulent conditions.' --- -[xk6-disruptor](https://github.com/grafana/xk6-disruptor) is an extension that adds fault injection capabilities to k6. It implements the principles of the Chaos Engineering discipline to test the reliability of our applications under turbulent conditions such as latency delays and response errors. Key features include: +[xk6-disruptor](https://github.com/grafana/xk6-disruptor) is an extension that adds fault injection capabilities to k6. It implements the principles of the Chaos Engineering discipline to test the reliability of our applications under turbulent conditions such as delays and response errors. -- Everything as code. Facilitate test reuse without learning a new DSL. +Key features include: + +- Everything as code. Facilitate test reuse and collaboration between teams without learning a new DSL. - Fast to adopt with no day-two surprises. [No need to deploy and maintain](/javascript-api/xk6-disruptor/explanations/how-xk6-disruptor-works/) a fleet of agents or operators. @@ -15,12 +17,11 @@ excerpt: 'xk6-disruptor is a k6 extension providing fault injection capabilities ## Capabilities -Currently, the disruptor is intended to test systems running in Kubernetes. Other platforms are not supported at this time. +Currently, the disruptor is intended to test applications running in Kubernetes. Other platforms are not supported at this time. -It provides a Javascript API that can create [PodDisruptors](javascript-api/xk6-disruptor/api/poddisruptor) and [ServiceDisruptors](/javascript-api/xk6-disruptor/api/servicedisruptor) to inject different [faults](/javascript-api/xk6-disruptor/api/faults/) in HTTP and gRPC responses, such as errors and delays, into the selected Kubernetes Pods or Services. +It provides a Javascript API to inject different [faults](/javascript-api/xk6-disruptor/api/faults/) in HTTP and gRPC requests, such as errors and delays, into the selected Kubernetes [Pods](javascript-api/xk6-disruptor/api/poddisruptor) or [Services](/javascript-api/xk6-disruptor/api/servicedisruptor). -Other types of faults and disruptors will be introduced in the future. -The [Roadmap](https://github.com/grafana/xk6-disruptor/blob/main/ROADMAP.md) presents the project's goals for the coming months regarding new functionalities and enhancements. +Other types of faults and disruptors will be introduced in the future. The [Roadmap](https://github.com/grafana/xk6-disruptor/blob/main/ROADMAP.md) presents the project's goals for the coming months regarding new functionalities and enhancements. ```javascript export default function () { @@ -47,13 +48,12 @@ export default function () { } ``` - ## Use cases -The disruptor lets you test the resiliency of applications and distributed systems by introducing service errors. +The disruptor lets you test the resiliency of distributed applications by introducing errors in the requests served by your services. -The disruptor does not reproduce root causes, such as killing an instance or degrading the memory and CPU. -It focuses on the side effect, the propagation of errors to internal and public services, so you can work more easily on the error handling of the application and distributed systems. +The disruptor does not try to reproduce root causes, such as failed application instances or degraded computing or network resources. +It focuses on reproducing the side effects of such failures, so you can focus on understanding the propagation of errors between internal and public services and improving the error handling in your application. This way, the disruptor makes reliability tests repeatable and predictable while limiting their blast radius. These are essentials to test applications deployed on shared infrastructures such as pre-production and testing environments. @@ -62,7 +62,7 @@ Common use cases are: - Test resilient policies such as backoff, timeouts, retries, etc. - Test the fallback functionality when internal failures arise. - Test SLOs under common internal failures. -- Test application performance when experiencing network delays. +- Test application performance when experiencing delays. - Add fault injection to existing performance tests. ## Learn more @@ -73,6 +73,8 @@ This documentation presents a few [examples of injecting faults in different sce Also, an [interactive demo environment in Killercoda](https://killercoda.com/grafana-xk6-disruptor/scenario/killercoda) is available to use the k6 disruptor right away. You can fail the services of a demo application without having to install Kubernetes on your local machine. +For any unexpected behavior, please search the [GitHub issues](https://github.com/grafana/xk6-disruptor/issues) first. + +And if you are interested in contributing to the development of this project, check the [contributing guide](https://github.com/grafana/xk6-disruptor/blob/main/docs/01-development/01-contributing.md). -And if you are interested in contributing to the development of this project, check the [contributing guide](https://github.com/grafana/xk6-disruptor/blob/main/docs/01-development/01-contributing.md). For any unexpected behavior, please search the [GitHub issues](https://github.com/grafana/xk6-disruptor/issues) first. From 3f43a2aff34bd687ff3083956bf324874989820a Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Mon, 26 Jun 2023 13:15:23 +0200 Subject: [PATCH 10/11] style: consistent bullet points --- .../markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md | 2 -- 1 file changed, 2 deletions(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 67664e8a3..750964b46 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -10,9 +10,7 @@ excerpt: 'xk6-disruptor is a k6 extension providing fault injection capabilities Key features include: - Everything as code. Facilitate test reuse and collaboration between teams without learning a new DSL. - - Fast to adopt with no day-two surprises. [No need to deploy and maintain](/javascript-api/xk6-disruptor/explanations/how-xk6-disruptor-works/) a fleet of agents or operators. - - Easy to extend and integrate with other types of k6 tests. No need to try to glue multiple tools together to get the job done. ## Capabilities From 8ec699b7fa60f6fc25aec7b6aae989c72c47df40 Mon Sep 17 00:00:00 2001 From: Pepe Cano <825430+ppcano@users.noreply.github.com> Date: Mon, 26 Jun 2023 13:22:02 +0200 Subject: [PATCH 11/11] Update src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md Co-authored-by: Roberto Santalla --- .../markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md index 750964b46..7b53fdb42 100644 --- a/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md +++ b/src/data/markdown/docs/40 xk6-disruptor/01 Get started/01 Welcome.md @@ -27,7 +27,7 @@ export default function () { // that matches pods from the "default" namespace with the label "app=my-app" const disruptor = new PodDisruptor({ namespace: "default", - select: { labels: { app: "my-app" } }, + select: { labels: { "app.kubernetes.io/name": "my-app" } }, }); // Check that there is at least one target