Generating Kubernetes definitions (yaml) with python, inspired by cdk8s. The main use case is to use those definitions with helm. This means cdk8s does replace all the templating that helm does - but helm still takes care of rolling out your changes to your cluster.
Know cdk8s? See our overview of the differences between pdk8s and cdk8s.
- Python >= 3.7.
pdk8s is available on PyPi, you can install it with your preferred python package manage, pip, pipenv, poetry, etc:
pip install pdk8s
The format of pdk8s charts is similar to helm charts, just that they are python instead of yaml. Your “python chart" must define the following variables:
name: Name of your chartchart_version: This is the chart version. This version number should be incremented each time you make changes to the chart and its templates, including the app version. Versions are expected to follow Semantic Versioning.app_version: This is the version number of the application being deployed. This version number should be incremented each time you make changes to the application. Versions are not expected to follow Semantic Versioning. They should reflect the version the application is using.chart: Your chart. A list orpdk8s.k8s.Chart(or actually any iterable python object) of k8s resources.
If you had a déjà vu while reading - that is because the description for chart_version and app_version are copied straight from Helm ;)
$ pdk8s init
chart_name [awesome chart]: Webserver Example
slug [awesome_chart]:
chart_version [0.1.0]:
app_version [0.1.0]: You will find a new folder awesome_chart. Inside the folder you will find a hello world example, open the chart.py:
chart = [
k8s.Deployment(name='deployment',
spec=k8s.DeploymentSpec(
replicas=2,
selector=k8s.LabelSelector(match_labels=label),
template=k8s.PodTemplateSpec(
metadata=k8s.ObjectMeta(labels=label),
spec=k8s.PodSpec(containers=[
k8s.Container(
name='hello-kubernetes',
image='paulbouwer/hello-kubernetes:1.7',
ports=[k8s.ContainerPort(container_port=8080)])]))))
]Which you can turn into a running helm chart with:
$ cd awesome_chart
$ pdk8s synthYou will find your generated chart under dist:
├── chart.py
└── dist
├── Chart.yaml
├── templates
│ └── generated.yaml
└── values.yaml
Per default pdk8s synth loads the chart.py in the current directory.
You can also use -i to specify a different python file.
Also the chart.py generated by pdk8s init provides the same api as pdk8s except without the -i option:
$ ./chart.py synthpdk8s also can generate the helm chart to a different directoy using -o.
Per default it generated a folder called dist in the same folder as your input chart.py.
Creating a service:
from pdk8s import k8s
service = k8s.Service(name="service",
spec=k8s.ServiceSpec(
type="LoadBalancer",
ports=[k8s.ServicePort(port=80, target_port=8080)],
selector={"app": "hello-k8s"}))
chart = [service]All pdk8s classes are pydantic data classes. Which provides - among other things - automatic conversion for parameters, so you can just as well write:
from pdk8s import k8s
k8s.Service(name="service",
spec={
"type": "LoadBalancer",
"ports": [{"port": 80, "target_port": 8080}],
"selector": {"app": "hello-k8s"}})All attributes can be manipulated after creation:
deployment = k8s.Deployment(name='deployment',
spec=k8s.DeploymentSpec(
replicas=2))
deployment.spec.replicas = math.randint(0, 666)Note 1: Automatic casting is only available on creation. deployment.spec = {"replicas": 2} would not work.
Note 2: Currently all required parameters must be provided at creation time. You cannot create an empty k8s.Deployment(). This might change.
The Kubernetes APIs use camelCase for naming attributes, while python usually uses snake_case. pdk8s also follows the snake_case convention, same as cdk8s.
pdk8s provides aliases for all arguments:
k8s.ServicePort(port=80, target_port=8080)
k8s.ServicePort(port=80, targetPort=8080)Both work and result in the same result. This is for compatibility when importing from other sources (and makes pdk8s.k8s.parse possible).
You might already have templates you want to build upon, you can easily import them using pdk8s.k8s.parse. Let's assume you have the following chart.yaml:
apiVersion: v1
kind: Service
metadata:
name: service
spec:
ports:
- port: 80
targetPort: 8080
selector:
app: hello-k8s
type: LoadBalancerWith:
import pdk8s
from pdk8s import k8s
my_chart = k8s.parse("example/chart.yaml")
my_chart[0].name = "service_new"
pdk8s.synth(my_chart)You get:
apiVersion: v1
kind: Service
metadata:
name: service_new
spec:
ports:
- port: 80
targetPort: 8080
selector:
app: hello-k8s
type: LoadBalancerIn cdk8s names are automatically made unique by adding a hash to it. pdk8s does not observe this behavior. Also in pdk8s names must be provided as keyword argument.
# cdk8s
k8s.Service(Chart("hello"), "service")
# kind: Service
# apiVersion: v1
# metadata:
# name: hello-service-9878228b
# pdk8s
k8s.Service(name='service')
# kind: Service
# apiVersion: v1
# metadata:
# name: service
TODO explain why this exists (NIH syndrome)
Generate everything at build time and not runtime as it makes it easier for linters and other dev tools, like IDEs.
Currently, generating the code of pdk8s depends on a patched version of datamodel-code-generator. I am working on upstreaming changes to not depend on local patches anymore.