A node sdk for building services capable of injecting chaos into PaaS offerings. βοΈ π©
Platform chaos is a collection of tools and sdks that enable engineers to experiement on distributed systems built atop PaaS offerings to ensure confidence in such a system's capabilities. It does so by defining a common interface for inducing chaos, through a construct we call chaos extensions. Given this common interface, we're able to provide tooling that can schedule, start, and stop chaotic events.
This project is the core sdk that enables chaos extension development using NodeJS.
The common interface mentioned above that all chaos extensions must implement is defined using OpenAPI docs here. As such, an extension can be developed using any language. SDKs to simplify creation of extensions using other languages may be added in the future.
To consume this sdk, install it from NPM:
npm install platform-chaos
Then consume the module in code, leveraging the following API.
Review this Wiki article for a tutorial on building and using your own Platform Chaos Extension.
This is the exported API from the platform-chaos
NPM module.
Request validation helpers. Useful to ensure data coming in is behaving as expecting.
const validate = require('platform-chaos/validators')
Validates that the body
of a req
object contains a valid accessToken
.
try { require('platform-chaos/validators').accessToken(req) } catch (ex) { console.error(`error: ${ex}`) }
Validates that the body
of a req
object contains a valid resources
array.
try { require('platform-chaos/validators').resources(req) } catch (ex) { console.error(`error: ${ex}`) }
Note: these depend on the validators to ensure only valid data is parsed.
Request parser helpers. Useful to parse valid request data into models.
const parsers = require('platform-chaos/parsers')
Inflates the accessToken
from a req
objects body
into a ms-rest-azure compatible credentials object.
const credentials = require('platform-chaos/parsers').accessTokenToCredentials(req)
Inflates the resources
from a req
objects body
into a collection of objects containing the following properties:
subscriptionId
- the azure subscription id to targetresourceGroupName
- the azure resource group name to targetresourceName
- the azure resource name to target
const objs = require('platform-chaos/parsers').resourcesToObjects(req)
A documented implementation of the verbose logging format defined in Auditing. The auditer is implemented by monkeypatching the context
instance log and done methods. As a developer there is little extra effort you need to do to start using the auditer. At the beginning of your extension file, initialize the auditer by passing in the eventName and resources. Then use context.log
as usual. Everything you log will be added to an intern audit list. When you call context.done
at the end of your extension, the internal audit list is appended to the context.res.body
under the __audits
property.
Initialize the auditer by using the following method:
const index = require('platform-chaos')
index.auditer(/* Azure Function context */, {
eventName: /* Chaos event name : string */,
resources: /* Target resources : string */
})
See a fully implemented example in this chaos extension. To learn more read here.
- platform-chaos-api - An API for introducing chaos into Azure PaaS offerings using configurable extensions.
- platform-chaos-cli - A tool for introducing chaos into Azure PaaS offerings using configurable extensions.
For a list of already built chaos extensions, please see The extensions document.
This project welcomes contributions and suggestions! Here's what you need to know to get started.
When you're ready, you can open issues here!
To submit feedback or request features please do a quick search for similar issues, then open a new issue. If you're requesting a new feature, please briefly explain in the issue what scenario you're planning to use the feature for.
To get started developing, you'll need to first ensure you have these tools installed:
Once you've installed those, clone this repository and install dependencies:
git clone https://github.com/Azure/platform-chaos.git
cd platform-chaos
npm install
Now you're ready to begin contributing!
This project uses Typescript. In order to run the code it must first be compiled using npm run compile
. This command will first remove any existing compiled files by running rimraf dist/
. It then compiles all javascript files contained within the src
directory following the configurtion in tsconfig.json
.
To run the tests for this project, first ensure you've installed the requirements. Next, compile the project using npm run compile
. Following a successful compile, you can run npm test
. The test script will also run tslint
on the project.
Note that this command is meant to be run from the project directory. That is,
the folder that you cloned the project into (likey platform-chaos
).
Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
When you're ready, you can submit pull requests here!
We've defined a pull request template that should be filled out when you're submitting a pull request. You'll see it when you create your PR. Please fill it out to the best of your ability!
Further, your pull request should:
- Include a description of what your change intends to do
- Be a child commit of a reasonably recent commit in the master branch
- Requests need not be a single commit, but should be a linear sequence of commits (i.e. no merge commits in your PR)
- It is desirable, but not necessary, for the tests to pass at each commit
- Have clear commit messages
- e.g. "Refactor feature", "Fix issue", "Add tests for issue"
- Include adequate tests
- At least one test should fail in the absence of your non-test code changes. If your PR does not match this criteria, please specify why
- Tests should include reasonable permutations of the target fix/change
- Include baseline changes with your change
Note that once you've submitted a pull request you may need to sign a CLA - see the legal section for more information.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.