| Name | chaostoolkit-lib JSON |
| Version |
1.44.0
JSON |
| download |
| home_page | None |
| Summary | Chaos Toolkit core library |
| upload_time | 2024-08-25 09:09:36 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.8 |
| license | Apache-2.0 |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<h2 align="center">
<br>
<p align="center"><img src="https://avatars.githubusercontent.com/u/32068152?s=200&v=4"></p>
</h2>
<h4 align="center">Chaos Toolkit - Chaos Engineering for Everyone</h4>
<p align="center">
<a href="https://github.com/chaostoolkit/chaostoolkit-lib/releases">
<img alt="Release" src="https://img.shields.io/pypi/v/chaostoolkit-lib.svg">
<a href="#">
<img alt="Build" src="https://github.com/chaostoolkit/chaostoolkit-lib/actions/workflows/build.yaml/badge.svg">
<a href="https://github.com/chaostoolkit/chaostoolkit-lib/issues">
<img alt="GitHub issues" src="https://img.shields.io/github/issues/chaostoolkit/chaostoolkit-lib?style=flat-square&logo=github&logoColor=white">
<a href="https://github.com/chaostoolkit/chaostoolkit-lib/blob/master/LICENSE.md">
<img alt="License" src="https://img.shields.io/github/license/chaostoolkit/chaostoolkit-lib">
<a href="#">
<img alt="Python version" src="https://img.shields.io/pypi/pyversions/chaostoolkit-lib.svg">
<a href="https://pkg.go.dev/github.com/chaostoolkit/chaostoolkit-lib">
</p>
<p align="center">
<a href="https://join.slack.com/t/chaostoolkit/shared_invite/zt-22c5isqi9-3YjYzucVTNFFVIG~Kzns8g">Community</a> •
<a href="https://github.com/chaostoolkit/chaostoolkit-lib/blob/master/CHANGELOG.md">ChangeLog</a>
</p>
---
## Purpose
The purpose of this library is to provide the core of the Chaos Toolkit
[model][concepts] and functions it needs to render its services.
[concepts]: https://docs.chaostoolkit.org/reference/concepts/
## Features
The library provides the followings features:
* discover capabilities from extensions
Allows you to explore the support from an extension that would help you
initialize an experiment against the system this extension targets
* validate a given experiment syntax
The validation looks at various keys in the experiment and raises errors
whenever something doesn't look right.
As a nice addition, when a probe calls a Python function with arguments,
it tries to validate the given argument list matches the signature of the
function to apply.
* run your steady state before and after the method. The former as a gate to
decide if the experiment can be executed. The latter to see if the system
deviated from normal.
* run probes and actions declared in an experiment
It runs the steps in a experiment method sequentially, applying first steady
probes, then actions and finally close probes.
A journal, as a JSON payload, is return of the experiment run.
The library supports running probes and actions defined as Python functions,
from importable Python modules, processes and HTTP calls.
* run experiment's rollbacks when provided
* Load secrets from the experiments, the environ or [vault][vault]
* Provides event notification from Chaos Toolkit flow (although the actual
events are published by the CLI itself, not from this library), supported
events are:
* on experiment validation: started, failed or completed
* on discovery: started, failed or completed
* on initialization of experiments: started, failed or completed
* on experiment runs: started, failed or completed
For each event, the according payload is part of the event as well as a UTC
timestamp.
[vault]: https://www.vaultproject.io/
## Install
If you are user of the Chaos Toolkit, you probably do not need to install this
package yourself as it comes along with the [chaostoolkit cli][cli].
[cli]: https://github.com/chaostoolkit/chaostoolkit
However, should you wish to integrate this library in your own Python code,
please install it as usual:
```
$ pip install -U chaostoolkit-lib
```
### Specific dependencies
In addition to essential dependencies, the package can install a couple of
other extra dependencies for specific use-cases. They are not mandatory and
the library will warn you if you try to use a feature that requires them.
### Vault
If you need [Vault][vault] support to read secrets from, run the following
command:
[vault]: https://www.vaultproject.io/
```
$ pip install -U chaostoolkit-lib[vault]
```
To authenticate with Vault, you can either:
* Use a token through the `vault_token` configuration key
* Use an [AppRole][approle] via the `vault_role_id`, `vault_secret_id` pair of configuration keys
* Use a [service account][serviceaccount] configured with an appropriate [role][role] via the `vault_sa_role` configuration key. The `vault_sa_token_path`, `vault_k8s_mount_point`, and `vault_secrets_mount_point` configuration keys can optionally be specified to point to a location containing a service account [token][sa-token], a different Kubernetes authentication method [mount point][k8s-mount], or a different secrets [mount point][secrets-mount], respectively.
[approle]: https://www.vaultproject.io/docs/auth/approle.html
[serviceaccount]: https://www.vaultproject.io/api/auth/kubernetes/index.html
[role]: https://www.vaultproject.io/api/auth/kubernetes/index.html#create-role
[sa-token]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#service-account-token-volume-projection
[k8s-mount]: https://www.vaultproject.io/docs/auth/kubernetes.html
[secrets-mount]: https://www.vaultproject.io/api/secret/kv/kv-v1.htm
### JSON Path
If you need [JSON Path support][jpath] for tolerance probes in the hypothesis,
also run the following command:
[jpath]: http://goessner.net/articles/JsonPath/
```
$ pip install -U chaostoolkit-lib[jsonpath]
```
## Contribute
Contributors to this project are welcome as this is an open-source effort that
seeks [discussions][join] and continuous improvement.
[join]: https://join.chaostoolkit.org/
From a code perspective, if you wish to contribute, you will need to run a
Python 3.6+ environment. Please, fork this project, write unit tests to cover
the proposed changes, implement the changes, ensure they meet the formatting
standards set out by `black`, `flake8`, and `isort`, add an entry into
`CHANGELOG.md`, and then raise a PR to the repository for review.
Please refer to the [formatting](#formatting-and-linting) section for more
information on the formatting standards.
The Chaos Toolkit projects require all contributors must sign a
[Developer Certificate of Origin][dco] on each commit they would like to merge
into the master branch of the repository. Please, make sure you can abide by
the rules of the DCO before submitting a PR.
[dco]: https://github.com/probot/dco#how-it-works
### Develop
If you wish to develop on this project, make sure to install the development
dependencies. To do so, first install [pdm](https://pdm-project.org/latest/).
```console
$ pdm install --dev
```
Now, you can edit the files and they will be automatically be seen by your
environment, even when running from the `chaos` command locally.
### Test
To run the tests for the project execute the following:
```
$ pdm run test
```
### Formatting and Linting
We use [ruff]() to perform linting and code style.
[ruff]: https://astral.sh/ruff
Before raising a Pull Request, we recommend you run formatting against your
code with:
```console
$ pdm run format
```
This will automatically format any code that doesn't adhere to the formatting
standards.
As some things are not picked up by the formatting, we also recommend you run:
```console
$ pdm run lint
```
To ensure that any unused import statements/strings that are too long, etc.
are also picked up.
Raw data
{
"_id": null,
"home_page": null,
"name": "chaostoolkit-lib",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.8",
"maintainer_email": null,
"keywords": null,
"author": null,
"author_email": "Chaos Toolkit <contact@chaostoolkit.org>, Sylvain Hellegouarch <sh@defuze.org>",
"download_url": "https://files.pythonhosted.org/packages/2e/c7/6c7e9a93307a213f821236f5444c92c0cf82fd8866e987600c21af2a020b/chaostoolkit_lib-1.44.0.tar.gz",
"platform": null,
"description": "\n<h2 align=\"center\">\n <br>\n <p align=\"center\"><img src=\"https://avatars.githubusercontent.com/u/32068152?s=200&v=4\"></p>\n</h2>\n\n<h4 align=\"center\">Chaos Toolkit - Chaos Engineering for Everyone</h4>\n\n<p align=\"center\">\n <a href=\"https://github.com/chaostoolkit/chaostoolkit-lib/releases\">\n <img alt=\"Release\" src=\"https://img.shields.io/pypi/v/chaostoolkit-lib.svg\">\n <a href=\"#\">\n <img alt=\"Build\" src=\"https://github.com/chaostoolkit/chaostoolkit-lib/actions/workflows/build.yaml/badge.svg\">\n <a href=\"https://github.com/chaostoolkit/chaostoolkit-lib/issues\">\n <img alt=\"GitHub issues\" src=\"https://img.shields.io/github/issues/chaostoolkit/chaostoolkit-lib?style=flat-square&logo=github&logoColor=white\">\n <a href=\"https://github.com/chaostoolkit/chaostoolkit-lib/blob/master/LICENSE.md\">\n <img alt=\"License\" src=\"https://img.shields.io/github/license/chaostoolkit/chaostoolkit-lib\">\n <a href=\"#\">\n <img alt=\"Python version\" src=\"https://img.shields.io/pypi/pyversions/chaostoolkit-lib.svg\">\n <a href=\"https://pkg.go.dev/github.com/chaostoolkit/chaostoolkit-lib\">\n</p>\n\n<p align=\"center\">\n <a href=\"https://join.slack.com/t/chaostoolkit/shared_invite/zt-22c5isqi9-3YjYzucVTNFFVIG~Kzns8g\">Community</a> \u2022\n <a href=\"https://github.com/chaostoolkit/chaostoolkit-lib/blob/master/CHANGELOG.md\">ChangeLog</a>\n</p>\n\n---\n\n## Purpose\n\nThe purpose of this library is to provide the core of the Chaos Toolkit \n[model][concepts] and functions it needs to render its services.\n\n[concepts]: https://docs.chaostoolkit.org/reference/concepts/\n\n## Features\n\nThe library provides the followings features:\n\n* discover capabilities from extensions\n Allows you to explore the support from an extension that would help you\n initialize an experiment against the system this extension targets\n\n* validate a given experiment syntax\n The validation looks at various keys in the experiment and raises errors\n whenever something doesn't look right.\n As a nice addition, when a probe calls a Python function with arguments,\n it tries to validate the given argument list matches the signature of the\n function to apply.\n\n* run your steady state before and after the method. The former as a gate to\n decide if the experiment can be executed. The latter to see if the system\n deviated from normal.\n\n* run probes and actions declared in an experiment\n It runs the steps in a experiment method sequentially, applying first steady\n probes, then actions and finally close probes.\n\n A journal, as a JSON payload, is return of the experiment run.\n\n The library supports running probes and actions defined as Python functions,\n from importable Python modules, processes and HTTP calls.\n\n* run experiment's rollbacks when provided\n\n* Load secrets from the experiments, the environ or [vault][vault]\n\n* Provides event notification from Chaos Toolkit flow (although the actual\n events are published by the CLI itself, not from this library), supported\n events are:\n * on experiment validation: started, failed or completed\n * on discovery: started, failed or completed\n * on initialization of experiments: started, failed or completed\n * on experiment runs: started, failed or completed\n\n For each event, the according payload is part of the event as well as a UTC\n timestamp.\n\n[vault]: https://www.vaultproject.io/\n\n## Install\n\nIf you are user of the Chaos Toolkit, you probably do not need to install this\npackage yourself as it comes along with the [chaostoolkit cli][cli].\n\n[cli]: https://github.com/chaostoolkit/chaostoolkit\n\nHowever, should you wish to integrate this library in your own Python code,\nplease install it as usual:\n\n```\n$ pip install -U chaostoolkit-lib\n```\n\n### Specific dependencies\n\nIn addition to essential dependencies, the package can install a couple of\nother extra dependencies for specific use-cases. They are not mandatory and\nthe library will warn you if you try to use a feature that requires them.\n\n### Vault\n\nIf you need [Vault][vault] support to read secrets from, run the following\ncommand:\n\n[vault]: https://www.vaultproject.io/\n```\n$ pip install -U chaostoolkit-lib[vault]\n```\n\nTo authenticate with Vault, you can either:\n* Use a token through the `vault_token` configuration key\n* Use an [AppRole][approle] via the `vault_role_id`, `vault_secret_id` pair of configuration keys\n* Use a [service account][serviceaccount] configured with an appropriate [role][role] via the `vault_sa_role` configuration key. The `vault_sa_token_path`, `vault_k8s_mount_point`, and `vault_secrets_mount_point` configuration keys can optionally be specified to point to a location containing a service account [token][sa-token], a different Kubernetes authentication method [mount point][k8s-mount], or a different secrets [mount point][secrets-mount], respectively.\n\n[approle]: https://www.vaultproject.io/docs/auth/approle.html\n[serviceaccount]: https://www.vaultproject.io/api/auth/kubernetes/index.html\n[role]: https://www.vaultproject.io/api/auth/kubernetes/index.html#create-role\n[sa-token]: https://kubernetes.io/docs/tasks/configure-pod-container/configure-service-account/#service-account-token-volume-projection\n[k8s-mount]: https://www.vaultproject.io/docs/auth/kubernetes.html\n[secrets-mount]: https://www.vaultproject.io/api/secret/kv/kv-v1.htm\n\n\n### JSON Path\n\nIf you need [JSON Path support][jpath] for tolerance probes in the hypothesis,\nalso run the following command:\n\n[jpath]: http://goessner.net/articles/JsonPath/\n\n```\n$ pip install -U chaostoolkit-lib[jsonpath]\n```\n\n## Contribute\n\nContributors to this project are welcome as this is an open-source effort that\nseeks [discussions][join] and continuous improvement.\n\n[join]: https://join.chaostoolkit.org/\n\nFrom a code perspective, if you wish to contribute, you will need to run a \nPython 3.6+ environment. Please, fork this project, write unit tests to cover\nthe proposed changes, implement the changes, ensure they meet the formatting\nstandards set out by `black`, `flake8`, and `isort`, add an entry into \n`CHANGELOG.md`, and then raise a PR to the repository for review.\n\nPlease refer to the [formatting](#formatting-and-linting) section for more\ninformation on the formatting standards.\n\nThe Chaos Toolkit projects require all contributors must sign a\n[Developer Certificate of Origin][dco] on each commit they would like to merge\ninto the master branch of the repository. Please, make sure you can abide by\nthe rules of the DCO before submitting a PR.\n\n[dco]: https://github.com/probot/dco#how-it-works\n\n\n### Develop\n\nIf you wish to develop on this project, make sure to install the development\ndependencies. To do so, first install [pdm](https://pdm-project.org/latest/).\n\n\n```console\n$ pdm install --dev\n```\n\nNow, you can edit the files and they will be automatically be seen by your\nenvironment, even when running from the `chaos` command locally.\n\n### Test\n\nTo run the tests for the project execute the following:\n\n```\n$ pdm run test\n```\n\n### Formatting and Linting\n\nWe use [ruff]() to perform linting and code style.\n\n[ruff]: https://astral.sh/ruff\n\nBefore raising a Pull Request, we recommend you run formatting against your\ncode with:\n\n```console\n$ pdm run format\n```\n\nThis will automatically format any code that doesn't adhere to the formatting\nstandards.\n\nAs some things are not picked up by the formatting, we also recommend you run:\n\n```console\n$ pdm run lint\n```\n\nTo ensure that any unused import statements/strings that are too long, etc.\nare also picked up.\n",
"bugtrack_url": null,
"license": "Apache-2.0",
"summary": "Chaos Toolkit core library",
"version": "1.44.0",
"project_urls": {
"Changelog": "https://github.com/chaostoolkit/chaostoolkit-lib/blob/main/CHANGELOG.md",
"Documentation": "https://chaostoolkit.org",
"Homepage": "https://chaostoolkit.org/",
"Repository": "https://github.com/chaostoolkit/chaostoolkit-lib"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "6b65896a35305da1029d6699fb51bf2b5035751440c9557b731d76d93989b15d",
"md5": "bcf051d31f076a21cb5dc4e12e243fd2",
"sha256": "fb5543bf46076694db80fc93c2b53e893c5204e38755d64473399cc3429ab6ac"
},
"downloads": -1,
"filename": "chaostoolkit_lib-1.44.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "bcf051d31f076a21cb5dc4e12e243fd2",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.8",
"size": 63056,
"upload_time": "2024-08-25T09:09:35",
"upload_time_iso_8601": "2024-08-25T09:09:35.182943Z",
"url": "https://files.pythonhosted.org/packages/6b/65/896a35305da1029d6699fb51bf2b5035751440c9557b731d76d93989b15d/chaostoolkit_lib-1.44.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "2ec76c7e9a93307a213f821236f5444c92c0cf82fd8866e987600c21af2a020b",
"md5": "36a33313e267aea6a1e258cd5cab0b81",
"sha256": "ad6f3dad4c97b20711bcc0e8e4475cdcaf65fbf995552ea67efb97136e56842f"
},
"downloads": -1,
"filename": "chaostoolkit_lib-1.44.0.tar.gz",
"has_sig": false,
"md5_digest": "36a33313e267aea6a1e258cd5cab0b81",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.8",
"size": 85733,
"upload_time": "2024-08-25T09:09:36",
"upload_time_iso_8601": "2024-08-25T09:09:36.707843Z",
"url": "https://files.pythonhosted.org/packages/2e/c7/6c7e9a93307a213f821236f5444c92c0cf82fd8866e987600c21af2a020b/chaostoolkit_lib-1.44.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-08-25 09:09:36",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "chaostoolkit",
"github_project": "chaostoolkit-lib",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "chaostoolkit-lib"
}
