Package: kubernator
KubernatorKubernator™ (Ktor™) is an integrated solution for the Kubernetes state management. It operates on directories,
processing their content via a collection of plugins, generating Kubernetes resources in the process, validating them,
transforming them and then applying against the Kubernetes cluster.NoticesBeta SoftwareWhile fully functional in the current state and used in production, this software is inBETA. A lot of things
are expected to change rapidly, including main APIs, initialization procedures and some core features. Documentation at
this stage is basically non-existent.LicenseThe product is licensed under the Apache License, Version 2.0. Please see LICENSE for further details.Warranties and LiabilityKubernator and its plugins are provided on an "AS IS" BASIS, WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either
express or implied, including, without limitation, any warranties or conditions of TITLE, NON-INFRINGEMENT,
MERCHANTABILITY, or FITNESS FOR A PARTICULAR PURPOSE. You are solely responsible for determining the appropriateness of
using or redistributing Kubernator and assume any risks associated with doing so.Trademarks"Kubernator" and "Ktor" are trademarks or registered trademarks of Express Systems USA, Inc and Karellen, Inc. All other
trademarks are property of their respective owners.Problem StatementSolutionUsing Kubernator with DockerA simple example is as follows:$ docker run --mount type=bind,source="$(pwd)",target=/root,readonly -t ghcr.io/karellen/kubernator:latestUsing Kubernator on MacOS$ brew install python3.11
$ pip3.11 install 'kubernator~=1.0.9'
$ kubernator --versionPlease note, that some plugins (e.g.awscli,eks) may require additional volume mounts or environmental
variables to be passed for credentials and other external configuration.Mode of OperationKubernator is a command line utility. Upon startup and processing of the command line arguments and initializing
logging, Kubernator initializes plugins. Current plugins include:Kubernator AppTerraformkOpsKubernetesHelmTemplateThe order of initialization matters as it's the order the plugin handlers are executed!The entire application operates in the following stages by invoking each plugin's stage handler in sequence:Plugin Init StagePre-start script (if specified)Plugin Start StageFor each directory in the pipeline:Plugin Before Directory StageIf.kubernator.pyis present in the directory:Plugin Before Script Stage.kubernator.pyscriptPlugin After Script StagePlugin After Directory StagePlugin End StageEach plugin individually plays a specific role and performs a specific function which will be described in a later
section.State/ContextThere is a global state that is carried through as the application is running. It is a hierarchy of objects (context)
that follows the parent-child relationship as the application traverses the directory structure. For example, given the
directory structure/a/b,/a/c, and/a/c/dany value of the context set or modified in context scoped to
directory/ais visible in directories/a/b,/a/cand/a/c/d, while the same modified or set in/a/bis only
visible there, while one in/a/cis visible in/a/cand in/a/c/dbut not/aor/a/b.Additionally, there is acontext.globalswhich is the top-most context that is available in all stages that are not
associated with the directory structure.Note, that in cases where the directory structure traversal moves to remote directories (that are actualized by local
temporary directories), such remote directory structure enters the context hierarchy as a child of the directory in
which remote was registered.Also note, that context carries not just data by references to essential functions.In pre-start and.kubernator.pyscripts the context is fully available as a global variablektor.PluginsKubernator App PluginThe role of the Kubernator App Plugin is to traverse the directory structure, expose essential functions through context
and to run Kubernator scripts.In theAfter Directory StageKubernator app scans the directories immediately available in the current, sorts them in
the alphabetic order, excludes those matching any of the patterns incontext.app.excludesand then queues up the
remaining directories in the order the match the patterns incontext.app.includes.Thus, for a directory content/a/foo,/a/bal,/a/bar,/a/baz, excludesf*, and includesbazand*, the
resulting queue of directories to traverse will be/a/baz,/a/bal,/a/bar.Notice, that user can further interfere with processing order of the directory queue by asking Kubernator to walk
arbitrary paths, both local and remote.Contextktor.app.argsNamespace containing command line argument valuesktor.app.walk_local(*paths: Union[Path, str, bytes])Immediately schedules the paths to be traversed after the current directory by adding them to the queue
Relative path is relative to the current directoryktor.app.walk_remote(repo, *path_prefixes: Union[Path, str, bytes])Immediately schedules the path prefixes under the remote repo URL to be traversed after the current directory by
adding them to the queue. Only Git URLs are currently supported.
All absolute path prefixes are relativized based on the repository.ktor.app.repository_credentials_provider(func: Callable)Sets a repository credentials provider functionfuncthat sets/overwrites credentials for URLs being specified bywalk_remote. The callablefuncaccepts a single argument containing a parsed URL in a form of tuple. Thefuncis expected to return a tuple of three elements representing URL schema, username and password. If the value should
not be changed it should be None. To convert fromgit://repo.com/helloto HTTPS authentication one should write
a function returning("https", "username", "password"). The best utility is achieved by logic that allows running
the plan both in CI and local environments using different authentication mechanics in different environments.TerraformThis is exclusively designed to pull the configuration options out of Terraform and to allow scripts and plugins to
utilize that data.Contextktor.tfA dictionary containing the values from Terraform outputKopsContextKubernetesContextHelmContextTemplatesContextExamplesAdding Remote Directoryktor.app.repository_credentials_provider(lambdar:("ssh","git",None))ktor.app.walk_remote("git://repo.example.com/org/project?ref=dev","/project")Adding Local Directoryktor.app.walk_local("/home/username/local-dir")Using Transformersdefremove_replicas(resources,r:"K8SResource"):if(r.group=="apps"andr.kindin("StatefulSet","Deployment")and"replicas"inr.manifest["spec"]):logger.warning("Resource%sin%scontains `replica` specification that will be removed. Use HPA!!!",r,r.source)delr.manifest["spec"]["replicas"]ktor.k8s.add_transformer(remove_replicas)