kubernetes-client / kubernetes-client/python

Documentation creates steep learning curve.

Open
#601 10 comments 7 reactions 0 assignees View on GitHub
help wanted kind/documentation lifecycle/frozen
Dominant language
Python
Stars
7.7k
Forks
3.5k
Avg merge
1d 14h
Merged PRs (30d)
18

Description

My guess is that most of those who use settle on python as their k8s client are doing so due to python being their dominant language. The clean programming pattern for this client appears to be relying on the structs of each component needed to build request bodies and not combining structs with python dicts to generate requests. There are a lot of structs to choose from. Point being: the pythonic way of implementing the client is not necessarily obvious and users can benefit from documentation that points them to a clean programming pattern.

My request is to break out documentation into a similar format to k8s concepts docs https://kubernetes.io/docs/concepts/ and subtopic the same resources and have tutorials to manage said resources. As an example:

If I were looking to use the python client to create a job programmatically, I could navigate to:
```
Workloads
|___Controllers
|___ Jobs
```

Where there is a clean tutorial that can show you how to build a job using only the structs required.

For example, to build the jobs in the k8s documentation https://kubernetes.io/docs/concepts/workloads/controllers/jobs-run-to-completion/

```
apiVersion: batch/v1
kind: Job
metadata:
name: pi
spec:
template:
spec:
containers:
- name: pi
image: perl
command: ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
restartPolicy: Never
backoffLimit: 4
```

The tutorial can show code like so:
```
from kubernetes import client
container = client.V1Container(name="pi")
container.image = "perl"
container.command = ["perl", "-Mbignum=bpi", "-wle", "print bpi(2000)"]
temp_spec = client.V1PodSpec(containers=[container])
temp_spec.restart_policy = "Never"
template = client.V1beta1JobTemplateSpec()
template.spec = temp_spec
spec = client.V1JobSpec(template=template)
spec.backoff_limit = 4
job = client.V1Job()
job.spec = spec
meta = client.V1ObjectMeta()
meta.name = "pi"
job.metadata = meta
```

Contributor guide

Open the contributing guide

Research direction

Start by reviewing the Kubernetes concepts documentation and the Python client’s existing documentation structure. Use the Jobs example in the issue as the first tutorial target, documenting the required client structs and the resource hierarchy. Done means users can find a Job tutorial and follow it to construct the shown resource.

Written by the indexing model from the issue text.

Assessment

Tech stack
kubernetes, python
Domain
documentation
Issue type
Documentation
Difficulty
5/5
Estimated time
Over a week
Activity status
Stale
Clarity
Mostly clear
Newbie friendliness
35/100

Get new issues in your inbox

A short digest of beginner-friendly GitHub issues.