kubernator 1.0.9.dev20231224171539__tar.gz → 1.0.10__tar.gz

{kubernator-1.0.9.dev20231224171539 → kubernator-1.0.10}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kubernator
-Version: 1.0.9.dev20231224171539
+Version: 1.0.10
 Summary: Kubernator is the a pluggable framework for K8S provisioning
 Home-page: https://github.com/karellen/kubernator
 Author: Express Systems USA, Inc.
@@ -86,7 +86,7 @@ $ docker run --mount type=bind,source="$(pwd)",target=/root,readonly -t ghcr.io/
 
 ```
 $ brew install python3.11
-$ pip3.11 install `kubernator~=1.0.9`
+$ pip3.11 install 'kubernator~=1.0.9'
 $ kubernator --version
 ```
 

{kubernator-1.0.9.dev20231224171539 → kubernator-1.0.10}/kubernator/__init__.py

@@ -16,7 +16,7 @@
 #   limitations under the License.
 #
 
-__version__ = "1.0.9.dev20231224171539"
+__version__ = "1.0.10"
 
 
 def _main():

{kubernator-1.0.9.dev20231224171539 → kubernator-1.0.10}/kubernator/plugins/k8s.py

@@ -49,6 +49,9 @@ proc_logger = logger.getChild("proc")
 stdout_logger = StripNL(proc_logger.info)
 stderr_logger = StripNL(proc_logger.warning)
 
