Initial attempt at documentation (#1)
* Initial attempt at documentation 📝
* adding openapi docs, pr template
This commit is contained in:
Ben Greenier
GitHub
Родитель
8dfed64246
Коммит
901d5de3c8
|
|
@ -0,0 +1,54 @@
|
|||
<!--
|
||||
For __feature requests__, please ignore this template (you can delete it)
|
||||
Instead please include a description of the desired feature, and a brief
|
||||
description of the scenario in which you intend to use it
|
||||
-->
|
||||
|
||||
### Environment
|
||||
|
||||
<!--
|
||||
Please fill in all the relevant fields by running these commands in terminal.
|
||||
-->
|
||||
|
||||
4. `node -v`:
|
||||
5. `npm -v`:
|
||||
|
||||
Then, specify:
|
||||
|
||||
<!-- Which operating system are you using? Specify macOS, Windows, or Linux, along with specific release versions -->
|
||||
- Development Operating System:
|
||||
|
||||
### Steps to Reproduce
|
||||
|
||||
<!--
|
||||
How would you describe your issue to someone who doesn’t know you or your project?
|
||||
Try to write a sequence of steps that anybody can repeat to see the issue.
|
||||
Be specific! If the bug cannot be reproduced, your issue may be closed.
|
||||
-->
|
||||
|
||||
(Write your steps here:)
|
||||
|
||||
1.
|
||||
2.
|
||||
3.
|
||||
|
||||
### Expected Behavior
|
||||
|
||||
<!--
|
||||
How did you expect your project to behave?
|
||||
It’s fine if you’re not sure your understanding is correct.
|
||||
Just write down what you thought would happen.
|
||||
-->
|
||||
|
||||
(Write what you thought would happen.)
|
||||
|
||||
### Actual Behavior
|
||||
|
||||
<!--
|
||||
Did something go wrong?
|
||||
Is something broken, or not behaving as you expected?
|
||||
Describe this section in detail, and attach screenshots if possible.
|
||||
Don't just say "it doesn't work"!
|
||||
-->
|
||||
|
||||
(Write what happened. Add screenshots if you have them!)
|
||||
|
|
@ -0,0 +1 @@
|
|||
The logos and image files in this folder are © 2018 Microsoft Corporation. All rights reserved.
|
||||
|
|
@ -0,0 +1,17 @@
|
|||
|
||||
## Description
|
||||
|
||||
<!-- Briefly describe what this PR does, and why we need it -->
|
||||
|
||||
## Checklist for success
|
||||
|
||||
<!-- please complete this checklist before submitting -->
|
||||
|
||||
- [ ] This change isn't already implemented by a pending pull request
|
||||
- [ ] This change is 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)
|
||||
- [ ] All tests pass locally (see [the testing section](https://github.com/azure/platform-chaos/blob/master/README.md#testing) for more info)
|
||||
- [ ] All New behaviors or major functional changes have tests
|
||||
|
||||
|
||||
<!-- Add any context here that you think is relevant. If you're hunting for specific feedback, this is the spot to ask for it! -->
|
||||
Двоичный файл не отображается.
|
После Ширина: | Высота: | Размер: 36 KiB |
|
|
@ -0,0 +1,11 @@
|
|||
# Extensions
|
||||
|
||||
This file serves to document chaos extensions built with this sdk.
|
||||
To leverage these extensions, see [How to use](README.md#how-to-use) in `README.md`.
|
||||
|
||||
| Extension name | Description |
|
||||
| --------------- | ------------- |
|
||||
| [azure-chaos-fn-webapp-startstop](https://github.com/trstringer/azure-chaos-fn-webapp-startstop) | Starts and stops Azure web apps. |
|
||||
| [azure-chaos-fn-logicapp-startstop](https://github.com/gavination/azure-chaos-fn-logicapp-startstop) | Starts and stops Azure logic apps. |
|
||||
|
||||
Want to add your extension? Send us [a pull request](https://github.com/Azure/platform-chaos/pulls) - see [Contributing](README.md#contributing) in `README.md` for more info.
|
||||
158
README.md
158
README.md
|
|
@ -1,14 +1,162 @@
|
|||
# platform-chaos
|
||||
|
||||
# Contributing
|
||||
A node sdk for building services capable of injecting chaos into PaaS offerings. ⚙️ 🌩
|
||||
|
||||
This project welcomes contributions and suggestions. 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.
|
||||
|
||||
|
||||
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](https://nodejs.org).
|
||||
|
||||
The common interface mentioned above that all chaos extensions must implement is defined using OpenAPI docs [here](https://rebilly.github.io/ReDoc/?url=https://raw.githubusercontent.com/azure/platform-chaos/master/swagger.yaml). 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.
|
||||
|
||||
## How to use
|
||||
|
||||
To consume this sdk, install it from [NPM](https://npmjs.com/package/platform-chaos):
|
||||
|
||||
```
|
||||
npm install platform-chaos
|
||||
```
|
||||
|
||||
Then consume the module in code, leveraging the following API.
|
||||
|
||||
## API
|
||||
|
||||
This is the exported API from the `platform-chaos` NPM module.
|
||||
|
||||
### validators
|
||||
|
||||
Request validation helpers. Useful to ensure data coming in is behaving as expecting.
|
||||
|
||||
```
|
||||
const validate = require('azure-chaos-fn/validators')
|
||||
```
|
||||
|
||||
#### accessToken
|
||||
|
||||
Validates that the `body` of a `req` object contains a valid `accessToken`.
|
||||
|
||||
```
|
||||
try { require('azure-chaos-fn/validators').accessToken(req) } catch (ex) { console.error(`error: ${ex}`) }
|
||||
```
|
||||
|
||||
#### resources
|
||||
|
||||
Validates that the `body` of a `req` object contains a valid `resources` array.
|
||||
|
||||
```
|
||||
try { require('azure-chaos-fn/validators').resources(req) } catch (ex) { console.error(`error: ${ex}`) }
|
||||
```
|
||||
|
||||
### parsers
|
||||
|
||||
> Note: these depend on the [validators](#validators) to ensure only valid data is parsed.
|
||||
|
||||
Request parser helpers. Useful to parse valid request data into models.
|
||||
|
||||
```
|
||||
const parsers = require('azure-chaos-fn/parsers')
|
||||
```
|
||||
|
||||
#### accessTokenToCredentials
|
||||
|
||||
Inflates the `accessToken` from a `req` objects `body` into a [ms-rest-azure](https://www.npmjs.com/package/ms-rest-azure) compatible credentials object.
|
||||
|
||||
```
|
||||
const credentials = require('azure-chaos-fn/parsers').accessTokenToCredentials(req)
|
||||
```
|
||||
|
||||
#### resourcesToObjects
|
||||
|
||||
Inflates the `resources` from a `req` objects `body` into a collection of objects containing the following properties:
|
||||
|
||||
+ `subscriptionId` - the azure subscription id to target
|
||||
+ `resourceGroupName` - the azure resource group name to target
|
||||
+ `resourceName` - the azure resource name to target
|
||||
|
||||
```
|
||||
const objs = require('azure-chaos-fn/parsers').resourcesToObjects(req)
|
||||
```
|
||||
|
||||
## Related Projects
|
||||
|
||||
* [platform-chaos-api](https://github.com/Azure/platform-chaos-api) - An API for introducing chaos into Azure PaaS offerings using configurable extensions.
|
||||
* [platform-chaos-cli](https://github.com/Azure/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](EXTENSIONS.md).
|
||||
|
||||
## Contributing
|
||||
|
||||
This project welcomes contributions and suggestions! Here's what you need to know to get started.
|
||||
|
||||
### Feedback and Feature Requests
|
||||
|
||||
> When you're ready, you can open issues [here](https://github.com/Azure/platform-chaos/issues)!
|
||||
|
||||
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.
|
||||
|
||||
### Development Requirements
|
||||
|
||||
To get started developing, you'll need to first ensure you have these tools installed:
|
||||
|
||||
* [Git](https://git-scm.com)
|
||||
* [NodeJS](https://nodejs.org)
|
||||
|
||||
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!
|
||||
|
||||
### Testing
|
||||
|
||||
To run the tests for this project, first ensure you've installed the [requirements](#development-requirements). Then use npm to run the tests locally:
|
||||
|
||||
```
|
||||
npm test
|
||||
```
|
||||
|
||||
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`).
|
||||
|
||||
### Legal
|
||||
|
||||
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.
|
||||
|
||||
### Submitting Pull Requests
|
||||
|
||||
> When you're ready, you can submit pull requests [here](https://github.com/Azure/platform-chaos/pulls)!
|
||||
|
||||
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](https://github.com/Azure/platform-chaos/pulls) you may need to sign a CLA - see [the legal section](#legal) for more information.
|
||||
|
||||
### Code of Conduct
|
||||
|
||||
This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/).
|
||||
For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
|
||||
|
|
@ -0,0 +1,78 @@
|
|||
swagger: "2.0"
|
||||
info:
|
||||
description: "This documents the expected API that an [azure-chaos](https://github.com/bengreenier/azure-chaos) extension should implement.\n> Note: security for this API is optional, but if implemented as a part of the service, it should be done via a `code` query parameter as part of the url."
|
||||
version: "1.0.0"
|
||||
title: "azure-chaos extension API"
|
||||
license:
|
||||
name: "MIT"
|
||||
url: "https://github.com/bengreenier/azure-chaos/blob/master/LICENSE"
|
||||
schemes:
|
||||
- "https"
|
||||
paths:
|
||||
/start:
|
||||
post:
|
||||
tags:
|
||||
- "extension"
|
||||
summary: "Starts a chaotic event"
|
||||
description: "This endpoint is expected to start some chaotic event using to provided information to target and invoke said event"
|
||||
operationId: "start"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
parameters:
|
||||
- in: "body"
|
||||
name: "body"
|
||||
description: "event arguments"
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/Arguments'
|
||||
responses:
|
||||
200:
|
||||
description: "Chaotic event started"
|
||||
security:
|
||||
- codeAuth: []
|
||||
/stop:
|
||||
post:
|
||||
tags:
|
||||
- "extension"
|
||||
summary: "Starts a chaotic event"
|
||||
description: "This endpoint is expected to stop some chaotic event using to provided information to target and invoke said stopping action"
|
||||
operationId: "stop"
|
||||
consumes:
|
||||
- "application/json"
|
||||
produces:
|
||||
- "application/json"
|
||||
parameters:
|
||||
- in: "body"
|
||||
name: "body"
|
||||
description: "event arguments"
|
||||
required: true
|
||||
schema:
|
||||
$ref: '#/definitions/Arguments'
|
||||
responses:
|
||||
200:
|
||||
description: "Chaotic event stopped"
|
||||
security:
|
||||
- codeAuth: []
|
||||
securityDefinitions:
|
||||
codeAuth:
|
||||
type: "apiKey"
|
||||
name: "code"
|
||||
in: "query"
|
||||
definitions:
|
||||
Arguments:
|
||||
properties:
|
||||
accessToken:
|
||||
description: "The Azure accessToken, in the form of `Bearer <tokenValue>`"
|
||||
example: 'Bearer ZXhhbXBsZSBlbmNvZGVy'
|
||||
type: 'string'
|
||||
resources:
|
||||
description: "Array of Azure resource identifiers in the form of `subId/resourceGroupName/resourceName`"
|
||||
type: 'array'
|
||||
items:
|
||||
type: 'string'
|
||||
example: '00000000-0000-0000-0000-000000000000/myresourcegroup/myapp'
|
||||
externalDocs:
|
||||
description: "Find out more about azure-chaos"
|
||||
url: "https://github.com/bengreenier/azure-chaos"
|
||||
Загрузка…
Ссылка в новой задаче