| Name | ksux JSON |
| Version |
0.7.0
JSON |
| download |
| home_page | None |
| Summary | Easy customization of kubernetes manifests |
| upload_time | 2024-04-10 12:33:10 |
| maintainer | None |
| docs_url | None |
| author | Tomas Sladecek |
| requires_python | >=3.12 |
| license | MIT License Copyright (c) 2022 Tomáš Sládeček Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. |
| keywords |
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
<p align="center">
<img src="misc/logo.svg" width="75%">
</p>
<p align=center>
<em>A simple way for templating kubernetes manifests.</em>
</p>
<p align=center>
<img src='https://img.shields.io/github/actions/workflow/status/tsladecek/ksux/test.yml?branch=main&label=tests&logo=GitHub' alt=''/>
<img src='https://img.shields.io/github/repo-size/tsladecek/ksux' alt=''/>
<img src='https://img.shields.io/github/license/tsladecek/ksux' alt='License: MIT'/>
<img src='https://img.shields.io/github/v/tag/tsladecek/ksux?color=yellow&label=version&logo=GitHub'/>
<a href='https://pypi.org/project/ksux/'><img src='https://img.shields.io/pypi/v/ksux?logo=Pypi'/></a>
<a href='https://hub.docker.com/r/tsladecek/ksux'><img src='https://img.shields.io/docker/image-size/tsladecek/ksux?logo=Docker&sort=date' /></a>
<a href='https://tsladecek.github.io/ksux/'><img src='https://img.shields.io/badge/Documentation-link-green' /></a>
</p>
---
- [Requirements](#requirements)
- [Installation](#installation)
- [Local](#local)
- [Docker](#docker)
- [How does it work?](#how-does-it-work)
- [the `op.path`](#the-oppath)
- [Example](#example)
#### tldr
***`ksux` reads `yaml` / `json` manifests in a `base/` directory and applies patches to them specified in the `patches/` directory. The output are patched manfests in the `output/` directory***
```shell
ksux -b <path_to_base_dir> -p <path_to_patches_dir> -o <output_dir>
```
or using docker:
```shell
docker run --rm -v /path/to/your/configs:/configs tsladecek/ksux ksux -b /configs/base -p /configs/patches -o /configs/out
```
---
## Requirements
This is a python package. So the only requirements are `python3` and `pip`
## Installation
### Local
- Optional: Create and activate a virtual env.
```shell
# option 1: virualvenv
virtualvenv ksux
source ksux/bin/activate
# option 2: venv
python -m venv ksux
source ksux/bin/activate
# option 3: conda
conda create -n ksux python
conda activate ksux
```
- Install
```shell
pip install ksux
```
### Docker
use the [docker image](https://hub.docker.com/r/tsladecek/ksux)
To run the command inside a docker container, you need to make sure that all volumes are mapped to the container. Let's say that you have a following file structure:
```shell
|- /home/project
| |- base
| |- patches
| |- out
```
To generate patched manifests in the `/home/project/out` folder, run following command:
```shell
docker run --rm -v /home/project:/configs tsladecek/ksux ksux -b /configs/base -p /configs/patches -o /configs/out
```
the important part is the `-v` flag, which will mount your local folder as a volume to the container.
## How does it work?
Let's say that you have many manifests in some directory (`base` directory) that you wish to patch with patches (in the `patches` directory).
Patches could be in `yaml` or `json` format (as well as your manifests). However the patches **must** adhere to following schema:
```yaml
name: <patch description>
target:
apiVersion: <apiVersion of targeted resource>
kind: <kind of targeted resource>
name: <name of targeted resource>
ops:
- name: <operation description>
path: <path to the part of the manifest to be patched>
value: <value which should be replaced or added>
action: <add|replace|remove>
enforce_integer: <Optional - bool. whether exported value must be an integer in output json. Defaults to "false">
list_key: <Optional - key by which an element in list should be targeted. Defaults to "name">
```
each patch file can be a list of patches. You can use the classic yaml format, e.g.:
```yaml
- name: deployment patches
target:
apiVersion: apps/v1
kind: Deployment
name: web
ops:
- name: replace_image
path: /spec/template/spec/containers/nginx/image
value: nginx:1.23
action: replace
- name: service patches
target:
apiVersion: v1
kind: Service
name: nginx-service
ops:
- name: add_https_port
path: /spec/ports
value:
name: https
port: 443
protocol: TCP
targetPort: 443
action: add
- name: rename_http_port
path: /spec/ports/http/name
action: replace
value: new_name
```
or use the `---` separator:
```yaml
---
name: deployment patches
target:
apiVersion: apps/v1
kind: Deployment
name: web
ops:
- name: replace_image
path: /spec/template/spec/containers/nginx/image
value: nginx:1.23
action: replace
---
name: service patches
target:
apiVersion: v1
kind: Service
name: nginx-service
ops:
- name: add_https_port
path: /spec/ports
value:
name: https
port: 443
protocol: TCP
targetPort: 443
action: add
- name: rename_http_port
path: /spec/ports/http/name
action: replace
value: new_name
```
Then all you need to do, is run:
```shell
ksux -b <path_to_base_dir> -p <path_to_patches_dir> -o <output_dir>
```
**note**: By default, ksux will output patched manifests in `json` format. If you wish to output them in `yaml`, provide the `-e yaml` flag to the command above
This will save all patched manifests to the output dir. You can use the `--dry-run` flag to print the patched manifests to stdout:
```shell
ksux -b <path_to_base_dir> -p <path_to_patches_dir> --dry-run
```
For a list of all options see:
```shell
ksux --help
```
### the `op.path`
This is the "bread and butter" of this package. Similar to kustomize path, however you **can** target list item by names of child objects. E.g. say you have a list of ports in a service:
```yaml
apiVersion: v1
kind: Service
metadata:
labels:
app: nginx-service
name: nginx-service
spec:
ports:
- name: new_name
port: 80
protocol: TCP
targetPort: 80
- name: https
port: 443
protocol: TCP
targetPort: 443
selector:
app: web
type: ClusterIP
```
To target the `https` service and change its name, you can specify the path: `/spec/ports/https/name` and then set the value to the new name:
```yaml
name: service patches
target:
apiVersion: v1
kind: Service
name: nginx-service
ops:
- name: rename_https_port
path: /spec/ports/https/name
action: replace
value: new_name
```
---
You can extend this even further. If you provide the `list_key` prop to a patch, you can target any list item with any key you wish to use. For example, lets say you have an ingress:
```yaml
apiVersion: networking.k8s.io/v1
kind: Ingress
metadata:
name: ingress
namespace: default
annotations:
nginx.ingress.kubernetes.io/rewrite-target: /
spec:
ingressClassName: nginx
rules:
- host: "domain.com"
http:
paths:
- path: /api
pathType: Prefix
backend:
service:
name: backend
port:
number: 80
```
and you wish to use a different host in each of your environments. E.g. in `dev` environment, you would like the host to be `dev.domain.com`, in `staging` environment `staging.domain.com`, etc.
You can easily write a patch for each such environment:
```yaml
name: ingress dev patches
target:
apiVersion: networking.k8s.io/v1
kind: Ingress
name: ingress
ops:
- name: replace host
path: /spec/rules/domain.com/host
action: replace
value: "dev.domain.com"
list_key: "host"
```
Ez 🙃
## Example
In the `./examples` folder there are 3 sub-folders:
- `/examples/base` with deployment, service and a configmap manifests. These are the base manifests which we wish to patch
- `/examples/patches` contain the patches (notice that both base kubernetes manifests and patches can be either in `json` or `yml`/`yaml` format)
- `/examples/out` is the output directory where the patched resources will be output
First, we will `dry-run` the patching:
```shell
ksux -b examples/base -p examples/patches --dry-run
```
You should see the patched manifests printed out to the console. Now we can run it and save the patched manifests
to the `output` folder:
```shell
ksux -b examples/base -p examples/patches -o examples/out
```
By default, the manifests will be saved in `json` format with `.json` extension. If you wish to save the manifests in `yaml` format, simply provide the `-e` flag with corresponding extension. E.g.:
```shell
ksux -b examples/base -p examples/patches -o examples/out -e yaml
```
Raw data
{
"_id": null,
"home_page": null,
"name": "ksux",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.12",
"maintainer_email": null,
"keywords": null,
"author": "Tomas Sladecek",
"author_email": null,
"download_url": "https://files.pythonhosted.org/packages/09/43/e777af760b9716bcb0db179afe82681d05664aa2c7a76e14d2a3bedb7289/ksux-0.7.0.tar.gz",
"platform": null,
"description": "<p align=\"center\">\n <img src=\"misc/logo.svg\" width=\"75%\">\n</p>\n\n<p align=center>\n <em>A simple way for templating kubernetes manifests.</em>\n</p>\n\n<p align=center>\n <img src='https://img.shields.io/github/actions/workflow/status/tsladecek/ksux/test.yml?branch=main&label=tests&logo=GitHub' alt=''/>\n <img src='https://img.shields.io/github/repo-size/tsladecek/ksux' alt=''/>\n <img src='https://img.shields.io/github/license/tsladecek/ksux' alt='License: MIT'/>\n <img src='https://img.shields.io/github/v/tag/tsladecek/ksux?color=yellow&label=version&logo=GitHub'/>\n <a href='https://pypi.org/project/ksux/'><img src='https://img.shields.io/pypi/v/ksux?logo=Pypi'/></a>\n <a href='https://hub.docker.com/r/tsladecek/ksux'><img src='https://img.shields.io/docker/image-size/tsladecek/ksux?logo=Docker&sort=date' /></a>\n <a href='https://tsladecek.github.io/ksux/'><img src='https://img.shields.io/badge/Documentation-link-green' /></a>\n</p>\n\n---\n\n- [Requirements](#requirements)\n- [Installation](#installation)\n - [Local](#local)\n - [Docker](#docker)\n- [How does it work?](#how-does-it-work)\n - [the `op.path`](#the-oppath)\n- [Example](#example)\n\n#### tldr\n\n***`ksux` reads `yaml` / `json` manifests in a `base/` directory and applies patches to them specified in the `patches/` directory. The output are patched manfests in the `output/` directory***\n\n```shell\nksux -b <path_to_base_dir> -p <path_to_patches_dir> -o <output_dir>\n```\n\nor using docker:\n\n```shell\ndocker run --rm -v /path/to/your/configs:/configs tsladecek/ksux ksux -b /configs/base -p /configs/patches -o /configs/out\n```\n\n---\n\n## Requirements\n\nThis is a python package. So the only requirements are `python3` and `pip`\n\n## Installation\n\n### Local\n\n- Optional: Create and activate a virtual env.\n\n```shell\n# option 1: virualvenv\nvirtualvenv ksux\nsource ksux/bin/activate\n\n# option 2: venv\npython -m venv ksux\nsource ksux/bin/activate\n\n# option 3: conda\nconda create -n ksux python\nconda activate ksux\n```\n\n- Install\n\n```shell\npip install ksux\n```\n\n### Docker\n\nuse the [docker image](https://hub.docker.com/r/tsladecek/ksux)\n\nTo run the command inside a docker container, you need to make sure that all volumes are mapped to the container. Let's say that you have a following file structure:\n\n```shell\n|- /home/project\n| |- base\n| |- patches\n| |- out\n```\n\nTo generate patched manifests in the `/home/project/out` folder, run following command:\n\n```shell\ndocker run --rm -v /home/project:/configs tsladecek/ksux ksux -b /configs/base -p /configs/patches -o /configs/out\n```\n\nthe important part is the `-v` flag, which will mount your local folder as a volume to the container.\n\n## How does it work?\n\nLet's say that you have many manifests in some directory (`base` directory) that you wish to patch with patches (in the `patches` directory).\n\nPatches could be in `yaml` or `json` format (as well as your manifests). However the patches **must** adhere to following schema:\n\n```yaml\nname: <patch description>\ntarget:\n apiVersion: <apiVersion of targeted resource>\n kind: <kind of targeted resource>\n name: <name of targeted resource>\nops:\n - name: <operation description>\n path: <path to the part of the manifest to be patched>\n value: <value which should be replaced or added>\n action: <add|replace|remove>\n enforce_integer: <Optional - bool. whether exported value must be an integer in output json. Defaults to \"false\">\n list_key: <Optional - key by which an element in list should be targeted. Defaults to \"name\">\n```\n\neach patch file can be a list of patches. You can use the classic yaml format, e.g.:\n\n```yaml\n- name: deployment patches\n target:\n apiVersion: apps/v1\n kind: Deployment\n name: web\n ops:\n - name: replace_image\n path: /spec/template/spec/containers/nginx/image\n value: nginx:1.23\n action: replace\n- name: service patches\n target:\n apiVersion: v1\n kind: Service\n name: nginx-service\n ops:\n - name: add_https_port\n path: /spec/ports\n value:\n name: https\n port: 443\n protocol: TCP\n targetPort: 443\n action: add\n - name: rename_http_port\n path: /spec/ports/http/name\n action: replace\n value: new_name\n```\n\nor use the `---` separator:\n\n```yaml\n---\nname: deployment patches\ntarget:\n apiVersion: apps/v1\n kind: Deployment\n name: web\nops:\n- name: replace_image\n path: /spec/template/spec/containers/nginx/image\n value: nginx:1.23\n action: replace\n---\nname: service patches\ntarget:\n apiVersion: v1\n kind: Service\n name: nginx-service\nops:\n- name: add_https_port\n path: /spec/ports\n value:\n name: https\n port: 443\n protocol: TCP\n targetPort: 443\n action: add\n- name: rename_http_port\n path: /spec/ports/http/name\n action: replace\n value: new_name\n```\n\nThen all you need to do, is run:\n\n```shell\nksux -b <path_to_base_dir> -p <path_to_patches_dir> -o <output_dir>\n```\n\n**note**: By default, ksux will output patched manifests in `json` format. If you wish to output them in `yaml`, provide the `-e yaml` flag to the command above\n\nThis will save all patched manifests to the output dir. You can use the `--dry-run` flag to print the patched manifests to stdout:\n\n```shell\nksux -b <path_to_base_dir> -p <path_to_patches_dir> --dry-run\n```\n\nFor a list of all options see:\n\n```shell\nksux --help\n```\n\n### the `op.path`\n\nThis is the \"bread and butter\" of this package. Similar to kustomize path, however you **can** target list item by names of child objects. E.g. say you have a list of ports in a service:\n\n```yaml\napiVersion: v1\nkind: Service\nmetadata:\n labels:\n app: nginx-service\n name: nginx-service\nspec:\n ports:\n - name: new_name\n port: 80\n protocol: TCP\n targetPort: 80\n - name: https\n port: 443\n protocol: TCP\n targetPort: 443\n selector:\n app: web\n type: ClusterIP\n```\n\nTo target the `https` service and change its name, you can specify the path: `/spec/ports/https/name` and then set the value to the new name:\n\n```yaml\nname: service patches\ntarget:\n apiVersion: v1\n kind: Service\n name: nginx-service\nops:\n- name: rename_https_port\n path: /spec/ports/https/name\n action: replace\n value: new_name\n```\n\n---\n\nYou can extend this even further. If you provide the `list_key` prop to a patch, you can target any list item with any key you wish to use. For example, lets say you have an ingress:\n\n```yaml\napiVersion: networking.k8s.io/v1\nkind: Ingress\nmetadata:\n name: ingress\n namespace: default\n annotations:\n nginx.ingress.kubernetes.io/rewrite-target: /\nspec:\n ingressClassName: nginx\n rules:\n - host: \"domain.com\"\n http:\n paths:\n - path: /api\n pathType: Prefix\n backend:\n service:\n name: backend\n port:\n number: 80\n```\n\nand you wish to use a different host in each of your environments. E.g. in `dev` environment, you would like the host to be `dev.domain.com`, in `staging` environment `staging.domain.com`, etc.\n\nYou can easily write a patch for each such environment:\n\n```yaml\nname: ingress dev patches\ntarget:\n apiVersion: networking.k8s.io/v1\n kind: Ingress\n name: ingress\nops:\n - name: replace host\n path: /spec/rules/domain.com/host\n action: replace\n value: \"dev.domain.com\"\n list_key: \"host\"\n```\n\nEz \ud83d\ude43\n\n## Example\n\nIn the `./examples` folder there are 3 sub-folders:\n - `/examples/base` with deployment, service and a configmap manifests. These are the base manifests which we wish to patch\n - `/examples/patches` contain the patches (notice that both base kubernetes manifests and patches can be either in `json` or `yml`/`yaml` format)\n - `/examples/out` is the output directory where the patched resources will be output\n\nFirst, we will `dry-run` the patching:\n\n```shell\nksux -b examples/base -p examples/patches --dry-run\n```\n\nYou should see the patched manifests printed out to the console. Now we can run it and save the patched manifests\nto the `output` folder:\n\n```shell\nksux -b examples/base -p examples/patches -o examples/out\n```\n\nBy default, the manifests will be saved in `json` format with `.json` extension. If you wish to save the manifests in `yaml` format, simply provide the `-e` flag with corresponding extension. E.g.:\n\n```shell\nksux -b examples/base -p examples/patches -o examples/out -e yaml\n```\n",
"bugtrack_url": null,
"license": "MIT License Copyright (c) 2022 Tom\u00e1\u0161 Sl\u00e1de\u010dek Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the \"Software\"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions: The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software. THE SOFTWARE IS PROVIDED \"AS IS\", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE. ",
"summary": "Easy customization of kubernetes manifests",
"version": "0.7.0",
"project_urls": {
"Homepage": "https://github.com/tsladecek/ksux"
},
"split_keywords": [],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "3d5170181e33c0c2c0fc9a7918c63f977bb46223827bd13df8a57da7e29cd4d3",
"md5": "ad183e22c0a653f8db487d075a5a4861",
"sha256": "ad3cd054fe4ec93b6f70ef189d6d2d3fd6b3df6576552e6ef58ce37d7b59fa27"
},
"downloads": -1,
"filename": "ksux-0.7.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "ad183e22c0a653f8db487d075a5a4861",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.12",
"size": 15291,
"upload_time": "2024-04-10T12:33:09",
"upload_time_iso_8601": "2024-04-10T12:33:09.159473Z",
"url": "https://files.pythonhosted.org/packages/3d/51/70181e33c0c2c0fc9a7918c63f977bb46223827bd13df8a57da7e29cd4d3/ksux-0.7.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "0943e777af760b9716bcb0db179afe82681d05664aa2c7a76e14d2a3bedb7289",
"md5": "48d19d0cff807aa03df8f695e6cd584d",
"sha256": "422a5329cec263b7e4f5e394d1c7b7447d17ae874615c1b4c60c474797a59b36"
},
"downloads": -1,
"filename": "ksux-0.7.0.tar.gz",
"has_sig": false,
"md5_digest": "48d19d0cff807aa03df8f695e6cd584d",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.12",
"size": 15446,
"upload_time": "2024-04-10T12:33:10",
"upload_time_iso_8601": "2024-04-10T12:33:10.523374Z",
"url": "https://files.pythonhosted.org/packages/09/43/e777af760b9716bcb0db179afe82681d05664aa2c7a76e14d2a3bedb7289/ksux-0.7.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-04-10 12:33:10",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "tsladecek",
"github_project": "ksux",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "ksux"
}