+FIELD_VALIDATION_STRICT_MARKER = "strict decoding error: "
+VALID_FIELD_VALIDATION = ("Ignore", "Warn", "Strict")
+
 
 def final_resource_validator(resources: Sequence[K8SResource],
                              resource: K8SResource,
@@ -81,10 +84,12 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
     def set_context(self, context):
         self.context = context
 
-    def register(self, **kwargs):
+    def register(self, field_validation="Strict", field_validation_warn_fatal=True):
         self.context.app.register_plugin("kubeconfig")
 
-    def handle_init(self):
+        if field_validation not in VALID_FIELD_VALIDATION:
+            raise ValueError("'field_validation' must be one of %s" % (", ".join(VALID_FIELD_VALIDATION)))
+
         context = self.context
         context.globals.k8s = dict(patch_field_excludes=("^/metadata/managedFields",
                                                          "^/metadata/generation",
@@ -108,6 +113,9 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
                                    add_validator=self.api_remove_validator,
                                    get_api_versions=self.get_api_versions,
                                    create_resource=self.create_resource,
+                                   field_validation=field_validation,
+                                   field_validation_warn_fatal=field_validation_warn_fatal,
+                                   field_validation_warnings=0,
                                    _k8s=self,
                                    )
         context.k8s = dict(default_includes=Globs(context.globals.k8s.default_includes),
@@ -115,6 +123,9 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
                            )
         self.api_add_validator(final_resource_validator)
 
+    def handle_init(self):
+        pass
+
     def handle_start(self):
         self.context.kubeconfig.register_change_notifier(self._kubeconfig_changed)
         self.setup_client()
@@ -180,6 +191,19 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
 
         logger.info("Found Kubernetes %s on %s", k8s.server_git_version, k8s.client.configuration.host)
         K8SResource._k8s_client_version = tuple(map(int, pkg_version("kubernetes").split(".")))
+        K8SResource._k8s_field_validation = k8s.field_validation
+        K8SResource._logger = self.logger
+        K8SResource._api_warnings = self._api_warnings
+
+    def _api_warnings(self, resource, warn):
+        k8s = self.context.k8s
+        self.context.globals.k8s.field_validation_warnings += 1
+
+        log = self.logger.warning
+        if k8s.field_validation_warn_fatal:
+            log = self.logger.error
+
+        log("FAILED FIELD VALIDATION on resource %s from %s: %s", resource, resource.source, warn)
 
     def handle_before_dir(self, cwd: Path):
         context = self.context
@@ -205,6 +229,8 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
 
     def handle_apply(self):
         context = self.context
+        k8s = context.k8s
+
         self._validate_resources()
 
         cmd = context.app.args.command
@@ -258,6 +284,14 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
                                  create_func,
                                  delete_func,
                                  status_msg)
+
+        if ((dump or dry_run) and
+                k8s.field_validation_warn_fatal and self.context.globals.k8s.field_validation_warnings):
+            msg = ("There were %d field validation warnings and the warnings are fatal!" %
+                   self.context.globals.k8s.field_validation_warnings)
+            logger.fatal(msg)
+            raise RuntimeError(msg)
+
         if dump:
             if file_format in ("json", "json-pretty"):
                 json.dump(dump_results, file, sort_keys=True,
@@ -339,6 +373,19 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
         rdef = resource.rdef
         rdef.populate_api(client, self.context.k8s.client)
 
+        def handle_400_strict_validation_error(e: ApiException):
+            if e.status == 400:
+                status = json.loads(e.body)
+
+                if status["status"] == "Failure" and FIELD_VALIDATION_STRICT_MARKER in status["message"]:
+                    message = status["message"]
+                    messages = message[message.find(FIELD_VALIDATION_STRICT_MARKER) +
+                                       len(FIELD_VALIDATION_STRICT_MARKER):].split(",")
+                    for m in messages:
+                        self._api_warnings(resource, m.strip())
+
+                    raise e from None
+
         def create(exists_ok=False):
             logger.info("Creating resource %s%s%s", resource, status_msg,
                         " (ignoring existing)" if exists_ok else "")
@@ -350,7 +397,6 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
                         status = json.loads(e.body)
                         if status["reason"] == "AlreadyExists":
                             return
-
                 raise
 
         logger.debug("Applying resource %s%s", resource, status_msg)
@@ -359,7 +405,12 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
             logger.trace("Current resource %s: %s", resource, remote_resource)
         except ApiException as e:
             if e.status == 404:
-                create()
+                try:
+                    create()
+                except ApiException as e:
+                    if not handle_400_strict_validation_error(e):
+                        raise
+
             else:
                 raise
         else:
@@ -396,7 +447,8 @@ class KubernetesPlugin(KubernatorPlugin, K8SResourcePluginMixin):
                                 return
                         raise
                 else:
-                    raise
+                    if not handle_400_strict_validation_error(e):
+                        raise
             else:
                 logger.trace("Merged resource %s: %s", resource, merged_resource)
                 patch = jsonpatch.make_patch(remote_resource, merged_resource)

{kubernator-1.0.9.dev20231224171539 → kubernator-1.0.10}/kubernator/plugins/k8s_api.py

@@ -37,6 +37,7 @@ from openapi_schema_validator import OAS30Validator
 
 from kubernator.api import load_file, FileType, load_remote_file, calling_frame_source
 
+K8S_WARNING_HEADER = re.compile(r'(?:,\s*)?(\d{3})\s+(\S+)\s+"(.+?)(?<!\\)"(?:\s+\"(.+?)(?<!\\)\")?\s*')
 UPPER_FOLLOWED_BY_LOWER_RE = re.compile(r"(.)([A-Z][a-z]+)")
 LOWER_OR_NUM_FOLLOWED_BY_UPPER_RE = re.compile(r"([a-z0-9])([A-Z])")
 
@@ -338,6 +339,9 @@ class K8SResourceKey(namedtuple("K8SResourceKey", ["group", "kind", "name", "nam
 
 class K8SResource:
     _k8s_client_version = None
+    _k8s_field_validation = None
+    _logger = None
+    _api_warnings = None
 
     def __init__(self, manifest: dict, rdef: K8SResourceDef, source: Union[str, Path] = None):
         self.key = self.get_manifest_key(manifest)
@@ -403,13 +407,18 @@ class K8SResource:
         rdef = self.rdef
         kwargs = {"body": self.manifest,
                   "_preload_content": False,
-                  "field_manager": "kubernator"
+                  "field_manager": "kubernator",
                   }
+
+        if self._k8s_client_version[0] > 22:
+            kwargs["field_validation"] = self._k8s_field_validation
         if rdef.namespaced:
             kwargs["namespace"] = self.namespace
         if dry_run:
             kwargs["dry_run"] = "All"
-        return json.loads(rdef.create(**kwargs).data)
+        resp = rdef.create(**kwargs)
+        self._process_response_headers(resp)
+        return json.loads(resp.data)
 
     def patch(self, json_patch, *, patch_type: K8SResourcePatchType, force=False, dry_run=True):
         rdef = self.rdef
@@ -420,6 +429,9 @@ class K8SResource:
                   "_preload_content": False,
                   "field_manager": "kubernator",
                   }
+
+        if self._k8s_client_version[0] > 22:
+            kwargs["field_validation"] = self._k8s_field_validation
         if patch_type == K8SResourcePatchType.SERVER_SIDE_PATCH:
             kwargs["force"] = force
         if rdef.namespaced:
@@ -442,7 +454,9 @@ class K8SResource:
         old_func = api_client.select_header_content_type
         try:
             api_client.select_header_content_type = select_header_content_type_patch
-            return json.loads(rdef.patch(**kwargs).data)
+            resp = rdef.patch(**kwargs)
+            self._process_response_headers(resp)
+            return json.loads(resp.data)
         finally:
             api_client.select_header_content_type = old_func
 
@@ -484,6 +498,20 @@ class K8SResource:
             return False
         return self.key == other.key and self.manifest == other.manifest
 
+    def _process_response_headers(self, resp):
+        headers = resp.headers
+        warn_headers = headers.get("Warning")
+        if warn_headers:
+            for warn in K8S_WARNING_HEADER.findall(warn_headers):
+                code, _, msg, _ = warn
+                code = int(code)
+                msg = msg.encode("utf-8").decode("unicode_escape")
+                if code == 299:
+                    self._api_warnings(self, msg)
+                else:
+                    self._logger.warning("Unknown API warning received for resource %s from %s: code %d: %s",
+                                         self, self.source, code, msg)
+
 
 class K8SResourcePluginMixin:
     def __init__(self):

{kubernator-1.0.9.dev20231224171539 → kubernator-1.0.10}/kubernator/plugins/minikube.py

@@ -116,7 +116,7 @@ class MinikubePlugin(KubernatorPlugin):
         minikube_file = Path(self.minikube_dir.name) / "minikube"
         minikube_file.symlink_to(minikube_dl_file)
         prepend_os_path(self.minikube_dir.name)
-        version_out: str = self.context.app.run_capturing_out([minikube_file, "version", "--short"],
+        version_out: str = self.context.app.run_capturing_out([str(minikube_file), "version", "--short"],
                                                               stderr_logger).strip()
         version = version_out[1:]
         logger.info("Found minikube %s in %s", version, minikube_file)

{kubernator-1.0.9.dev20231224171539 → kubernator-1.0.10}/kubernator.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.1
 Name: kubernator
-Version: 1.0.9.dev20231224171539
+Version: 1.0.10
 Summary: Kubernator is the a pluggable framework for K8S provisioning
 Home-page: https://github.com/karellen/kubernator
 Author: Express Systems USA, Inc.
@@ -86,7 +86,7 @@ $ docker run --mount type=bind,source="$(pwd)",target=/root,readonly -t ghcr.io/
 
 ```
 $ brew install python3.11
-$ pip3.11 install `kubernator~=1.0.9`
+$ pip3.11 install 'kubernator~=1.0.9'
 $ kubernator --version
 ```
 

kubernator-1.0.10/setup.py

@@ -0,0 +1,95 @@
+#!/usr/bin/env python
+#   -*- coding: utf-8 -*-
+
+from setuptools import setup
+from setuptools.command.install import install as _install
+
+class install(_install):
+    def pre_install_script(self):
+        pass
+
+    def post_install_script(self):
+        pass
+
+    def run(self):
+        self.pre_install_script()
+
+        _install.run(self)
+
+        self.post_install_script()
+
+if __name__ == '__main__':
+    setup(
+        name = 'kubernator',
+        version = '1.0.10',
+        description = 'Kubernator is the a pluggable framework for K8S provisioning',
+        long_description = '# Kubernator\n\nKubernator™ (Ktor™) is an integrated solution for the Kubernetes state management. It operates on directories,\nprocessing their content via a collection of plugins, generating Kubernetes resources in the process, validating them,\ntransforming them and then applying against the Kubernetes cluster.\n\n[![Gitter](https://img.shields.io/gitter/room/karellen/lobby?logo=gitter)](https://gitter.im/karellen/Lobby)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/karellen/kubernator/kubernator.yml?branch=master)](https://github.com/karellen/kubernator/actions/workflows/kubernator.yml)\n[![Coverage Status](https://img.shields.io/coveralls/github/karellen/kubernator/master?logo=coveralls)](https://coveralls.io/r/karellen/kubernator?branch=master)\n\n[![Kubernator Version](https://img.shields.io/pypi/v/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Python Versions](https://img.shields.io/pypi/pyversions/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Downloads Per Day](https://img.shields.io/pypi/dd/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Downloads Per Week](https://img.shields.io/pypi/dw/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Downloads Per Month](https://img.shields.io/pypi/dm/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n\n## Notices\n\n### Beta Software\n\nWhile fully functional in the current state and used in production, this software is in **BETA**. A lot of things\nare expected to change rapidly, including main APIs, initialization procedures and some core features. Documentation at\nthis stage is basically non-existent.\n\n### License\n\nThe product is licensed under the Apache License, Version 2.0. Please see LICENSE for further details.\n\n### Warranties and Liability\n\nKubernator and its plugins are provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either\nexpress or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,\nMERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of\nusing or redistributing Kubernator and assume any risks associated with doing so.\n\n### Trademarks\n\n"Kubernator" and "Ktor" are trademarks or registered trademarks of Express Systems USA, Inc and Karellen, Inc. All other\ntrademarks are property of their respective owners.\n\n## Problem Statement\n\n## Solution\n\n## Using Kubernator with Docker\n\nA simple example is as follows:\n```\n$ docker run --mount type=bind,source="$(pwd)",target=/root,readonly -t ghcr.io/karellen/kubernator:latest\n```\n\n## Using Kubernator on MacOS\n\n```\n$ brew install python3.11\n$ pip3.11 install \'kubernator~=1.0.9\'\n$ kubernator --version\n```\n\nPlease note, that some plugins (e.g. `awscli`, `eks`) may require additional volume mounts or environmental\nvariables to be passed for credentials and other external configuration.\n\n## Mode of Operation\n\nKubernator is a command line utility. Upon startup and processing of the command line arguments and initializing\nlogging, Kubernator initializes plugins. Current plugins include:\n\n0. Kubernator App\n1. Terraform\n2. kOps\n3. Kubernetes\n4. Helm\n5. Template\n\nThe order of initialization matters as it\'s the order the plugin handlers are executed!\n\nThe entire application operates in the following stages by invoking each plugin\'s stage handler in sequence:\n\n1. Plugin Init Stage\n2. Pre-start script (if specified)\n3. Plugin Start Stage\n4. For each directory in the pipeline:\n    1. Plugin Before Directory Stage\n    2. If `.kubernator.py` is present in the directory:\n        1. Plugin Before Script Stage\n        2. `.kubernator.py` script\n        3. Plugin After Script Stage\n    3. Plugin After Directory Stage\n5. Plugin End Stage\n\nEach plugin individually plays a specific role and performs a specific function which will be described in a later\nsection.\n\n## State/Context\n\nThere is a global state that is carried through as the application is running. It is a hierarchy of objects (`context`)\nthat follows the parent-child relationship as the application traverses the directory structure. For example, given the\ndirectory structure `/a/b`, `/a/c`, and `/a/c/d` any value of the context set or modified in context scoped to\ndirectory `/a` is visible in directories `/a/b`, `/a/c` and `/a/c/d`, while the same modified or set in `/a/b` is only\nvisible there, while one in `/a/c` is visible in `/a/c` and in `/a/c/d` but not `/a` or `/a/b`.\n\nAdditionally, there is a `context.globals` which is the top-most context that is available in all stages that are not\nassociated with the directory structure.\n\nNote, that in cases where the directory structure traversal moves to remote directories (that are actualized by local\ntemporary directories), such remote directory structure enters the context hierarchy as a child of the directory in\nwhich remote was registered.\n\nAlso note, that context carries not just data by references to essential functions.\n\nIn pre-start and `.kubernator.py` scripts the context is fully available as a global variable `ktor`.\n\n### Plugins\n\n#### Kubernator App Plugin\n\nThe role of the Kubernator App Plugin is to traverse the directory structure, expose essential functions through context\nand to run Kubernator scripts.\n\nIn the *After Directory Stage* Kubernator app scans the directories immediately available in the current, sorts them in\nthe alphabetic order, excludes those matching any of the patterns in `context.app.excludes` and then queues up the\nremaining directories in the order the match the patterns in `context.app.includes`.\n\nThus, for a directory content `/a/foo`, `/a/bal`, `/a/bar`, `/a/baz`, excludes `f*`, and includes `baz` and `*`, the\nresulting queue of directories to traverse will be `/a/baz`, `/a/bal`, `/a/bar`.\n\nNotice, that user can further interfere with processing order of the directory queue by asking Kubernator to walk\narbitrary paths, both local and remote.\n\n##### Context\n\n* `ktor.app.args`\n  > Namespace containing command line argument values\n* `ktor.app.walk_local(*paths: Union[Path, str, bytes])`\n  > Immediately schedules the paths to be traversed after the current directory by adding them to the queue\n  > Relative path is relative to the current directory\n* `ktor.app.walk_remote(repo, *path_prefixes: Union[Path, str, bytes])`\n  > Immediately schedules the path prefixes under the remote repo URL to be traversed after the current directory by\n  > adding them to the queue. Only Git URLs are currently supported.\n  > All absolute path prefixes are relativized based on the repository.\n* `ktor.app.repository_credentials_provider(func: Callable)`\n  > Sets a repository credentials provider function `func` that sets/overwrites credentials for URLs being specified by\n  > `walk_remote`. The callable `func` accepts a single argument containing a parsed URL in a form of tuple. The `func`\n  > is expected to return a tuple of three elements representing URL schema, username and password. If the value should\n  > not be changed it should be None. To convert from `git://repo.com/hello` to HTTPS authentication one should write\n  > a function returning `("https", "username", "password")`. The best utility is achieved by logic that allows running\n  > the plan both in CI and local environments using different authentication mechanics in different environments.\n\n#### Terraform\n\nThis is exclusively designed to pull the configuration options out of Terraform and to allow scripts and plugins to\nutilize that data.\n\n##### Context\n\n* `ktor.tf`\n  > A dictionary containing the values from Terraform output\n\n#### Kops\n\n##### Context\n\n#### Kubernetes\n\n##### Context\n\n#### Helm\n\n##### Context\n\n#### Templates\n\n##### Context\n\n## Examples\n\n### Adding Remote Directory\n\n```python\nktor.app.repository_credentials_provider(lambda r: ("ssh", "git", None))\nktor.app.walk_remote("git://repo.example.com/org/project?ref=dev", "/project")\n```\n\n### Adding Local Directory\n\n```python\nktor.app.walk_local("/home/username/local-dir")\n```\n\n### Using Transformers\n\n```python\ndef remove_replicas(resources, r: "K8SResource"):\n    if (r.group == "apps" and r.kind in ("StatefulSet", "Deployment")\n            and "replicas" in r.manifest["spec"]):\n        logger.warning("Resource %s in %s contains `replica` specification that will be removed. Use HPA!!!",\n                       r, r.source)\n        del r.manifest["spec"]["replicas"]\n\n\nktor.k8s.add_transformer(remove_replicas)\n```\n',
+        long_description_content_type = 'text/markdown',
+        classifiers = [
+            'License :: OSI Approved :: Apache Software License',
+            'Programming Language :: Python :: 3.9',
+            'Programming Language :: Python :: 3.10',
+            'Programming Language :: Python :: 3.11',
+            'Operating System :: MacOS :: MacOS X',
+            'Operating System :: POSIX',
+            'Operating System :: POSIX :: Linux',
+            'Environment :: Console',
+            'Topic :: Utilities',
+            'Topic :: System :: Monitoring',
+            'Topic :: System :: Distributed Computing',
+            'Topic :: System :: Clustering',
+            'Topic :: System :: Networking',
+            'Intended Audience :: System Administrators',
+            'Intended Audience :: Developers',
+            'Development Status :: 4 - Beta'
+        ],
+        keywords = 'kubernetes k8s kube top provisioning kOps terraform tf AWS',
+
+        author = 'Express Systems USA, Inc.',
+        author_email = '',
+        maintainer = 'Karellen, Inc., Arcadiy Ivanov',
+        maintainer_email = 'supervisor@karellen.co,arcadiy@karellen.co',
+
+        license = 'Apache License, Version 2.0',
+
+        url = 'https://github.com/karellen/kubernator',
+        project_urls = {
+            'Bug Tracker': 'https://github.com/karellen/kubernator/issues',
+            'Documentation': 'https://github.com/karellen/kubernator/',
+            'Source Code': 'https://github.com/karellen/kubernator/'
+        },
+
+        scripts = [],
+        packages = [
+            'kubernator',
+            'kubernator.plugins'
+        ],
+        namespace_packages = [],
+        py_modules = [],
+        entry_points = {
+            'console_scripts': ['kubernator = kubernator:main']
+        },
+        data_files = [],
+        package_data = {
+            'kubernator': ['LICENSE']
+        },
+        install_requires = [
+            'appdirs~=1.4',
+            'coloredlogs~=15.0',
+            'gevent>=21.1.2',
+            'jinja2~=3.1',
+            'json-log-formatter~=0.3',
+            'jsonpatch~=1.32',
+            'jsonpath-ng~=1.5',
+            'jsonschema<4.0',
+            'kubernetes~=28.0',
+            'openapi-schema-validator~=0.1',
+            'openapi-spec-validator~=0.3',
+            'requests~=2.25'
+        ],
+        dependency_links = [],
+        zip_safe = True,
+        cmdclass = {'install': install},
+        python_requires = '>=3.9',
+        obsoletes = [],
+    )

kubernator-1.0.9.dev20231224171539/setup.py

@@ -1,95 +0,0 @@
-#!/usr/bin/env python
-#   -*- coding: utf-8 -*-
-
-from setuptools import setup
-from setuptools.command.install import install as _install
-
-class install(_install):
-    def pre_install_script(self):
-        pass
-
-    def post_install_script(self):
-        pass
-
-    def run(self):
-        self.pre_install_script()
-
-        _install.run(self)
-
-        self.post_install_script()
-
-if __name__ == '__main__':
-    setup(
-        name = 'kubernator',
-        version = '1.0.9.dev20231224171539',
-        description = 'Kubernator is the a pluggable framework for K8S provisioning',
-        long_description = '# Kubernator\n\nKubernator™ (Ktor™) is an integrated solution for the Kubernetes state management. It operates on directories,\nprocessing their content via a collection of plugins, generating Kubernetes resources in the process, validating them,\ntransforming them and then applying against the Kubernetes cluster.\n\n[![Gitter](https://img.shields.io/gitter/room/karellen/lobby?logo=gitter)](https://gitter.im/karellen/Lobby)\n[![Build Status](https://img.shields.io/github/actions/workflow/status/karellen/kubernator/kubernator.yml?branch=master)](https://github.com/karellen/kubernator/actions/workflows/kubernator.yml)\n[![Coverage Status](https://img.shields.io/coveralls/github/karellen/kubernator/master?logo=coveralls)](https://coveralls.io/r/karellen/kubernator?branch=master)\n\n[![Kubernator Version](https://img.shields.io/pypi/v/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Python Versions](https://img.shields.io/pypi/pyversions/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Downloads Per Day](https://img.shields.io/pypi/dd/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Downloads Per Week](https://img.shields.io/pypi/dw/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n[![Kubernator Downloads Per Month](https://img.shields.io/pypi/dm/kubernator?logo=pypi)](https://pypi.org/project/kubernator/)\n\n## Notices\n\n### Beta Software\n\nWhile fully functional in the current state and used in production, this software is in **BETA**. A lot of things\nare expected to change rapidly, including main APIs, initialization procedures and some core features. Documentation at\nthis stage is basically non-existent.\n\n### License\n\nThe product is licensed under the Apache License, Version 2.0. Please see LICENSE for further details.\n\n### Warranties and Liability\n\nKubernator and its plugins are provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either\nexpress or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,\nMERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of\nusing or redistributing Kubernator and assume any risks associated with doing so.\n\n### Trademarks\n\n"Kubernator" and "Ktor" are trademarks or registered trademarks of Express Systems USA, Inc and Karellen, Inc. All other\ntrademarks are property of their respective owners.\n\n## Problem Statement\n\n## Solution\n\n## Using Kubernator with Docker\n\nA simple example is as follows:\n```\n$ docker run --mount type=bind,source="$(pwd)",target=/root,readonly -t ghcr.io/karellen/kubernator:latest\n```\n\n## Using Kubernator on MacOS\n\n```\n$ brew install python3.11\n$ pip3.11 install `kubernator~=1.0.9`\n$ kubernator --version\n```\n\nPlease note, that some plugins (e.g. `awscli`, `eks`) may require additional volume mounts or environmental\nvariables to be passed for credentials and other external configuration.\n\n## Mode of Operation\n\nKubernator is a command line utility. Upon startup and processing of the command line arguments and initializing\nlogging, Kubernator initializes plugins. Current plugins include:\n\n0. Kubernator App\n1. Terraform\n2. kOps\n3. Kubernetes\n4. Helm\n5. Template\n\nThe order of initialization matters as it\'s the order the plugin handlers are executed!\n\nThe entire application operates in the following stages by invoking each plugin\'s stage handler in sequence:\n\n1. Plugin Init Stage\n2. Pre-start script (if specified)\n3. Plugin Start Stage\n4. For each directory in the pipeline:\n    1. Plugin Before Directory Stage\n    2. If `.kubernator.py` is present in the directory:\n        1. Plugin Before Script Stage\n        2. `.kubernator.py` script\n        3. Plugin After Script Stage\n    3. Plugin After Directory Stage\n5. Plugin End Stage\n\nEach plugin individually plays a specific role and performs a specific function which will be described in a later\nsection.\n\n## State/Context\n\nThere is a global state that is carried through as the application is running. It is a hierarchy of objects (`context`)\nthat follows the parent-child relationship as the application traverses the directory structure. For example, given the\ndirectory structure `/a/b`, `/a/c`, and `/a/c/d` any value of the context set or modified in context scoped to\ndirectory `/a` is visible in directories `/a/b`, `/a/c` and `/a/c/d`, while the same modified or set in `/a/b` is only\nvisible there, while one in `/a/c` is visible in `/a/c` and in `/a/c/d` but not `/a` or `/a/b`.\n\nAdditionally, there is a `context.globals` which is the top-most context that is available in all stages that are not\nassociated with the directory structure.\n\nNote, that in cases where the directory structure traversal moves to remote directories (that are actualized by local\ntemporary directories), such remote directory structure enters the context hierarchy as a child of the directory in\nwhich remote was registered.\n\nAlso note, that context carries not just data by references to essential functions.\n\nIn pre-start and `.kubernator.py` scripts the context is fully available as a global variable `ktor`.\n\n### Plugins\n\n#### Kubernator App Plugin\n\nThe role of the Kubernator App Plugin is to traverse the directory structure, expose essential functions through context\nand to run Kubernator scripts.\n\nIn the *After Directory Stage* Kubernator app scans the directories immediately available in the current, sorts them in\nthe alphabetic order, excludes those matching any of the patterns in `context.app.excludes` and then queues up the\nremaining directories in the order the match the patterns in `context.app.includes`.\n\nThus, for a directory content `/a/foo`, `/a/bal`, `/a/bar`, `/a/baz`, excludes `f*`, and includes `baz` and `*`, the\nresulting queue of directories to traverse will be `/a/baz`, `/a/bal`, `/a/bar`.\n\nNotice, that user can further interfere with processing order of the directory queue by asking Kubernator to walk\narbitrary paths, both local and remote.\n\n##### Context\n\n* `ktor.app.args`\n  > Namespace containing command line argument values\n* `ktor.app.walk_local(*paths: Union[Path, str, bytes])`\n  > Immediately schedules the paths to be traversed after the current directory by adding them to the queue\n  > Relative path is relative to the current directory\n* `ktor.app.walk_remote(repo, *path_prefixes: Union[Path, str, bytes])`\n  > Immediately schedules the path prefixes under the remote repo URL to be traversed after the current directory by\n  > adding them to the queue. Only Git URLs are currently supported.\n  > All absolute path prefixes are relativized based on the repository.\n* `ktor.app.repository_credentials_provider(func: Callable)`\n  > Sets a repository credentials provider function `func` that sets/overwrites credentials for URLs being specified by\n  > `walk_remote`. The callable `func` accepts a single argument containing a parsed URL in a form of tuple. The `func`\n  > is expected to return a tuple of three elements representing URL schema, username and password. If the value should\n  > not be changed it should be None. To convert from `git://repo.com/hello` to HTTPS authentication one should write\n  > a function returning `("https", "username", "password")`. The best utility is achieved by logic that allows running\n  > the plan both in CI and local environments using different authentication mechanics in different environments.\n\n#### Terraform\n\nThis is exclusively designed to pull the configuration options out of Terraform and to allow scripts and plugins to\nutilize that data.\n\n##### Context\n\n* `ktor.tf`\n  > A dictionary containing the values from Terraform output\n\n#### Kops\n\n##### Context\n\n#### Kubernetes\n\n##### Context\n\n#### Helm\n\n##### Context\n\n#### Templates\n\n##### Context\n\n## Examples\n\n### Adding Remote Directory\n\n```python\nktor.app.repository_credentials_provider(lambda r: ("ssh", "git", None))\nktor.app.walk_remote("git://repo.example.com/org/project?ref=dev", "/project")\n```\n\n### Adding Local Directory\n\n```python\nktor.app.walk_local("/home/username/local-dir")\n```\n\n### Using Transformers\n\n```python\ndef remove_replicas(resources, r: "K8SResource"):\n    if (r.group == "apps" and r.kind in ("StatefulSet", "Deployment")\n            and "replicas" in r.manifest["spec"]):\n        logger.warning("Resource %s in %s contains `replica` specification that will be removed. Use HPA!!!",\n                       r, r.source)\n        del r.manifest["spec"]["replicas"]\n\n\nktor.k8s.add_transformer(remove_replicas)\n```\n',
-        long_description_content_type = 'text/markdown',
-        classifiers = [
-            'License :: OSI Approved :: Apache Software License',
-            'Programming Language :: Python :: 3.9',
-            'Programming Language :: Python :: 3.10',
-            'Programming Language :: Python :: 3.11',
-            'Operating System :: MacOS :: MacOS X',
-            'Operating System :: POSIX',
-            'Operating System :: POSIX :: Linux',
-            'Environment :: Console',
-            'Topic :: Utilities',
-            'Topic :: System :: Monitoring',
-            'Topic :: System :: Distributed Computing',
-            'Topic :: System :: Clustering',
-            'Topic :: System :: Networking',
-            'Intended Audience :: System Administrators',
-            'Intended Audience :: Developers',
-            'Development Status :: 4 - Beta'
-        ],
-        keywords = 'kubernetes k8s kube top provisioning kOps terraform tf AWS',
-
-        author = 'Express Systems USA, Inc.',
-        author_email = '',
-        maintainer = 'Karellen, Inc., Arcadiy Ivanov',
-        maintainer_email = 'supervisor@karellen.co,arcadiy@karellen.co',
-
-        license = 'Apache License, Version 2.0',
-
-        url = 'https://github.com/karellen/kubernator',
-        project_urls = {
-            'Bug Tracker': 'https://github.com/karellen/kubernator/issues',
-            'Documentation': 'https://github.com/karellen/kubernator/',
-            'Source Code': 'https://github.com/karellen/kubernator/'
-        },
-
-        scripts = [],
-        packages = [
-            'kubernator',
-            'kubernator.plugins'
-        ],
-        namespace_packages = [],
-        py_modules = [],
-        entry_points = {
-            'console_scripts': ['kubernator = kubernator:main']
-        },
-        data_files = [],
-        package_data = {
-            'kubernator': ['LICENSE']
-        },
-        install_requires = [
-            'appdirs~=1.4',
-            'coloredlogs~=15.0',
-            'gevent>=21.1.2',
-            'jinja2~=3.1',
-            'json-log-formatter~=0.3',
-            'jsonpatch~=1.32',
-            'jsonpath-ng~=1.5',
-            'jsonschema<4.0',
-            'kubernetes~=28.0',
-            'openapi-schema-validator~=0.1',
-            'openapi-spec-validator~=0.3',
-            'requests~=2.25'
-        ],
-        dependency_links = [],
-        zip_safe = True,
-        cmdclass = {'install': install},
-        python_requires = '>=3.9',
-        obsoletes = [],
-    )