hikaru 0.1a0

Usage

To create Python objects from a Kubernetes YAML source, use load_full_yaml():

from hikaru import load_full_yaml

docs = load_full_yaml(stream=open("test.yaml", "r"))
p = docs[0]

load_full_yaml() loads every Kubernetes YAML document in a YAML file and returns a list of the resulting Hikaru objects found. You can then use the YAML property names to navigate the resulting object. If you assert that an object is of a known object type, your IDE can provide you assistance in navigation:

from hikaru.model import Pod
assert isinstance(p, Pod)
print(p.metadata.labels["lab2"])
print(p.spec.containers[0].ports[0].containerPort)
for k, v in p.metadata.labels.items():
    print(f"key:{k} value:{v}")

You can create Kubernetes objects in Python:

from hikaru.model import Pod, PodSpec, Container, ObjectMeta
x = Pod(apiVersion='v1', kind='Pod',
        metadata=ObjectMeta(name='hello-kiamol-3'),
        spec=PodSpec(
            containers=[Container(name='web', image='kiamol/ch02-hello-kiamol') ]
             )
    )

…and then render it in YAML:

from hikaru import get_yaml
print(get_yaml(x))

…which yields:

---
apiVersion: v1
kind: Pod
metadata:
  name: hello-kiamol-3
spec:
  containers:
    - name: web
      image: kiamol/ch02-hello-kiamol

If you use Hikaru to parse this back in as Python objects, you can then ask Hikaru to output Python source code that will re-create it (thus providing a migration path):

from hikaru import get_python_source, load_full_yaml
docs = load_full_yaml(path="to/the/above.yaml")
print(get_python_source(docs[0], assign_to='x'))

…which results in:

x = Pod(apiVersion='v1', kind='Pod', metadata=ObjectMeta(name='hello-kiamol-3'),
        spec=PodSpec(containers=[Container(name='web', image='kiamol/ch02-hello-kiamol')]))

It is entirely possible to load YAML into Python, tailor it, and then send it back to YAML; Hikaru can round-trip YAML through Python and then back to the equivalent YAML.

The pieces of complex objects can be created separately and even stored in a standard components library module for assembly later, or returned as the value of a factory function, as opposed to using a templating system to piece text files together:

from component_lib import web_container, lb_container
from hikaru.model import Pod, ObjectMeta, PodSpec
# make an ObjectMeta instance here called "om"
p = Pod(apiVersion="v1", kind="Pod",
        metadata=om,
        spec=PodSpec(containers=[web_container, lb_container])
        )

Hikaru objects can be tested for equivalence with ‘==’, and you can also easily create deep copies of entire object structures with dup(). This latter is useful in cases where you have a component that you want to use multiple times in a model but need it slightly tweaked in each use; a shared instance can’t have different values at each use, so it’s easy to make a copy that can be customised in isolation.

Finally, every Hikaru object that holds other properties and objects have methods that allow you to search the entire collection of objects. This lets you find various objects of interest for review and checking against policies and conventions. For example, if we had a Pod ‘p’ that was pulled in with load_full_yaml(), we could examine all of the Container objects with:

containers = p.find_by_name("containers")
for c in containers:
    # check what you want...

Or you can get all of the ExecAction object (the value of ‘exec’ properties) that are part the second container’s lifecycle’s httpGet property like so:

execs = p.find_by_name("exec", following='containers.1.lifecycle.httpGet')

These queries result in a list of CatalogEntry objects, which are named tuples that provide the path to the found element. You can acquire the actual element for inspection with the object_at_path() method:

o = p.object_at_path(execs[0].path)

This makes it easy to scan for specific items in a config under automated control.